Name: AI代理HTTP服务器
Author: benhaotang

使用说明

mcp-http代理md

用于AGENTS.md和结构化任务的最小MCP（模型上下文协议）HTTP服务器，具有版本化历史记录（日志/恢复）和临时草稿栏，通过可流式HTTP端点公开。草稿栏还可以用于生成上下文隔离的子代理（通过Gemini、OpenAI、Groq、OpenAI兼容或MCP+OpenAI兼容），以解决专注的任务。还提供了一个身份验证中间件，用于用户隔离和公共服务。用户还可以在服务器内共享和协作项目。

由Codex（OpenAI）共同撰写。

架构概述

该项目为从事长期项目的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跟踪长期任务，阅读更多特工.md.
任务范围上下文：Scratchpad提供临时但集中、可管理的块，具有共享内存
亚代理隔离：每个子代理只看到相关上下文，防止信息过载
主代理上下文低：编排者只需要高层次的结果，而不需要详细的研究
持久的知识：项目状态在多个聊天会话中保持不变

自动安装和用户创建（类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

手动安装

首先，克隆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

本地

{
  "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.

创建用户（返回 { 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":"<project_id>","target_user_id":"<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/<project_id>/<file_id>.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.

使用说明

mcp-http代理md

架构概述

自动安装和用户创建（类Unix系统）

手动安装

环境

使用Node运行

码头工人

端点

身份验证和管理

定义

项目共享

定义

项目文件

定义

PDF OCR边车

MCP端点

Web用户界面（/UI）

工具

供应商和模型

许可证

相关 MCP

网页抓取与搜索MCP服务器

规范工作流管理工具

用户名搜索MCP服务器

Jupyter笔记本MCP服务器

协议桥接服务器

Claude Code开发工具包