mcp-csv-database: 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

This is an MCP (Model Context Protocol) server that provides tools for loading CSV files into a temporary SQLite database and executing SQL queries on the data. The server is built using FastMCP framework and provides a comprehensive set of tools for data analysis.

Development Commands

Installation and Setup

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Install from source
pip install -e .

Testing

# Run all tests
pytest

# Run tests with coverage
pytest --cov=src/mcp_csv_database

# Run specific test file
pytest tests/test_server.py

# Run with verbose output
pytest -v

Code Quality

# Format code with black (line length: 100)
black src/ tests/ examples/

# Sort imports with isort
isort src/ tests/ examples/

# Lint with flake8
flake8 src/ tests/ examples/

# Type checking with mypy
mypy src/

Running the Server

# Basic stdio transport
mcp-csv-database

# With auto-loading CSV files
mcp-csv-database --csv-folder /path/to/csv/files

# With different transports
mcp-csv-database --transport sse --port 8080
mcp-csv-database --transport streamable-http --port 8080

# Run module directly for development
python -m mcp_csv_database.server --csv-folder ./examples/sample_data

Code Architecture

Core Components

Main Server File (src/mcp_csv_database/server.py):

• Single-file MCP server implementation using FastMCP framework
• Global state management with _db_connection, _loaded_tables, _db_path
• Automatic CSV separator detection (tries ;, ,, \t)
• Temporary SQLite database creation and management
• Built-in cleanup functionality with atexit handlers

Key MCP Tools:

• load_csv_folder(): Loads CSV files from directory into SQLite
• execute_sql_query(): Executes SQL queries with automatic JSON formatting
• get_database_schema(): Returns complete database schema information
• get_table_info(): Detailed information about specific tables
• export_table_to_csv(): Exports query results back to CSV
• create_index(): Creates database indexes for performance
• backup_database(): Creates SQLite database backups