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 ` 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:///mcp",
      "headers": { "Authorization": "Bearer " }
    }
  }
}

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

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/.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.