🦀 Rust 文档分析器与知识图谱及 FastMCP 服务器

一个强大的工具，用于分析 Rust JSON 文档，提取实体和语义关系，并通过本地 SQLite 知识图谱进行高级分析，集成 FastMCP 2.0。无缝连接您的 Rust 文档到像 Claude 这样的大语言模型（LLMs），通过模型上下文协议。

✨ 主要特性

• 🔍 高级分析 - 自动从 Rust 代码中提取模块、结构体、函数和特征
• 🧠 知识图谱 - 在本地 SQLite 数据库中存储和查询实体之间的关系
• ⚡ FastMCP 2.0 - 具有异步支持的高性能 MCP 服务器实现
• 🤖 双传输 - 支持 STDIO 和 HTTP 传输
• 📊 强大的搜索 - 使用高级过滤器搜索实体，支持多个库
• 🚀 优化性能 - 快速响应时间处理大型代码库
• 🔌 扩展性 - 易于与其他工具和工作流程集成
• 🤝 大语言模型集成 - 无缝集成到 Claude Desktop 和其他兼容 MCP 的大语言模型

🚀 快速开始

前提条件

• Python 3.10+
• uv 包管理器
• Rust（用于构建文档）

📄 生成 Rust 文档 JSON

要分析您的 Rust 项目，您需要先生成 JSON 文档。请参阅 Rustdoc JSON 指南，了解如何从您的 Rust 项目生成所需的 JSON 文件。

安装

1. 克隆仓库

   git clone https://github.com/yourusername/mcp-py-json-doc.git
   cd mcp-py-json-doc
   

2. 设置虚拟环境（推荐）：

   # 创建并激活虚拟环境
   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   # .\venv\Scripts\activate  # Windows
   

3. 安装依赖项 使用 uv（比 pip 更快）：

   uv pip install -e .
   

   对于开发，安装额外的依赖项：

   uv pip install -e ".[dev]"
   

📥 导入文档

将 JSON 文件加载到知识图谱中

要将 Rust 文档 JSON 文件导入知识图谱，请使用以下命令：

uv run python -m src.main <json文件路径> -o 输出目录 [选项]

参数：

• <json文件路径>：指向 Rust 文档 JSON 文件的路径（必需）
• -o, --output：存储知识图谱数据库的输出目录（默认：output）
• --verbose, -v：启用调试的详细日志
• --no-kg：跳过加载数据到知识图谱（用于测试）
• --no-progress：禁用进度条

示例：

1. 基本用法（导入单个文件）：

   uv run python -m src.main doc/serde.json -o output
   

2. 带有详细输出的导入：

   uv run python -m src.main doc/tokio.json -o output --verbose
   

3. 导入多个文件（依次运行命令）：

   uv run python -m src.main doc/serde.json -o output && \
   uv run python -m src.main doc/tokio.json -o output
   

输出：

该命令将在指定的输出目录中创建以下文件：

• knowledge_graph.db：包含所有实体和关系的 SQLite 数据库
• analysis_results.json：导入过程的概要
• full_analysis.json：导入文档的详细分析

注意事项：

• 如果不存在，数据库将会被创建
• 现有数据会被追加到数据库中（使用不同的输出目录以保持数据集分离）
• 对于大型文档文件，导入过程可能需要几分钟

验证导入

导入后，您可以使用交互式浏览器验证知识图谱的内容：

python explore_kg.py output/knowledge_graph.db

这将启动一个交互式 shell，您可以在其中查询导入的数据。

🛠 使用方法

1. 导入 Rust 文档

首先，将 Rust 文档导入知识图谱：

uv run python -m src.main rust_docs.json路径 -o 输出目录

2. 启动 MCP 服务器

您可以以两种不同的传输模式运行 MCP 服务器：

STDIO 传输（用于 LLM 集成）

PYTHONPATH=. python -c "from src.mcp_server.server import main; main()" --kg-db 输出目录/knowledge_graph.db --transport stdio

此模式适用于与 Claude Desktop、Anthropic API 或其他兼容 MCP 的 LLM 客户端集成。

HTTP 传输（用于 API 访问）

PYTHONPATH=. python -c "from src.mcp_server.server import main; main()" --kg-db 输出目录/knowledge_graph.db --transport http --host 0.0.0.0 --port  8000

此模式提供 REST API 接口，用于测试或与 Web 应用程序集成。

3. MCP 客户端集成

MCP 服务器与支持 Model Context Protocol 的应用程序和平台生态系统兼容：

AI 开发环境

• Windsurf - 内置 MCP 支持的现代 IDE
• Cursor - 集成了 MCP 的 AI 首选代码编辑器
• Zed - 具有原生 MCP 能力的高性能编辑器
• Replit - 具有 MCP 支持的基于云的开发环境

AI 助手

• Claude Desktop - Anthropic 的桌面应用，具有 MCP 工具集成
• Claude API - 使用 Claude API 的工具调用功能
• 其他 MCP 客户端 - 实现了 MCP 规范的任何应用程序

配置

大多数 MCP 客户端可以通过向各自的配置文件添加服务器详情来配置。常见位置包括：

