麦普-http代理-微版本

Name: 麦普-http代理-微版本
Author: benhaotang

作者：benhaotang5 星标更新：2025-11-16

安装使用来源：spider==github.com

项目介绍

mcp-http-agent-md

这是一个最小化的MCP（模型上下文协议）HTTP服务器，用于AGENTS.md和结构化任务，带有版本历史记录（日志/回滚）和一个临时草稿垫，通过可流式传输的HTTP端点暴露。草稿垫也可以用来生成上下文隔离的子代理（通过Gemini、OpenAI、Groq、兼容OpenAI或MCP+兼容OpenAI），以解决特定任务。还提供了一个认证中间件，用于用户隔离和公共服务。用户还可以在服务器内共享和协作项目。

共同作者：Codex（OpenAI）。

架构概述

该项目实现了一个分层上下文管理系统，用于长期项目的AI代理：

graph LR
    subgraph "完整项目知识"
        PK["📚 整个项目<br/>• 所有代码文件<br/>• 所有文档<br/>• 网络资源<br/>• 工具输出<br/>海量上下文"]
    end
    
    subgraph "压缩知识"
        A["📄 AGENTS.md<br/>(基本知识)"]
        P["📋 progress.md<br/>(任务板)"]
    end
    
    subgraph "主代理"
        MA["🧠 调度器<br/>低上下文<br/>• 阅读压缩知识<br/>• 创建草稿垫<br/>• 更新项目状态"]
    end
    
    subgraph "草稿垫"
        CM["通用记忆<br/>(共享上下文)"]
        
        subgraph "任务池"
            T1["任务 1"]
            T2["任务 2"]
            T3["任务 ..."]
        end
        
        subgraph "子代理"
            SA1["🤖 代理 1<br/>高上下文"]
            SA2["🤖 代理 2<br/>高上下文"]
        end
    end
    
    %% 知识压缩流程
    PK --> |压缩为| A
    PK --> |压缩为| P
    
    %% 主代理阅读压缩知识
    A --> MA
    P --> MA
    
    %% 主代理创建包含较小任务的草稿垫
    MA --> |分解为任务| T1
    MA --> |分解为任务| T2
    MA --> |分解为任务| T3
    MA --> |维护| CM
    
    %% 主代理可以直接读写
    MA <--> |读写| CM
    MA <--> |读写| T1
    MA <--> |读写| T2
    MA <--> |读写| T3
    
    %% 任务生成子代理
    T1 --> |生成| SA1
    T2 --> |生成| SA2
    
    %% 子代理获取上下文并处理特定任务
    SA1 --> |完全访问| PK
    SA2 --> |完全访问| PK
    CM --> |共享上下文| SA1
    CM --> |共享上下文| SA2
    
    %% 子代理向其任务报告结果
    SA1 --> |结果/评论| T1
    SA2 --> |结果/评论| T2
    
    %% 主代理更新压缩知识
    MA --> |更新| A
    MA --> |更新| 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或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              # 可选
AI_ATTACHMENT_TEXT_LIMIT=120000  # 可选；-1保留全部提取文本

[!NOTE] 对于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：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）。这些文件对子代理可用，并可以自动通过AI进行总结。PDF可以通过UI文件标签中的“OCR”按钮进行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侧车（设置force=true以重新生成）
POST /project/files/process-all?project_id=...：批量处理项目目录中的每个PDF（可选force=true）

PDF OCR侧车

当配置了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，但如果存在侧车，则还会提供提取的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 (/ui)

WebUI看板视图

一个可选的轻量级管理控制台（Next.js应用路由器）捆绑并托管在/ui：

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

开发模式：当您运行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。
- 锁定规则：当任务（或任何祖先）完成或归档时，不允许编辑该任务或其后代，除非解锁任务本身为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 }。返回每个文件的原始文件名、描述和文件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时启用），代理可以选择按块或按页读取。

草稿垫（瞬态，会话级别）工具：

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?, file_id?, file_path? }。工具依赖于提供商（AI_API_TYPE）。标准工具：grounding（搜索）、crawling（网络抓取）、code_execution（执行代码）。自动将common_memory附加到提示中。可以通过file_id（来自list_file）或file_path