内容
[](LICENSE)
[](https://rustup.rs/)
[](https://github.com/herdr-mcp)
[](https://github.com/herdr-mcp)
[](https://github.com/herdr-mcp)
# herdr-mcp
MCP（模型上下文协议）服务器，使用 Rust 编写，暴露 [herdr](https://herdr.dev) —— 一个终端原生的代理多路复用器 —— 作为工具。
**HTTP 桥接 + 交互式网页游乐场** 已包含：运行单个工具或将它们链接成多步骤的配方，并传递变量，所有操作都可以在浏览器中完成。
- [快速入门](#快速入门)
- [功能](#功能)
- [架构](#架构)
- [文档](#文档)
- [安装和构建](#安装和构建)
- [用法](#用法)
- [MCP 模式](#mcp-模式)
- [HTTP + 网页游乐场](#http--网页游乐场)
- [HTTP API](#http-api)
- [配方格式](#配方格式)
- [环境](#环境)
- [工具（49）](#工具49)
- [开发](#开发)
- [贡献](#贡献)
- [许可证](#许可证)
---
## 快速入门
```bash
cargo build --release
./target/release/herdr-mcp
```
需要 `herdr` 命令行工具位于 `PATH` 中（[安装](https://herdr.dev)）。
对于网页游乐场：
```bash
cargo build --release
./target/release/herdr-mcp serve --http 7676 --http-only
# 打开 http://localhost:7676/
```
---
## 功能
- **MCP 模式** — 插入任何与 MCP 兼容的客户端（Claude Desktop、Cursor、Claude Code、Continue、OpenCode）以控制 herdr 工作区、标签、窗格和代理
- **HTTP 桥接** — 内置 Axum HTTP 服务器实现基于浏览器的交互
- **网页游乐场** — 完整的 React 用户界面，用于探索和调用工具、构建配方和检查结果
- **49 个工具** — 发现、生命周期、读取、写入、同步、a2a 原语、消息修剪、配方模板、调度器和文件夹密钥操作，针对 herdr
- **配方引擎** — 链接多个工具调用，带有变量插值（`{{ stepId.result.path }}`）
- **消息修剪管道** — `caveman`（有损风格）和 `pfc1`（无损 Cherokee 音节文字语音）压缩器，用于代理到代理通信
- **4- crate 工作区** — `herdr-mcp-core`、`herdr-mcp-trim`、`herdr-mcp-server`、`herdr-mcp-cli`（233 个测试，均通过）
- **无外部依赖**，除了 herdr 本身 — 通过 `tokio::process::Command` 调用命令行工具
---
## 架构
```mermaid
graph TB
subgraph MCP[" "]
direction LR
AI(["AI 客户端<br/>(Claude Desktop, Cursor 等)"])
STDIO["herdr-mcp<br/>(stdio JSON-RPC)"]
AI -- stdin/stdout --> STDIO
end
subgraph HTTP[" "]
direction LR
B1["浏览器<br/>(localhost:5173)"]
VITE["Vite 开发服务器<br/>(代理 /api)"]
B2["浏览器<br/>(localhost:8080)"]
AXUM["Axum HTTP 桥接<br/>(端口 8080)"]
B1 --> VITE -- 代理 --> AXUM
B2 --> AXUM
end
subgraph CORE[" "]
TOOL["herdr-mcp server.rs<br/>(工具调度 + 配方引擎)"]
CLI["herdr 命令行工具<br/>(tokio::process::Command)"]
end
STDIO --> TOOL
AXUM --> TOOL
TOOL --> CLI
CLI --> DAEMON["herdr 守护进程<br/>(工作区、标签、窗格、代理)"]
```
服务器是一个薄的包装层，它调用本地的 `herdr` 命令行工具。它支持两种传输模式：
- **MCP stdio** — 通过 stdin/stdout 使用 JSON-RPC，兼容所有 MCP 客户端
- **HTTP 桥接** — 当提供 `--http <port>` 时，与 MCP 服务器一起运行；网页游乐场通过 HTTP 通信
**为什么调用而不是直接使用 socket 协议？** herdr 的线协议没有公开记录，可能会更改；命令行工具是稳定且有文档的接口。零耦合，容易保持更新。
### 项目结构
```
herdr-mcp/
├── crates/
│ ├── herdr-mcp-core/ # 配置系统（TOML + env + 命令行工具）、错误类型
│ ├── herdr-mcp-trim/ # 消息修剪管道（caveman、pfc1、文件夹密钥、仪表盘）
│ ├── herdr-mcp-server/ # MCP 服务器、49 个工具、HTTP 桥接、配方引擎、事件订阅者
│ └── herdr-mcp-cli/ # 二进制入口点（serve/trim/dashboard/folder-key）
├── src/
│ ├── main.rs # 遗留的单体二进制入口点
│ ├── server.rs # 遗留的单体服务器：21+ 工具定义、HTTP 桥接、配方引擎
│ ├── main.tsx # React 入口点（Vite + Tailwind + TypeScript）
│ ├── App.tsx # HashRouter：主页 / 文档 / 网页游乐场 / 修剪 / 变量
│ ├── components/ # 主页 + 文档 + 网页游乐场组件
│ └── recipes/ # 前端 TypeScript 配方类型
├── Cargo.toml # 4-成员工作区 — rmcp、axum、clap、tokio
├── package.json # Vite + React 19 + Tailwind 4 + react-router-dom + @dnd-kit
├── vite.config.ts # vite-plugin-singlefile，/api 代理 → localhost:8080
└── index.html
```
4-crate 工作区是新代码的规范家园；`src/` 单体是遗留代码。参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 以获取完整参考。
---
## 文档
| 文档 | 描述 |
|---|---|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 综合架构参考：数据流、工具参考、HTTP API、配方引擎、修剪系统、代理注册、持久性、调度器、前端、依赖项、构建/运行、设计决策、已知问题 |
| [docs/PRD.md](docs/PRD.md) | 产品需求文档 |
| [AGENTS.md](AGENTS.md) | 跨工具代理说明，用于 AI 编程助手（约定、风险等级、工作流、反模式） |
| [compressorplan.md](compressorplan.md) | 消息修剪设计计划（caveman + pfc1） |
| [a2a.md](a2a.md) | 代理到代理原始设计和用法 |
| [TEST_PLAN.md](TEST_PLAN.md) | 测试套件规范（4 个 crate 中的 233 个测试） |
| [herdmcp.toml](herdmcp.toml) | 持久化配置（HTTP 端口、数据目录、herdr 套接字） |
---
## 安装和构建
### 需求
- [Rust](https://rustup.rs/) 1.75+
- [herdr](https://herdr.dev) 命令行工具位于 `PATH`
- [Node.js](https://nodejs.org/) 20+（仅用于网站开发）
### 从源码构建
```bash
git clone <仓库网址>
cd herdr-mcp
# 构建 MCP 服务器二进制文件
cargo build --release
# 构建网站（可选 — 单个 HTML 文件）
npm install
npm run build
```
### 命令行标志
| 标志 | 描述 |
|------|-------------|
| `--http <port>` | 在给定端口上启动 HTTP 桥接 |
| `--http-only` | 仅运行 HTTP 服务器（跳过 MCP stdio 传输） |
### 持久化配置
创建 `herdmcp.toml` 文件在工作目录中以设置默认值：
```toml
# herdmcp.toml - herdr-mcp 的持久化配置
# 此文件在 herdr-mcp 启动时从当前工作目录读取。
[persistent]
# HTTP 桥接端口（默认值：7676）。命令行标志 --http 覆盖此设置。
http_port = 7676
# 用于配方、会话、修剪统计、PFC1 内存的数据目录（默认值：./data）
data_dir = "./data"
# herdr 守护进程套接字路径（默认值：~/.config/herdr/herdr.sock）
herdr_socket = "~/.config/herdr/herdr.sock"
```
`herdmcp.toml` 中的所有设置都可以通过命令行标志和环境变量覆盖。
---
## 用法
### MCP 模式
```bash
./target/release/herdr-mcp
```
添加到您的 MCP 客户端配置：
```json
{
"mcpServers": {
"herdr-mcp": {
"command": "/path/to/herdr-mcp"
}
}
}
```
默认情况下，这会启动 MCP stdio 传输 **和** HTTP 桥接，端口为 **7676**。
### HTTP + 网页游乐场
```bash
# 启动服务器，HTTP 桥接端口为 7676（默认），跳过 MCP stdio 传输
./target/release/herdr-mcp serve --http 7676 --http-only
# 打开 http://localhost:7676/
```
用于网站开发的热重载：
```bash
# 终端 1：Rust HTTP 服务器
cargo run --release -- serve --http 7676 --http-only
# 终端 2：Vite 开发服务器（代理 /api → localhost:7676）
npm run dev
# 打开 http://localhost:5173/
```
### HTTP API
所有端点均返回 JSON。有关完整的路由参考，请参见 [docs/ARCHITECTURE.md §5](docs/ARCHITECTURE.md#5-http-bridge-api)。
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/api/health` | 健康检查 → `"ok"` |
| `GET` | `/api/tools` | 列出所有 49 个工具及其 JSON 模式 |
| `POST` | `/api/tools/:name` | 按名称调用工具，请求体为参数对象 |
| `POST` | `/api/recipe` | 执行具有变量插值的多步骤配方 |
| `GET` | `/api/recipes` | 列出已保存的配方 |
| `POST` | `/api/recipes` | 创建配方 |
| `GET` / `PUT` / `DELETE` | `/api/recipes/:id` | 获取 / 更新 / 删除配方 |
| `POST` | `/api/recipes/:id/run` | 按 ID 运行配方 |
| `GET` | `/api/trim/status` | 聚合修剪节省（查询：`?workspace_id=`） |
| `POST` | `/api/trim/diagnose` | 端到端修剪就绪检查 |
| `GET` | `/api/variables` | 列出所有变量 |
### 配方格式
```json
{
"name": "可选名称",
"steps": [
{
"id": "step1",
"tool": "list_workspaces",
"params": {},
"description": "获取工作区"
},
{
"id": "step2",
"tool": "read_pane",
"params": {
"pane_id": "{{ step1.result.content[0].workspaces[0].active_tab_id }}",
"source": "visible"
},
"description": "读取第一个窗格"
}
]
}
```
变量使用 `{{ stepId.result.path }}` 语法从前一步骤的结果中解析，具有点/括号导航。
### 环境
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `HERDR_BIN` | `herdr` | herdr 命令行工具路径 |
| `RUST_LOG` | `herdr_mcp=info` | 跟踪过滤器 |
---
## 工具（49）
完整参数参考：[docs/ARCHITECTURE.md §4](docs/ARCHITECTURE.md#4-mcp-tool-reference-49-tools-total)。
### 发现（7）
| 工具 | 描述 |
|------|-------------|
| `status` | 获取整体 herdr 服务器状态 |
| `list_workspaces` | 列出所有工作区 |
| `list_tabs` | 列出标签（可选，按工作区） |
| `list_panes` | 列出窗格（可选，按工作区） |
| `list_agents` | 列出所有检测到的代理 |
| `get_pane` | 按 pane_id 或标签获取窗格详细信息 |
| `get_agent` | 获取代理详细信息 |
### 生命周期（5）
| 工具 | 描述 |
|------|-------------|
| `create_workspace` | 创建新的工作区 |
| `create_tab` | 创建新的标签 |
| `split_pane` | 向右或向下拆分窗格（按 pane_id 或标签） |
| `close_pane` | 按 pane_id 或标签关闭窗格 |
| `start_agent` | 在新的窗格中启动代理 |
### 读取（2）/ 写入（4）
| 工具 | 描述 |
|------|-------------|
| `read_pane` | 从窗格中读取输出（按 pane_id 或标签） |
| `read_agent` | 从代理读取输出 |
| `send_text` | 向窗格发送文本（无 Enter，按 pane_id 或标签） |
| `send_keys` | 向窗格发送按键（按 pane_id 或标签） |
| `run_command` | 在窗格中运行命令（文本 + Enter，按 pane_id 或标签） |
| `send_agent` | 向代理发送文本 |
### 同步（3）
| 工具 | 描述 |
|------|-------------|
| `wait_output` | 在窗格中等待特定输出（按 pane_id 或标签） |
| `wait_pane_agent_status` | 等待窗格的代理状态（按 pane_id 或标签） |
| `wait_agent_status` | 按目标等待代理状态 |
### A2A 原语（5）
| 工具 | 描述 |
|------|-------------|
| `agent_spawn` | 生成代理，注册角色→窗格，等待依赖项，捕获输出 |
| `agent_message` | 发送消息，可选修剪；遵守每个窗格的策略 |
| `agent_read` | 读取 + 存储为工作产品；自动解压 PFC1 |
| `agent_wait` | 按角色/窗格等待代理 |
| `agent_list` | 列出注册代理 |
### 会话变量（2）/ 消息修剪（8）/ 配方（3）/ 调度器（4）/ 文件夹密钥（4）
| 工具 | 描述 |
|------|-------------|
| `var_get` / `var_set` | 获取 / 设置会话变量 |
| `compress` / `decompress` | PFC1/Caveman 修剪往返 |
| `trim_policy_get` / `trim_policy_set` | 读取 / 附加修剪策略到代理 |
| `trim_eval` / `trim_bench` / `trim_status` / `trim_diagnose` / `trim_summary` / `trim_dashboard_open` | 修剪分析和仪表盘 |
| `list_templates` / `get_template` / `instantiate_template` | 捆绑的配方模板 |
| `schedule_recipe` / `list_schedules` / `delete_schedule` / `enable_schedule` | 基于 cron 的配方调度 |
| `build_folder_key` / `get_folder_key` / `list_folder_keys` / `decompress_with_folder_key` | 按文件夹的 PFC1 密钥 |
**重要：** ID 是会话本地的，当项目关闭时可能会压缩。在结构更改后，请从列表命令中重新读取 ID。
所有以窗格为目标的工具都接受一个可选的 `label` 参数，作为 `pane_id` 的替代方案 — 服务器通过 `herdr pane list` 自动查找标签。
---
## 开发
参见 [AGENTS.md](AGENTS.md) 以获取完整的代理特定开发约定、构建命令和设计说明。参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 以获取综合架构参考。
```bash
# 终端 1：带有 HTTP 桥接的 Rust 服务器
cargo run --release -- --http 8080 --http-only
# 终端 2：Vite 开发服务器
npm run dev
# 完整的测试套件（4 个 crate 中的 233 个测试）
cargo test --workspace
```
- Rust 代码位于 `crates/`（4-crate 工作区）；遗留的 `src/server.rs` 单体也在其中
- 网站是一个单页 React 应用，通过 `vite-plugin-singlefile` 捆绑到 `dist/index.html`
- 4 个 crate 中的 233 个测试（全部通过）：`herdr-mcp-trim`（126）、`herdr-mcp-server`（73）、`herdr-mcp-core`（24）、`herdr-mcp-cli`（10）
- `RUST_LOG` 控制跟踪详细程度；stdout 保留用于 MCP JSON-RPC（stderr 用于日志）
---
## 贡献
请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取有关行为准则和拉取请求过程的详细信息。
所有贡献必须通过 [开发者证书来源 (DCO)](https://github.com/apps/dco/) 进行认证。
---
## 许可证
该项目根据 **GNU Affero 通用公共许可证 v3.0** 许可 — 有关详细信息，请参见 [LICENSE](LICENSE) 文件。
