docMCP (Visheshd)

DocMCP：使用pgvector在PostgreSQL上索引LLM的最新文档，并向AI IDE公开

一个用于抓取、处理和查询文档的系统，具有人工智能驱动的嵌入生成和语义搜索功能。

特性

• 文档爬行：自动抓取具有可自定义深度和速率限制的文档网站
• 内容处理：通过元数据提取将HTML转换为干净的Markdown
• 矢量嵌入：使用AWS Bedrock生成嵌入以进行语义搜索
• 作业管理：通过详细的进度报告跟踪和管理文档处理作业
• MCP集成：用于AI代理集成的内置MCP工具

路线图

• SPA支持：目前爬虫不支持SPA
• 缓存：抓取的网址直接添加到数据库中

入门（开发设置）

先决条件

• Docker(安装指南)
• Docker编写(安装指南)
• Node.js 16+
• Git
• 具有基岩访问权限的AWS帐户
• AWS CLI配置了适当的凭据

快速入门步骤

1. 克隆存储库：

   git clone https://github.com/visheshd/docmcp.git
   cd docmcp

1. 配置环境：

- 复制示例环境文件：

     cp .env.example .env

- 编辑 .env 文件： - 集 DATABASE_URL 向 postgresql://postgres:postgres@localhost:5433/docmcp - 配置AWS基岩： - 集 AWS_REGION 到您的AWS区域（例如。， us-east-1) - 集 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 使用您的AWS凭据 - 或者确保您的AWS CLI配置了适当的凭据 - 调整其他设置，如 LOG_LEVEL 如有需要

1. 启动开发环境：

   # Make the script executable
   chmod +x dev-start.sh

   # Start the development environment
   ./dev-start.sh

此脚本将：

- 在Docker容器中使用pgvector启动PostgreSQL - 安装项目依赖项 - 运行数据库迁移 - 自动导入种子数据 - 数据库将在端口5433上访问

1. 添加文档：

使用 add-docs 用于抓取和处理文档的脚本：

   # Basic usage
   npm run add-docs -- --url https://example.com/docs --max-depth 3

   # With additional options
   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 对于所有选项

1. 查询文档：

添加文档后，您可以使用MCP工具查询它。请参阅下面的“查询文档”部分。

1. 停止开发环境：

   docker-compose -f docker-compose.dev.yml down

此设置提供了一个轻量级的开发环境，仅包含所需的PostgreSQL数据库和预加载的种子数据。对于生产部署，或者如果您更喜欢完全容器化的设置，请参阅下面的“生产Docker设置”部分。

光标设置

要将DocMCP与Cursor IDE一起使用，您需要配置MCP传输。将以下配置添加到光标设置中：

{
    "docmcp-local-stdio": {
      "transport": "stdio",
      "command": "node",
      "args": [
        "/dist/stdio-server.js"
      ],
      "clientInfo": {
        "name": "cursor-client",
        "version": "1.0.0"
      }
    }
}

替换 `` 带有DocMCP安装目录的绝对路径。

例如，如果DocMCP安装在 /home/user/projects/docmcp，您的配置将是：

"args": ["/home/user/projects/docmcp/dist/stdio-server.js"]

添加此配置后，重新启动Cursor以使更改生效。

建筑

该系统由几个核心服务组成：

• 爬虫服务：使用robots.txt支持处理文档网站爬行
• 文档处理服务：处理文档（HTML→Markdown、分块、嵌入）
• 就业服务：通过详细的状态跟踪管理异步处理作业
• Chunk服务：使用矢量搜索功能存储和检索文档块
• MCP工具：用于添加和查询文档的代理友好界面

文档处理管道

DocMCP系统通过以下管道处理文档：

1. 文档输入

- 用户通过以下方式提供URL add_documentation MCP工具 - 系统创建状态为“待定”的作业记录 - 为作业分配标签以进行分类和未来的筛选

1. 网络爬虫 （爬虫服务）

- 爬虫遵守robots.txt限制 - 跟随链接到指定的最大深度 - 捕获HTML内容和元数据 - 创建链接到父作业的文档记录

1. 文档处理 （文档处理服务）

- 清理HTML并转换为结构化Markdown - 提取元数据（包信息、版本、文档类型） - 在文档之间建立父子关系 - 在处理过程中更新作业进度

1. 分块与嵌入 （ChunkService）

- 将文档拆分为语义块，以便更好地检索 - 使用AWS Bedrock生成矢量嵌入 - 使用pgvector扩展在PostgreSQL中存储嵌入 - 保留块元数据和文档引用

1. 工作最终确定 （就业服务）

- 将作业状态更新为“已完成” - 计算和存储文档统计信息 - 使文档可供查询

1. 查询与检索

- 用户通过发送查询 query_documentation MCP工具 - 系统将查询转换为向量嵌入 - 执行相似性搜索以查找相关块 - 返回带有源信息的格式化结果 - 支持按标签、状态和元数据进行筛选

该管道能够高效地存储、处理和检索具有语义理解能力的文档。所有步骤都通过作业系统进行跟踪，允许进行详细的进度监控和错误处理。

项目结构

docmcp/
├── prisma/                  # Database schema and migrations
│   └── schema.prisma        # Prisma model definitions and database configuration
├── src/
│   ├── config/              # Application configuration
│   │   └── database.ts      # Database connection setup
│   ├── generated/           # Generated code (Prisma client)
│   ├── services/            # Core service modules
│   │   ├── crawler.service.ts     # Website crawling functionality
│   │   ├── document.service.ts    # Document management
│   │   ├── document-processor.service.ts # Document processing and transformation
│   │   ├── job.service.ts         # Async job management
│   │   ├── chunk.service.ts       # Document chunking and vector operations
│   │   └── mcp-tools/       # MCP integration tools
│   │       ├── add-documentation.tool.ts    # Tool for adding new documentation
│   │       ├── get-job-status.tool.ts       # Tool for checking job status
│   │       ├── list-documentation.tool.ts   # Tool for listing available documentation
│   │       ├── query-documentation.tool.ts  # Tool for querying documentation
│   │       ├── sample.tool.ts               # Example tool implementation
│   │       └── index.ts                     # Tool registry and exports
│   ├── types/               # TypeScript type definitions
│   │   └── mcp.ts           # MCP tool interface definitions
│   ├── utils/               # Utility functions
│   │   ├── logger.ts        # Logging utilities
│   │   └── prisma-filters.ts # Reusable Prisma filtering patterns
│   └── __tests__/           # Test files
│       └── utils/           # Test utilities
│           └── testDb.ts    # Test database setup and teardown
├── .env                     # Environment variables
└── package.json             # Project dependencies and scripts