Agents.md

mcp-http-agent-md

AGENTS.md と構造化タスク向けの最小構成の MCP（Model Context Protocol）HTTP サーバーです。バージョン管理された履歴（ログ／復元）と一時的なスクラッチパッドを備え、Streamable HTTP エンドポイント経由で利用できます。スクラッチパッドは、コンテキストを分離したサブエージェント（Gemini、OpenAI、Groq、OpenAI 互換、または MCP + OpenAI 互換経由）を起動して、範囲を絞ったタスクを解決するためにも使用できます。また、ユーザーごとの分離と公開に対応する認証ミドルウェアも用意されています。ユーザーはサーバー上でプロジェクトを共有し、共同作業することもできます。

Codex（OpenAI）との共著です。

アーキテクチャの概要

このプロジェクトは、長期プロジェクトに取り組む AI エージェント向けの階層型コンテキスト管理システムを実装しています。

graph LR
    subgraph "Full Project Knowledge"
        PK["📚 Entire Project<br/>• All code files<br/>• All documentation<br/>• Web resources<br/>• Tool outputs<br/>MASSIVE CONTEXT"]
    end
    
    subgraph "Compressed Knowledge"
        A["📄 AGENTS.md<br/>(Essential Knowledge)"]
        P["📋 progress.md<br/>(Task Board)"]
    end
    
    subgraph "Main Agent"
        MA["🧠 Orchestrator<br/>LOW CONTEXT<br/>• Reads compressed knowledge<br/>• Spawns scratchpads<br/>• Updates project state"]
    end
    
    subgraph "Scratchpad"
        CM["Common Memory<br/>(Shared Context)"]
        
        subgraph "Task Pool"
            T1["Task 1"]
            T2["Task 2"]
            T3["Task ..."]
        end
        
        subgraph "Subagents"
            SA1["🤖 Agent 1<br/>HIGH CONTEXT"]
            SA2["🤖 Agent 2<br/>HIGH CONTEXT"]
        end
    end
    
    %% Knowledge compression flow
    PK --> |compresses to| A
    PK --> |compresses to| P
    
    %% Main agent reads compressed knowledge
    A --> MA
    P --> MA
    
    %% Main agent creates scratchpad with smaller tasks
    MA --> |break into tasks| T1
    MA --> |break into tasks| T2
    MA --> |break into tasks| T3
    MA --> |maintains| CM
    
    %% Main agent can read/write directly
    MA <--> |read/write| CM
    MA <--> |read/write| T1
    MA <--> |read/write| T2
    MA <--> |read/write| T3
    
    %% Tasks spawn subagents
    T1 --> |spawns| SA1
    T2 --> |spawns| SA2
    
    %% Subagents get context and work on specific tasks
    SA1 --> |full access| PK
    SA2 --> |full access| PK
    CM --> |shared context| SA1
    CM --> |shared context| SA2
    
    %% Subagents report back to their tasks
    SA1 --> |results/comments| T1
    SA2 --> |results/comments| T2
    
    %% Main agent updates compressed knowledge
    MA --> |updates| A
    MA --> |updates| P

    style PK fill:#ffecb3
    style A fill:#e1f5fe
    style P fill:#e8f5e8
    style MA fill:#ffebee
    style CM fill:#f3e5f5
    style SA1 fill:#fff3e0
    style SA2 fill:#fff3e0

主なメリット：

• プロジェクト全体のコンテキスト：AGENTS.md に蓄積した知識を保存し、progress.md で長期タスクを追跡します。詳しくは agents.md をご覧ください。
• タスク全体のコンテキスト：スクラッチパッドを使うと、一時的ながら焦点を絞った、管理しやすい単位で共有メモリを利用できます。
• サブエージェントの分離：各サブエージェントに関連するコンテキストだけを提示し、情報過多を防ぎます。
• メインエージェントのコンテキストを低減：オーケストレーターが必要とするのは概要レベルの結果だけで、詳細な調査内容は不要です。
• 知識の永続化：プロジェクトの状態は複数のチャットセッションをまたいで保持されます。

