AI导哈

代码文档生成工具

一个Python工具，用于扫描Python代码库，提取API详细信息，并生成开发者友好的Markdown文档，包括模拟的MCP接口以交互式查询代码元素。

  • by Mishail01
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Mishail01/MCP-Doc-Bot

使用说明

MCP开发人员文档机器人

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

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

目录

特性

核心

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

计划的

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

快速演示

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

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

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

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

安装

需求

  • Python 3.8+
  • 点
  1. 克隆
git clone https://github.com/<your-username>/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 <path-to-target-repo> [--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进行模板构建。
  • 受到自动化代码文档和开发人员辅助工具方法的启发。

相关 MCP