McpDoc

AgentDoc

AgentDoc（原名 C4-Agent）是一种 MCP 服务实现，旨在为现有系统生成文档。它提供了一组 MCP 提示词和工具，用于生成代码摘要和基于 Mermaid.js 的 C4 架构图。

深入了解 MCP。 深入了解 C4。

这些提示词会引导模型遍历系统的目录树，在遍历过程中生成摘要文档，最后将摘要逐级汇总到顶层。

1. 对于每个包含“源代码”的目录（你可以通过调整提示词来决定如何定义），生成一个 README.C4Diagrammer.md 文件。 其理念是，任何需要自动生成文档的代码仓库都可能大到无法放入上下文窗口，因此需要“预先存储”比源代码信息密度更高的摘要。提示词会引导模型检查文件时间戳，以便仅在需要时重新生成摘要。

2. 在每个 README.C4Diagrammer.md 旁边，我们都会生成一张 C4Component 图，用于展示该目录中源代码模块的结构。

3. 最后，我们会将所有 README.C4Diagrammer.md 文件汇总为根目录中的一张 C4Context 图和一张 C4Container 图，作为概览。原则上，你可以从根目录的概览图一路向下浏览，逐级查看每个包含源代码的子目录中的图。

我们采用 C4 模型，因为它旨在通过提供“恰到好处”的文档来适应现代敏捷实践。C4 方法强调轻量、持续更新的文档，让文档随着代码库一同演进，避免文档随时间推移变得过时或无关紧要这一常见问题（即“文档腐化”）。C4 通过聚焦于不同详细程度下的关键架构视图，帮助团队维护实用的文档，同时避免传统文档方法常见的繁重维护负担。

这个理念旨在解决一个广受关注的问题：遗留代码库十分复杂，新开发者需要花费大量时间熟悉；开发者难以确定应该在哪里进行修改；团队以外的人则完全不了解系统的情况。如果你能自动生成覆盖系统从顶层到底层的文档，就更有机会帮助新人快速上手，也能帮助所有人了解和浏览系统。

今后，你可以在 IDE 中运行这些工具，检查并调整输出，然后就大功告成了：你为后来者争取到了更好的机会。

C4 图架构

C4 模型是一种分层的软件架构文档方法，由四个层级的图组成：

1. 上下文图 —— 最高层级的视图，展示软件系统如何与用户及其他系统交互。此图有助于利益相关方和非技术受众了解整体情况。

2. 容器图 —— 聚焦展示软件系统的高层技术构建模块。容器代表协同提供功能的应用程序、数据存储、微服务等。

3. 组件图 —— 展示各个容器内部关键逻辑组件及其交互的详细视图。这有助于开发者了解容器的内部结构。

4. 部署图 —— 展示软件系统如何部署到基础设施中，包括技术、硬件和部署环境的详细信息。

每个层级都会逐步增加细节，同时遵循一致的表示法。C4 方法通过为不同受众展示恰当的细节层级来帮助保持清晰度，无论受众是高层利益相关方，还是负责特定组件的开发者。

深入了解 C4。

示例

以下是使用 MCP Typescript SDK 运行这些提示词的示例：

