GCS-ZHN/mcp-sentinel

mcp-sentinel

一个位于 AI agent 与 MCP 服务器之间的 sentinel（哨兵）——代表 agent 轮询长时间运行的任务，使消耗 token 的状态轮询循环永远不会进入 LLM 推理路径。

这是一个 monorepo：一个与 harness 无关的核心（@gcszhn/mcp-sentinel-core），加上每个 agent 宿主一个轻量插件包。

设计原则

零 MCP 重新配置。 sentinel 从不要求用户配置它自己的 MCP
服务器。安装插件就是全部设置——它会发现并复用 harness 已经拥有的 MCP 服务器，无论该 harness 以何种方式暴露它们：

- 来自宿主的 MCP 配置 —— OpenCode。插件读取
client.config.get().mcp，并将解析后的服务器交给核心，由核心
负责连接生命周期。无需额外的 MCP 设置。
- 通过 harness SDK —— DeepSeek Harness。插件调用
已由 @deepseek-ai/dsh-mcp-client 通过 ctx.tools.execute 注册的
mcp____ 工具。无需额外的 MCP 设置。
- 作为与 harness 无关的 MCP CLI —— 任何 harness。mcp-sentinel mcp --harness
是一个普通的 stdio MCP 服务器，它会发现 harness
已经暴露的 MCP 服务器（codex mcp list --json、opencode debug
config，或一个 --mcp-config 文件），并跳过它自己的条目。默认没有消息
通知通道——agent 通过
attach/status/read 收集结果，除非它们通过
mcp_sentinel_set_notifier_commands 选择启用基于命令的通知器。

agent 会立即看到它已经为该 harness 配置好的 MCP 服务器；
无需维护任何 sentinel 专属的 MCP 配置、模拟服务器或演示接线。

支持的 harness

安装说明和每个 harness 的详细信息位于各自插件的 README 中。

| Harness           | 插件包                                                                                                               | 文档                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| OpenCode          | @gcszhn/mcp-sentinel-opencode-plugin                 | README         |
| DeepSeek Harness  | @gcszhn/mcp-sentinel-deepseek-harness-plugin | README |
| 任何 harness（CLI） | @gcszhn/mcp-sentinel-cli                                         | README              |

共享核心单独发布为 @gcszhn/mcp-sentinel-core —— 参见 其 README。

动机
当 agent 通过 MCP 工具提交一个长时间运行的任务时，它必须反复调用服务器来检查进度——每一次往返都会消耗上下文窗口的 token。

sequenceDiagram
participant A as Agent (LLM)
participant M as MCP Server

Note over A: Without sentinel
A->>M: check status
M-->>A: running...
Note over A: token cost 💸
A->>M: check status
M-->>A: running...
Note over A: token cost 💸
A->>M: check status
M-->>A: completed ✓
Note over A: token cost 💸

mcp-sentinel 将轮询循环从 agent 中移出，放入插件运行时——无论任务持续多久，都只需 2 次推理调用。

sequenceDiagram
participant A as Agent (LLM)
participant S as Sentinel Plugin
participant M as MCP Server

A->>S: poll_mcp(server, tool, until)
Note over A: token cost 💸 (once)

loop silent polling (zero tokens)
S->>M: call tool
M-->>S: running...
S->>S: evaluate condition
end

S->>M: call tool
M-->>S: completed ✓
S->>A: promptAsync(result)
Note over A: token cost 💸 (once)

配置

用于控制内存使用的环境变量：

| Variable                | Default   | Description                                       |
| ----------------------- | --------- | ------------------------------------------------- |
| SENTINEL_MAX_POLL_LOG | unlimited | Max poll log entries per task (FIFO trim)         |
| SENTINEL_TASK_TTL_MS  | unlimited | Auto-cleanup completed tasks after N milliseconds |

两者都只接受正整数。零、负数或非数值会被视为无限制/禁用。

工具

mcp_sentinel_poll

提交一个长时间运行的 MCP 工具调用，并按固定间隔轮询它，直到满足某个条件。sentinel 会静默轮询（零 token 成本），并在完成时通知你。

