framework-mcp

framework-mcp

A dependency currency-check layer for coding agents: a remote MCP server that gives coding agents (Claude Code, Cursor, etc.) verified, version-pinned answers about fast-moving frameworks - Expo, Next.js, Supabase, Prisma, and growing.

Why: LLM training data goes stale faster than framework release cycles. Agents keep re-guessing the same version-specific questions instead of checking a verified, version-pinned source. This server is that source - not a single-framework tool, but a general layer any coding agent can query before trusting what it "remembers" about a dependency's current behavior.

Stack

Node 24 + TypeScript, @modelcontextprotocol/sdk over Streamable HTTP transport (stateful, session-per-connection), Express, Postgres (pg), API-key auth via the SDK's own requireBearerAuth middleware.

Hosting: Railway (compute, ~$5/mo Hobby plan) + Neon (Postgres, free tier, branchable).

Local setup

1. Create a free Neon account and project. Copy the connection string for a dev branch.
2. cp .env.example .env and fill in DATABASE_URL (from Neon) and API_KEY_PEPPER (any long random string - generate one with node -e "console.log(require('crypto').randomBytes(32).toString('hex'))").
3. Install, migrate, seed, build:

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

4. Create yourself an API key:

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

   This prints the raw key once - save it, it's not recoverable.
5. Run locally:

   npm run dev
   

   curl http://localhost:3000/health should return ok.

Verify with MCP Inspector

npx @modelcontextprotocol/inspector

Connect to http://localhost:3000/mcp with transport "Streamable HTTP" and set an Authorization: Bearer <your-api-key> header in the connection settings. Confirm all 3 tools (ping, query_framework_doc, report_outcome) list and are callable.

Deploy to Railway

1. curl -fsSL agents.railway.com | sh then railway login.
2. From this repo: railway init (or railway link if a project already exists).
3. Set env vars (dashboard, or railway variable set KEY=value): DATABASE_URL (your Neon production branch connection string, separate from your dev branch), API_KEY_PEPPER, NODE_ENV=production.
4. railway up.
5. In the Railway dashboard: Settings → Networking → Generate Domain. Set PUBLIC_HOSTNAME to that domain (needed for the SDK's DNS-rebinding host check to allow real traffic).
6. Run npm run db:migrate && npm run db:seed once against the production DATABASE_URL (from your machine, pointed at the prod connection string).
7. Create a production API key with npm run create-api-key, pointed at the prod DATABASE_URL.

Get an API key

Self-service: visit https://framework-mcp-production.up.railway.app/, enter an email, get a key instantly (one active key per email, rate-limited).

Maintainer/local fallback: npm run create-api-key -- "label".

Connect a remote client

In a Claude Code .mcp.json:

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

Tools

• ping(message) - health check
• list_frameworks() - lists every framework/version covered, with entry counts - call this first if you don't know the exact slug/version to pass below
• query_framework_doc(framework, version, question) - look up a verified answer, returns query_id
• report_outcome(query_id, worked, note?) - log whether the returned answer actually worked

Coverage

Framework	Version	Entries	Source
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

All entries verified 2026-08-22 against the official sources cited in each seed file under db/seed/. To add a framework: create a new db/seed/<slug>.json following the existing files' shape, then npm run db:seed (it picks up every *.json in that folder automatically).

Status

Self-service signup live at / (email -> instant API key, one per email, IP rate-limited). Published to the official MCP Registry (registry.modelcontextprotocol.io) and submitted to mcpservers.org and Glama (both pending review). Not on Smithery (their OAuth-discovery scanner doesn't support simple static bearer-key auth) or mcp.so (no free listing tier).

Deferred (Stage B, not built yet): Stripe billing, plan_tier / credit_balance / rate-limit-enforcement-per-key on api_keys, scoring/ranking on feedback.