自動インストールとユーザー作成（Unix 系システム）

• Docker を使わない場合：（$HOME/.config/mcp-http-agent-md にインストールし、デフォルトユーザーで起動します）

  curl -fsSL https://raw.githubusercontent.com/benhaotang/mcp-http-agent-md/main/install/install.sh | bash
  

• Docker を使う場合：（データは $HOME/.config/mcp-http-agent-md/data に永続化されます）

  curl -fsSL https://raw.githubusercontent.com/benhaotang/mcp-http-agent-md/main/install/install-docker.sh | bash
  

手動インストール

まず、リポジトリをクローンします：git clone https://github.com/benhaotang/mcp-http-agent-md.git

環境変数

.env.example で定義されている環境変数は、すべてターミナルから export XXX=xxx で設定できます。

.env で設定する場合：cp .env.example .env

• サーバーのデフォルト値：HOST=localhost、PORT=3000、BASE_PATH=/mcp。
• 外部 AI（任意）：サブエージェントのツールを使う場合は、.env または ENV で設定します。対応している プロバイダーとモデル の詳細をご覧ください。

USE_EXTERNAL_AI=true
AI_API_TYPE=google   # google | openai | groq | compat | mcp
AI_API_KEY=...   # required when enabled
AI_MODEL="gemini-2.5-pro"  # optional; default depends on provider
AI_TIMEOUT=120              # optional
AI_ATTACHMENT_TEXT_LIMIT=120000  # optional; -1 keeps full extracted text

メモ

Docker ではセキュリティ上、現在 -e XXX=xxx による追加のみをサポートしています。.env ファイルを使う場合は、.dockerignore から除外してイメージをローカルでビルドしてください。Docker をご覧ください。

Node で実行

• pnpm（推奨）：
  • インストール：pnpm install
  • 開発：pnpm dev
  • 本番：pnpm start
• npm：
  • インストール：npm install
  • 開発：npx nodemon --watch index.js --ext js,mjs,cjs index.js
  • 本番：npm run start

Docker

• GitHub Package から取得：docker pull ghcr.io/benhaotang/mcp-http-agent-md:latest
  • 実行（DB を永続化し、管理者キーを設定）：

   docker run -it --restart always \
     -p 3000:3000 \
     -e MAIN_API_KEY=change-me \
     -e HOST=0.0.0.0 \
     -v $(pwd)/data:/app/data \
     --name mcp-http-agent-md \
     ghcr.io/benhaotang/mcp-http-agent-md:latest
  

  • サブエージェントを使用するには、-e AI_API_KEY=xxx -e USE_EXTERNAL_AI=true を追加します。
• ローカルビルド：docker build -t mcp-http-agent-md .

エンドポイント

• 管理 API：http://localhost:3000/auth（Bearer MAIN_API_KEY）。まず USER_API_KEY を生成してください。認証 をご覧ください。
• MCP エンドポイント：POST http://localhost:3000/mcp?apiKey=USER_API_KEY
  • ローカル

    {
      "mcpServers": {
        "mcp-agent-md": {
          "command": "npx",
          "args": ["-y","mcp-remote","http://localhost:3000/mcp?apiKey=USER_API_KEY`"]
        }
      }
    }
    

  • リモート

    {
      "mcpServers": {
        "mcp-agent-md": {
          "url": "https://<your-deployment>/mcp?apiKey=USER_API_KEY",
        }
      }
    }
    

認証と管理

• MCP：クエリ ?apiKey=... または Authorization: Bearer ... でユーザーの apiKey を指定します。
• 管理者：Authorization: Bearer MAIN_API_KEY を使用します。

ユーザーを作成します（{ id, apiKey } を返します）：

curl -X POST http://localhost:3000/auth/users \
  -H "Authorization: Bearer $MAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"alice"}'

定義

ベース：/auth（Bearer MAIN_API_KEY）

• POST /auth/users：ユーザーを作成 → { id, apiKey, name? }
• GET /auth/users：ユーザー一覧を取得（完全なキーを表示するには ?reveal=true を指定）
• GET /auth/users/:id：ユーザーを取得
• POST /auth/users/:id/regenerate：API キーをローテーション
• DELETE /auth/users/:id：ユーザーを削除