• ~/.config/mcp/config.json
• .codeium/windsurf/mcp_config.json
• .kiro/settings/mcp.json

有关详细设置说明，请参阅客户端文档中的 MCP 集成部分。

MCP 客户端配置

要使用此服务器与任何兼容 MCP 的客户端（如 Codeium、Claude 或自定义客户端）配合使用，请在 MCP 客户端的配置文件（通常是 mcp_config.json 或类似名称）中添加以下配置：

{
  "mcpServers": {
    "rust-docs": {
      "command": "/path/to/your/venv/bin/python",
      "args": [
        "/path/to/mcp-py-json-doc/run_mcp_server.py",
        "--kg-db",
        "/path/to/mcp-py-json-doc/output/knowledge_graph.db",
        "--transport",
        "stdio"
      ]
    }
  }
}

本地开发设置示例

{
  "mcpServers": {
    "rust-docs": {
      "command": "/home/username/mcp-py-json-doc/.venv/bin/python",
      "args": [
        "/home/username/mcp-py-json-doc/run_mcp_server.py",
        "--kg-db",
        "/home/username/mcp-py-json-doc/output/knowledge_graph.db",
        "--transport",
        "stdio"
      ]
    }
  }
}

重要注意事项：

1. 更新所有文件路径以匹配系统目录结构
2. 确保 Python 路径指向虚拟环境的 Python 可执行文件
3. 服务器将作为 rust-docs 提供给 MCP 客户端
4. 对于生产部署，考虑使用绝对路径以确保可靠性

4. 可用的 MCP 工具

以下工具可通过 MCP 服务器接口获得，使强大的代码分析和文档检索成为可能：

1. 搜索实体

在 Rust 文档中搜索实体（函数、结构体、特征等）。

参数：

• query：与实体名称匹配的搜索词
• entity_type：（可选）按类型过滤（functions、structs、traits、impls、enums、constants、modules）
• limit：返回的最大结果数（默认：10）

示例：

{
  "query": "Serialize",
  "entity_type": "trait",
  "limit": 5
}

2. 获取实体详情

获取特定实体的全面信息，包括其文档、属性和关系。

参数：

• entity_id：实体的完全限定名（例如，serde::ser::Serialize）

示例：

{
  "entity_id": "serde::ser::Serialize"
}

3. 查找相关实体

发现与指定实体有关系的实体，如实现、定义或依赖。

参数：

• entity_id：源实体的 ID
• relation_type：（可选）关系类型（implements、defines、contains、depends_on）
• depth：遍历的关系层级数（默认：1）

示例：

{
  "entity_id": "serde::ser::Serialize",
  "relation_type": "implements",
  "depth": 2
}

4. 分析特征实现

分析特定特征在整个代码库中的实现情况，包括所有实现类型及其位置。

参数：

• trait_name：要分析的特征名称

示例：

{
  "trait_name": "serde::ser::Serialize"
}

5. 获取模块结构

获取模块的层次结构，展示不同级别的代码组织情况。

参数：

• module_name：（可选）要检查的具体模块名称。如果未提供，则返回完整的模块层次结构。

示例：

{
  "module_name": "serde"
}

6. 搜索文档

在文档中执行语义搜索，包括函数/方法文档和内联代码注释。

参数：

• query：搜索查询字符串
• include_code_examples：（可选）是否在搜索结果中包含代码示例（默认：false）

示例：

{
  "query": "serialization",
  "include_code_examples": true
}

7. 获取图谱统计

获取关于知识图谱的统计数据和指标，包括实体数量、关系类型和数据库指标。

参数： 无

示例：

{}

🔧 开发

项目结构

mcp-py-json-doc/
├── src/
│   ├── mcp_server/
│   │   ├── __init__.py
│   │   ├── server.py      # FastAPI 服务器实现
│   │   ├── handlers.py    # 请求处理器
│   │   ├── tools.py       # 工具定义
│   │   └── models.py      # 数据模型
│   └── native_kg/         # 知识图谱实现
├── tests/                 # 测试文件
├── pyproject.toml         # 项目配置
└── README.md              # 本文档

🤝 贡献

欢迎贡献！请随意提交拉取请求。

1. 分叉仓库
2. 创建您的功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开拉取请求

📄 许可证

本项目采用 MIT 许可证 - 详情见 LICENSE 文件。

� FastMCP 集成

本项目使用 FastMCP 2.0 来实现 Model Context Protocol (MCP)，为 LLM 与 Rust 文档交互提供标准化方式。

为什么选择 FastMCP 2.0？

FastMCP 2.0 相比官方 MCP SDK 具有以下优势：

• 更多功能：超越核心 MCP 规范的综合工具包
• 积极维护：定期更新新特性和改进
• 生产就绪：设计用于生产环境部署
• Pythonic API：清晰的装饰器方式定义工具
• 双传输：支持 STDIO 和 HTTP 传输

🙏 致谢

• FastMCP 提供高性能的 MCP 服务器实现
• Model Context Protocol 标准化 LLM 工具交互
• Rust 社区提供了出色的文档工具
• 所有帮助改进此项目的贡献者