Agents Md Generator

Claude Code、Gemini CLI、Cursor、Windsurf、Codex CLIなど、MCP 対応クライアントであればどれでも利用できます。

このサーバーは、役割を明確に分けた3つのツールを提供します。

• generate_agents_md — メインのエントリーポイントです。分析パイプラインを内部で実行し、書き込みルールをペイロードに埋め込み、分割された読み取り指示をクライアントに返します。
• scan_codebase — ファイルを生成せずにコードベースを深く理解したい場合に使う、単独で利用できるコンテキストツールです。
• read_payload_chunk — どのツールがペイロードを生成したかに関わらず、ペイロードを分割してストリーミングします。

MCP の通信経路を通じて、大量のデータが送信されることはありません。

目次

• インストール
  • オプションA — pip install + セットアップウィザード
  • オプションB — uvx
• 使い方
  • ツール
  • ツールのパラメーター
• 生成される内容
• インクリメンタルスキャンの仕組み
  • 大きなペイロードのストリーミング方法
  • キャッシュとペイロードの保存場所
• プロジェクト設定
  • オプション
  • 環境変数
  • プロジェクト規模のプロファイル
• 分析で検出される内容
• 謝辞

インストール

必要条件： Python 3.11以降、Git、およびMCP対応クライアント。

前提条件やトラブルシューティングを含む完全なガイドは、**INSTALLATION.md**を参照してください。

オプションA — pip install + セットアップウィザード（推奨）

pip install agents-md-generator
agents-md-generator setup

セットアップウィザードは、インストール済みのクライアントを検出し、グローバルまたはプロジェクト単位で設定するかを確認したうえで、設定ファイルを自動的に更新します。Claude Code、Gemini CLI、Cursor、Windsurf、Codex CLIに対応しています。

オプションB — uvx（インストール不要）

uvをインストール済みの場合、uvxを使うと、事前にインストールすることなくパッケージを実行できます。クライアントのMCP設定にエントリを手動で追加してください。

{
  "mcpServers": {
    "agents-md": {
      "command": "uvx",
      "args": ["agents-md-generator"]
    }
  }
}

Claude Codeの場合：

claude mcp add agents-md -- uvx agents-md-generator

claude mcp addの既定のスコープは--scope local（現在のプロジェクトのみ）です。すべてのプロジェクトに登録するには、-s userを追加してください。

使い方

登録したら、AIクライアントに次のように依頼します。

「このプロジェクトのAGENTS.mdを生成してください」

クライアントはgenerate_agents_mdを自動的に呼び出します。別のディレクトリをスキャンする場合：

「/path/to/project にあるプロジェクトのAGENTS.mdを生成してください」

ツール

ツールのパラメーター

生成される内容

生成される AGENTS.md は、agents.md のオープン標準に準拠しています。人間向けのドキュメントではなく、AI エージェント向けの README として記述されます。次のセクションが含まれます。

データが検出されなかったセクションは完全に省略されます。

インクリメンタルスキャンの仕組み

1. 初回実行（コールドスタート） — Git で追跡されているすべてのソースファイルを tree-sitter で解析し、キャッシュします
2. 以降の実行 — 前回のスキャン以降に SHA-256 ハッシュが変わったファイルのみを再解析します
3. セマンティック差分 — 変更されたファイルについて、変更された公開シンボルのみをペイロードに含めます
4. ソースに変更がない場合 — ツールは停止し、既存の AGENTS.md の内容も改善するかどうかを尋ねます
5. プライベートシンボルとテストファイルの内部は、キャッシュとペイロードの両方から除外されます — AGENTS.md では公開 API の表面のみが重要です

大容量ペイロードのストリーミング方法

大規模なコードベースでは、分析ペイロードが大きすぎて MCP 経由でインライン返却できない場合があります。サーバーは read_payload_chunk を通じて、この処理を透過的に行います。

スキャンは別プロセスで実行され、ステージの進行状況通知と 5 分間のタイムアウトが設定されています。キャンセルすると、スキャンワーカーが停止します。1 つのサーバーインスタンスでは、プロジェクトごとに同時に実行できるスキャンは 1 つだけです。制限時間を超えるリポジトリは、.agents-config.json を使って対象を絞り込んでください。

生成時には常に最新のスナップショットが組み立てられ、変更されていないソースファイルのシンボルはキャッシュから再利用されます。ペイロードが消費された後や別のスキャンが実行された後でも、中断された生成を再試行できます。AGENTS.md の書き込みは引き続きクライアント側で行います。

シリアライズされたペイロードの上限は 300,000 文字です。除外された分析セクションは metadata.degradations および metadata.truncated_sections に記録されます。既存の AGENTS.md の内容と書き込み指示は保持されます。これらだけで上限を超える場合、ドキュメントを切り詰める代わりにツールがエラーを返します。

