> For the complete documentation index, see [llms.txt](https://docs.tuannvm.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tuannvm.com/kafka-mcp-server/claude.md).

# 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tuannvm.com/kafka-mcp-server/claude.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.