# CLAUDE.md

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

## Project Overview

Apollo MCP Server is a Model Context Protocol (MCP) server that exposes GraphQL operations as MCP tools for AI models. It provides a standard way for AI models to access and orchestrate APIs running with Apollo GraphOS.

## Build & Test Commands

```bash
# Build
cargo build
cargo build --release

# Run all tests
cargo test

# Run a single test
cargo test test_name

# Run tests for a specific crate
cargo test -p apollo-mcp-server

# Linting (CI enforces --deny warnings)
cargo clippy --all-targets -- --deny warnings

# Formatting
cargo fmt
cargo fmt --check

# Generate documentation
cargo doc --no-deps

# Code coverage (requires cargo-llvm-cov)
cargo llvm-cov --all-features --workspace --codecov --output-path codecov.json
```

## Runtime Quick Reference

- Start with config file: `cargo run -p apollo-mcp-server -- path/to/config.yaml`
- Start from env only: `cargo run -p apollo-mcp-server`
- Config precedence: `APOLLO_MCP_*` env overrides YAML values.
- Supported transports: `stdio` (default) and `streamable_http`; `sse` is not supported.
- YAML env expansion supports `${env.VAR}` and `${env.VAR:-default}`.

### Common Config Keys

- Top-level keys: `endpoint`, `transport`, `operations`, `schema`, `introspection`, `graphos`, `overrides`, `headers`, `forward_headers`, `health_check`, `cors`, `telemetry`, `logging`, `server_info`, `instructions`, `custom_scalars`.
- `auth` must be nested under `transport` (not top-level).
- `operations.source`: `infer` (default), `local`, `manifest`, `collection`, `introspect`, `uplink`.
- `schema.source`: `local` or `uplink`.

### Useful Env Vars

- GraphOS mapping:
  - `APOLLO_GRAPH_REF` -> `graphos.apollo_graph_ref`
  - `APOLLO_KEY` -> `graphos.apollo_key`
  - `APOLLO_UPLINK_ENDPOINTS` -> `graphos.apollo_uplink_endpoints`
- Nested config override format: `APOLLO_MCP_<SECTION>__<NESTED_KEY>=...`
  - Example: `APOLLO_MCP_INTROSPECTION__EXECUTE__ENABLED=true`

## Workspace Structure

The project is a Rust workspace with three crates:

- **apollo-mcp-server** (`crates/apollo-mcp-server/`) - Main binary. MCP protocol handler, HTTP/WebSocket transport, GraphQL execution, auth, telemetry.
- **apollo-mcp-registry** (`crates/apollo-mcp-registry/`) - Schema and operations provider. Handles schema sources (Uplink, local files) and operation sources (Platform API collections, persisted queries, local files).
- **apollo-schema-index** (`crates/apollo-schema-index/`) - GraphQL schema indexing using Tantivy for full-text search.

## Key Architecture Patterns

**Server State Machine** (`apps/tools/states/`): The server transitions through states: Configuring → SchemaConfigured → OperationsConfigured → Running.

**MCP Apps** (`apps/`): Tool definitions (execute, introspect, search, validate), resources (schema, operations), and manifests.

**Operations Module** (`operations/`): Converts GraphQL operations into MCP tools, handles variable coercion and execution.

**Runtime Configuration** (`runtime/`): YAML config parsing with environment variable expansion (`${VAR}` syntax), telemetry setup, auth configuration.

## Code Quality Requirements

- **Clippy**: Strict lints enforced. Panics, unwraps, and expects are denied in library code.
- **Coverage**: 80% minimum on new/modified code (patch coverage).
- **Pre-commit**: Run `cargo test`, `cargo clippy`, `cargo fmt` before committing.
- **Testing**: Uses `rstest` for parameterized tests, `insta` for snapshot testing, `mockito` for HTTP mocking.

## Key Dependencies

- `rmcp 0.14` - MCP protocol implementation
- `apollo-compiler`, `apollo-federation` - GraphQL parsing and schema handling
- `axum 0.8` - HTTP server
- `tokio` - Async runtime
- `opentelemetry` - Observability

## Security Considerations

- Input validation on external data
- JWT authentication with JWKS support
- Host header validation for DNS rebinding protection
- Secrets are never logged (use `secrecy` crate)
