MCP Http Agent Md

🚀 mcp-http-agent-md

このプロジェクトは、AGENTS.md と構造化されたタスクに対応した最小限の MCP (Model Context Protocol) HTTP サーバーです。バージョン管理された履歴 (ログ/リバート) と一時的なスクラッチパッドを備え、ストリーム可能な HTTP エンドポイントを介して公開されます。スクラッチパッドは、特定のタスクを解決するために、コンテキストが分離されたサブエージェント (Gemini、OpenAI、Groq、OpenAI 互換、または MCP + OpenAI 互換を介して) を生成するためにも使用できます。ユーザー分離と公開サービングのための認証ミドルウェアも提供されています。ユーザーは、サーバー内でプロジェクトを共有し、共同作業することもできます。

Codex (OpenAI) と共同作成されました。

🚀 クイックスタート

このセクションでは、mcp-http-agent-md のインストール方法や基本的な使い方を説明します。

✨ 主な機能

• プロジェクト全体のコンテキスト管理：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 または環境変数で設定します。サポートされている プロバイダーとモデル の詳細を参照してください。

USE_EXTERNAL_AI=true
AI_API_TYPE=google   # google | openai | groq | compat | mcp
AI_API_KEY=...   # 有効にする場合は必須
AI_MODEL="gemini-2.5-pro"  # オプション; デフォルトはプロバイダーに依存
AI_TIMEOUT=120              # オプション

⚠️ 重要提示 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 .

💻 使用例

基本的な使用法

以下は、エンドポイントを使用してツールをリストする基本的な例です。

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"}'

高度な使用法

ここでは、ユーザーやプロジェクトの管理、スクラッチパッドの操作など、高度なシナリオでの使用例を示します。

ユーザーの作成

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

プロジェクトの共有

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"}'

スクラッチパッドの初期化

# 具体的なコマンドは省略

📚 ドキュメント

エンドポイント

• 管理 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 はクエリ ?apiKey=... または Authorization: Bearer ... を使用して提供します。
• 管理者：Authorization: Bearer MAIN_API_KEY を使用します。

定義

ベースパス：/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 トークン認証)

定義

• GET /project/list：プロジェクトをリスト (管理者：すべてのプロジェクト、ユーザー：所有 + 共有)
• POST /project/share：プロジェクトを共有 { project_id, target_user_id, permission, revoke? }。権限：ro (読み取り専用) または rw (読み書き)。revoke: true を設定すると、アクセスを削除します。
• GET /project/status?project_id=...：プロジェクトの共有ステータスを取得

MCP エンドポイント

• ベースパス：POST /mcp (ストリーム可能な HTTP、ステートレス JSON-RPC)

ツールのリスト

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 で提供されます。

開発モード

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：このユーザーが使用していない N 個の一意の 8 文字の ID を生成 { 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 }。共有参加者は、最も新しい連続シーケンスのコミットにのみ戻すことができます (他のユーザーの作業を破棄しないように)。履歴はその時点までトリミングされます (ブランチはありません)。

スクラッチパッド (一時的、セッションごと) ツール

• 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? }。ツールはプロバイダー (AI_API_TYPE) に依存します。標準的なツール：grounding (検索)、crawling (ウェブフェッチ)、code_execution (コード実行)。common_memory が自動的にプロンプトに追加されます。status: in_progress と run_id で早期に返される場合があります。
• scratchpad_subagent_status：実行ステータスを確認 { name, run_id }。最終ステータスを返し、実行中の場合は最大約 25 秒間ポーリングします。

注意事項

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

プロジェクトの選択

すべてのタスクツールは name (プロジェクト名) パラメーターを受け取り、サーバーはそれを内部のプロジェクト ID に解決します。project_id を提供する必要はありません。

🔧 技術詳細

アーキテクチャの概要

このプロジェクトは、長期的なプロジェクトに取り組む 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 を参照してください。
• タスク単位のコンテキスト：スクラッチパッドが一時的でありながら集中的で管理しやすいデータチャンクを共有メモリで提供します。
• サブエージェントの分離：各サブエージェントは関連するコンテキストのみを見ることができ、情報の過負荷を防ぎます。
• メインエージェントの低コンテキスト化：オーケストレーターは高レベルの結果のみを必要とし、詳細な調査を必要としません。
• 永続的な知識管理：プロジェクトの状態は複数のチャットセッションにわたって維持されます。

プロバイダーとモデル

• 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 を使用します。MCP サーバーを subagent_config.json で構成します。エンドポイントとモデルの組み合わせが関数呼び出しをサポートする必要があります

例 (.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 互換 (例: LM Studio)
# AI_API_TYPE=compat
# AI_BASE_ENDPOINT="http://localhost:1234/v1"
# AI_MODEL="qwen/qwen3-4b-2507"

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

MCP プロバイダーの構成

• MCP クライアントの設定をリポジトリのルートにある subagent_config.json に配置します。このリポジトリには例が含まれています。
• mcpServers の下にサーバーを定義します。リモートサーバーの場合は { "serverUrl": "https://.../mcp" } (HTTP) または .../sse (SSE; レガシーですがサポートされています) を使用します。ローカルの標準入出力サーバーの場合は { "command": "...", "args": [ ... ] } を使用します。
• 各サーバーに短い一行の short_descriptions を追加して、エージェントが選択しやすくすることをお勧めします。最小限の例については、リポジトリの subagent_config.json を参照してください。

📄 ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。詳細は LICENSE を参照してください。