AI导哈

文档索引与语义搜索系统

一个用于爬取、处理和查询文档的系统，具有AI驱动的嵌入生成和语义搜索功能，适用于开发者和AI集成环境。

  • by visheshd
  • TypeScript
  • 本地部署
  • 9 星标
  • 更新于
在 GitHub 查看 visheshd/docmcp

使用说明

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

  2. 配置环境：

    • 复制示例环境文件：
      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 如有需要

  3. 启动开发环境：

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

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

    此脚本将：

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

  4. 添加文档： 使用 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 对于所有选项

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

  6. 停止开发环境：

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

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

光标设置

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

{
    "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以使更改生效。

建筑

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

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

文档处理管道

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

  1. 文档输入

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

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

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

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

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

  4. 分块与嵌入 （ChunkService）

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

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

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

  6. 查询与检索

    • 用户通过发送查询 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

相关 MCP