framework-mcp

framework-mcp

面向编码 Agent 的依赖项时效检查层：一个远程 MCP 服务，为编码 Agent（Claude Code、Cursor 等）提供经过验证、固定版本的答案，涵盖快速迭代的框架——Expo、Next.js、Supabase、Prisma 等，且持续扩展。

原因：大模型的训练数据比框架发布周期更快过时。Agent 不断重新猜测相同的版本相关问题，而不是查询经过验证、固定版本的来源。这个服务就是这样的来源——它并非只针对单个框架的工具，而是一个通用层，任何编码 Agent 在相信自己对依赖项当前行为的“记忆”之前，都可以先查询它。

技术栈

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

托管：Railway（计算资源，Hobby 计划约 $5/月）+ 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) - 健康检查
• list_frameworks() - 列出涵盖的所有框架/版本及条目数；如果不知道下方要传入的确切 slug/版本，请先调用此工具
• query_framework_doc(framework, version, question) - 查找经过验证的答案，返回 query_id
• report_outcome(query_id, worked, note?) - 记录返回的答案是否确实有效

覆盖范围

框架	版本	条目数	来源
Expo SDK	54.0.0	20	expo.dev/changelog/sdk-54
Next.js	16.3.2	20	nextjs.org/blog、nextjs.org/docs upgrade guide
Supabase (supabase-js)	2.112.3	20	supabase.com/changelog、GitHub releases
Prisma ORM	7.9.1	20	prisma.io/docs upgrade guide、prisma.io/changelog
Vercel AI SDK	7.0.77	20	ai-sdk.dev migration guides、vercel.com/blog
Nuxt	4.5.2	20	nuxt.com/docs upgrade guide、nuxt.com/blog

所有条目均已于 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-key 身份验证）或 mcp.so（没有免费发布选项）。

延后处理（阶段 B，尚未构建）：Stripe 计费、api_keys 上的 plan_tier / credit_balance / 按密钥实施速率限制，以及对反馈进行评分和排名。