C4Context
    title Model Context Protocol (MCP) System Architecture

    Person(developer, "Developer", "Uses MCP tools and services")
    Person(end_user, "End User", "Interacts with applications built using MCP")

    System_Boundary(mcp, "Model Context Protocol (MCP)") {

        System(sdk, "MCP SDK", "Development kit for building applications using MCP")
        System(everything, "Everything Server", "Comprehensive server with various MCP features")
        
        System_Boundary(data_storage, "Data Storage") {
            System(filesystem, "Filesystem Server", "File operations with security measures")
            System(memory, "Memory Server", "Knowledge Graph-based memory system")
            System(postgres, "PostgreSQL Server", "Database access and querying")
            System(redis, "Redis Server", "Key-value store operations")
            System(sqlite, "SQLite Server", "Database operations and business insights")
        }
        
        System_Boundary(external_integrations, "External Service Integrations") {
            System(aws_kb, "AWS KB Retrieval", "AWS Bedrock Knowledge Base retrieval")
            System(brave_search, "Brave Search", "Web and local search capabilities")
            System(everart, "EverArt", "AI image generation")
            System(gdrive, "Google Drive", "Google Drive file access")
            System(github, "GitHub", "Repository and issue management")
            System(gitlab, "GitLab", "Project and merge request management")
            System(google_maps, "Google Maps", "Location-based services")
            System(puppeteer, "Puppeteer", "Browser automation")
            System(sentry, "Sentry", "Error tracking and analysis")
            System(slack, "Slack", "Workspace communication")
            System(time, "Time", "Timezone operations and conversions")
        }
        
        System(sequential_thinking, "Sequential Thinking", "Structured problem-solving framework")
    }

    System_Ext(aws_system, "AWS Bedrock", "AI models and knowledge base")
    System_Ext(brave_system, "Brave Search API", "Web search engine")
    System_Ext(everart_system, "EverArt API", "Image generation service")
    System_Ext(gdrive_system, "Google Drive API", "Cloud storage service")
    System_Ext(github_system, "GitHub API", "Code repository hosting")
    System_Ext(gitlab_system, "GitLab API", "Code repository hosting")
    System_Ext(gmaps_system, "Google Maps API", "Mapping and location services")
    System_Ext(sentry_system, "Sentry API", "Error tracking platform")
    System_Ext(slack_system, "Slack API", "Team communication platform")
      
    Rel(developer, sdk, "Builds apps with")      
    Rel(end_user, developer, "Interacts with apps created by")

    Rel(aws_kb, aws_system, "Retrieves data from")
    Rel(brave_search, brave_system, "Searches using")
    Rel(everart, everart_system, "Generates images using")
    Rel(gdrive, gdrive_system, "Accesses files on")
    Rel(github, github_system, "Manages repositories on")
    Rel(gitlab, gitlab_system, "Manages projects on")
    Rel(google_maps, gmaps_system, "Gets location data from")
    Rel(sentry, sentry_system, "Tracks errors using")
    Rel(slack, slack_system, "Communicates through")
    
    Rel(everything, sequential_thinking, "Uses for structured problem solving")
    Rel(everything, filesystem, "Uses for file operations")
    Rel(everything, memory, "Uses for knowledge storage")
    Rel(everything, postgres, "Uses for SQL database operations")
    Rel(everything, redis, "Uses for key-value storage")
    Rel(everything, sqlite, "Uses for embedded database operations")
    
    Rel(everything, aws_kb, "Uses for knowledge retrieval")
    Rel(everything, brave_search, "Uses for web search")
    Rel(everything, everart, "Uses for image generation")
    Rel(everything, gdrive, "Uses for cloud storage")
    Rel(everything, github, "Uses for code management")
    Rel(everything, gitlab, "Uses for code management")
    Rel(everything, google_maps, "Uses for location services")
    Rel(everything, puppeteer, "Uses for web automation")
    Rel(everything, sentry, "Uses for error tracking")
    Rel(everything, slack, "Uses for team communication")
    Rel(everything, time, "Uses for time operations")    

效果还不错。它找出了所有主要组件，并正确地将它们关联起来。依我之见，如果你有一百万行 VB 代码，却不知道该从哪里着手，这类东西会很有用。

这是另一个示例——这次是 C4-Agent 为自己绘制的图：

