Mcp Http Agent Md

笔记 JavaScript

🚀 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
• 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 跟踪长期任务，更多信息请参考 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:///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":"","target_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
• 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 跟踪长期任务，更多信息请参考 agents.md。
任务范围上下文：便签提供临时但专注、可管理的块，并具有共享内存。
子代理隔离：每个子代理仅查看相关上下文，防止信息过载。
主代理低上下文：协调器仅需要高级结果，而不需要详细的研究。
持久知识：项目状态在多个聊天会话中保持不变。

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE。

0 条评论
分类：笔记

Mcp Http Agent Md

🚀 mcp-http-agent-md

🚀 快速开始

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

手动安装

环境配置

使用 Node 运行

Docker

✨ 主要特性

架构概述

📦 安装指南

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

手动安装

环境配置

使用 Node 运行

Docker

💻 使用示例

端点使用示例

管理 API

MCP 端点

列出工具

Web UI 使用示例

开发模式

生产模式

工具使用示例

列出项目

初始化项目

删除项目

重命名项目

读取 AGENTS.md

写入 AGENTS.md

读取项目进度

添加项目进度

更新任务状态

生成任务 ID

获取 AGENTS.md 最佳实践和示例

列出项目日志

回滚项目

初始化便签

查看便签

更新便签任务

追加便签共享内存

启动子代理

检查子代理运行状态

📚 详细文档

认证和管理

创建用户

定义

项目共享

只读共享项目给其他用户

定义

MCP 端点

列出工具

Web UI (/ui)

开发模式

生产模式

工具

便签（临时，每个会话）工具

外部 AI 子代理（仅当 USE_EXTERNAL_AI 不为 false 时显示）

注意事项

项目选择

提供商和模型

示例（.env）

MCP 提供商配置

🔧 技术细节

架构概述

主要优势

📄 许可证

0 个评论

相似服务问题

相关AI产品

热议话题 »

外部 AI 子代理（仅当 `USE_EXTERNAL_AI` 不为 `false` 时显示）