GenPDM MCP Server

A TypeScript/Express MCP server skeleton for exposing a fixed business GraphQL API as safe, typed MCP tools.

Features

• MCP SDK v2 Streamable HTTP endpoint at ALL /mcp

• HS256 Bearer JWT validation and scope checks

• Per-IP and per-subject in-memory rate limits

• GraphQL client backed by a bounded Undici keep-alive pool

• Query-only retries, mutation idempotency, concurrency and response-size limits

• Reproducible mock GraphQL upstream

• Liveness/readiness endpoints and graceful shutdown

The current rate-limit store is intentionally process-local. src/rate-limit.ts contains the adapter boundary for a future Redis-backed store. Do not treat the current counters as global when running multiple replicas.

Related MCP server: gqai

Documentation

• System architecture

• Implementation guide

• Development guide

• Testing guide

• Local run and manual testing

• AI Agent integration

• Agent user acceptance testing

Repository automation:

• AGENTS.md defines always-on architecture and naming rules.

• genpdm-mcp-development guides Codex through GraphQL operation and MCP tool changes.

Runnable example:

• Isolated GenPDM sample agent

Run locally

Requires Node.js 20 or newer.

Copy-Item .env.example .env
npm install
npm run dev:mock

In a second terminal:

npm run dev
$token = npm.cmd run --silent token

Configure an MCP client with endpoint http://127.0.0.1:3000/mcp and header Authorization: Bearer <token>.

Available tools:

• get_customer: { "id": "cust-001" }, requires customers:read

• create_order: { "customerId": "cust-001", "items": [{ "sku": "SKU-1", "quantity": 2 }] }, requires orders:write

Health endpoints are unauthenticated:

• GET /health/live

• GET /health/ready

Verify

npm run typecheck
npm run build
npm test

Production notes

• Replace HS256 verification with the company IdP's JWKS verifier.

• Replace the in-memory rate-limit store with Redis before horizontal scaling requires strict global limits.

• Inject JWT and GraphQL credentials from a secret manager.

• Restrict ALLOWED_HOSTS, CORS_ORIGINS, and trusted proxy settings for the deployment topology.