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

## Documentation

- [System architecture](docs/architecture.md)
- [Implementation guide](docs/implementation.md)
- [Development guide](docs/development-guide.md)
- [Testing guide](docs/testing-guide.md)
- [Local run and manual testing](docs/local-run-and-manual-test.md)
- [AI Agent integration](docs/agent-integration.md)
- [Agent user acceptance testing](docs/agent-user-testing.md)

Repository automation:

- [`AGENTS.md`](AGENTS.md) defines always-on architecture and naming rules.
- [`genpdm-mcp-development`](.agents/skills/genpdm-mcp-development/SKILL.md) guides Codex through GraphQL operation and MCP tool changes.

Runnable example:

- [Isolated GenPDM sample agent](examples/agent/README.md)

## Run locally

Requires Node.js 20 or newer.

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

In a second terminal:

```powershell
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

```powershell
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.