gx-mcp-server: Instructions file for Claude Code

CLAUDE.md

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

Development Commands

Installation and Setup

# Install uv package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install project with dependencies
uv sync

# Install pre-commit hooks
uv run pre-commit install

Running the Server

The server can be run in different modes using the --transport argument. The default transport is stdio.

When using Docker, the transport can be controlled with the MCP_MODE environment variable, which defaults to stdio.

# STDIO mode (for AI clients like Claude Desktop)
uv run python -m gx_mcp_server

# HTTP mode (for web-based clients)  
uv run python -m gx_mcp_server --http

# Development mode with MCP Inspector (testing UI)
uv run python -m gx_mcp_server --inspect

Testing

uv run pytest                         # Run all tests
uv run pytest tests/test_datasets.py  # Run specific test file
uv run pytest tests/test_expectations.py
uv run pytest tests/test_validation.py

# Run end-to-end examples
python scripts/run_examples.py

Code Quality

uv run ruff format .              # Format code and sort imports
uv run ruff check . --fix          # Lint and fix issues
uv run mypy gx_mcp_server         # Type checking
uv run pre-commit run --all-files  # Run pre-commit hooks

Development Workflow

# Add new dependency
uv add package-name

# Add development dependency  
uv add --dev package-name

# Update dependencies
uv sync --upgrade

# Run commands in the virtual environment
uv run python script.py

Architecture Overview

This is a Great Expectations MCP Server that exposes Great Expectations functionality through the Model Context Protocol (MCP). The server provides data validation capabilities as MCP tools for LLM agents.

Core Components

MCP Server (gx_mcp_server/__init__.py & gx_mcp_server/server.py):

• Main MCP server instance using FastMCP framework
• Supports both STDIO and HTTP transports
• Client-agnostic design works with any MCP-compatible LLM agent