このフローは純粋な MCP であり、クライアント側でファイルシステムにアクセスする必要はありません。MCP 互換のクライアントならどれでも、このフローに従うことができます。

キャッシュとペイロードの保存場所

すべての実行時アーティファクトは、プロジェクトの外部にあるユーザーキャッシュディレクトリに保存されます。

~/.cache/agents-md-generator/<project-hash>/cache.json  ← incremental scan cache

<project-hash> はプロジェクトの絶対パスを SHA-256 でハッシュ化したもので、プロジェクトごとに一意です。リポジトリには何も書き込まれません。

注： 分析中、サーバーはこのディレクトリにも一時的な payload.json を書き込みますが、これは read_payload_chunk ツールによって完全に管理され、最後のチャンクが読み取られると自動的に削除されます。直接アクセスする必要はありません。

プロジェクト設定

動作をカスタマイズするには、プロジェクトのルートに .agents-config.json を作成します。このファイルは任意です。すべてのフィールドにはデフォルト値が設定されており、チームで設定を共有するためにコミットすることもできます。

{
  "project_size": "medium",
  "exclude": [
    "**/node_modules/**",
    "**/bin/**",
    "**/obj/**",
    "**/.git/**",
    "**/dist/**",
    "**/build/**",
    "**/__pycache__/**",
    "**/*.min.js",
    "**/*.min.css",
    "**/*.bundle.js",
    "**/vendor/**",
    "**/packages/**",
    "**/.venv/**",
    "**/venv/**",
    "**/bower_components/**",
    "**/app/lib/**",
    "**/wwwroot/lib/**",
    "**/wwwroot/libs/**",
    "**/static/vendor/**",
    "**/public/vendor/**",
    "**/assets/vendor/**",
    "**/site-packages/**"
  ],
  "include": [],
  "languages": "auto",
  "agents_md_path": "./AGENTS.md",
  "max_file_size_bytes": 1048576
}

オプション

環境変数

プロジェクト規模プロファイル

project_size 設定では、ペイロードの圧縮の度合いを調整します。1 つの設定ですべての内部上限（クラスあたりのメソッド数、ファイルあたりのシンボル数、ディレクトリの集約、ルートの上限、ツリーの深さ、影響範囲のフィルタリング）を調整できます。

解析で検出される内容

環境変数

サーバーは言語固有のパターンを使用して、すべてのソースファイルから環境変数の参照をスキャンします。

プロジェクトのルートにある .env.example、.env.template、.env.sample ファイルも解析します。

エントリーポイント

index、main、app、server、program、bootstrap、startup という名前のファイル（サポートされる任意の拡張子）は、エントリーポイントとして検出され、推定される役割（例：「HTTP サーバーのブートストラップ」、「Electron のメインプロセス」）が注記されます。

パブリック API の範囲

Tree-sitter は各ソースファイルを解析し、クラス、関数、メソッド、インターフェースなどのパブリックシンボルを抽出します。その際、プライベート／保護されたメンバーと、アンダースコアで始まるシンボルは除外されます。クラスと構造体については、コンストラクター（パラメーターがある場合）とパブリックプロパティも含めることで、依存性注入のパターンとデータ構造を明らかにします。インターフェースのメソッドはパブリックな契約を定義するため、常に含まれます。これらの情報は、レイヤー間の命名規則、DI パターン、エクスポート契約の検出に使用されます。

アーキテクチャの抽出

大規模なコードベースでは、ペイロードの情報密度を高く保つため、ツールはいくつかのヒューリスティックを適用します。

• ボイラープレートの抑制 — Migrations、bin、obj、Properties などの一般的なディレクトリは自動的に識別され、プロジェクト構造内で折りたたまれます。これにより、ディレクトリ一覧が肥大化するのを防ぎます。
• 情報量の少ないファイルの要約 — ロジックメソッドがなく、主にデータ構造（DTO、エンティティ）を含むファイルは「最小化」されます。すべてのプロパティを列挙する代わりに、「25 個の DTO クラスを含む」といった概要を提示します。
• 意味的なクラスタリング — アグリゲーターは、最小化されたこれらの概要をディレクトリ単位でグループ化します。これにより、利用する AI は、1 行の情報からデータレイヤー全体を理解できます。
• 指示の埋め込み — generate_agents_md 経由で呼び出された場合、記述ルールがペイロードに直接埋め込まれ、AI エージェントはコードアーキテクチャを処理する前に「取り組み方のルール」を読みます。scan_codebase を直接呼び出した場合は、指示を含まない純粋なデータが返されます。

クレジット

AGENTS.md 形式は、公開されている agents.md 標準に基づいています。