C4Container
    title Container diagram for C4-Agent Documentation Generator
    
    Person(developer, "Software Developer", "Uses C4-Agent to generate documentation")
    Person(maintainer, "Project Maintainer", "Maintains and extends C4-Agent")
    
    System_Boundary(C4Agent, "C4-Agent Documentation Generator") {
        Container(mcp_server, "MCP Server", "TypeScript, Node.js", "Model Context Protocol server handling client requests")
        Container(doc_generator, "Documentation Generator", "TypeScript", "Generates README and C4 documentation from source code")
        Container(mermaid_engine, "Mermaid Engine", "TypeScript", "Processes and validates Mermaid diagrams")
        Container(file_handler, "File Handler", "TypeScript, Node.js", "Manages file system operations and timestamps")
        Container(prompt_manager, "Prompt Manager", "TypeScript", "Manages and expands documentation generation prompts")
        Container(type_system, "Type System", "TypeScript", "Core types and interfaces for the application")
    }
    
    System_Ext(mermaidjs, "Mermaid.js", "External diagram rendering library")
    System_Ext(vscode, "Visual Studio Code", "IDE integration")
    System_Ext(browser, "Web Browser", "Diagram preview")
    System_Ext(filesystem, "File System", "Source code and documentation storage")
    
    Rel(developer, mcp_server, "Sends requests", "HTTP/WebSocket")
    Rel(maintainer, mcp_server, "Maintains", "Development and testing")
    
    Rel(mcp_server, doc_generator, "Delegates", "Documentation tasks")
    Rel(mcp_server, prompt_manager, "Uses", "Get prompts")
    Rel(doc_generator, mermaid_engine, "Uses", "Generate diagrams")
    Rel(doc_generator, file_handler, "Uses", "Read/Write files")
    Rel(mermaid_engine, mermaidjs, "Uses", "Render diagrams")
    Rel(file_handler, filesystem, "Reads/Writes", "Files")
    Rel(mermaid_engine, browser, "Previews via", "HTML")
    Rel(mcp_server, vscode, "Integrates with", "Extension API")
    
    Rel_Back(type_system, mcp_server, "Provides types", "TypeScript interfaces")
    Rel_Back(type_system, doc_generator, "Provides types", "TypeScript interfaces")
    Rel_Back(type_system, mermaid_engine, "Provides types", "TypeScript interfaces")
    Rel_Back(type_system, file_handler, "Provides types", "TypeScript interfaces")
    Rel_Back(type_system, prompt_manager, "Provides types", "TypeScript interfaces")

功能

• 文档工具

  • README 生成能力——提供一个提示词，配合 MCP 文件系统工具使用时，可在模型找到源代码的每个目录中生成一个 README.C4Diagrammer.md。
  • C4 图生成——提供一个提示词，配合 MCP 文件系统工具使用时，可在模型找到源代码的每个目录中生成一个 C4Component.C4Diagrammer.md。
  • 汇总 C4 图生成——提供一个提示词，配合 MCP 文件系统工具使用时，可根据模型在目录系统中找到的每个 README.C4Diagrammer.md 文件的内容，生成一张“总览” C4Context 或 C4Container 图。

• Mermaid 支持

  • 提供各种工具，帮助验证并提升生成的 Mermaid.js 图表质量
  • 基于浏览器的预览功能

架构

C4-Agent 采用模块化架构，旨在实现可扩展性和易维护性。如上方的 C4 容器图所示，系统由几个关键组件构成：

核心组件

• 服务核心：主要入口和请求路由器，实现了 Model Context Protocol。它负责初始化服务、注册功能，并通过 MCP SDK 管理通信。

• 提示词管理器：负责文档生成提示词的注册和处理，包括 README 文件、组件级 C4 图和系统级 C4 图的提示词。

• 函数处理器：负责管理工具注册，并处理 Mermaid 图操作的函数调用。它负责协调不同工具，并验证输入和输出。

图表处理组件

• Mermaid 解析器：验证并解析 Mermaid.js 图表语法，确保生成的图表在保存或预览前语法正确。

• 预览生成器：创建基于 HTML 的 Mermaid 图表预览，可在 Web 浏览器中查看。

• 图表验证器：专门验证 C4 图类型和格式，确保其符合 C4 模型规范。

1. 开发者通过 MCP 协议与服务核心交互
2. 请求被路由到提示词管理器或函数处理器
3. 生成的图表通过 Mermaid 解析器和图表验证器进行验证
4. 有效图表可通过预览生成器进行预览
5. 结果通过服务核心返回给开发者

提示词

