MCP Docs Tools

MCP Docs Tools

一个基于 Node.js 的 MCP（Model Context Protocol）工具服务，为 Python 项目提供三种专用文档生成工具。它以 npm 包形式构建，可直接从 Git 仓库安装。

功能

🔧 三种强大的工具

1. create_class_diagram —— 分析 Python 文件并生成 PlantUML 格式的 UML 类图
2. create_tree_structure —— 创建简洁的目录树文档，并智能排除不相关内容
3. create_module_functions —— 记录模块级函数，包括签名、装饰器和类型提示

🚀 主要优势

• 零配置：采用合理的默认设置，开箱即用
• 智能排除：自动过滤缓存、构建和 IDE 文件
• 丰富的文档：记录类型提示、装饰器、文档字符串和继承关系
• MCP 集成：通过 Model Context Protocol 与 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 3，则回退到 python。

如果找不到 Python 3 解释器，你将看到一条可执行的错误提示：

"Python 3 interpreter not found. Install Python 3 or set MCP_PYTHON (and optional MCP_PYTHON_ARGS). Tried: ..."

环境变量覆盖（可选）

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

• 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 服务

启动服务，通过 Model Context Protocol 提供工具：

# If installed globally
mcp-docs-tools

# Or from the project directory
npm start

# Or run directly with node
node bin/server.js

服务将在 stdin/stdout 上监听，并向 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 文档
• 内容：按模块整理的函数，包含完整签名、装饰器和文档字符串

示例：

## 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、*.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 文件：

# 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

选项 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
   # Copy this path for your MCP configuration
   

3. 使用第 2 步中的路径更新 MCP 配置

4. 在 Python 项目中测试这些工具！

错误处理

这些工具包含全面的错误处理机制：

• Python 进程失败：提供包含 stdout/stderr 的详细错误消息
• 缺少依赖项：提供清晰的 Python 安装说明
• 文件权限问题：妥善处理并显示提示信息
• 无效的项目路径：处理前验证路径

性能

• 轻量：Python 进程运行时间短，内存占用极少
• 快速：采用高效的 AST 解析和智能文件筛选
• 可扩展：支持处理包含数千个文件的大型代码库
• 并发：多个工具可以同时运行

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 视情况添加测试
5. 提交拉取请求

许可证

MIT 许可证——详情请参阅 LICENSE 文件。

支持

• 问题：在 GitHub 上报告 Bug 和功能请求
• 文档：仓库中提供完整的 API 文档
• 示例：examples 目录中提供示例项目和用法模式

---

为 Python 开发社区倾心打造 ❤️