内容
# Hermes 看板 MCP 服务器
一个独立的[模型上下文协议](https://modelcontextprotocol.io)服务器，暴露Hermes Agent的看板SQLite数据库给**任何**支持MCP的客户端——Claude Code、Codex、Cursor、VS Code等。服务器读取和写入与Hermes本身使用的**相同**数据库，因此外部AI代理创建的任务由Hermes调度，Hermes创建的任务可以从编辑器中读取、评论和完成。
## 为什么
Hermes Agent的看板是其跨配置文件协调的基元：调度器声明任务，派生工作线程，跟踪运行和交接，并解决依赖关系。直到现在，只有Hermes构建的代理才能访问此看板。此MCP服务器允许任何外部代理参与，而无需依赖Hermes Python包。
## 工具（13）
| 工具 | 用途 |
|---|---|
| `kanban_list` | 列出任务（按状态/指派人/租户筛选）。 |
| `kanban_show` | 显示任务完整状态：正文、父任务、子任务、评论、事件、运行、预格式化工作线程上下文。 |
| `kanban_context` | 显示格式化的工作线程上下文Markdown（比`kanban_show`轻量）。 |
| `kanban_create` | 创建任务（可选父任务、租户、优先级、技能、工作区类型、幂等键、最大运行时秒数、分类）。 |
| `kanban_complete` | 将任务状态从`running|ready|blocked`转换为`done`，并附上摘要和结构化元数据。 |
| `kanban_block` | 将任务状态从`running|ready`转换为`blocked`，并附上原因。 |
| `kanban_unblock` | 将任务状态从`blocked`转换为`ready`。 |
| `kanban_claim` | 原子操作：将任务状态从`ready`转换为`running`，并返回工作区路径。 |
| `kanban_assign` | （重新）分配配置文件。如果任务正在运行，则拒绝。 |
| `kanban_link` | 添加父子依赖关系。拒绝循环依赖。 |
| `kanban_unlink` | 删除父子依赖关系。 |
| `kanban_comment` | 在任务线程中追加Markdown评论。 |
| `kanban_heartbeat` | 长运行操作的活跃信号。 |
## 数据库兼容性
服务器使用Hermes的精确模式——`tasks`、`task_links`、`task_comments`、`task_events`、`task_runs`、`kanban_notify_subs`——并具有相同的WAL编译器和`BEGIN IMMEDIATE`写入事务。SQLite序列化并发写入者，因此此服务器可以在同一数据库上与运行的Hermes调度器共存，无需协调。
## 安装
需要Python 3.10+（Hermes本身目标为3.11+，但此服务器仅使用自3.10起的标准库功能）。
```bash
git clone <此仓库> /mnt/s3vo/hermes-kanban-mcp
cd /mnt/s3vo/hermes-kanban-mcp
python3 -m venv .venv
.venv/bin/pip install 'mcp[cli]>=1.0.0'
# （可选）运行测试套件
.venv/bin/pip install pytest
.venv/bin/pytest tests/
```
## 环境变量
数据库路径从以下环境变量中解析（优先级从高到低）：
| 变量 | 影响 |
|---|---|
| `HERMES_KANBAN_DB` | 直接固定数据库文件路径。优先级最高。 |
| `HERMES_KANBAN_HOME` | 根目录，用于锚定看板路径。回退到`HERMES_HOME`，然后是`~/.hermes`。 |
| `HERMES_HOME` | 当`HERMES_KANBAN_HOME`未设置时使用的根目录。 |
| `HERMES_KANBAN_BOARD` | 看板slug。`default`（新安装时唯一的看板）位于`<root>/kanban.db`；其他看板位于`<root>/kanban/boards/<slug>/kanban.db`。 |
| `HERMES_KANBAN_TASK` | 在省略时，`kanban_show`/`kanban_complete`/`kanban_block`/`kanban_comment`/`kanban_heartbeat`/`kanban_context`的隐含`task_id`。在Hermes调度器派生的工作线程中很有用。 |
| `HERMES_PROFILE` | `kanban_comment`的默认`author`（回退到`mcp-client`）。 |
## 客户端设置
### Claude Code
```bash
claude mcp add kanban -- /mnt/s3vo/hermes-kanban-mcp/.venv/bin/python /mnt/s3vo/hermes-kanban-mcp/server.py
```
在Claude Code中，输入`/mcp`以验证服务器是否已连接，或者只需要求代理“列出我的看板任务”—工具路由器将调度到`kanban_list`。
### Codex / Cursor / VS Code
在MCP配置文件（`.mcp.json`或客户端特定文件）中添加一个条目：
```jsonc
{
"mcpServers": {
"kanban": {
"command": "/mnt/s3vo/hermes-kanban-mcp/.venv/bin/python",
"args": ["/mnt/s3vo/hermes-kanban-mcp/server.py"],
"env": {
"HERMES_KANBAN_BOARD": "default"
}
}
}
}
```
使用此仓库中的`.mcp.json`作为参考。
### Hermes（自测试）
```bash
hermes mcp add kanban --command /mnt/s3vo/hermes-kanban-mcp/.venv/bin/python /mnt/s3vo/hermes-kanban-mcp/server.py
hermes mcp test kanban
```
## 验证
端到端健全性：
```bash
# 1. 服务器启动并在标准输入/输出上等待
echo "" | .venv/bin/python server.py # 按Ctrl-C退出
# 2. 单元测试通过
.venv/bin/pytest tests/
# 3. 跨工具数据库兼容性（已安装Hermes）
hermes kanban list # 查看Hermes显示的内容
# 然后在Claude Code中：
# "列出我的看板任务" # 应该显示相同的行
```
## 状态流程回顾
```
分类 ──规格──▶ 待办
│
│ 所有父任务完成
▼
运行 ◀──声明── 就绪 ◀── （重新计算就绪）
│
├─ 完成 ──▶ 已完成
├─ 阻塞 ──▶ 已阻塞 ──取消阻塞──▶ 就绪
└─ 存档 ──▶ 已存档
```
## 限制/范围
- 无看板管理命令（使用Hermes `hermes kanban boards ...`）。
- 无通知订阅（`kanban_notify_subs`）读写。
- 无工作流模板（`workflow_template_id`）控制。
- 仅标准输入/输出传输（无SSE/HTTP）。
- 工具始终对启动时从环境变量中解析的**单个**看板进行操作。通过在启动服务器前设置`HERMES_KANBAN_BOARD`来切换看板。
