mcp-http代理md
用于AGENTS.md和结构化任务的最小MCP(模型上下文协议)HTTP服务器,具有版本化历史记录(日志/恢复)和临时草稿栏,通过可流式HTTP端点公开。草稿栏还可以用于生成上下文隔离的子代理(通过Gemini、OpenAI、Groq、OpenAI兼容或MCP+OpenAI兼容),以解决专注的任务。还提供了一个身份验证中间件,用于用户隔离和公共服务。用户还可以在服务器内共享和协作项目。
由Codex(OpenAI)共同撰写。
架构概述
该项目为从事长期项目的AI代理实现了一个分层上下文管理系统:```mermaid
graph LR
subgraph "Full Project Knowledge"
PK["📚 Entire Project
• All code files
• All documentation
• Web resources
• Tool outputs
MASSIVE CONTEXT"]
end
subgraph "Compressed Knowledge"
A["📄 AGENTS.md
(Essential Knowledge)"]
P["📋 progress.md
(Task Board)"]
end
subgraph "Main Agent"
MA["🧠 Orchestrator
LOW CONTEXT
• Reads compressed knowledge
• Spawns scratchpads
• Updates project state"]
end
subgraph "Scratchpad"
CM["Common Memory
(Shared Context)"]
subgraph "Task Pool"
T1["Task 1"]
T2["Task 2"]
T3["Task ..."]
end
subgraph "Subagents"
SA1["🤖 Agent 1
HIGH CONTEXT"]
SA2["🤖 Agent 2
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跟踪长期任务,阅读更多 特工.md.
- **任务范围上下文**:Scratchpad提供临时但集中、可管理的块,具有共享内存
- **亚代理隔离**:每个子代理只看到相关上下文,防止信息过载
- **主代理上下文低**:编排者只需要高层次的结果,而不需要详细的研究
- **持久的知识**:项目状态在多个聊天会话中保持不变
## 自动安装和用户创建(类Unix系统)
- 不带docker:(安装到 `$HOME/.config/mcp-http-agent-md` 并从默认用户开始)```bash
curl -fsSL https://raw.githubusercontent.com/benhaotang/mcp-http-agent-md/main/install/install.sh | bash
- 使用docker:(数据持久化
$HOME/.config/mcp-http-agent-md/data)```bash
curl -fsSL https://raw.githubusercontent.com/benhaotang/mcp-http-agent-md/main/install/install-docker.sh | bash
## 手动安装
首先,克隆repo: `git clone https://github.com/benhaotang/mcp-http-agent-md.git`
### 环境
您可以设置中定义的所有环境 .env.示例 在终端通过 `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 并在本地构建图像。看 码头工人.
使用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
码头工人
- 来自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: `http://localhost:3000/auth` (持票人 `MAIN_API_KEY`), **生成一个 `USER_API_KEY` 第一**,请参阅 认证
- MCP端点: `POST http://localhost:3000/mcp?apiKey=USER_API_KEY`
- 本地```json
{
"mcpServers": {
"mcp-agent-md": {
"command": "npx",
"args": ["-y","mcp-remote","http://localhost:3000/mcp?apiKey=USER_API_KEY`"]
}
}
}
- 远程```json
{
"mcpServers": {
"mcp-agent-md": {
"url": "https:///mcp?apiKey=USER_API_KEY",
}
}
}
## 身份验证和管理
- MCP:供应用户 `apiKey` 通过查询 `?apiKey=...` 或 `Authorization: Bearer ...`.
- 管理员:使用 `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 (持票人 MAIN_API_KEY)
- 发布
/auth/users:创建用户→{ id, apiKey, name? } - 获取
/auth/users:列出用户(?reveal=true显示完整密钥) - 获取
/auth/users/:id:获取用户 - 发布
/auth/users/:id/regenerate:旋转API键 - 删除
/auth/users/:id:删除用户
项目共享
通过REST API与其他用户共享项目。基地: /project (承载令牌认证)
与其他用户以只读方式共享项目:```
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":"","target_user_id":"","permission":"ro"}'
### 定义
- 获取 `/project/list`:列出项目(管理员:所有项目,用户:拥有+共享)
- 发布 `/project/share`:共享项目 `{ project_id, target_user_id, permission, revoke? }`.权限: `ro` (只读)或 `rw` (读写)。集 `revoke: true` 删除访问权限。
- 获取 `/project/status?project_id=...`:获取项目共享状态
## 项目文件
上传和管理项目中的文档(PDF、MD、TXT)。子代理可以访问文件,并可以使用AI自动汇总。PDF可以通过带有“OCR”按钮的UI文件选项卡进行OCR处理。
### 定义
基地: `/project/files` (承载令牌认证)
- 发布 `/project/files`:上传文件(≤20MB),可选描述
- 获取 `/project/files?project_id=...`:列出包含元数据的项目文件
- 删除 `/project/files/:fileId?project_id=...`:删除文件
- 发布 `/project/files/:fileId/summarize?project_id=...`:AI摘要文件(需要 `USE_EXTERNAL_AI=true`)
- 发布 `/project/files/:fileId/process?project_id=...`:为单个PDF生成/更新OCR sidecar(设置 `force=true` 再生)
- 发布 `/project/files/process-all?project_id=...`:批量处理项目目录中的每个PDF(可选 `force=true`)
### PDF OCR边车
- 当任一Mistral时,PDF会自动上传排队OCR(`MISTRAL_AI_API`/`MISTRAL_API_KEY`)或本地模型(`USE_LOCAL_AI_FOR_DOC_UNDERSTANDING=true`)已配置。上传响应是即时的;处理在后台运行。
- OCR输出与二进制文件一起存储为 `data//.ocr.json` 使用提供者的原生形状(`{ pages: [...] }`).
- 摘要和外部AI调用会继续附加原始PDF,但当sidecar存在时,也会提供提取的Markdown,因此纯文本提供者具有完整的上下文。
- 本地OCR需要 `pdftoppm` (来自poppler-utils)将于 `PATH` 因此PDF可以拆分为每页的PNG。
## 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)
一个可选的轻量级管理控制台(Next.js App Router)被捆绑在 /ui:
- 拖放式任务管理看板
- 支持markdown的AGENTS.md编辑器
- 用于文档上传、管理和描述的“文件”选项卡(可以通过子代理生成)。
- 项目共享与协作
- 提交历史记录和版本控制
开发模式:运行时自动包含 pnpm dev (热重新加载)。访问 /ui 一旦服务器启动。
生产:构建一次UI,然后以生产模式启动服务器:```
pnpm build:ui
NODE_ENV=production pnpm start
### 工具
- list_projects:列出所有项目名称。
- init_project:创建/init项目 `{ name, agent?, progress? }`。立即创建初始备份(提交)并返回 `hash`.
- delete_project:删除项目 `{ name }`.(仅限所有者)
- 重命名项目:重命名项目 `{ 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_pactices_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 }] }`The `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)。默认设置为开始=0,长度=10000。对于已处理的PDF,请使用pages=“1-3,5”而不是开始/长度。(仅当USE_EXTERNAL_AI=false时启用),代理只能选择按块或按页读取。
Scratchpad(临时性,每次会话)工具:
- scratchpad_initialize:为一次性任务启动一个新的scratchpad `{ 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:通过以下方式更新现有的scratchpad任务 `task_id` `{ name, scratchpad_id, updates }`,在哪里 `updates` 是一个数组 `{ task_id, status?, task_info?, scratchpad?, comments? }`.退货 `{ updated, notFound, scratchpad }`.
- scratchpad_append_common_memory:追加到scratchpad的共享内存 `{ name, scratchpad_id, append }` 哪里 `append` 是字符串或字符串数组。返回更新的草稿行。
外部AI子代理(仅在以下情况下显示 `USE_EXTERNAL_AI` 不是 `false`):
- scratchpad_subagent:启动子代理处理scratchpad任务 `{ 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秒的轮询。
笔记:
- Scratchpad就像RAM一样是瞬态的;此处不提供列表/删除工具。目前,外部清理工具“预计”会在会话后删除它们。
- 代理人必须通过以下方式解决草稿 `(project name, scratchpad_id)` 在同一会话期间重新打开现有会话。
项目选择:所有任务工具都需要 `name` (项目名称)参数;服务器将其解析为内部project_id。您永远不需要提供 `project_id`.
## 供应商和模型
- 谷歌(双子座):双子座-2.5-pro,双子座-2.5-flash
- openai(响应API):目前只有gpt-5、gpt-5-mini、gpt-5-nano
- groq(聊天完成):目前只有openai/gpt-oss-120b、openai/gft-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‑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在repo根目录下。示例包含在此repo中。 - 在下定义服务器
mcpServers。对于远程服务器,请使用{ "serverUrl": "https://.../mcp" }(HTTP)或.../sse(苏格兰和南方能源公司;传统但受支持)。对于本地stdio服务器,请使用{ "command": "...", "args": [ ... ] }. - 添加一条短横线
short_descriptions每台服务器,以帮助代理进行选择(推荐)。查看回购subagent_config.json举个最小的例子。
许可证
MIT。看 LICENSE.
