framework-mcp

面向编码智能体的依赖时效性校验层：一个远程 MCP 服务器，为编码智能体（Claude Code、Cursor 等）提供经过验证、锁定版本号的快速演进框架（Expo、Next.js、Supabase、Prisma 等，持续扩充中）相关答案。

原因：LLM 训练数据的过时速度比框架发布周期更快。智能体不断重复猜测同一批与版本相关的问题，而不是去查询一个经过验证、锁定版本号的来源。本服务器就是这样一个来源——它不是单一框架工具，而是一个通用层，任何编码智能体在信任其对依赖当前行为的"记忆"之前，都可以先查询它。

技术栈

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

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

Related MCP server: react-native-dev-mcp

本地搭建

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 生产分支连接字符串，与 dev 分支分开）、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) - 健康检查

• list_frameworks() - 列出所有已覆盖的框架/版本及条目数量——如果你不确定下面要传的确切 slug/版本，先调用这个

• query_framework_doc(framework, version, question) - 查询已验证的答案，返回 query_id

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

覆盖范围

所有条目已于 2026-08-22 对照 db/seed/ 下各种子文件中引用的官方来源验证。要添加框架：按照现有文件的格式创建新的 db/seed/<slug>.json，然后执行 npm run db:seed（它会自动拾取该文件夹中的所有 *.json 文件）。

状态

自助注册已在 / 上线（邮箱 → 即时 API 密钥，每邮箱一个，按 IP 限速）。已发布到官方 MCP Registry（registry.modelcontextprotocol.io），并已提交至 mcpservers.org 和 Glama（均待审核）。未上架 Smithery（其 OAuth 发现扫描器不支持简单的静态 bearer 密钥认证）和 mcp.so（无免费收录层级）。

暂缓（B 阶段，尚未构建）：Stripe 计费、api_keys 上的 plan_tier / credit_balance / 按密钥限速执行、基于反馈的评分/排名。