# MCP Server for Query Layer API

An MCP (Model Context Protocol) server that exposes a metrics query-layer API to AI assistants. Built with the official Python MCP SDK v2.

## Quick Start

```bash
# Prerequisites: Python 3.10+, uv
uv sync
uv run mcp dev src/server.py
```

Open the MCP Inspector at the URL printed to the console. You'll see the `ping` tool available.

## Cursor Integration

The `.cursor/mcp.json` file is pre-configured. Restart Cursor and the `query-layer` MCP server will be available to the AI assistant.

## Local Tracing with Phoenix (Optional)

```bash
# Terminal 1: start Phoenix
uv run phoenix serve

# Terminal 2: run the server pointing at Phoenix
export PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006
uv run mcp dev src/server.py
```

View traces at http://localhost:6006 — Phoenix natively renders MCP tool calls, prompts, and GenAI spans.

## Documentation

| Document | Purpose |
|----------|---------|
| [Plan](docs/plan.md) | Problem statement, solution approach, implementation plan |
| [Review](docs/review.md) | Production-grade plan review |
| [Design](docs/design.md) | MCP concepts, technology choices, design decisions |
| [Getting Started](docs/getting-started.md) | Setup, install, run, configure, troubleshoot |
| [Observability](docs/observability.md) | Logging, tracing, OTLP, local Phoenix |

## Project Structure

```
src/
  server.py          # MCPServer + tools (entry point)
  logging_config.py  # Structured JSON logging to stderr
  otel_config.py     # OpenTelemetry exporter configuration
.cursor/
  mcp.json           # Cursor MCP server configuration
docs/
  plan.md            # Full implementation plan
  review.md          # Plan review
  design.md          # Design document
  getting-started.md # Setup guide
  observability.md   # Observability guide
```

## License

Apache 2.0 — see [LICENSE](LICENSE).