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。