MCP Docs Tools

一个基于Node.js的MCP（模型上下文协议）工具服务器，为Python项目提供三个专注于文档生成的工具。作为npm包构建，可以直接从Git仓库安装。

特性

🔧 三大强大工具

1. create_class_diagram - 分析Python文件并生成PlantUML格式的UML类图
2. create_tree_structure - 创建干净的目录树结构文档，并智能排除不需要的文件
3. create_module_functions - 记录模块级别的函数签名、装饰器和类型提示

🚀 主要优势

• 零配置：开箱即用，具有合理的默认设置
• 智能排除：自动过滤缓存、构建和IDE文件
• 丰富的文档：捕获类型提示、装饰器、文档字符串和继承关系
• MCP集成：通过模型上下文协议无缝集成AI助手
• 混合架构：Node.js编排 + Python AST解析以确保可靠性

安装

从Git仓库安装（推荐）

# 克隆仓库
git clone https://github.com/your-username/mcp-docs-tools.git
cd mcp-docs-tools

# 安装依赖
npm install

# 全局安装（可选）
npm install -g .

# 或者直接运行
npm start

直接从Git安装

# 直接从GitHub安装
npm install -g git+https://github.com/your-username/mcp-docs-tools.git

# 然后运行
mcp-docs-tools

本地开发

git clone https://github.com/your-username/mcp-docs-tools.git
cd m-oc-docs-tools
npm install
npm start

要求

• Node.js ≥18.0.0
• Python 3.x（用于AST解析）
• Git（用于克隆仓库）

Python解释器检测与Windows支持

服务器在运行时会自动检测可用的Python 3解释器。在Windows上，如果可用则优先使用py -3，否则回退到python或python3。在macOS/Linux上，优先使用python3，如果python是Python 3，则回退到python。

如果没有找到Python 3解释器，您将看到一个可操作的错误：

"未找到Python 3解释器。请安装Python 3或设置MCP_PYTHON（以及可选的MCP_PYTHON_ARGS）。尝试过：..."

环境覆盖（可选）

您可以显式指定解释器和参数：

• MCP_PYTHON：命令或绝对路径（例如，py，python3，C:\\Python312\\python.exe）
• MCP_PYTHON_ARGS：空格分隔的参数（例如，-3）

示例：

# Windows PowerShell
$env:MCP_PYTHON = "python"
$env:MCP_PYTHON_ARGS = "-3"
npm start

# macOS/Linux bash
export MCP_PYTHON=py
export MCP_PYTHON_ARGS=-3
npm start

使用方法

作为MCP服务器

启动服务器以通过模型上下文协议暴露工具：

# 如果全局安装
mcp-docs-tools

# 或从项目目录
npm start

# 或直接使用node运行
node bin/server.js

服务器将监听标准输入/输出，并暴露可以由MCP客户端调用的三个工具。

工具规范

1. create_class_diagram

目的：从Python代码生成UML类图

参数：

• project_path（字符串，必需）：要分析的Python项目的根路径

输出：

• 文件：docs/uml.txt
• 格式：PlantUML语法
• 内容：包含公共/私有方法、属性和继承关系的类

示例：

@startuml
class MyClass {
  +public_attr: str
  -_private_attr: int
  --
  +__init__(self, name: str)
  +public_method(self, arg: int): bool
  -{static} _private_method(): None
}
@enduml

2. create_tree_structure

目的：生成项目目录树结构

参数：

• project_path（字符串，必需）：要分析的项目的根路径

输出：

• 文件：docs/tree-structure.txt
• 格式：Unicode框绘树
• 内容：带有智能排除的完整文件/目录结构

示例：

my-project
├── src/
│   ├── main.py
│   └── utils/
│       └── helpers.py
├── tests/
│   └── test_main.py
└── README.md

3. create_module_functions

目的：记录模块级别的函数及其签名

参数：

• project_path（字符串，必需）：要分析的Python项目的根路径

输出：

• 文件：docs/module-functions.txt
• 格式：分层Markdown文档
• 内容：按模块组织的函数，包括完整的签名、装饰器和文档字符串

示例：

## 模块：src.utils.helpers

### `async def process_data(data: List[str], timeout: int = 30) -> Dict[str, Any]`

**装饰器**：
- `@retry(max_attempts=3)`

**描述**：
处理带可选超时的数据列表。

**行号**：42

架构

混合Node.js + Python方法

该工具采用结合了两者优点的混合架构：

• Node.js服务器：处理MCP协议、工具注册和进程编排
• Python脚本：执行健壮的AST解析和文档生成
• 清晰分离：协议处理与解析逻辑分离

