# Syncnox MCP Server

An [MCP](https://modelcontextprotocol.io) server that gives AI agents (like Claude) direct access to the Syncnox route-management backend.

## Transport

**Streamable HTTP** — the server exposes a single HTTP endpoint at `/mcp`.  
This means you can deploy it in Docker, expose it over the network, and connect multiple remote clients.

## Authentication

Every request must include the header:

```
X-API-Key: <your MCP_API_KEY>
```

The server itself also authenticates to your Syncnox FastAPI backend using a Bearer token (`API_KEY`).

## Available Tools

| Tool                    | What it does                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------- |
| `add_stop`              | Add a new stop to an existing route                                                   |
| `optimize_route`        | Re-order stops for fastest time or shortest distance                                  |
| `get_eta`               | Get ETA for the whole route or a single stop                                          |
| `get_route`             | Fetch full route details including all stops                                          |
| `get_job_info`          | Fetch the details of a specific job by its ID                                         |
| `add_job`               | Add a single job (address geocoded automatically)                                     |
| `add_jobs`              | Add multiple jobs from a JSON list of dictionaries (addresses geocoded automatically) |
| `import_jobs_from_text` | Import jobs from CSV content passed directly as text                                  |
| `import_jobs_from_file` | Import a list of jobs from a local CSV/Excel file path                                |

## Project Layout

```
syncnox-mcp/
├── server.py          ← entry point, Streamable HTTP app
├── middleware.py      ← API-key auth middleware (production ASGI wrapper)
├── config.py          ← settings loaded from .env
├── api_client.py      ← shared httpx client for Syncnox backend
├── tools/
│   ├── __init__.py    ← central tools registry exposing register_all()
│   ├── routes.py      ← route-related tools (get_route, optimize_route, get_eta)
│   ├── stops.py       ← stop-related tools (add_stop)
│   └── jobs.py        ← job-related tools (get_job_info)
├── requirements.txt
└── .env               ← secrets (not committed to git)
```

## Setup

```bash
# 1. Create & activate virtual env
python -m venv .venv
source .venv/bin/activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure
cp .env .env.local    # edit values
# Set: API_BASE_URL, API_KEY, MCP_API_KEY, PORT

# 4. Run
python server.py
```

Server starts at `http://0.0.0.0:8100`.

## Connecting a Client

In Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "syncnox": {
      "type": "http",
      "url": "http://localhost:8100/mcp",
      "headers": {
        "X-API-Key": "changeme-mcp-secret"
      }
    }
  }
}
```

## Health Check

```bash
curl http://localhost:8100/health
# → OK
```

## Deployment on EC2

```bash
cd syncnox-mcp
git pull
sudo systemctl restart syncnox-mcp.service
```