# Setup Guide

## Prerequisites
- Docker
- Node.js v18+ (for `npx mcp-remote`)
- VPN access to QA environment (for Option A)
- Auth credentials (JWT, orchard identity headers)

## Quick Start

### 1. Configure environment
```bash
cp .env.example .env
# Edit .env with your credentials
```

### 2. Start the MCP server
```bash
docker run -it --rm \
  --name apollo-mcp \
  -p 8000:8000 \
  --env-file .env \
  -v $(pwd)/mcp.yaml:/config.yaml \
  -v $(pwd)/operations:/operations \
  -v $(pwd)/schema.graphql:/schema.graphql \
  ghcr.io/apollographql/apollo-mcp-server:v1.11.0 /config.yaml
```

### 3. Connect Claude Code
```bash
claude mcp add apollo-mcp -- npx mcp-remote http://127.0.0.1:8000/mcp
```

### 4. Test
In a new Claude Code session, the MCP tools should be available. Try:
- Use the `search` tool to find types related to "artist" or "analytics"
- Use the `introspect` tool to explore a specific type
- Use the `validate` tool to check a query before running it
- Use the `execute` tool to run a query

## Alternative: Local Router (Option B)

If you can't reach the QA router directly, run a local router:

### 1. Install router binary
```bash
curl -sSL https://router.apollo.dev/download/nix/latest | sh
```

### 2. Clone the router repo and compose the supergraph
```bash
git clone git@github.com:theorchard/graphql-router.git
cd graphql-router
./scripts/generate-supergraph.sh
```

### 3. Run the router
```bash
cp config-qa.yaml config.yaml
./router --hot-reload -c config.yaml -s supergraph.graphql
```
Router listens on `http://localhost:8080/graphql`.

### 4. Update .env
```
GRAPHQL_ENDPOINT=http://host.docker.internal:8080/graphql
```
Note: Use `host.docker.internal` instead of `localhost` since the MCP server runs in Docker.

### 5. Start MCP server and connect (same as Quick Start steps 2-4)

## Adding Operations

Create `.graphql` files in the `operations/` directory:

```graphql
# operations/SearchKnowledge.graphql

# Search the knowledge graph for entities matching a query.
# Returns artist, label, and release information.
query SearchKnowledge($query: String!, $limit: Int) {
  search(query: $query, limit: $limit) {
    results {
      ... on Artist {
        id
        name
      }
    }
  }
}
```

Files hot-reload automatically — no restart needed.

## Troubleshooting

### MCP server can't reach the endpoint
- Verify VPN is connected (for QA URLs)
- Check `docker logs apollo-mcp` for connection errors
- For local router, use `host.docker.internal` not `localhost`

### "Missing apollographql-client-name" error
The router plugin enforces this header. It's set in `mcp.yaml` as `frontend-insights`.

### Auth errors
Ensure your JWT token in `.env` is valid and not expired. Get a fresh token from your QA session.