Benhaotang MCP

MCPAI代理

提供方 benhaotang

AI代理 stdio · 本地进程 Token 社区 / 第三方
查看接入方式

一个用于结构化任务和代理协作的HTTP服务器,支持版本历史记录、临时工作区和子代理生成。

一句话选型结论

按资料字段整理

Benhaotang MCP 属于AI代理类 MCP 服务器,stdio · 本地进程,Token,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式stdio · 本地进程 鉴权Token 部署方式本地部署
GitHub 星标 5 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

适用场景

AI代理JavaScript本地部署HTTP服务器任务管理协作工具知识管理

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
docker run -it --restart always \

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Docker,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Benhaotang MCP当前 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方benhaotang上游标注的维护方 benhaotang
分类AI代理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Docker本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

15.9 KB
来自项目仓库与上游目录的原文,未做删改

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=&quot;gemini-2.5-pro&quot;  # 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
{
&quot;mcpServers&quot;: {
&quot;mcp-agent-md&quot;: {
&quot;command&quot;: &quot;npx&quot;,
&quot;args&quot;: [&quot;-y&quot;,&quot;mcp-remote&quot;,&quot;http://localhost:3000/mcp?apiKey=USER_API_KEY`&quot;]
}
}
}
  • 远程```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 &quot;Authorization: Bearer $MAIN_API_KEY&quot; \
-H &quot;Content-Type: application/json&quot; \
-d &#x27;{&quot;name&quot;:&quot;alice&quot;}&#x27;

定义

基地: /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 &#x27;http://localhost:3000/mcp?apiKey=USER_API_KEY&#x27; \
-H &#x27;Content-Type: application/json&#x27; \
-d &#x27;{&quot;jsonrpc&quot;:&quot;2.0&quot;,&quot;id&quot;:&quot;1&quot;,&quot;method&quot;:&quot;tools/list&quot;}&#x27;

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: &quot;...&quot; }` 哪里 `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: [&quot;abcd1234&quot;, ...] }`.
- get_agents_md_best_pactices_and_examples:从返回最佳实践和示例 `example_agent_md.json`默认情况下仅返回 `the_art_of_writing_agents_md` (最佳实践)。使用 `include=&#x27;all&#x27;` 包括所有示例或集合 `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: &#x27;open&#x27;|&#x27;complete&#x27;, 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=&quot;gemini-2.5-pro&quot;

# OpenAI
# AI_API_TYPE=openai
# AI_MODEL=&quot;gpt-5-mini&quot;

# Groq
# AI_API_TYPE=groq
# AI_MODEL=&quot;openai/gpt-oss-120b&quot;

# OpenAI‑compatible (e.g., LM Studio)
# AI_API_TYPE=compat
# AI_BASE_ENDPOINT=&quot;http://localhost:1234/v1&quot;
# AI_MODEL=&quot;qwen/qwen3-4b-2507&quot;

# MCP + OpenAI‑compatible
# AI_API_TYPE=mcp
# AI_BASE_ENDPOINT=&quot;http://localhost:1234/v1&quot;
# AI_MODEL=&quot;qwen/qwen3-4b-2507&quot;

MCP提供程序配置:

  • 将MCP客户端配置放入 subagent_config.json 在repo根目录下。示例包含在此repo中。
  • 在下定义服务器 mcpServers。对于远程服务器,请使用 { &quot;serverUrl&quot;: &quot;https://.../mcp&quot; } (HTTP)或 .../sse (苏格兰和南方能源公司;传统但受支持)。对于本地stdio服务器,请使用 { &quot;command&quot;: &quot;...&quot;, &quot;args&quot;: [ ... ] }.
  • 添加一条短横线 short_descriptions 每台服务器,以帮助代理进行选择(推荐)。查看回购 subagent_config.json 举个最小的例子。

许可证

MIT。看 LICENSE.

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Benhaotang MCP 怎么安装?

在客户端按下面的安装命令接入:docker run -it --restart always \。装完在客户端配置里引用同一个包或端点。

Benhaotang MCP 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

Benhaotang MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Benhaotang MCP 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

Benhaotang MCP 能提供哪些能力?

资料显示能力标签包括 AI代理、协作工具、JavaScript、知识管理、HTTP服务器。具体工具清单以官方文档为准。

Benhaotang MCP 需要什么运行环境?

运行时为 Docker;属于本地进程,需要在本机装好运行环境。

Benhaotang MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。