使用说明
MCP 文档工具
一个基于Node.js的MCP（模型上下文协议）工具服务器，为Python项目提供三个专注于文档生成的工具。它作为一个npm包构建，可以直接从Git仓库安装。
特点/特性
🔧 三款强大工具
create_class_diagram- 分析Python文件并生成PlantUML格式的UML类图create_tree_structure- 创建带有智能排除功能的清晰目录树结构文档create_module_functions- 为模块级函数添加签名、装饰器和类型提示的文档
🚀 核心优势
- 零配置开箱即用，具备合理的默认设置
- 智能排除自动过滤掉缓存、构建和IDE文件
- 丰富的文档资料捕获类型提示、装饰器、文档字符串和继承关系
- MCP集成通过模型上下文协议与AI助手无缝集成
- 混合架构Node.js编排 + Python AST解析以确保可靠性
安装
从Git仓库获取（推荐）
# Clone the repository
git clone https://github.com/your-username/mcp-docs-tools.git
cd mcp-docs-tools
# Install dependencies
npm install
# Install globally (optional)
npm install -g .
# Or run directly
npm start
直接从Git安装
# Install directly from GitHub
npm install -g git+https://github.com/your-username/mcp-docs-tools.git
# Then run
mcp-docs-tools
本地开发
git clone https://github.com/your-username/mcp-docs-tools.git
cd mcp-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 如果它们解析为 Python 3。在 macOS/Linux 上，它更倾向于 python3，然后回落到 python 如果是 Python 3 的话。
如果未找到 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服务器
启动服务器以通过模型上下文协议暴露工具：
# If installed globally
mcp-docs-tools
# Or from the project directory
npm start
# Or run directly with node
node bin/server.js
服务器将在标准输入/输出上监听，并提供三个工具供MCP客户端调用。
工具规格
1. 创建类图
目的从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. 创建树结构
目的生成项目目录树结构
参数:
project_path（字符串，必填）：要分析的项目的根路径
输出：
- 文件：
docs/tree-structure.txt - 格式：Unicode框线绘制树形图
- 内容：包含智能排除功能的完整文件/目录结构
示例：
my-project
├── src/
│ ├── main.py
│ └── utils/
│ └── helpers.py
├── tests/
│ └── test_main.py
└── README.md
3. 创建模块函数
目的记录模块级函数和签名
参数:
project_path（字符串，必填）：要分析的Python项目的根路径
输出:
- 文件：
docs/module-functions.txt - 格式：层次结构的Markdown文档
- 内容：按模块组织的函数，包含完整签名、装饰器和文档字符串
示例：
## Module: src.utils.helpers
### `async def process_data(data: List[str], timeout: int = 30) -> Dict[str, Any]`
**Decorators:**
- `@retry(max_attempts=3)`
**Description:**
Process a list of data items with optional timeout.
**Line:** 42
建筑学
Node.js + Python 混合方法
该工具采用了一种混合架构，结合了两种方案的最佳特性：
- Node.js 服务器处理MCP协议、工具注册和流程编排
- Python 脚本执行稳健的AST（抽象语法树）解析和文档生成
- 干净分离协议处理与解析逻辑分离
项目结构
mcp-docs-tools/
├── package.json # npm package configuration
├── bin/
│ └── server.js # Main MCP server entry point
├── src/
│ ├── server.js # MCP server implementation
│ ├── tools/ # Tool implementations
│ │ ├── class-diagram.js # UML generation wrapper
│ │ ├── tree-structure.js # Tree generation wrapper
│ │ └── module-functions.js # Function docs wrapper
│ └── config/
│ └── exclusions.js # Default exclusion patterns
├── python/
│ ├── generate_uml.py # Python AST parsing for classes
│ ├── generate_tree.py # Directory tree generation
│ ├── generate_functions.py # Function parsing and documentation
│ └── requirements.txt # Python dependencies (none needed)
└── README.md
智能排除
这些工具会自动排除不应被记录的常见文件和目录：
python
__pycache__，*.pyc，*.pyo，*.pydbuild，dist，eggs，*.egg-info- 虚拟环境：
venv，.venv，env，virtualenv
开发工具
- 版本控制：
.git，.svn，.hg - 集成开发环境（IDEs）：
.idea，.vscode，.cursor - 测试：
.pytest_cache，.coverage，.tox
构建与包管理器
node_modules，target，out，binpackage-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项目中创建文件：
# Documentation Tools Integration
## Available MCP Tools
- `create_class_diagram` - Generate UML class diagrams
- `create_tree_structure` - Generate directory tree
- `create_module_functions` - Document module functions
## Usage
Run these tools at session start to generate documentation in `docs/` directory.
Reference the generated files to understand codebase structure.
## Generated Files
- `docs/uml.txt` - PlantUML class diagrams
- `docs/tree-structure.txt` - Directory structure
- `docs/module-functions.txt` - Function documentation
Claude Desktop（中文可译为“Claude桌面版”或根据具体语境简化为“Claude桌面”）
选项A：如果您已克隆了仓库（推荐方法）
在您的Claude桌面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"
}
}
}
快速设置指南
-
克隆并安装 （推荐）：
git clone https://github.com/your-username/mcp-docs-tools.git cd mcp-docs-tools npm install -
找到您的安装路径：
pwd # Copy this path for your MCP configuration -
更新您的MCP配置 使用步骤2中的路径
-
测试工具 在你的Python项目中！
错误处理
这些工具包括全面的错误处理功能：
- Python 进程失败带有 stdout/stderr 的详细错误信息
- 缺少依赖项清晰的Python安装指南
- 文件权限问题优雅处理，信息丰富
- 无效的项目路径处理前进行路径验证
演出
- 轻便的使用短生命周期的Python进程，实现最小内存占用
- 快速高效的AST解析，结合智能文件过滤
- 可扩展的处理包含数千个文件的大型代码库
- 同时发生的；并发的多个工具可以同时运行
贡献；做出贡献
- 克隆该仓库
- 创建一个特性分支
- 做出你的更改
- 如适用，请添加测试
- 提交拉取请求
许可证
MIT 许可证 - 详见 LICENSE 文件。
支持
- 问题在GitHub上报告错误和功能请求
- 文档完整API文档可在代码库中查看
- 示例示例目录中的样本项目和使用模式
为Python开发社区倾心打造
