feat(mcp): MCP 集成进网关本体 —— POST /api/v1/mcp（Streamable HTTP）

## 为什么要集成而不是独立进程

上一版（29ad8aa）是独立进程 `plugins/zcode-mail-bridge/mcp/server.mjs`，
用 HTTP 调本网关。四条真实成本：

1. **工具语义有两份**。桥里的 read_inbox / send_mail 是**手抄**网关的，
   抄错就是行为分叉 —— 已抓到两次：`connect_to_server` 只发
   `X-Agent-Secret` 头，而 `/agent/register` 只认 Bearer 或 body 里的
   secret ⇒ secret-only 的 Agent 必然 400。
2. **鉴权与收窄要再实现一遍**。工作区收窄、会话收窄、冷静期、配额住在服务端。
3. **多一跳 + 多一个故障点**。
4. **接入端仍要装东西**（node + 桥 + 环境变量）。

现在：工具**包装现有 handler**，同一份代码、同一套鉴权与收窄；
接入端只填一个 URL。

## 传输与实现（用户裁定）

- **Streamable HTTP**（规范 2025-06-18）：单端点 POST，通知回 202，
  请求回 JSON-RPC。
- **包装 handler**（不是直调 repo）：`newRequest` + `invoke` 造内部请求
  交给 `handler.GetInbox` / `SendMail` / … 于是 `AgentMayReadSession`、
  冷静期、配额、附件保护目录全部是同一条代码路径，不是复述。
- 手写零依赖 JSON-RPC（协议面只有 4 个方法），与本仓取向一致。

端点挂在 `AgentAuth` **之内**：必须与 /mail/send 同一套凭证，
否则就成了绕过收窄的旁门。

## 11 个工具，名字与参数与四桥逐字一致

`connect_to_server` 在这里只做一次真实读来确认连通性 —— 能调到它本身
就证明凭证已过（它是局内端点，不再需要 register）。

## ★ 端到端撞出并修掉的两个真 bug

**① `Tool.Run` 丢掉了身份**（本来写成 `context.Background()`）。
症状：每个工具调用都 Unauthorized，模型表现为「说连上了但读不到任何信」。

**② 路径参数没到位**：被包装的 handler 用 `chi.URLParam(r,"id")` 取 id，
而 `httptest.NewRequest` 造的请求**没过 chi 的路由** ⇒ `URLParam` 恒空
⇒ 任何带路径参数的工具都报「Invalid id」。

第②个的发现过程值得记：端到端测越权时，主人和越权者**都**返回
「Invalid id」。只看越权那一次会误判成「收得太紧」，进而把**正确的收窄改松**；
做对照才看出是参数没到位。

修法两处：`withRouteParams` 注入 chi RouteContext；`invoke` 里**不能**再
`WithContext(ctx)` —— 那会覆盖掉刚注入的 RouteContext。

**③ 发现并暴露了会话越权漏洞**（同批，单独提交 095213b）：
`AgentMayReadSession` 只比 `scope == target`，不问「你是不是参与方」，
而 session_id 由请求方给。对照实验 + 生产复核证实可读他人正文。

## 判据（13 格）

`internal/mcp/mcp_test.go`。真正在钉三件**只有集成才可能坏**的事：

1. MCP 不能成为越权旁门（工具参数里没有身份字段）。
2. 参数映射不许偷偷放宽/收紧（`attachment_ids` 被吞 ⇒ 附件静默不随信发出）。
3. 协议语义不许退化（工具失败必须 result+isError，不是 JSON-RPC error）。

`TestEveryErrorResponseCarriesID` 是被真 bug 逼出来的：曾用
`ID json.RawMessage` + `omitempty`，nil 时**整个 id 字段从 JSON 里消失**，
客户端会一直等这条的响应。遍历全部错误出口逐条验。

**变异验证**：

    Run 丢身份                    → 红 4
    工具失败回 JSON-RPC error     → 红 4
    read_inbox 丢 workspace 收窄  → 红 1
    id 泄露（tag+idPtr 同时失效） → 红 1 ★（真 bug 需两处同时失效，故两处防御都要留）
    去掉 withRouteParams          → 红 1
    invoke 里加回 WithContext     → 红 1

## 端到端（真实网关进程，临时库，备用端口 8199，不动生产）

    未认证 /mcp              → 401
    错误密钥                 → 401
    initialize               → 回显 2025-06-18
    notifications/initialized→ 202 且无响应体
    tools/list               → 11 个，带 annotations 与 required
    send_mail → read_inbox   → mcp-peer 通过 MCP 读到对方发来的信
    read_mail（带 session_id）→ 主人读到自己的信

## 未做

- 未删除旧桥 `plugins/zcode-mail-bridge/mcp/server.mjs`。它是 zcode 插件
  清单里声明的入口（`.zcode-plugin/plugin.json` 的 mcpServers），删掉会破坏
  该插件的组装。两者并存无害：桥仍走 HTTP，服务端这份是接入端零安装的那条路。
- 未部署（本提交只含代码）。

server/cmd/server/main.go

@@ -14,6 +14,7 @@ import (
 	"github.com/agentmail/gateway/internal/config"
 	"github.com/agentmail/gateway/internal/db"
 	"github.com/agentmail/gateway/internal/handler"
+	"github.com/agentmail/gateway/internal/mcp"
 	"github.com/agentmail/gateway/internal/middleware"
 	"github.com/agentmail/gateway/internal/push"
 	"github.com/agentmail/gateway/internal/repo"
@@ -73,6 +74,13 @@ func main() {
 	scheduler.Start()
 	defer scheduler.Stop()
 
+	// MCP 端点（Streamable HTTP）。工具**包装现有 handler**，所以工具语义
+	// 与 /api/v1/agent/* 完全同一份代码 —— 不存在第二套收窄或配额逻辑。
+	mcpServer := mcp.NewServer(nil)
+	mcp.NewTools().RegisterAll(mcpServer)
+	mcpHandler := mcpServer.HandleHTTP
+	log.Printf("MCP 端点就绪：POST /api/v1/mcp（%d 个工具）", mcpServer.ToolCount())
+
 	r := chi.NewRouter()
 
 	r.Use(chimw.Logger)
@@ -116,6 +124,16 @@ func main() {
 		// ---- Agent 侧（X-Agent-Name + X-Agent-Secret） ----
 		r.Group(func(r chi.Router) {
 			r.Use(middleware.AgentAuth)
+
+			// ★ 2026-10-02：MCP 端点。挂在 AgentAuth **之内**是刻意的 ——
+			// 它必须与 /mail/send、/mail/inbox 走同一套凭证，否则就成了
+			// 绕过工作区收窄与会话收窄的旁门（那正是 2026-10-02 修掉的
+			// 越权形状）。工具内部包装的就是下面这些 handler。
+			//
+			// 这样接入端只需填一个 URL（Streamable HTTP 的 POST），不用装插件、
+			// 不用起进程、不用配环境变量。
+			r.Post("/mcp", mcpHandler)
+
 			r.Post("/agent/heartbeat", handler.HeartbeatAgent)
 			r.Post("/mail/send", handler.SendMail)
 			r.Get("/mail/inbox", handler.GetInbox)