请注意，这些提示词已使用 Claude Sonnet 3.5（来自 Cursor）和 Claude Opus 3.7（来自 Claude Desktop）进行了大量测试。总体而言，这两种模型都能生成相当不错的图表。在使用 OpenAI GPT40 和 Gemini 1.5 测试此软件的早期版本时，错误率要高得多，因此提示词写得更详细。实际效果可能因人而异。

我个人只会将它用于 Claude 系列模型，它们在代码生成方面似乎处于业界领先水平，而 Mermaid.js Markdown 是代码生成中的一个小众子领域。

1. 为每个包含源代码的目录生成文档：

Use the filesystem tool to list all subdirectories of {RootDirectory}. Ignore any 'node_modules' subdirectories. Then recursively list the contents of each other subdirectory (apart from any 'node_modules' subdirectories) for typescript files. If the subdirectory contains one or more typescript files, call the mcp_documenter tool 'should_regenerate_readme' to see if the README file should be regenerated. If the README file should be regenerated, then read every typescript file in the subdirectory, and create a 50 word summary of the file in markdown format intended to brief new developers on its content. Accumulate all the summaries and write a concatenated summary into a file named README.C4Diagrammer.md in the same subdirectory, giving an absolute path to the tool.

2. 为每个包含源代码的目录生成一张 C4Component 图：

Use the filesystem tool to list all subdirectories of ${RootDirectory}. Ignore the node_modules subdirectory. Then recursively seach each other subdirectory. If the subdirectory contains a file README.C4Diagrammer.md, then read the contents of the file. and generate a C4Component Mermaid.js diagram from the contents. Use the provided tools to parse and validate the generated diagram, and if it is valid, generate a preview, and write the markdown to a file named C4Component.C4Diagrammer.md in the same subdirectory, giving an absolute path to the tool.

Your chain of thought:
1) Use C4Component for the diagram type (avoid C4_Component, PlantUML syntax, or any unrecognized element)
2) Identify the primary users and the main system elements
3) If you see any non-standard C4 elements, convert them to valid Mermaid C4 elements like Person, Container, or System
4) Group related nodes in System_Boundary blocks if appropriate
5) Use System_Ext for external systems or services
6) Only create relationships ('Rel()') between valid elements — refer to components by ID (not just strings). Only use 'Rel', not 'Rel_Neighbor'. Link to nodes directly, not to System_Boundary() groups.
7) Output only valid Mermaid code — no extra commentary or text —  which supports built-in rendering in markdown environments
8) Verify there are no lexical or syntax errors. If the markdown is not valid mermaid.js, try to diagnose the error using the parse tool and try again    

根据我的经验，Claude 并不太需要“思维链”。不过，它似乎无伤大雅；而在本文撰写时（2025 年 3 月），Gemini 或 OpenAI GPT4o 确实需要它们，才能生成语法正确的模型。

3. 为每个包含源代码的目录生成一张 C4Component 图：

Use the filesystem tool to list all subdirectories of ${RootDirectory}. Ignore the node_modules subdirectory. Then recursively search each other subdirectory for a file named README.C4Diagrammer.md. Concatenate the contents of all these files, and generate a ${C4Type} Mermaid.js diagram from the contexts. Use the provided tools to parse and validate the generated diagram, and if it is valid, generate a preview, and write the markdown to a file named ${C4Type}.C4Diagrammer.md in the directory ${RootDirectory}.

Your chain of thought:
1) Use ${C4Type} for the diagram type (avoid C4_Component, PlantUML syntax, or any unrecognized element).
2) Identify the primary user(s) and the main system element(s).
3) If you see any non-standard C4 elements, convert them to valid Mermaid C4 elements like Person(), Container(), or System().
4) Group related nodes in System_Boundary() blocks if appropriate.
5) Use System_Ext() for external systems or services.
6) Only create relationships ('Rel()') between valid elements — refer to components by ID (not just strings). Only use 'Rel', not 'Rel_Neighbor'. Link to nodes directly, not to System_Boundary() groups.
7) Output only valid Mermaid code — no extra commentary or text —  which supports built-in rendering in markdown environments.
8) Verify there are no lexical or syntax errors. If the markdown is not valid mermaid.js, try to diagnose the error using the parse tool and try again.

