传输协议

Keepamore MCP 服务使用 Streamable HTTP 传输，遵循 Model Context Protocol 1.0 规范。本页给想要自己实现客户端或排查网络层问题的开发者参考。

端点

* /mcp           — 全部 MCP 流量入口，单一端点处理 POST/GET/DELETE
GET  /health     — 健康检查（不需鉴权）

HTTP 方法语义

方法	用途
POST /mcp	客户端 → 服务端的 JSON-RPC 请求（初始化、tools/list、tools/call 等）
GET /mcp	打开 SSE 流，服务端推送消息（通知、进度、中断等）
DELETE /mcp	结束会话

典型客户端实现会在首次 POST 后根据响应里的 mcp-session-id 决定是否打开 SSE。

请求头

Header	必填	说明
Content-Type	✅	application/json
Accept	✅	application/json, text/event-stream
X-API-Key	✅（任一）	km_xxx
Authorization	✅（任一）	Bearer km_xxx
mcp-session-id	⚠️	由服务端在首次响应里下发；后续请求必带
mcp-protocol-version	⚠️	协议版本协商字段
Last-Event-ID	可选	SSE 断线重连用

CORS：Access-Control-Allow-Origin: *，允许方法 GET POST DELETE OPTIONS，暴露头 mcp-session-id、mcp-protocol-version。

会话管理

• 本服务当前不强制会话（sessionIdGenerator 为 undefined，每次请求独立）
• 客户端若传了 mcp-session-id 也不会被拒绝，向前兼容未来开启会话
• 这意味着：无需显式断开，客户端随用随连

超时

• 服务端 idleTimeout: 120s（覆盖 Bun 默认 10s），用于支撑大接口（如 lightningdeal 全量约 20MB）
• HTTP 上限硬性 255s，超过请拆分查询

错误响应映射

MCP 层错误仍然透传 HTTP 状态码 + JSON 结构。业务层错误码见 通用错误码。

例子：

// 401
{
	"jsonrpc": "2.0",
	"id": 1,
	"error": {
		"code": -32001,
		"message": "缺少 API Key，请通过请求头 X-API-Key（推荐）、Authorization: Bearer 或 URL 参数 ?key= 之一传入"
	}
}

工具发现

客户端通过标准 tools/list 方法获取全部工具定义：

curl -X POST https://mcp.keepamore.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: km_xxx" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

返回结构（节选）：

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"tools": [
			{
				"name": "keepa_get_product",
				"description": "...",
				"inputSchema": { "type": "object", "properties": { ... } }
			}
		]
	}
}

所有工具定义（inputSchema）都是纯 JSON Schema，可直接由 LLM / 客户端类型系统消费。

工具调用

curl -X POST https://mcp.keepamore.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: km_xxx" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"keepa_get_quota",
      "arguments":{}
    }
  }'

自行实现客户端的建议

• 用官方 TypeScript SDK @modelcontextprotocol/sdk 的 StreamableHTTPClientTransport 最省事
• 不要在浏览器端直连：API Key 会泄漏；请走自己的后端代理
• 批量调用请读响应 metadata.quotaHint 做自适应限速

---

下一步：工具参考