mcp-odbc: Instructions file for Claude Code

CLAUDE.md — mcp-odbc

Agent and contributor guide for the Universal ODBC MCP Server.

---

What This Is

mcp-odbc — a Python MCP server that connects to any ODBC data source, auto-detects the DBMS, and exposes schema discovery + read-only query tools. Designed for Claude Code but works with any MCP client.

---

Architecture (read before writing code)

MANDATORY: Read research/05_architecture_design.md before making any changes. It contains the full design spec including module structure, tool signatures, adapter pattern, config schema, and security model. All code should follow this design.

Key Research Files

File	What It Covers
research/05_architecture_design.md	START HERE — full architecture, module structure, phased roadmap
research/01_mcp_sdk_patterns.md	FastMCP v2 API, tool decorators, transport, error handling, testing
research/02_existing_implementations.md	4 repos analyzed, anti-patterns to avoid, ideas to steal
research/03_pyodbc_drivers.md	pyodbc catalog API, driver quirks, encoding, platform differences
research/04_erp_schemas_detection.md	12 ERP/DB systems, detection queries, SQL_DBMS_NAME values, drift

---

Tech Stack

• FastMCP v2.x (fastmcp>=2.0,<3.0) — MCP framework, decorator-based tools
• pyodbc >=5.0 — ODBC driver binding
• Pydantic >=2.0 — config validation
• Transport: STDIO (Claude Code native)
• Packaging: pyproject.toml + hatchling
• Testing: pytest + pytest-asyncio + FastMCP Client

---

Module Structure

mcp-odbc/
+-- pyproject.toml
+-- src/mcp_odbc/
|   +-- __init__.py
|   +-- server.py           # FastMCP server + tool registration + entry point
|   +-- connection.py       # ConnectionManager (lazy connect, health check, close)
|   +-- config.py           # Pydantic models, env var / INI loading
|   +-- query.py            # Query execution, read-only enforcement
|   +-- metadata.py         # Schema discovery, caching
|   +-- detection.py        # DBMS detection via SQL_DBMS_NAME
|   +-- formatting.py       # Markdown tables, JSON, value truncation
|   +-- errors.py           # SQLSTATE mapping, credential sanitization
|   +-- adapters/
|       +-- __init__.py     # Adapter registry + get_adapter()
|       +-- base.py         # SystemAdapter ABC
|       +-- generic.py      # GenericODBCAdapter (ODBC catalog fallback)
|       +-- netsuite.py     # OA_TABLES, OA_COLUMNS, OA_FKEYS
|       +-- mssql.py        # sys.* catalog views
|       +-- postgresql.py   # pg_catalog
|       +-- mysql.py        # INFORMATION_SCHEMA
|       +-- oracle.py       # ALL_* data dictionary
|       +-- (others)        # hana, db2, sage, quickbooks
+-- tests/
+-- config/config.example.ini
+-- research/               # Research docs (read-only reference)