MCP Server
Sigil 的 MCP Server 是 AI 客户端接入的入口。本篇讲它的协议、监听机制、客户端授权。
协议选择
Sigil 实现的是 Model Context Protocol（MCP）的 Streamable HTTP transport，协议版本 2025-06-18：
- 基于 HTTP（不是 stdio）：远程 / 容器 / 多客户端场景天然支持
- JSON-RPC 2.0 消息封装
- Bearer Token 鉴权（每个客户端独立 Token）
- 支持服务端推流（
tools/list_changed等通知） - 结构化输出（2025-06-18）：
tools/call在人读content之外，对支持的能力额外返回机读的structuredContent；tools/list为这些能力同时声明outputSchema - 工具注解：
tools/list为每个能力标注readOnlyHint/destructiveHint，客户端据此对只读工具免确认、对破坏型工具强确认
MCP 是 Anthropic 推出的开放协议，被 Claude Code、Cursor、Cline、Zed、Continue 等主流 AI 客户端原生支持。
默认配置
| 项 | 值 |
|---|---|
| 监听地址 | 127.0.0.1:8421（仅本机回环） |
| 路径 | /mcp |
| 端口策略 | 8421 被占用时自动顺延 |
| TLS | 不启用（仅本机回环，TLS 是 overkill） |
| Token 算法 | 自托管签发，Constant-time 比对 |
| Origin 校验 | 所有路由强制校验 Origin 头（防 DNS rebinding） |
| 端点文件 | endpoint.json 仅当前用户可读（Windows ACL / Unix 0600） |
如果需要绑定其他网口（如 0.0.0.0，给同一局域网的移动端用），需手动启用"远程网关"——这是显式行为，不会被默默开启。
Origin 校验（防 DNS rebinding）
MCP 规范要求本机 HTTP server 必须校验 Origin 头，否则恶意网页可借 DNS rebinding 让浏览器向 127.0.0.1:8421 发请求。Sigil 的策略：
- 无
Origin头 → 放行：非浏览器 MCP 客户端（Claude Code / Cursor / curl）天然不发 Origin，不受影响 Origin为本机回环（localhost/127.0.0.1/[::1]）→ 放行- 其它外部域名 →
403 Forbidden（正是 rebinding 攻击的来源）
这道校验覆盖所有路由，包括无鉴权的 /health、/metrics，杜绝聚合指标被恶意网页旁路读取。
客户端授权
Token 颗粒度
Sigil 给每个客户端独立颁发 Bearer Token：
Sigil ──┬── Bearer "sk_sigil_aaaa..." ──→ Claude Code
├── Bearer "sk_sigil_bbbb..." ──→ Cursor
└── Bearer "sk_sigil_cccc..." ──→ Cline（仅只读）每个 Token 有独立的：
- 名称（出现在审计日志的 caller 列）
- 范围（哪些能力可调用）
- 创建时间 / 最后使用时间
- 过期时间（可选）
- 是否启用
撤销
撤销 Token = 立即让对应的客户端连接失效。在 MCP 页 → 客户端管理 → 行末"⋯" → 撤销。
撤销是即时生效的，不需要重启 Sigil。
Token 一次性显示
新建客户端时显示的明文 Token 只在生成那一刻可见——关闭对话框后，UI 不再展示，OS 密钥环里只有 hash 用于比对。
如果你忘了 Token：撤销旧的，重新生成一个。
协议方法（关心实现的人看）
Sigil 实现以下 MCP 方法：
| 方法 | 用途 |
|---|---|
initialize | 客户端握手 + 版本协商（声明 protocolVersion 2025-06-18） |
tools/list | 列出当前 Token 可用的所有能力（含 inputSchema / outputSchema / readOnlyHint / destructiveHint） |
tools/call | 调用某个能力（返回 content 人读文本 + 可选 structuredContent 机读结果） |
notifications/tools/list_changed | 服务端推送：能力列表变更 |
ping | 心跳 |
不支持的方法（Sigil 不暴露这些）：
resources/*—— Sigil 不暴露文件资源prompts/*—— Sigil 不维护 Prompt 模板sampling/*—— Sigil 不做模型采样
只做凭据与能力代理——其他能力交给客户端自己实现。
工具列表的动态构造
调用 tools/list 时，Sigil 不是简单返回"所有内置能力"——而是按当前 Token 的范围 + Scope Policy 动态过滤：
请求方 当前 Token 范围 返回的工具列表
─────────────────────────────────────────────────────────
Claude Code 全部能力 git_query / git_mutate /
db_query / db_execute /
ssh_query / ssh_exec /
http_request /
password_generate /
[13 个工具]
Cline 仅只读能力 git_query / db_query /
ssh_query / http_request(GET) /
health_check
[5 个工具]
某第三方客户端 仅 http_request http_request
[1 个工具]这意味着：你给某个客户端的 Token 范围越小，它看到的工具就越少——它甚至不知道还有别的工具存在。
性能特征
- 单连接 RTT: < 5 ms（本机回环）
- 并发能力调用: 内部用 tokio 多任务，无明显瓶颈
- 内存占用: MCP Server 本身 < 30 MB（不含 Sigil UI）
写类能力（db_execute / ssh_exec 等）受限于目标服务的网络与执行时间，Sigil 不引入额外开销。
错误码
Sigil 遵循 MCP 标准错误响应，并增加了一组应用级 code：
| code | 说明 |
|---|---|
unauthorized | Bearer Token 无效 / 已撤销 |
not_in_scope | 该 Token 不允许调用此能力 |
credential_missing | 找不到合适的凭据 |
credential_expired | 凭据已过期 |
scope_policy_denied | 凭据的 Scope Policy 拒绝此能力 |
kill_switch_active | AI Kill Switch 已启用 |
confirmation_required | 写类能力需用户在 Sigil UI 确认 |
forbidden_command | 命中危险命令黑名单（仅 ssh_exec / db_execute） |
客户端收到这些错误时，建议把 message 直接展示给用户——它们都是已经人化的中文描述。
远程网关（可选 / 进阶）
如果你需要让局域网其他机器（如手机、平板）也通过 MCP 访问本机 Sigil，可以在"设置 → 远程网关"启用：
- 监听地址改为
0.0.0.0:8421（或自定义网口） - 强制要求 Bearer Token 鉴权
- 建议同时启用"失败追踪"（连续 N 次错误后封禁源 IP）
如果要从公网访问，强烈建议自建反向代理（Caddy / Nginx）加 TLS + 双向 mTLS。Sigil 本身不内嵌 frpc / easytier 等内网穿透——这类二进制在不少国内杀软里被误报，体验不好。
⚠️ 远程网关是双刃剑。仅在你清楚知道自己在做什么时启用。