Agents.md

mcp-http-agent-md

用于 AGENTS.md 和结构化任务的轻量级 MCP（Model Context Protocol）HTTP 服务，支持带版本的历史记录（日志/回滚）和临时暂存区，并通过 Streamable HTTP 端点提供服务。暂存区还可用于启动上下文隔离的子 Agent（通过 Gemini、OpenAI、Groq、兼容 OpenAI 的服务，或 MCP + 兼容 OpenAI 的服务），以解决重点任务。项目还提供了身份验证中间件，用于隔离用户和公开提供服务。用户也可以在服务中共享和协作处理项目。

由 Codex（OpenAI）共同编写。

架构概览

本项目为处理长期项目的 AI Agent 实现了分层上下文管理系统：

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。
• 任务级上下文：暂存区提供临时但聚焦、易于管理的内容块，并共享记忆
• 子 Agent 隔离：每个子 Agent 只能看到相关上下文，避免信息过载
• 降低主 Agent 的上下文负担：编排器只需了解高层结果，无需查看详细研究内容
• 持久化知识：项目状态可跨多个聊天会话保留

自动安装和创建用户（类 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（可选）：使用子 Agent 工具时，在 .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
  • 运行（持久化数据库并设置管理员密钥）：

   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 以使用子 Agent。
• 本地构建：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）。子 Agent 可访问这些文件，并可使用 AI 自动生成摘要。可通过 UI 的 Files 选项卡上的 “OCR” 按钮对 PDF 进行 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 sidecar（设置 force=true 可重新生成）
• POST /project/files/process-all?project_id=...：批量处理项目目录中的所有 PDF（可选设置 force=true）

PDF OCR Sidecar

• 配置 Mistral（MISTRAL_AI_API/MISTRAL_API_KEY）或本地模型（USE_LOCAL_AI_FOR_DOC_UNDERSTANDING=true）后，上传 PDF 会自动加入 OCR 队列。上传响应会立即返回；处理任务在后台运行。
• OCR 输出与二进制文件存放在一起，路径为 data/<project_id>/<file_id>.ocr.json，采用提供方的原生格式（{ pages: [...] }）。
• 摘要和外部 AI 调用仍会附带原始 PDF；如果存在 sidecar，也会一并提供提取出的 Markdown，以便仅支持文本的提供方获取完整上下文。
• 本地 OCR 需要在 PATH 中提供 pdftoppm（来自 poppler-utils），以便将 PDF 拆分为逐页 PNG 文件。

MCP 端点

• 基础路径：POST /mcp（Streamable 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 提供服务：

• 用于任务管理的看板，支持拖放
• 支持 Markdown 的 AGENTS.md 编辑器
• 用于文档上传、管理和描述的 Files 选项卡（可通过子 Agent 生成描述）。
• 项目共享与协作
• 提交历史和版本控制

开发模式：运行 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 }。共享参与者只能还原到其最近连续操作序列中的提交（以防丢弃其他人的工作）。历史记录会截断至该位置（不支持分支）。
• list_file：列出项目已上传的文档 { project_id }。返回每个文件的原始文件名、描述和供参考的 file_id。
• read_project_file：读取已上传项目文档的特定片段 { project_id, file_id, start?, length?, pages? }。返回 UTF-8 文本（PDF 会解析为文本）。默认值为 start=0、length=10000。对于已处理的 PDF，请使用 pages="1-3,5"，而非 start/length。（仅在 USE_EXTERNAL_AI=false 时启用），Agent 只能选择按片段或按页读取。 临时记事板（临时、按会话）工具：
• 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 子 Agent（仅当 USE_EXTERNAL_AI 不为 false 时显示）：

• scratchpad_subagent：启动子 Agent 来处理记事板任务 { 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；此处不提供列表或删除工具。目前“预期”由外部清理工具在会话结束后移除。
• 在同一会话期间，Agent 必须通过 (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 的 Chat）：取决于你的端点；不提供子 Agent 工具。
• 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 提供方配置：

• 将 MCP 客户端配置放在仓库根目录的 subagent_config.json 中。本仓库中包含示例。
• 在 mcpServers 下定义服务。远程服务使用 { "serverUrl": "https://.../mcp" }（HTTP）或 .../sse（SSE；旧版协议，但仍受支持）。本地 stdio 服务使用 { "command": "...", "args": [ ... ] }。
• 为每个服务添加简短的一行 short_descriptions，帮助 Agent 进行选择（推荐）。最简示例请参阅仓库中的 subagent_config.json。

许可证

MIT。详见 LICENSE。