项目结构

mcp-docs-tools/
├── package.json              # npm包配置
├── bin/
│   └── server.js             # 主MCP服务器入口点
├── src/
│   ├── server.js             # MCP服务器实现
│   ├── tools/                # 工具实现
│   │   ├── class-diagram.js  # UML生成包装器
│   │   ├── tree-structure.js # 树生成包装器
│   │   └── module-functions.js # 函数文档包装器
│   └── config/
│       └── exclusions.js     # 默认排除模式
├── python/
│   ├── generate_uml.py       # 类的Python AST解析
│   ├── generate_tree.py      # 目录树生成
│   ├── generate_functions.py # 函数解析和文档生成
│   └── requirements.txt      # Python依赖项（无需任何依赖项）
└── README.md

智能排除

这些工具会自动排除不应被文档化的常见文件和目录：

Python

• __pycache__, *.pyc, *.pyo, *.pyd
• build, dist, eggs, *.egg-info
• 虚拟环境：venv, .venv, env, virtualenv

开发工具

• 版本控制：.git, .svn, .hg
• IDE：.idea, .vscode, .cursor
• 测试：.pytest_cache, .coverage, .tox

构建及包管理器

• node_modules, target, out, bin
• package-lock.json, yarn.lock, Pipfile.lock

操作系统及临时文件

• .DS_Store, Thumbs.db, *.tmp, *.log

与AI助手集成

Cursor IDE

配置取决于您如何安装这些工具：

方案A：如果您克隆了仓库（推荐方法）

在您的项目中创建一个.cursorrules文件，并添加到您的Cursor MCP配置中：

{
  "mcpServers": {
    "docs-tools": {
      "command": "node",
      "args": ["/path/to/mcp-docs-tools/bin/server.js"],
      "cwd": "/path/to/mcp-docs-tools"
    }
  }
}

替换/path/to/mcp-docs-tools为您实际克隆仓库的位置。

例如：

• macOS/Linux："/Users/yourname/projects/mcp-docs-tools"
• Windows："C:\\Users\\yourname\\projects\\mcp-docs-tools"

方案B：如果您全局安装了npm install -g

{
  "mcpServers": {
    "docs-tools": {
      "command": "mcp-docs-tools"
    }
  }
}

.cursorrules文件内容（适用于任何安装方法）

在您的Python项目中创建这个.cursorrules文件：

# 文档工具集成

## 可用的MCP工具
- `create_class_diagram` - 生成UML类图
- `create_tree_structure` - 生成目录树
- `create_module_functions` - 记录模块函数

## 使用方法
在会话开始时运行这些工具以在`docs/`目录中生成文档。
参考生成的文件以了解代码库结构。

## 生成的文件
- `docs/uml.txt` - PlantUML类图
- `docs/tree-structure.txt` - 目录结构
- `docs/module-functions.txt` - 函数文档

Claude Desktop

方案A：如果您克隆了仓库（推荐方法）

添加到您的Claude Desktop MCP配置中：

{
  "mcpServers": {
    "docs-tools": {
      "command": "node",
      "args": ["/path/to/mcp-docs-tools/bin/server.js"],
      "cwd": "/path/to/mcp-docs-tools"
    }
  }
}

替换/path/to/mcp-docs-tools为您实际克隆仓库的位置。

方案B：如果您全局安装了npm install -g

{
  "mcpServers": {
    "docs-tools": {
      "command": "mcp-docs-tools"
    }
  }
}

快速设置指南

1. 克隆并安装（推荐）：

   git clone https://github.com/your-username/mcp-docs-tools.git
   cd mcp-docs-tools
   npm install
   

2. 查找您的安装路径：

   pwd
   # 复制此路径用于您的MCP配置
   

3. 更新您的MCP配置，使用步骤2中的路径

4. 测试工具 在您的Python项目中！

错误处理

这些工具包括全面的错误处理：

• Python进程失败：详细的错误消息，包括标准输出/标准错误
• 缺少依赖项：明确的Python安装说明
• 文件权限问题：优雅处理并提供信息性消息
• 无效项目路径：处理前验证路径

性能

• 轻量级：最小内存占用，短暂的Python进程
• 快速：高效的AST解析和智能文件过滤
• 可扩展：处理数千个文件的大代码库
• 并发：多个工具可以同时运行

贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 如适用，添加测试
5. 提交拉取请求

许可证

MIT许可证 - 详情见LICENSE文件。

支持

• 问题：在GitHub上报告错误和功能请求
• 文档：完整的API文档可在仓库中找到
• 示例：示例项目和使用模式在examples目录中

---

为Python开发社区制作 ❤️