McpDoc

AgentDoc

AgentDoc（以前の名称は C4-Agent）は、既存のシステムのドキュメントを生成するために設計された、Model Context Protocol（MCP）サーバーの実装です。Mermaid.js を使用してコードの概要と C4 アーキテクチャ図を生成するための、MCP プロンプトとツールのセットを提供します。

MCP の詳細はこちら。 C4 の詳細はこちら。

プロンプトは、モデルにシステムのディレクトリツリーをたどりながら概要ドキュメントを作成し、最後にそれらを最上位へと集約するよう指示します。

1. 「ソースコード」を含む各ディレクトリについて（何をソースコードとするかは、プロンプトを調整して決められます）、README.C4Diagrammer.md ファイルを生成します。 自動ドキュメント生成が必要なリポジトリは、コンテキストウィンドウに収まらないほど大きい可能性が高いため、ソースよりも情報密度の高い概要を「事前に保存」しておく必要がある、という考え方です。プロンプトはファイルのタイムスタンプを確認し、必要な場合にのみ概要を再生成するようモデルに指示します。

2. 各 README.C4Diagrammer.md とともに、ディレクトリ内のソースモジュールの構造を示す C4Component 図を生成します。

3. 最後に、すべての README.C4Diagrammer.md ファイルをルートディレクトリの C4Context 図と C4Container 図に集約し、概要を示します。 原則として、ルートディレクトリの概要図から、ソースコードを含む各サブディレクトリの中間図まで、すべてたどることができます。

C4 モデルを採用しているのは、「必要十分な」ドキュメントを提供することで、現代のアジャイル開発手法に適合することを目指しているためです。C4 のアプローチでは、コードベースとともに進化する軽量で継続的なドキュメントを重視し、ドキュメントが時間とともに古くなったり、役に立たなくなったりするというよくある問題（「ドキュメントの腐敗」）を避けます。異なる詳細レベルで重要なアーキテクチャの視点に焦点を当てることで、従来のドキュメント作成でありがちな過剰な保守負担を生じさせずに、チームが役立つドキュメントを維持できるようにします。

この取り組みは、レガシーコードベースが複雑で、新しい開発者のオンボーディングに時間がかかること、開発者が変更箇所を見つけにくいこと、チーム外の人には何が起きているのか分からないことという、広く認識されている問題を解決することを目的としています。システムの最上位から最下位までを網羅するドキュメントを自動生成できれば、メンバーをすばやくオンボーディングし、誰もがシステム内を把握しやすくなる可能性が大きく高まります。

今後は、IDE 内からツールを実行し、出力を確認して調整すれば、後に続く人たちのために、少しでも良い環境を整えるという仕事を成し遂げられます。

C4 図のアーキテクチャ

C4 モデルは、ソフトウェアアーキテクチャをドキュメント化するための階層的なアプローチで、4 つのレベルの図で構成されます。

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 図の構文を検証して解析します。これにより、生成された図が保存またはプレビューされる前に、構文的に正しいことを確認できます。

• プレビュー生成ツール：Web ブラウザーで表示できる、Mermaid 図の HTML ベースのプレビューを作成します。

• 図のバリデーター：特に 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 からインストール（単独インストール）：

   このプロジェクトには、@jonverrier スコープを GitHub Packages 用に設定する .npmrc が含まれています。read:packages スコープを持つ GitHub Personal Access Token を使用して NODE_AUTH_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 – ローカルモノレポ（StrongAI）：

   StrongAI モノレポで PromptRepository と並行して開発する場合、install スクリプトがローカルパッケージをリンクします。

   npm run install
   

   これにより npm install ../PromptRepository が実行され、ローカルの PromptRepository が使用されます。

3. プロジェクトをビルドします。

   npm run build
   

テスト

このプロジェクトには、Mocha で作成されたユニットテストが含まれています。

npm run test

使用方法

ホストから MCP サーバーを使用するには、AI 開発環境を更新する必要があります。一般的な設定を以下に示します。2 番目の引数は、ファイルシステムへのアクセスを指定したディレクトリとその配下のすべての項目に制限します。

{
  "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 を参照してください。

ドキュメント

「ドッグフーディング」により生成されています。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）のみです。それ以外のモデルは、使用可能な図を適切に生成する能力が劣り、複雑なリポジトリでは失敗しました。すべてのモデルで、使用可能なコード要約は安定して生成できます。

コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/AmazingFeature）
3. 変更をコミットします（git commit -m 'Add some AmazingFeature'）
4. ブランチにプッシュします（git push origin feature/AmazingFeature）
5. プルリクエストを作成します

ライセンス

MIT