用途:为 Express.js(TypeScript)MCP 服务器添加 Scalekit OAuth 认证,提供从零脚手架和改造现有 Express 应用两种模式。
主要能力:需先确认模式。模式 A 用于新建项目(适合演示/POC);模式 B 用于改造现有 Express 应用(适合真实产品)。需收集的输入:服务器基础 URL 与端口(确认 audience 是否需尾斜杠,如 http://localhost:3002/);SK_ENV_URL、SK_CLIENT_ID、SK_CLIENT_SECRET;PROTECTED_RESOURCE_METADATA JSON(从 Scalekit 仪表板 MCP 服务器页复制);EXPECTED_AUDIENCE(须与 Scalekit 中注册的 Server URL 一致)。
必要产出:公开发现端点 GET /.well-known/oauth-protected-resource(返回 PROTECTED_RESOURCE_METADATA 的 JSON);公开健康端点 GET /health;鉴权中间件校验 Authorization: Bearer,失败返回 401 和带 resource_metadata URL 的 WWW-Authenticate;受中间件保护的 MCP 端点 POST /,由 MCP SDK 的 StreamableHTTPServerTransport 处理;至少注册一个 server.tool(...) 工具。
模式 A:以 assets/new-project 下模板创建 package.json、tsconfig.json、src/server.ts,用 assets/env.example 建 .env 并填真实值,运行 npm install 与 npm run dev。注意 EXPECTED_AUDIENCE 与 Server URL 精确匹配,保持发现端点公开。
模式 B:确认现有入口文件、路由结构、POST / 是否被占用、既有鉴权中间件与 CORS 设置。以最小改动加入环境变量、两个公开路由、鉴权中间件(公开路径豁免、Bearer 提取、带 audience 的 validateToken)、MCP 服务器与路由。若 POST / 空闲则挂载于 /,否则挂载到 /mcp 并同步更新 RESOURCE_METADATA_URL。模板含 auth-middleware.ts、well-known-route.ts、mcp-server.ts、mcp-route.ts。
验证:无 Authorization 头访问发现端点应成功;无令牌调用 MCP 端点应 401 且 WWW-Authenticate 指向发现 URL;正确 audience 的有效令牌应调用成功;错误 audience 令牌应 401。常见错误配置见 references/TROUBLESHOOTING.md。