# ping-iga-mcp-server

MCP server exposing Ping IGA self-service governance operations — access requests, approvals, certifications, and manual tasks — to MCP clients, acting on behalf of the authenticated user.

Stack: JavaScript (ES modules) on Node 20 + Express. No TypeScript, no build step. Zod for runtime validation. MCP 2026-07-28 stateless transport.

> **Status: Phase 1 complete.** Auth (introspection, throttle, rate-limit, RFC 9728 metadata) is wired. The `/mcp` endpoint and governance tools are built out phase by phase per the implementation plan.

## Requirements

- Node 20 LTS (`.nvmrc` pins `20`)

## Getting started

```bash
nvm use          # Node 20
npm install
cp .env.example .env   # adjust as needed
npm run dev           # starts with --watch on http://localhost:3000
curl http://localhost:3000/healthz   # -> {"status":"ok"}
```

## Scripts

| Script | Purpose |
|---|---|
| `npm run dev` | Start with `node --watch` |
| `npm start` | Start once |
| `npm test` | Run vitest |
| `npm run lint` | ESLint |
| `npm run format` | Prettier write |
| `npm run inspector` | Launch MCP Inspector against the server |

## 401 → metadata → token walkthrough

With the server running (`npm run dev`) and `.env` populated, the full bootstrap flow can be traced manually:

**Step 1 — hit a protected route without a token; receive a metadata pointer**
```bash
curl -si http://localhost:3000/_authcheck
# HTTP/1.1 401
# WWW-Authenticate: Bearer resource_metadata="https://<PUBLIC_URL>/.well-known/oauth-protected-resource"
```

**Step 2 — fetch the resource-server metadata document (no token needed)**
```bash
curl -s http://localhost:3000/.well-known/oauth-protected-resource | jq .
# {
#   "resource": "https://<PUBLIC_URL>",
#   "authorization_servers": ["https://<AIC_BASE_URL>/am/oauth2"],
#   "scopes_supported": ["iga:read", "iga:write", "iga:mutate"],
#   "bearer_methods_supported": ["header"]
# }
```

**Step 3 — obtain a token from the authorization server listed above**

Use the `authorization_servers[0]` URL with your preferred OAuth 2.0 flow
(client credentials, authorization code, device flow — whichever your AIC
tenant and client registration support). The resulting access token must have
at least the `iga:read` scope.

**Step 4 — call the probe route with the token**
```bash
TOKEN=<access token from step 3>
curl -si http://localhost:3000/_authcheck \
  -H "Authorization: Bearer $TOKEN"
# HTTP/1.1 200
# {"sub":"<user>","scopes":["iga:read",...]}
```

`/_authcheck` is a throwaway probe route (D1=a) that will be removed when
`/mcp` lands in Phase 2.

## Deployment prerequisites

Beyond the skeleton, running the server against a tenant requires AIC configuration
(a confidential client for token introspection, MCP tool-gating scopes, client
registration, and verification of the tenant's token model). These are enumerated
in the implementation plan and expanded in this README as each phase lands.

## WebStorm

Shared run configurations for `dev`, `test`, and `inspector` are committed under
`.run/`. Open the project folder in WebStorm; set the project Node interpreter to
your Node 20 install. The `.idea/` folder is intentionally not committed — WebStorm
generates it on first open.