mcp-confluent: 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 that exposes Confluent Cloud resources (Kafka, Flink, Schema Registry, Connectors, Tableflow, Billing) as tools for AI assistants. Built with TypeScript, Node.js ≥22.23.4, and the @modelcontextprotocol/sdk.

Build & Development Commands

pnpm run build          # tsc && tsc-alias (compile + resolve path aliases)
pnpm run dev            # watch mode: tsc + tsc-alias in parallel
pnpm run lint           # eslint
pnpm run lint:fix       # eslint --fix
pnpm run format         # prettier --write
pnpm run test                       # unit + integration (live CCloud, builds first)
pnpm run test:unit                  # unit tests only (fast, no build)
pnpm run test:unit:watch            # unit tests in watch mode
pnpm run test:unit:coverage         # unit tests with coverage
pnpm run test:integration           # integration tests only (live CCloud, builds first)
pnpm run test:integration:coverage  # integration tests with coverage
pnpm run test:coverage              # unit + integration with coverage
pnpm run typecheck                  # tsc --noEmit (type-check only, includes test suite)
pnpm run start          # node dist/index.js --env-file .env (stdio transport)
pnpm run start:http     # HTTP transport
pnpm run start:all      # all transports (http, sse, stdio)
pnpm run inspector      # launch MCP inspector for manual testing
pnpm run print:schema   # print tool schemas as markdown

Pre-commit hook runs pnpm exec prettier and pnpm exec eslint automatically via Husky on staged files only. Pre-push hook runs pnpm run lint and pnpm run typecheck in parallel.

Architecture

Entry Point & Startup Flow

src/index.ts is a thin preflight shim: it gates on the Node.js runtime version (via src/preflight.ts) and, only once that passes, dynamically imports src/server-main.ts — so an unsupported old Node fails with a clear version message instead of a cryptic parse error on our modern imports (issue #455). src/server-main.ts is the real entry: parseCliArgs() → initEnv() → branch on cliOptions.config: when -c <path> is supplied, loadConfigFromYaml(path, process.env) parses + interpolates + validates the YAML; otherwise buildConfigFromEnvAndCli(env, ...) synthesizes the same MCPServerConfiguration shape from env vars + CLI args. Both branches converge into ServerRuntime.fromConfig(), which constructs a DirectClientManager per connection → iterates ToolName enum to build enabled tool set → registers tools on McpServer → starts transports.