MCP开发人员文档机器人
一个Python工具，它扫描Python代码库，提取API详细信息，并在Markdown中生成开发人员友好的文档。它还包括一个模拟的MCP界面，因此您可以就函数、类和模块提出交互式问题，并生成示例对话日志。
此存储库旨在作为参考实现和入门工具包，用于构建由类似MCP的接口驱动的文档助理。
______________________________________________________________________
目录
- 生成文档 - 交互式MCP会话（模拟） - PowerShell交钥匙脚本
______________________________________________________________________
特性
核心
- 存储库扫描：在目标目录中递归查找.py文件。
- 基于AST的解析：提取函数、类、方法签名、参数和文档字符串。
- 文档生成：使用Jinja2模板在Markdown中创建一个项目README和一个详细的API文档。
- 交互式MCP（模拟）：一个简单的CLI服务器，可以回答有关代码元素的问题并记录对话。
计划的
- 依赖关系映射和可视化图形
- 图生成（UML/类图）
- 多语言文档和本地化
- 与Git集成的版本化文档
______________________________________________________________________
快速演示
- 为示例仓库生成文档并检查输出：
- python run.py测试/example_repo - 输出被写入 sample_output/
- 启动模拟MCP交互会话：
- python run_mcp_logging.py - 示例查询：解释（“添加”），解释（“计算器”）
______________________________________________________________________
安装
需求
- Python 3.8+
- 点
- 克隆
git clone https://github.com//mcp-doc-bot.git
cd mcp-doc-bot- （可选）创建并激活虚拟环境
python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1- 安装依赖项
pip install --upgrade pip
pip install -r requirements.txt注意：requirements.txt至少应包括：
- jinja2
如果您使用额外的功能，请添加graphviz、pydot或Sphinx等包。
______________________________________________________________________
用法
生成文档
python run.py
[--out sample_output] [--templates templates/]- 例子：
- python run.py tests/example_repo- 主要输出：
- sample_output/README.md — generated project README
- sample_output/api_docs.md — function/class API docs交互式MCP会话（模拟）
python run_mcp_logging.py- 启动一个CLI循环，接受以下简单命令：
- 解释（“函数名”） - 解释（“模块.ClassName”） - regenerate_doc（）
- 日志保存到
tests/results/mcp_conversation_log.txt（或配置的路径）。
PowerShell交钥匙脚本
- run_bot.ps1一步完成venv创建、依赖项安装、扫描和生成文档的自动化：
.\run_bot.ps1 -TargetPath "tests/example_repo"（调整脚本参数以适应您的环境。）
______________________________________________________________________
项目结构
mcp-doc-bot/
│
├── bot/
│ ├── __init__.py
│ ├── scanner.py # Repository crawler
│ ├── parser.py # AST-based code analysis
│ ├── generator.py # Jinja2-based docs generation
│ ├── mcp_server.py # Mocked MCP interface / CLI
│
├── templates/
│ ├── readme_template.md
│ ├── api_template.md
│
├── sample_output/ # Example generated outputs
│ ├── README.md
│ ├── api_docs.md
│
├── tests/
│ ├── example_repo/ # Small demo repo used for tests
│ │ ├── simple_functions.py
│ │ ├── sample_class.py
│ ├── results/
│ └── mcp_conversation_log.txt
│
├── requirements.txt
├── run.py # CLI entry: generate docs
├── run_mcp_logging.py # Run mocked MCP and write logs
├── run_bot.ps1 # Windows convenience script
└── README_submission.md # Optional submission notes______________________________________________________________________
运作原理
存储库扫描和解析
- scanner.py遍历目标目录并列出Python文件。
- parser.py使用Python的AST模块解析每个文件，提取：
- 函数和方法名称、参数（包括默认值和注释） - 类定义及其方法 - 顶级文档字符串和内联文档字符串
- 解析器输出生成器.py使用的结构化表示（JSON/dict）。
文档生成
- generator.py将Jinja2模板渲染为Markdown：
- 包含项目概述、安装步骤和顶级模块摘要的自述文件。 - API文档列出模块、类、函数、签名和文档字符串。
- 模板存在于模板中/便于定制。
MCP模拟接口
- mcp_server.py是一个简化的类似mcp的CLI服务器：
- 将上次扫描索引加载到内存中。 - 接受类似人类的命令并返回有用的摘要。 - 将会话日志写入tests/results/\*.txt以演示对话。
______________________________________________________________________
输出/示例
- sample_output/README.md
- 项目总结、如何运行以及简短的示例部分。
- sample_output/api_docs.md
- 按模块组织，包括： - 函数签名和文档字符串 - 类定义、构造函数和方法摘要 - 当文档字符串包含示例时的示例用法片段
- 测试/结果/mcpconversation_log.txt
- 显示解释（“添加”）和解释（“计算器”）响应的示例对话
在您的提交中包含这些示例输出，以显示机器人的功能。
______________________________________________________________________
配置和要求
- Python版本：3.8+
- 推荐的软件包（requirements.txt）：
- jinja2 - （可选）graphviz、pydot、sphinx用于高级功能
- 跨平台：Windows、macOS、Linux
- 如果在受限环境（CI）中运行，请提供较小的目标路径以加快扫描速度。
______________________________________________________________________
扩展bot
要添加的想法：
- 图生成：集成graphviz绘制类/模块依赖图。
- Sphinx输出：将生成的Markdown转换为reStructuredText并构建HTML文档。
- Git集成：检测更改，只为修改后的模块重新生成文档。
- 自然语言改进：用实时MCP客户端/SDK替换模拟MCP，以回答更自然的查询。
如果您添加功能，请：
- 在测试中添加测试/
- 更新模板/
- README_submission.md中的文档使用
______________________________________________________________________
贡献
- 分叉回购
- 创建特征分支（特征/你的特征）
- 编写测试和更新文档
- 打开一个描述变化和动机的PR
请保持更改的重点（每个PR一个功能/错误修复），并包括生成文档的示例。
______________________________________________________________________
许可证和联系方式
该项目“按原样”提供，用于教育和原型制作目的，并获得麻省理工学院许可。
作者
沙伊尔
______________________________________________________________________
致谢
- 使用Python的AST模块和Jinja2进行模板构建。
- 受到自动化代码文档和开发人员辅助工具方法的启发。