MCP Http Agent Md

🚀 mcp-http-agent-md

mcp-http-agent-md 是一個輕量級的 MCP（Model Context Protocol）HTTP 服務器，專為 AGENTS.md 和結構化任務設計。它具備版本化歷史記錄（日誌/回滾）和臨時便籤功能，並通過可流式傳輸的 HTTP 端點對外提供服務。便籤還可用於生成上下文隔離的子代理，以解決特定任務。此外，該服務器還提供了認證中間件，用於用戶隔離和公共服務，用戶還能在服務器內共享和協作項目。

本項目由 Codex (OpenAI) 共同創作。

🚀 快速開始

自動安裝和用戶創建（類 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

環境配置

你可以在終端通過 export XXX=xxx 設置 .env.example 中定義的所有環境變量。 如果你更喜歡通過 .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 包拉取：docker pull ghcr.io/benhaotang/mcp-http-agent-md:latest
  • 運行（持久化數據庫並設置管理員密鑰）：

   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 .

✨ 主要特性

架構概述

本項目為從事長期項目的 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

環境配置

你可以在終端通過 export XXX=xxx 設置 .env.example 中定義的所有環境變量。 如果你更喜歡通過 .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 包拉取：docker pull ghcr.io/benhaotang/mcp-http-agent-md:latest
  • 運行（持久化數據庫並設置管理員密鑰）：

   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

管理 API：http://localhost:3000/auth（Bearer MAIN_API_KEY），首先生成一個 USER_API_KEY，詳見 認證和管理

MCP 端點

• 本地：

{
  "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",
    }
  }
}

列出工具

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 使用示例

一個可選的輕量級管理控制檯（Next.js App Router）已打包並在 /ui 提供服務：

開發模式

在運行 pnpm dev 時會自動包含（熱重載）。服務器啟動後訪問 /ui。

生產模式

先構建 UI，然後以生產模式啟動服務器：

pnpm build:ui
NODE_ENV=production pnpm start

工具使用示例

列出項目

# 示例代碼調用 list_projects 工具

初始化項目

# 示例代碼調用 init_project 工具

刪除項目

# 示例代碼調用 delete_project 工具

重命名項目

# 示例代碼調用 rename_project 工具

讀取 AGENTS.md

# 示例代碼調用 read_agent 工具

寫入 AGENTS.md

# 示例代碼調用 write_agent 工具

讀取項目進度

# 示例代碼調用 read_progress 工具

添加項目進度

# 示例代碼調用 progress_add 工具

更新任務狀態

# 示例代碼調用 progress_set_new_state 工具

生成任務 ID

# 示例代碼調用 generate_task_ids 工具

獲取 AGENTS.md 最佳實踐和示例

# 示例代碼調用 get_agents_md_best_practices_and_examples 工具

列出項目日誌

# 示例代碼調用 list_project_logs 工具

回滾項目

# 示例代碼調用 revert_project 工具

初始化便籤

# 示例代碼調用 scratchpad_initialize 工具

查看便籤

# 示例代碼調用 review_scratchpad 工具

更新便籤任務

# 示例代碼調用 scratchpad_update_task 工具

追加便籤共享內存

# 示例代碼調用 scratchpad_append_common_memory 工具

啟動子代理

# 示例代碼調用 scratchpad_subagent 工具

檢查子代理運行狀態

# 示例代碼調用 scratchpad_subagent_status 工具

📚 詳細文檔

認證和管理

• MCP：通過查詢參數 ?apiKey=... 或 Authorization: Bearer ... 提供用戶 apiKey。
• 管理：使用 Authorization: Bearer MAIN_API_KEY。

創建用戶

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=...：獲取項目共享狀態

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：添加一個或多個結構化任務 { 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 一樣是臨時的；這裡沒有提供列表/刪除工具。目前“期望”一個外部清理工具在會話結束後刪除它們。
• 代理必須通過 (項目名稱, 便籤 ID) 來引用便籤，以便在同一會話中重新打開現有的便籤。

項目選擇

所有任務工具都接受一個 name（項目名稱）參數；服務器將其解析為內部項目 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 兼容（例如，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 示例。

🔧 技術細節

架構概述

本項目為從事長期項目的 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。
• 任務範圍上下文：便籤提供臨時但專注、可管理的塊，並具有共享內存。
• 子代理隔離：每個子代理僅查看相關上下文，防止信息過載。
• 主代理低上下文：協調器僅需要高級結果，而不需要詳細的研究。
• 持久知識：項目狀態在多個聊天會話中保持不變。

📄 許可證

本項目採用 MIT 許可證。詳見 LICENSE。