项目介绍
DocMCP: 在PostgreSQL上使用pgvector索引最新的LLM文档并将其暴露给AI IDE
一个用于爬取、处理和查询文档的系统，具备AI驱动的嵌入生成和语义搜索功能。
功能
- 文档爬取：自动爬取文档站点，支持自定义深度和速率限制
- 内容处理：将HTML转换为干净的Markdown，并提取元数据
- 向量嵌入：使用AWS Bedrock生成嵌入以进行语义搜索
- 任务管理：跟踪和管理文档处理任务，提供详细的进度报告
- MCP集成：内置MCP工具以实现AI代理集成
发展路线图
- SPA支持：当前爬虫不支持SPA
- 缓存：爬取的URL直接添加到数据库
开始使用（开发环境设置）
先决条件
快速开始步骤
-
克隆仓库：
git clone https://github.com/visheshd/docmcp.git cd docmcp -
配置环境：
- 复制示例环境文件：
cp .env.example .env - 编辑
.env文件：- 将
DATABASE_URL设置为postgresql://postgres:postgres@localhost:5433/docmcp - 配置AWS Bedrock：
- 将
AWS_REGION设置为您的AWS区域（例如，us-east-1） - 使用您的AWS凭证设置
AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY - 或确保您的AWS CLI已用适当的凭证配置
- 将
- 如需调整其他设置，如
LOG_LEVEL
- 将
- 复制示例环境文件：
-
启动开发环境：
# 使脚本可执行 chmod +x dev-start.sh # 启动开发环境 ./dev-start.sh此脚本将：
- 在Docker容器中启动带有pgvector的PostgreSQL
- 安装项目依赖项
- 运行数据库迁移
- 自动导入种子数据
- 数据库将在端口5433上可用
-
添加文档： 使用
add-docs脚本来爬取和处理文档：# 基本用法 npm run add-docs -- --url https://example.com/docs --max-depth 3 # 带附加选项 npm run add-docs -- \ --url https://example.com/docs \ --max-depth 3 \ --tags react,frontend \ --package react \ --version 18.0.0 \ --wait可用选项：
--url：要爬取的文档URL（必需）--max-depth：最大爬取深度（默认值：3）--tags：用于分类的逗号分隔标签--package：此文档对应的包名--version：包版本（默认为“最新”）--wait：等待处理完成--verbose：启用详细日志记录- 查看所有选项，请运行
npm run add-docs -- --help
-
查询文档： 添加文档后，您可以使用MCP工具对其进行查询。请参阅下面的“查询文档”部分。
-
停止开发环境：
docker-compose -f docker-compose.dev.yml down
此设置提供了一个轻量级的开发环境，仅包含所需的PostgreSQL数据库和预加载的种子数据。对于生产部署或如果您希望完全容器化设置，请参阅下面的“生产Docker设置”部分。
Cursor设置
要将DocMCP与Cursor IDE一起使用，您需要配置MCP传输。在您的Cursor设置中添加以下配置：
{
"docmcp-local-stdio": {
"transport": "stdio",
"command": "node",
"args": [
"<DOCMCP_DIR>/dist/stdio-server.js"
],
"clientInfo": {
"name": "cursor-client",
"version": "1.0.0"
}
}
}
将<DOCMCP_DIR>替换为您DocMCP安装目录的绝对路径。
例如，如果DocMCP安装在/home/user/projects/docmcp，则您的配置应为：
"args": ["/home/user/projects/docmcp/dist/stdio-server.js"]
添加此配置后，重启Cursor以使更改生效。
架构
该系统由几个核心服务组成：
- CrawlerService：处理具有robots.txt支持的文档站点爬取
- DocumentProcessorService：处理文档（HTML→Markdown，分块，嵌入）
- JobService：管理异步处理作业，具有详细的状态跟踪
- ChunkService：存储和检索具有向量搜索能力的文档片段
- MCP Tools：友好的代理接口，用于添加和查询文档
文档处理流水线
DocMCP系统通过以下流水线处理文档：
-
文档输入
- 用户通过
add_documentationMCP工具提供一个URL - 系统创建一个状态为“待处理”的作业记录
- 作业被分配用于分类和未来过滤的标签
- 用户通过
-
网络爬取（CrawlerService）
- 爬虫尊重robots.txt限制
- 跟随链接直到指定的最大深度
- 捕获HTML内容和元数据
- 创建与父作业关联的文档记录
-
文档处理（DocumentProcessorService）
- 清理HTML并转换为结构化的Markdown
- 提取元数据（包信息，版本，文档类型）
- 建立文档之间的父子关系
- 在处理过程中更新作业进度
-
分块及嵌入（ChunkService）
- 将文档分割成语义块以提高检索效率
- 使用AWS Bedrock生成向量嵌入
- 使用pgvector扩展将嵌入存储在PostgreSQL中
- 保留块元数据和文档引用
-
作业最终化（JobService）
- 更新作业状态为“已完成”
- 计算并存储文档统计信息
- 使文档可用于查询
-
查询及检索
- 用户通过
query_documentationMCP工具发送查询 - 系统将查询转换为向量嵌入
- 执行相似性搜索以找到相关块
- 返回带来源信息的格式化结果
- 支持按标签、状态和元数据过滤
- 用户通过
此流水线实现了文档的高效存储、处理和检索，具备语义理解能力。所有步骤都通过作业系统跟踪，允许详细进度监控和错误处理。
项目结构
docmcp/
├── prisma/ # 数据库模式和迁移
│ └── schema.prisma # Prisma模型定义和数据库配置
├── src/
│ ├── config/ # 应用程序配置
│ │ └── database.ts # 数据库连接设置
│ ├── generated/ # 生成的代码（Prisma客户端）
│ ├── services/ # 核心服务模块
│ │ ├── crawler.service.ts # 网站爬取功能
│ │ ├── document.service.ts # 文档管理
│ │ ├── document-processor.service.ts # 文档处理和转换
│ │ ├── job.service.ts # 异步作业管理
│ │ ├── chunk.service.ts # 文档分块和向量操作
│ │ └── mcp-tools/ # MCP集成工具
│ │ ├── add-documentation.tool.ts # 添加新文档的工具
│ │ ├── get-job-status.tool.ts # 检查作业状态的工具
│ │ ├── list-documentation.tool.ts # 列出可用文档的工具
│ │ ├── query-documentation.tool.ts # 查询文档的工具
│ │ ├── sample.tool.ts # 示例工具实现
│ │ └── index.ts # 工具注册和导出
│ ├── types/ # TypeScript类型定义
│ │ └── mcp.ts # MCP工具接口定义
│ ├── utils/ # 实用函数
│ │ ├── logger.ts # 日志实用工具
│ │ └── prisma-filters.ts # 可重用的Prisma过滤模式
│ └── __tests__/ # 测试文件
│ └── utils/ # 测试实用工具
│ └── testDb.ts # 测试数据库设置和拆卸
├── .env # 环境变量
└── package.json # 项目依赖项和脚本