mysql-schema-explorer-mcp: Instructions file for Claude Code

CLAUDE.md

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

Commands

Running Tests

# Run all tests
go test ./...

# Run tests with verbose output
go test -v ./...

# Run a specific test
go test -run TestListTables

Building

# Build the binary
go build -o mysql-schema-explorer-mcp

# Install globally
go install

Local Development with Docker

# Start MySQL test instance
docker-compose up -d

# Set environment variables for local testing
export DB_HOST=127.0.0.1
export DB_PORT=3306
export DB_USER=root
export DB_PASSWORD=root

Architecture

This is a Model Context Protocol (MCP) server that provides MySQL schema information to LLM applications. The codebase follows a clean architecture pattern:

• main.go: Entry point that sets up the MCP server, loads DB configuration from environment variables, and registers the two available tools (list_tables and describe_tables)
• handler.go: Contains the business logic for handling MCP tool requests. Implements ListTables and DescribeTables methods
• db.go: Database layer that handles MySQL connections and queries. Provides methods for fetching table metadata, columns, indexes, and constraints
• view.go: Formatting layer that converts raw database schema information into human-readable output

The server uses the mcp-go library (github.com/mark3labs/mcp-go) to implement the MCP protocol and communicates via stdio.

Code Guidelines

Language

• Use English for all comments and documentation.
• Use Japanese for all comments and documentation when the code is written in Japanese.

Appropriate Use of Comments

⚠️ Important: Keep comments to the absolute minimum. Do not comment on things that are immediately obvious from reading the code.

Limited cases where comments should be written:

1. Public API documentation: For documenting public methods and interfaces
2. Background context: When there's important background information not evident from the code
3. Complex logic explanation: When complex code requires explanation to understand the intended behavior
4. Large code section separation: For 100+ line code blocks where sectioning with explanatory comments is beneficial