CLAUDE.md

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

Development Commands

Building and Running

• make build - Build the binary to bin/kafka-mcp-server

• make run-dev - Run directly from source: go run cmd/server/main.go

• make run - Run the built binary

• go build -ldflags "-X main.Version=$(VERSION)" -o bin/kafka-mcp-server ./cmd/server - Build with version

Testing

• make test - Run all tests including integration tests (requires Docker)

• make test-no-kafka or SKIP_KAFKA_TESTS=true go test ./... - Skip Kafka integration tests

• go test -v -race -coverprofile=coverage.txt -covermode=atomic ./... - Run tests with coverage

Code Quality

• make lint - Run all linters (same as CI pipeline)

• golangci-lint run --timeout=5m - Run Go linter

• go mod tidy - Clean up module dependencies

Docker

• make run-docker - Build and run Docker container

• make docker-compose-up - Start with Docker Compose

• make docker-compose-down - Stop Docker Compose

Project Architecture

Core Components

• cmd/server/main.go - Application entry point with graceful shutdown

• config/ - Environment-based configuration management

• kafka/ - Kafka client wrapper using franz-go library

• mcp/ - MCP server implementation with tools, resources, and prompts

Key Dependencies

• github.com/twmb/franz-go - High-performance Kafka client

• github.com/mark3labs/mcp-go - Model Context Protocol implementation

• github.com/testcontainers/testcontainers-go/modules/kafka - Integration testing

Configuration

Environment variables control all configuration:

• KAFKA_BROKERS - Comma-separated broker list (default: localhost:9092)

• KAFKA_CLIENT_ID - Client identifier (default: kafka-mcp-server)

• MCP_TRANSPORT - Transport method: stdio/http (default: stdio)

• KAFKA_SASL_* - SASL authentication (PLAIN, SCRAM-SHA-256, SCRAM-SHA-512)

• KAFKA_TLS_* - TLS configuration

MCP Implementation

The server exposes:

• Tools - Kafka operations (produce/consume messages, describe topics/groups, etc.)

• Resources - Cluster health reports and diagnostics (overview, health-check, under-replicated-partitions, consumer-lag-report)

• Prompts - Pre-configured workflows for common operations

Code Structure

• kafka/interface.go - Defines KafkaClient interface

• kafka/client.go - Implementation using franz-go

• mcp/tools.go - MCP tool handlers

• mcp/resources.go - MCP resource handlers

• mcp/prompts.go - Pre-configured prompt definitions

Entry Point Details

The main.go correctly passes the KafkaClient interface to MCP registration functions, enabling dependency injection and testability.

CI/CD Pipeline

The project uses GitHub Actions with:

• Code Quality - golangci-lint, go mod tidy verification

• Security - govulncheck, Trivy scanning, SBOM generation

• Testing - Unit and integration tests with coverage

• Build Verification - For PRs and non-main branches

Testing Notes

Integration tests require Docker for Kafka containers. Use SKIP_KAFKA_TESTS=true to run only unit tests during development.