# Read-only Analytics MCP Server

A clean-room core for exposing warehouse queries as a guarded Model Context Protocol tool. It validates read-only SQL, injects a conservative row limit, requires JSON responses from the upstream API, and returns audit metadata without leaking authentication material.

This repository contains no production account locator, warehouse name, access token, table name, schema, query history, or employer configuration.

## What it demonstrates

- MCP tool design for analytics agents
- Read-only SQL validation
- SQL API request construction
- Required content negotiation headers
- Row and statement limits
- Secret-safe error handling
- Auditable query fingerprints

## Safety model

- Only one `SELECT`, `SHOW`, or `DESCRIBE` statement is accepted.
- Mutating keywords, comments, and multiple statements are rejected.
- `SELECT` queries receive a maximum row limit when one is not already present.
- Tokens are accepted by the transport boundary but never returned or logged.

## Run the tests

```bash
python -m unittest discover -s tests -v
```

## Run the optional MCP adapter

```bash
python -m pip install -e '.[mcp]'
export ANALYTICS_SQL_API_URL='http://localhost:9000/query'
export ANALYTICS_SQL_API_TOKEN='development-placeholder'
python -m readonly_analytics_mcp.mcp_server
```

The example values are local placeholders. Never commit a real token or private endpoint.

## Production extensions

- Replace the lightweight keyword guard with an AST-based SQL parser.
- Add per-tool table allowlists and policy-service authorization.
- Add a streamable-HTTP deployment option alongside the included stdio adapter.
- Add pagination, query cancellation, and structured observability.