プロジェクトの共有

REST API を使用して、プロジェクトを他のユーザーと共有できます。ベース：/project（Bearer トークン認証）

プロジェクトを別のユーザーと読み取り専用で共有します：

curl -X POST http://localhost:3000/project/share \
  -H "Authorization: Bearer $USER_API_KEY/$MAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"<project_id>","target_user_id":"<user_id>","permission":"ro"}'

定義

• GET /project/list：プロジェクト一覧を取得（管理者：すべてのプロジェクト、ユーザー：所有および共有されたプロジェクト）
• POST /project/share：プロジェクトを共有 { project_id, target_user_id, permission, revoke? }。権限：ro（読み取り専用）または rw（読み書き）。アクセス権を削除するには revoke: true を設定します。
• GET /project/status?project_id=...：プロジェクトの共有状況を取得

プロジェクトファイル

プロジェクト内でドキュメント（PDF、MD、TXT）をアップロードして管理します。ファイルはサブエージェントからアクセスでき、AI による自動要約も可能です。PDF は、UI の「Files」タブにある「OCR」ボタンから OCR 処理できます。

定義

ベース：/project/files（Bearer トークン認証）

• POST /project/files：ファイルをアップロード（≤20MB）。説明は任意です。
• GET /project/files?project_id=...：プロジェクトファイルのメタデータ一覧を取得
• DELETE /project/files/:fileId?project_id=...：ファイルを削除
• POST /project/files/:fileId/summarize?project_id=...：ファイルを AI で要約（USE_EXTERNAL_AI=true が必要）
• POST /project/files/:fileId/process?project_id=...：単一の PDF 用に OCR サイドカーを生成／更新（再生成するには force=true を設定）
• POST /project/files/process-all?project_id=...：プロジェクトディレクトリ内のすべての PDF を一括処理（force=true は任意）

PDF OCR サイドカー

• Mistral（MISTRAL_AI_API／MISTRAL_API_KEY）またはローカルモデル（USE_LOCAL_AI_FOR_DOC_UNDERSTANDING=true）が設定されている場合、PDF のアップロード時に OCR が自動的にキューに追加されます。アップロードへの応答はすぐに返され、処理はバックグラウンドで実行されます。
• OCR の出力は、プロバイダー固有の形式（{ pages: [...] }）でバイナリと同じ場所に data/<project_id>/<file_id>.ocr.json として保存されます。
• 要約と外部 AI 呼び出しでは元の PDF が引き続き添付されますが、サイドカーがある場合は、テキストのみを扱うプロバイダーにも十分なコンテキストを提供するため、抽出された Markdown も渡されます。
• ローカル OCR には、PDF をページごとの PNG に分割できるよう、pdftoppm（poppler-utils 由来）が PATH から利用可能である必要があります。

MCP エンドポイント

• ベースパス：POST /mcp（ステートフルでない JSON-RPC のストリーミング HTTP）

ツール一覧を取得：

curl -X POST 'http://localhost:3000/mcp?apiKey=USER_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}'

Web UI（/ui）

軽量な管理コンソール（Next.js App Router）がオプションでバンドルされており、/ui で提供されます：

• ドラッグ＆ドロップでタスクを管理できるカンバンボード
• Markdown に対応した AGENTS.md エディター
• ドキュメントのアップロード、管理、説明のための「Files」タブ（サブエージェントで生成できます）。
• プロジェクトの共有とコラボレーション
• コミット履歴とバージョン管理

開発モード：pnpm dev の実行時に自動的に含まれます（ホットリロード）。サーバーの起動後に /ui にアクセスしてください。

本番環境：UI を一度ビルドしてから、本番モードでサーバーを起動します：

pnpm build:ui
NODE_ENV=production pnpm start

ツール

