world-id-mcp

# World ID MCP Minimal MCP HTTP server that gates tools behind World ID proofs. Baseline verification defaults to `device`; privileged operations (demo) skip step-up for simplicity. Includes a tiny IDKit web page to fetch a proof and swap it for a JWT. ## Flow ```mermaid flowchart TD A[User opens web demo] --> B[IDKit shows QR] B --> C[User approves in World App] C --> D[session endpoint world-id.verify] D --> E[JWT issued token scopes exp] E --> F[Client calls tools with token] F --> G[Tool verifies JWT scopes enforced] G --> H[Audit log and response] ``` ## Setup - Node 18+, pnpm. - Install deps: `pnpm install -r` - Env: `cp server/.env.example server/.env` and set `WORLD_APP_ID`, `WORLD_ACTION_ID`, `WORLD_VERIFICATION_LEVEL` (default `device`), `SESSION_JWT_SECRET` (and `PORT` if desired). The server will exit if app/action IDs are missing. The web demo reads these from the server via `/config`, so you only set them once in `server/.env`. - Run server: `pnpm start` (serves `/health`, `/mcp`, `/session` on port 3000). - Build all (optional): `pnpm build` - Tests (server): `pnpm test` ## MCP tools - `world-id.verify` → validates proof, returns `{token, scopes, expiresAt}` - `echo` → requires scope `tools.echo` (send JWT) - `advanced-operation` → requires scope `tools.advanced` (send JWT); step-up disabled in demo ## REST helper - `POST /session` with a World ID proof mirrors `world-id.verify` (handy for the web demo or custom clients). - `POST /demo/echo` and `POST /demo/advanced` are simple REST shortcuts used by the web demo. ## IDKit Web Demo ```bash cd demo/idkit-web cp .env.example .env # set app/action/verification + server URL pnpm install pnpm dev # http://localhost:5173 ``` Click “Verify with World ID”; it posts the proof to `/session` and shows the JWT to paste into your agent. ## Using with Claude 1) Start server: `pnpm start` (set `PORT` if 3000 is busy). 2) Add MCP server to Claude: - CLI: `claude mcp add --transport http world-id http://localhost:3000/mcp` - Config: `"world-id": { "type": "http", "url": "http://localhost:3000/mcp" }` 3) Get a token (human proof): - Run the web demo (`pnpm dev` or `pnpm dev:web`) at http://localhost:5173 - Scan the QR, approve in World App, copy the `token`. 4) Call tools from Claude: - `echo`: `{ "token": "<jwt>", "message": "hi" }` - `advanced-operation`: `{ "token": "<jwt>", "operation": "something" }` 5) If you see errors: - Token invalid/expired → get a fresh proof. - “Missing required scope: tools.advanced” → request that scope when verifying. - (If step-up is re-enabled later) advanced will ask for a fresh proof; provide `stepUpProof`. ## File map - `server/src/mcp-server.ts` – MCP server + tools + `/session` - `server/src/auth/` – World ID verification, JWT minting, policies - `demo/test-client.ts` – sample MCP client - `demo/idkit-web/` – Vite + IDKit proof collector