同样的说明也适用于“思维链”。

安装

1. 克隆仓库：

   git clone https://github.com/jonverrier/AgentDoc.git
   cd AgentDoc
   

2. 安装依赖。MCP 服务使用 @jonverrier/prompt-repository（并间接依赖 @jonverrier/assistant-common）。这两个包均发布在 GitHub Packages 上。

   选项 A – 从 GitHub Packages 安装（独立安装）：

   项目包含一个 .npmrc，用于将 @jonverrier 作用域配置为使用 GitHub Packages。请将 NODE_AUTH_TOKEN 设置为具有 read:packages 权限范围的 GitHub Personal Access Token（参见 GitHub Packages 身份验证）。

   若要独立安装（本地没有 PromptRepository 仓库），请将 package.json 中的 prompt-repository devDependency 替换为：

   "prompt-repository": "npm:@jonverrier/prompt-repository@^0.3.15"
   

   然后运行：

   npm install
   

   @jonverrier/prompt-repository 和 @jonverrier/assistant-common（间接依赖）均已在 GitHub Packages 上公开发布。

   选项 B – 本地 monorepo（StrongAI）：

   在 StrongAI monorepo 中与 PromptRepository 一同开发时，install 脚本会链接本地包：

   npm run install
   

   这会运行 npm install ../PromptRepository，以使用本地 PromptRepository。

3. 构建项目：

   npm run build
   

测试

项目包含使用 Mocha 编写的单元测试。

npm run test

使用

若要从宿主使用 MCP 服务，需要更新 AI 开发环境。下方列出了常见的配置设置。第二个参数会将文件系统访问限制在指定目录及其下的所有内容。

{
  "mcpServers": {
    "AgentDoc": {
      "command": "node",
      "args": ["YourCodeRoot/AgentDoc/dist/src/index.js", "YourCodeRoot"]
    }
  }
} 

有关特定 IDE 的设置说明，请参阅：

• Cursor：https://docs.cursor.com/context/model-context-protocol
• Claude：https://modelcontextprotocol.io/quickstart/user

相关项目

• AutoDoc（@jonverrier/auto-doc）– 用于批量生成 C4 文档的自动化 CLI 兄弟项目。从 @jonverrier/c4-diagrammer 升级时，请参阅 MIGRATION.md。

文档

通过“dogfooding”生成 - C4-Agent 在每个子目录中生成了 README.C4Diagrammer.md 和 C4Component.C4Diagrammer.md，并在根目录中生成了主 C4Context 和 C4Container。

• ./C4Context.C4Diagrammer.md - 概览 C4Context 图
• ./C4Container.C4Diagrammer.md - 概览 C4Container 图
• src/README.C4Diagrammer.md - 源代码文档
• src/C4Component.C4Diagrammer.md - 源代码组件图
• test/README.C4Diagrammer.md - 测试套件文档
• test/C4Component.C4Diagrammer.md - 测试套件组件图

问题

最需要改进的方面是解析和验证图表，以便在模型出现语法错误时向其提供反馈。事实证明，很难通过编程方式从 Mermaid.js 获取错误消息。目前我们使用 Selenium 启动一个实时浏览器，这似乎能够正确检测语法错误是否存在，但无法提供任何诊断信息。于是模型只能盲目尝试修正生成的代码。

到目前为止，这些提示词只在 TypeScript 和 Python 上运行过。

如提示词中所述，这种方法只在使用 Claude Sonnet 3.5（Cursor）和 Claude Opus 3.7（Claude Desktop）处理具有一定规模的仓库时经过了充分测试。其他模型在成功生成可用图表方面表现较差，处理更复杂的仓库时也会失败。所有模型都能可靠地生成可用的代码摘要。

贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 创建 Pull Request

许可证

MIT