framework-mcp

远程 MCP 服务器，为编码代理（Claude Code、Cursor 等）提供关于快速迭代框架的经过验证、锁定版本的答案——从 Expo SDK 54 开始。

原因：LLM 训练数据过时的速度比框架发布周期更快。代理们一直在反复猜测同样的版本相关问题，而不是去查阅经过验证、锁定版本的来源。这个服务器就是那个来源。

技术栈

Node 24 + TypeScript，@modelcontextprotocol/sdk 基于 Streamable HTTP 传输（有状态，每连接一个会话），Express，Postgres（pg），通过 SDK 自带的 requireBearerAuth 中间件进行 API 密钥认证。

托管：Railway（计算，约 5 美元/月的 Hobby 套餐）+ Neon（Postgres，免费层，可分支）。

本地设置

1. 创建一个免费的 Neon 账户和项目。复制 dev 分支的连接字符串。

2. 执行 cp .env.example .env 并填写 DATABASE_URL（来自 Neon）和 API_KEY_PEPPER（任意长随机字符串——用 node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" 生成一个）。

3. 安装、迁移、填充种子数据、构建：

   npm install
   npm run db:migrate
   npm run db:seed
   npm run build

4. 为自己创建一个 API 密钥：

   npm run create-api-key -- "my laptop"

   这会一次性打印原始密钥——请保存好，它无法恢复。

5. 本地运行：

   npm run dev

   curl http://localhost:3000/health 应返回 ok。

使用 MCP Inspector 验证

npx @modelcontextprotocol/inspector

使用 "Streamable HTTP" 传输连接到 http://localhost:3000/mcp，并在连接设置中设置 Authorization: Bearer <your-api-key> 请求头。确认全部 3 个工具（ping、query_framework_doc、report_outcome）都能列出且可调用。

部署到 Railway

1. 执行 curl -fsSL agents.railway.com | sh，然后执行 railway login。

2. 在此仓库中：执行 railway init（如果项目已存在则执行 railway link）。

3. 设置环境变量（在仪表盘中，或执行 railway variable set KEY=value）：DATABASE_URL（你的 Neon 生产分支连接字符串，与开发分支分开）、API_KEY_PEPPER、NODE_ENV=production。

4. 执行 railway up。

5. 在 Railway 仪表盘中：Settings → Networking → Generate Domain。将 PUBLIC_HOSTNAME 设置为该域名（SDK 的 DNS 重绑定主机检查需要它来允许真实流量）。

6. 针对生产环境的 DATABASE_URL（从你的机器指向生产连接字符串）运行一次 npm run db:migrate && npm run db:seed。

7. 使用 npm run create-api-key 创建一个生产 API 密钥，指向生产环境的 DATABASE_URL。

获取 API 密钥

自助服务：访问 https://framework-mcp-production.up.railway.app/，输入邮箱，立即获得密钥（每个邮箱一个有效密钥，有限流）。

维护者/本地备用方式：npm run create-api-key -- "label"。

连接远程客户端

在 Claude Code 的 .mcp.json 中：

{
  "mcpServers": {
    "framework-mcp": {
      "type": "http",
      "url": "https://<your-railway-domain>/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

工具

• ping(message) - 健康检查

• query_framework_doc(framework, version, question) - 查找经过验证的答案，返回 query_id

• report_outcome(query_id, worked, note?) - 记录返回的答案是否实际有效

状态

db/seed/expo-54.json 中的种子数据（20 条）已于 2026-08-21 对照 https://expo.dev/changelog/sdk-54 和 https://docs.expo.dev/modules/autolinking/ 验证。

自助注册已在 / 上线（邮箱 → 即时 API 密钥，每个邮箱一个，按 IP 限流）。已收录于 Smithery / Glama / mcp.so。

延后（B 阶段，尚未构建）：Stripe 计费、api_keys 上的 plan_tier / credit_balance / 按密钥限流执行、其他框架、基于反馈的评分/排名。