| Parameter  | Type   | Default    | Description                                           |
| ---------- | ------ | ---------- | ----------------------------------------------------- |
| server   | string | _required_ | MCP server name (resolved from the host's MCP config) |
| tool     | string | _required_ | Tool name to call on the server                       |
| args     | object | {}       | JSON object of arguments for the tool                 |
| interval | number | 5000     | Poll interval in milliseconds                         |
| timeout  | number | _optional_ | Max poll duration in ms (unset = no limit)            |
| until    | object | _required_ | JSON condition object                                 |

立即返回一个 sentinel ID。完成时 agent 会收到通知（投递机制因宿主而异）。

args 和 until 是工具参数中的原生 JSON 值——不是 JSON 字符串。interval 会被限制为最小 1000 ms；正的 timeout 会被限制为最小 5000 ms（低于下限的值会被提升）。

mcp_sentinel_status
检查 sentinel 任务的状态、列出活动任务，或取消正在运行的任务。

| 参数      | 类型                                 | 描述                                             |
| --------- | ------------------------------------ | ------------------------------------------------ |
| action  | "status" \| "list" \| "cancel" | 要执行的操作                                     |
| id      | string                               | Sentinel ID（status 和 cancel 必填）         |

mcp_sentinel_attach

阻塞 agent，等待 sentinel 任务完成。在内部休眠并检查状态，token 成本为零。如果被 harness 中断，后台异步通知仍会正常触发。

| 参数      | 类型   | 默认值     | 描述                                             |
| --------- | ------ | ---------- | ------------------------------------------------ |
| id      | string | _必填_     | 要等待的 Sentinel ID                             |
| timeout | number | _可选_     | 最大等待时间（毫秒）（未设置 = 无限期等待）      |

mcp_sentinel_read

读取 sentinel 任务的原始轮询输出。当条件不匹配时，可用于调试——检查实际的 MCP 响应。通过 offset 支持基于范围的分页。

| 参数      | 类型   | 默认值     | 描述                                     |
| --------- | ------ | ---------- | ---------------------------------------- |
| id      | string | _必填_     | 要读取输出的 Sentinel ID                 |
| offset  | number | end-N    | 从 0 开始的起始索引（默认：从末尾开始）  |
| limit   | number | 5        | 返回的最大输出数量                       |

条件模型

条件是纯声明式数据——没有可执行代码，没有注入面。

// Simple comparison
{ "path": "status", "is": "eq", "value": "completed" }

// Array index access
{ "path": "[0].data.path", "is": "eq", "value": "found" }

// Regex match
{ "path": "log", "is": "match", "value": "^error" }

// Logical composition
{
"and": [
{ "path": "status", "is": "eq", "value": "completed" },
{ "path": "tasks[0].exit_code", "is": "eq", "value": 0 }
]
}

运算符

| 运算符     | 描述                                         |
| ---------- | -------------------------------------------- |
| eq       | 严格相等                                     |
| ne       | 不相等                                       |
| gt       | 大于（数值）                                 |
| gte      | 大于或等于                                   |
| lt       | 小于                                         |
| lte      | 小于或等于                                   |
| contains | 字符串包含                                   |
| match    | 正则匹配（new RegExp(value).test(data)）   |

逻辑组合器

| 组合器                   | 描述       |
| ------------------------ | ---------- |
| { "not":  } | 取反       |
| { "and": [...] }       | 所有条件都必须匹配 |
| { "or": [...] }        | 任意一个匹配即可 |

路径语法

使用属性访问表示法，并支持数组索引：

status               → obj.status
tasks[0].exit_code   → obj.tasks[0].exit_code
[0].data.path        → obj[0].data.path
items[2].name        → obj.items[2].name

架构

该项目是一个 monorepo，其中每一层都作为独立的 npm 包发布。核心层对任何宿主一无所知；每个 harness 都是构建在其之上的一个轻量、自包含的包。

分层

| 包                            | 用途                                                                                       | 发布为                                         |
| ----------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| packages/core               | sentinel 引擎、工具处理器、条件求值器、连接池、env、logger、类型                           | @gcszhn/mcp-sentinel-core                    |
| packages/opencode           | OpenCode 适配器：tool() 定义 + client.config.get() + session.promptAsync             | @gcszhn/mcp-sentinel-opencode-plugin         |
| packages/deepseek-harness   | DeepSeek Harness 适配器：通过 ctx.tools.execute + Agent.followup 的外部调用器模式       | @gcszhn/mcp-sentinel-deepseek-harness-plugin |
| packages/cli                | 与 harness 无关的 MCP stdio CLI（mcp-sentinel mcp --harness …）                          | @gcszhn/mcp-sentinel-cli                     |
| packages/（未来）  | 每个宿主一个入口，例如 claude-code                                                       | @gcszhn/mcp-sentinel--plugin        |

核心 / harness 契约

核心层暴露一个 统一的接缝 —— ToolInvoker，一个
(server, tool, args) => Promise 函数，引擎在每次轮询时调用一次
—— 这样每个 harness 都可以接入自己的 MCP 访问策略，而核心层无需知道它运行在哪个宿主之下。

// core — 统一接口（与 harness 无关）
type ToolInvoker = (server: string, tool: string, args: Record) => Promise;

// 核心引擎接受一个调用器，而不是自己读取宿主配置
startSentinel(request, invoke: ToolInvoker): Promise;

构建调用器有两种方式：

1. 连接池模式 —— harness 将宿主的 MCP 配置解析为核心 McpConfig，使用 makeServerResolver 构建 ServerResolver，并将其包装在 makeConnectionInvoker 中，让核心层负责连接生命周期。
2. 外部调用器模式 —— 宿主已经拥有 MCP（例如它自己的桥接已在工具注册表上注册了工具）；harness 传入自己的
(server, tool, args) => result 函数，核心层从不打开连接。

MCP 配置发现是 harness 的职责 —— 不同的宿主获取它的方式
不同的是（OpenCode 通过 client.config.get().data 的 mcp. 扁平键，Codex
通过 codex mcp list --json、一个 --mcp-config 文件，……），而外部调用方
宿主则完全跳过配置发现。

核心的第二个接缝是通知器：一个 harness 通过 setNotifier(task, event) 安装完成
回调，经由宿主的消息通道投递（OpenCode promptAsync、DeepSeek Harness
Agent.followup）。核心对通知如何渲染或推送没有任何意见。

添加一个新的 harness

0. 在它自己的 git worktree 中开发它 —— 一个新的 harness 插件与核心
以及与其他 harness 相互隔离；参见 AGENTS.md。
1. 创建 packages//package.json，命名为 @gcszhn/mcp-sentinel--plugin，
并依赖 @gcszhn/mcp-sentinel-core。
2. 构建一个 ToolInvoker：要么将宿主的 MCP 配置解析为 McpConfig
并用 makeConnectionInvoker(makeServerResolver(...)) 包装它
（连接池模式），要么传入一个宿主拥有的 (server, tool, args) => result
函数（外部调用方模式）。
3. 注册这四个工具，委托给核心的 handlePoll /
handleStatus / handleAttach / handleRead 处理器。
4. 用 setNotifier 安装通知器，通过宿主的消息通道推送完成事件
（例如 OpenCode promptAsync、DeepSeek Harness
Agent.followup）。

数据流（核心）

sequenceDiagram
participant A as Agent (any host)
participant H as Harness adapter
participant C as Core engine
participant M as MCP Server

A->>H: poll(server, tool, until)
H->>H: resolveServer()
H->>C: startSentinel(...)
C-->>H: sentinel ID
H-->>A: acknowledgment

loop every interval ms (zero tokens)
C->>M: call tool(args)
M-->>C: response
C->>C: evaluateCondition(until, response)
end

C->>H: notify(completed)
H->>A: host-specific completion push

布局

packages/
core/                         # @gcszhn/mcp-sentinel-core (zero host deps)
src/
engine.ts                 # startSentinel / cancel / getTask / getActive / cleanup
tools.ts                  # handlePoll / handleStatus / handleAttach / handleRead
condition.ts              # condition evaluator
connection-pool.ts        # MCP client pool (@modelcontextprotocol/sdk)
env.ts                    # SENTINEL_ env
logger.ts                 # pluggable sink
resolver.ts               # makeServerResolver (McpConfig → ServerResolver)
types.ts                  # McpServerConfig / ServerResolver / Sentinel*
index.ts                  # public barrel
tests/
opencode/                     # @gcszhn/mcp-sentinel-opencode-plugin
src/
plugin.ts                 # PluginModule entry
index.ts                  # tool() definitions + promptAsync notifier
config.ts                 # parseOpencodeMcpConfig (opencode mcp block) → McpConfig
tests/
deepseek-harness/             # @gcszhn/mcp-sentinel-deepseek-harness-plugin
src/
index.ts                  # external-invoker 模式：ctx.tools.execute + Agent.followup
tests/
cli/                          # @gcszhn/mcp-sentinel-cli（与 harness 无关的 stdio MCP 服务器）
src/
cli.ts                    # CLI 入口：mcp-sentinel mcp --harness
mcp-server.ts             # 注册这 4 个工具；连接池模式；无 notifier
config.ts                 # codex mcp list / opencode debug config / --mcp-config 发现
schema/                     # mcp-config.schema.json（随 npm tarball 一起发布）
tests/
未来的 harness，每个对应一个具体包：
claude-code/   ...

构建顺序：每个包独立构建，但适配器会针对
@gcszhn/mcp-sentinel-core 已发布的 dist/ 进行类型检查并运行。
在运行 bun test 之前，先运行 bun run build（先 core，然后是 opencode、deepseek-harness、cli）。

许可证

MIT