• list_projects: すべてのプロジェクト名を一覧表示します。
• init_project: プロジェクト { name, agent?, progress? } を作成／初期化します。初期バックアップ（コミット）をすぐに作成し、hash を返します。
• delete_project: プロジェクト { name } を削除します。（所有者のみ）
• rename_project: プロジェクト { oldName, newName, comment? } の名前を変更します（所有者のみ）。更新後の hash を返します。
• read_agent: AGENTS.md { name } を読み取ります。
• write_agent: AGENTS.md { name, content, comment? } に書き込みます。パッチ／差分にも対応しており、応答には更新後の hash が含まれます。
• read_progress: プロジェクト { name, only? } の構造化タスクを読み取ります。JSON { tasks: [...], markdown: "..." } を返します。markdown は、人が読みやすいネストされたアウトライン形式です。only では pending | in_progress | completed | archived（同義語も使用可能）で絞り込めます。デフォルトではアーカイブ済みタスクは除外され、only に archived が含まれる場合のみ表示されます。
• progress_add: 1 つ以上の構造化タスク { name, item, comment? } を追加します。タスクを追加するとコミットが作成され、hash を返します。
• progress_set_new_state: task_id（8 文字）または task_info の部分一致でタスクを更新します { name, match, state?, task_info?, parent_id?, extra_note?, comment? }。変更があるとコミットが作成され、hash を返します。
  • ロックのルール：タスク（またはその祖先）が completed または archived の場合、そのタスクや子孫タスクは編集できません。ただし、祖先がロックされていない場合に限り、タスク自体を pending または in_progress に戻してロックを解除できます。親タスクのロックを解除すると、子孫タスクにも反映されます。
• generate_task_ids: このユーザーが使用していない一意の 8 文字 ID を N 個生成します { count? }（デフォルトは 5）。{ ids: ["abcd1234", ...] } を返します。
• get_agents_md_best_practices_and_examples: example_agent_md.json のベストプラクティスと例を返します。デフォルトでは the_art_of_writing_agents_md（ベストプラクティス）のみを返します。すべての例を含めるには include='all' を使用するか、ユースケース／タイトルで絞り込むには include に文字列または配列を指定します。
• list_project_logs: コミットログ { name } を一覧表示します → { logs: [{ hash, message, modified_by, created_at }] }。modified_by フィールドには、各コミットを行ったユーザーが表示されます。
• revert_project: 以前の hash に戻します { name, hash }。共有プロジェクトの参加者が戻せるのは、他のユーザーの作業が破棄されないよう、直近の連続した自分のコミットまでです。その時点まで履歴が切り詰められます（ブランチはありません）。
• list_file: プロジェクト { project_id } にアップロードされたドキュメントを一覧表示します。各ファイルの元のファイル名、説明、参照用の file_id を返します。
• read_project_file: アップロードされたプロジェクトドキュメントの特定のチャンクを読み取ります { project_id, file_id, start?, length?, pages? }。UTF-8 テキストを返します（PDF はテキストに解析されます）。デフォルトは start=0、length=10000 です。処理済みの PDF では、start/length の代わりに pages="1-3,5" を使用してください。（USE_EXTERNAL_AI=false の場合のみ有効）エージェントは、チャンク単位またはページ単位のどちらか一方で読み取る方法のみ選択できます。 スクラッチパッド（セッションごとの一時的なもの）ツール：
• scratchpad_initialize：単発のタスク用に、新しいスクラッチパッドを開始します { name, tasks }。サーバーはランダムな scratchpad_id を生成して返します。tasks は最大6件の { task_id, status: 'open'|'complete', task_info, scratchpad?, comments? } です。{ scratchpad_id, project_id, tasks, common_memory } を返します。
• review_scratchpad：{ name, scratchpad_id, IncludeCM?, IncludeTk? } でスクラッチパッドを確認します。
  • IncludeCM：ブール値です。true の場合、出力に common_memory を含めます。
  • IncludeTk：文字列の配列です。task_id（大文字と小文字を区別しない完全一致）または task_info（大文字と小文字を区別しない部分一致）でタスクを絞り込みます。指定すると、一致するタスクのみが返されます。
  • IncludeCM と IncludeTk のどちらも指定しない場合は、tasks と common_memory の両方を返します（後方互換性のあるデフォルト）。それ以外の場合は、要求されたフィールドのみを含めます。IncludeTk を省略すると、tasks は返されません。
