MCP Py JSON Doc

🦀 具有知识图谱和FastMCP服务器的Rust文档分析器

一个强大的工具，用于分析Rust JSON文档，提取实体和语义关系，并在本地SQLite知识图中管理它们，以便与FastMCP 2.0集成进行高级分析。通过模型上下文协议将Rust文档无缝连接到Claude等LLM。

✨ 主要特点

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

🚀 快速开始

先决条件

• 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

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

   # Create and activate the virtual environment
   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   # .\venv\Scripts\activate  # Windows

1. 安装依赖项 随着 uv （比pip快）：

   uv pip install -e .

对于开发，请安装其他依赖项：

   uv pip install -e ".[dev]"

📥 导入文档

将JSON文件加载到知识图中

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

uv run python -m src.main 
 -o output [options]

参数：

• `

`：Rust文档JSON文件的路径（必需）

• -o, --output：存储知识图谱数据库的输出目录（默认： output)
• --verbose, -v：启用详细日志记录以进行调试
• --no-kg：跳过将数据加载到知识图谱中（用于测试）
• --no-progress：禁用进度条

示例：

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

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

1. 导入时输出详细信息:

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

1. 导入多个文件 （按顺序运行命令）：

   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 path/to/rust_docs.json -o output

2.启动MCP服务器

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

STDIO传输（用于LLM集成）

PYTHONPATH=. python -c "from src.mcp_server.server import main; main()" --kg-db output/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 output/knowledge_graph.db --transport http --host 0.0.0.0 --port 8000

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

3.MCP客户端集成

MCP服务器与支持模型上下文协议的不断增长的应用程序和平台生态系统兼容：

AI开发环境

• 帆板运动 -内置MCP支持的现代IDE
• 光标 -集成MCP的AI首款代码编辑器
• 泽德 -具有原生MCP功能的高性能编辑器
• 回复 -支持MCP的基于云的开发环境

AI助理

• 克劳德桌面 -Anthropic桌面应用程序与MCP工具集成
• 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. 服务器将可供MCP客户端使用 rust-docs
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 server implementation
│   │   ├── handlers.py    # Request handlers
│   │   ├── tools.py       # Tool definitions
│   │   └── models.py      # Data models
│   └── native_kg/         # Knowledge graph implementation
├── tests/                 # Test files
├── pyproject.toml         # Project configuration
└── README.md              # This file

🤝 贡献

欢迎投稿！请随时提交拉取请求。

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许可证获得许可-请参阅 许可证 文件以获取详细信息。

� FastMCP集成

此项目使用 FastMCP 2.0 实施 模型上下文协议 （MCP），为LLM与Rust文档交互提供了一种标准化的方式。

为什么选择FastMCP 2.0？

FastMCP 2.0比官方MCP SDK具有几个优势：

• 特征：超越核心MCP规范的综合工具包
• 主动维护：定期更新新功能和改进
• 生产就绪：专为在生产环境中部署而设计
• Python API：定义工具的干净、基于装饰器的方法
• 双重运输：支持STDIO和HTTP传输

🙏 致谢

• FastMCP 用于高性能MCP服务器的实现
• 模型上下文协议 用于标准化LLM工具交互
• Rust社区提供令人惊叹的文档工具
• 所有帮助改进此项目的贡献者