mcp-ory-kratos: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP (Model Context Protocol) server for Ory Kratos - an open-source identity and user management system.

Build & Development Commands

# Start MCP server
bun run start

# Lint (Biome)
bun run lint
bun run lint:fix  # Auto-fix issues

# Type check
bun x tsc --noEmit

# Type check src + tests
bun run typecheck

# Unit tests only (CI-safe, no external dependencies, with coverage)
bun run test:unit

# Integration tests against a local Kratos v26.2.0
docker compose up -d --wait && bun run test:api

# All tests / watch mode (requires Kratos - see .env.test.local.example)
bun run test
bun run test:watch

# Dependency audit
bun run audit

CI/CD

GitHub Actions CI runs on every push and PR:

• Lint: bun run lint (Biome)
• Type Check: bun x tsc --noEmit
• Audit: bun audit --audit-level=high
• Test: Unit tests with coverage (tests/unit/)
• Integration: Starts Kratos v26.2.0 via docker-compose.yml (config in tests/kratos/) and runs bun run test:api

Test organization:

• tests/unit/ - Hermetic unit tests (in-memory MCP client, stubbed Kratos)
• tests/api/ - Integration tests against a real Kratos (docker compose locally and in CI)

Architecture

Stateless proxy from MCP to the Kratos Admin API. Layers, bottom up:

• src/config.ts - loadConfig(env) validates KRATOS_* env vars into a Config (URL, auth, timeout, toolsets, runtime flags).
• src/kratos/client.ts - createKratosClients(config) builds @ory/kratos-client IdentityApi/CourierApi/MetadataApi plus a raw http.get for endpoints the SDK cannot reach. Strips trailing / and a trailing /admin from the base URL (the SDK adds /admin itself). kratos/pagination.ts extracts nextPageToken from Link headers; kratos/types.ts holds CREDENTIAL_TYPES (7 login types), ALL_CREDENTIAL_TYPES (11) and redactCredentials.
• src/tools/define.ts - defineTool(ctx, def) is the single registration path. It wraps McpServer.registerTool with logging/timing, mapError (src/errors/mapper.ts), structuredContent when an outputSchema is given, annotations (READ_ONLY, CREATE, UPDATE, UPDATE_IDEMPOTENT, DESTRUCTIVE presets), toolset gating and read-only gating (disabled tools are hidden from tools/list), and a confirm(message) helper that uses MCP elicitation for destructiveHint tools (returns CANCELLED when declined).
• src/tools/*.ts - one registerXxxTools(ctx) per toolset (identity, session, courier, recovery, health, analytics). Zod input/output schemas live in src/schemas/tools.ts.
• src/resources/schemas.ts - resources kratos://schemas, kratos://schemas/{schema_id} (ResourceTemplate with list + completion) and kratos://config/connection.
• src/server.ts - createServer(config, clients) builds the McpServer (instructions, logging bridge to the client, logging/setLevel) and registers every toolset and the resources.
• src/index.ts - CLI entrypoint: load config, create clients, create server, connect stdio.