• scratchpad_update_task：task_id で既存のスクラッチパッドのタスクを更新します { name, scratchpad_id, updates }。updates は { task_id, status?, task_info?, scratchpad?, comments? } の配列です。{ updated, notFound, scratchpad } を返します。
• scratchpad_append_common_memory：スクラッチパッドの共有メモリーに追記します { name, scratchpad_id, append }。append は文字列または文字列の配列です。更新されたスクラッチパッドを返します。

外部 AI サブエージェント（USE_EXTERNAL_AI が false でない場合のみ表示）：

• scratchpad_subagent：スクラッチパッドのタスクに取り組むサブエージェントを開始します { name, scratchpad_id, task_id, prompt, sys_prompt?, tool?, file_id?, file_path? }。ツールはプロバイダー（AI_API_TYPE）によって異なります。標準ツール：grounding（検索）、crawling（ウェブ取得）、code_execution（コード実行）。common_memory は自動的にプロンプトに追加されます。file_id（list_file から取得）または file_path（絶対パス）を使ってドキュメントを添付できます。status: in_progress と run_id を返して、処理を早期に終了する場合があります。
• scratchpad_subagent_status：{ name, run_id } で実行状況を確認します。最終ステータスを返すか、実行中の場合は最大約25秒間ポーリングします。

注：

• スクラッチパッドは RAM のように一時的なもので、このツールには一覧表示や削除のツールはありません。セッション後に削除する外部クリーンアップツールが現在「想定」されています。
• エージェントが同じセッション中に既存のスクラッチパッドを再度開くには、(project name, scratchpad_id) で指定する必要があります。

プロジェクトの選択：すべてのタスクツールは name（プロジェクト名）パラメーターを受け取ります。サーバーはこれを内部の project_id に解決します。project_id を指定する必要はありません。

プロバイダーとモデル

• google（Gemini）：gemini-2.5-pro、gemini-2.5-flash
• openai（Responses API）：現在は gpt-5、gpt-5-mini、gpt-5-nano のみ
• groq（Chat Completions）：現在は openai/gpt-oss-120b、openai/gpt-oss-20b のみ
• openai_com（OpenAI 互換チャット）：エンドポイントによって異なります。サブエージェントツールはありません。
• mcp（OpenAI 互換 + MCP ツール）：AI_BASE_ENDPOINT と AI_MODEL を使用し、subagent_config.json で MCP サーバーを設定してください。エンドポイントとモデルの組み合わせが関数呼び出しに対応している必要があります

例（.env）：

# Gemini
AI_API_TYPE=google
AI_MODEL="gemini-2.5-pro"

# OpenAI
# AI_API_TYPE=openai
# AI_MODEL="gpt-5-mini"

# Groq
# AI_API_TYPE=groq
# AI_MODEL="openai/gpt-oss-120b"

# OpenAI‑compatible (e.g., LM Studio)
# AI_API_TYPE=compat
# AI_BASE_ENDPOINT="http://localhost:1234/v1"
# AI_MODEL="qwen/qwen3-4b-2507"

# MCP + OpenAI‑compatible
# AI_API_TYPE=mcp
# AI_BASE_ENDPOINT="http://localhost:1234/v1"
# AI_MODEL="qwen/qwen3-4b-2507"

MCP プロバイダーの設定：

• リポジトリのルートにある subagent_config.json に MCP クライアント設定を記述します。このリポジトリには例が含まれています。
• mcpServers の下にサーバーを定義します。リモートサーバーの場合は { "serverUrl": "https://.../mcp" }（HTTP）または .../sse（SSE。レガシーですがサポートされています）を使用します。ローカルの stdio サーバーの場合は { "command": "...", "args": [ ... ] } を使用します。
• エージェントが選択しやすいよう、サーバーごとに短い1行の short_descriptions を追加することをおすすめします。最小限の例は、リポジトリの subagent_config.json を参照してください。

ライセンス

MIT。LICENSE を参照してください。