# Identity Admin MCP Server

Cloudflare Worker MCP server that exposes a focused Identity-Service admin toolset.

## Endpoints

- `GET /healthz` is public and returns service health.
- `/mcp` is the MCP Streamable HTTP endpoint and requires `Authorization: Bearer <MCP_CLIENT_TOKEN>`.

## Configuration

Secrets must be configured outside source control:

```bash
pnpm install
pnpm exec wrangler secret put MCP_CLIENT_TOKEN
pnpm exec wrangler secret put IDENTITY_ADMIN_TOKEN
```

Non-secret variables:

- `IDENTITY_BASE_URL`: Identity-Service base URL.
- `MCP_DEFAULT_CHANNEL`: default mutation channel when a tool call omits `channel` (`mcp` by default).

For local development, use an uncommitted `.dev.vars` file.

## Tools

Admin operation mutation tools require an explicit `idempotencyKey`, generate a per-call `correlationId`, default `channel` from `MCP_DEFAULT_CHANNEL`, and call Identity-Service only through `@cesco_valle/identity-auth-sdk/admin`. `auth.decideApproval` decides an already-anchored approval using the Identity contract.

- `auth.createUser`
- `auth.assignProjectRole`
- `auth.revokeProjectAccess`
- `auth.revokeSession`
- `auth.banUser`
- `auth.unbanUser`
- `auth.readmitProjectMembership`
- `auth.decideApproval`
- `auth.listProjectUsers`
- `auth.getUserAccessStatus`
- `auth.listPendingApprovals`


## Conversational clients

Tool calls return both redacted JSON text content and matching `structuredContent` so Claude, Codex, Telegram gateways, and other conversational clients can show readable summaries while using structured data for UI state. List-style Identity responses keep the raw redacted `result` intact and may add `structuredContent.client.list` with defensive metadata such as `itemCount`, detected item key, pagination fields, and action hints.

The server also exposes guidance resources/prompts for safe admin workflow, pagination, Telegram gateway responsibilities, and the no-direct-DB Identity boundary when supported by the installed MCP TypeScript SDK.

## Telegram gateway contract

A Telegram gateway should authenticate to `/mcp` with `Authorization: Bearer <MCP_CLIENT_TOKEN>`, keep `/healthz` as a public health check, render concise text content to operators, and use `structuredContent` for buttons, pagination state, approval summaries, and safe follow-up actions. It must not forward secrets to chat clients.

## Architecture decisions

- [ADR-0001](docs/adrs/0001-adopt-cloudflare-workers-for-identity-admin-mcp.md): runtime and deployment model.
- [ADR-0002](docs/adrs/0002-expose-identity-admin-operations-as-discrete-mcp-tools.md): discrete `auth.*` tool boundary.
- [ADR-0003](docs/adrs/0003-use-project-local-agent-instructions-and-adr-skill-lock.md): local agent instructions and ADR skill lock.

## Commands

```bash
pnpm typecheck
pnpm test
pnpm build
pnpm dev
```

## Security notes

- No OAuth v1.
- No direct database access.
- Tool responses include JSON text content and matching `structuredContent`, with common secret fields redacted in both.