MCP 概览

Kestrel 在同一个二进制里同时承载 API、web UI 和 MCP（Model Context Protocol）server。Agent 看到的是一个小而专注的工具集，围绕这一条工作流设计：

列错误 → 拿一条 → 排障 → 用 commit SHA 标记已解决

没有 create_issue、assign、add_comment、set_priority —— 这些概念在 Kestrel 里不存在。

两种传输，同一套工具

stdio

# 适合本地 agent（Claude Code / Cursor / 你自己的 CLI）。stdio 直接读
# SQLite 文件，所以必须跟 data/kestrel.db 在同一台机器上（也可以用 --db
# 指向别的路径）。
kestrel mcp
# 或者放进 JSON 配置：
{
  "command": "kestrel",
  "args": ["mcp"],
  "env": { "KESTREL_TOKEN": "<project-token>" }
}

HTTP (StreamableHTTP)

# Agent 和 server 不在同一台机器时用这个 —— 包括最常见的 Docker 部署。
POST /mcp HTTP/1.1
Authorization: Bearer <project-token>

HTTP 端点要求每个调用都带 Authorization: Bearer <token> —— 匿名调用方在 tools/list 或 initialize 之前就吃 401，所以无 token 的人连 schema 都拿不到。

鉴权 → 项目隔离

每个项目的 ingest token 同时也是它的 MCP 凭证。请求带的 token 决定它能访问的项目；拿别人的 token 读不到你的 issue。

设计上故意比 RBAC 简单：一个 token、一个项目、一个心智模型。

接到 Claude Code 里

Agent 和 server 在同一台机器（二进制安装、SQLite 在 ./data/kestrel.db）：

// ~/.claude/mcp.json
{
  "mcpServers": {
    "kestrel": {
      "command": "kestrel",
      "args": ["mcp"],
      "env": { "KESTREL_TOKEN": "your-project-token" }
    }
  }
}

Kestrel 跑在 Docker 里、或者在另一台主机上，把 Claude Code 接到 HTTP 端点：

{
  "mcpServers": {
    "kestrel": {
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer your-project-token" }
    }
  }
}

Claude Code 重启后下面那些工具直接可用，不需要任何 prompt 脚手架。试一下："列出未处理的错误，挑一个最该优先看的。"

这一切的意义

Kestrel 想把这个闭环尽量做短：

1. Bug 上线。
2. SDK 上报 envelope。
3. Agent 看到新错误，读到带源码上下文、最近日志、责任 commit 的解析后堆栈。
4. Agent 提出修复方案，人 review 后提交。
5. Agent 调 mark_resolved(issue_id, commit_sha)。

第 4 步是唯一必须人介入的环节。其它都是 agent 在做 on-call 会做的事 —— 只是更快、不用半夜叫醒任何人。