MCP Doc Bot

MCP开发人员文档机器人

一个Python工具，它扫描Python代码库，提取API详细信息，并在Markdown中生成开发人员友好的文档。它还包括一个模拟的MCP界面，因此您可以就函数、类和模块提出交互式问题，并生成示例对话日志。

此存储库旨在作为参考实现和入门工具包，用于构建由类似MCP的接口驱动的文档助理。

______________________________________________________________________

目录

• 特性
• 快速演示
• 安装
• 用法

- 生成文档 - 交互式MCP会话（模拟） - PowerShell交钥匙脚本

• 项目结构
• 运作原理

- 存储库扫描和解析 - 文档生成 - MCP模拟接口

• 输出/示例
• 配置和要求
• 扩展bot
• 贡献
• 许可证和联系方式

______________________________________________________________________

特性

核心

• 存储库扫描：在目标目录中递归查找.py文件。
• 基于AST的解析：提取函数、类、方法签名、参数和文档字符串。
• 文档生成：使用Jinja2模板在Markdown中创建一个项目README和一个详细的API文档。
• 交互式MCP（模拟）：一个简单的CLI服务器，可以回答有关代码元素的问题并记录对话。

计划的

• 依赖关系映射和可视化图形
• 图生成（UML/类图）
• 多语言文档和本地化
• 与Git集成的版本化文档

______________________________________________________________________

快速演示

1. 为示例仓库生成文档并检查输出：

- python run.py测试/example_repo - 输出被写入 sample_output/

1. 启动模拟MCP交互会话：

- python run_mcp_logging.py - 示例查询：解释（“添加”），解释（“计算器”）

______________________________________________________________________

安装

需求

• Python 3.8+
• 点

1. 克隆

git clone https://github.com//mcp-doc-bot.git
cd mcp-doc-bot

1. （可选）创建并激活虚拟环境

python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1

1. 安装依赖项

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中的文档使用

______________________________________________________________________

贡献

1. 分叉回购
2. 创建特征分支（特征/你的特征）
3. 编写测试和更新文档
4. 打开一个描述变化和动机的PR

请保持更改的重点（每个PR一个功能/错误修复），并包括生成文档的示例。

______________________________________________________________________

许可证和联系方式

该项目“按原样”提供，用于教育和原型制作目的，并获得麻省理工学院许可。

作者

沙伊尔

______________________________________________________________________

致谢

• 使用Python的AST模块和Jinja2进行模板构建。
• 受到自动化代码文档和开发人员辅助工具方法的启发。