Metadata-Version: 2.4
Name: trackline-mcp
Version: 0.2.0
Summary: Trackline MCP Client — Device Flow Auth + stdio<->SSE Bridge for the Trackline railway data platform
License: MIT
Keywords: ai,claude,mcp,railway,trackline
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# trackline-mcp

[![PyPI](https://img.shields.io/pypi/v/trackline-mcp)](https://pypi.org/project/trackline-mcp/)
[![Test & Lint](https://github.com/Trackline-Live/trackline-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/Trackline-Live/trackline-mcp/actions/workflows/test.yml)

A zero-dependency Python MCP client that bridges Claude Code (and other MCP hosts) to the [Trackline](https://trackline.live) railway data platform via SSE. Distributed as a `uvx`-runnable package — no manual installation or virtualenv required.

---

## Installation

### Via uvx (recommended)

No installation needed. Run directly:

```bash
uvx trackline-mcp --auth
```

### Via pip

```bash
pip install trackline-mcp
trackline-mcp --auth
```

---

## Authentication

Trackline MCP uses OAuth 2.0 Device Authorization Grant (no browser redirect required). You authenticate once and the token is cached at `~/.trackline/token.json` with automatic refresh via an offline token.

**Step 1 — Authenticate in a terminal:**

```bash
uvx trackline-mcp --auth
```

This opens a URL. Visit it, log in, and the token is cached automatically.

**Step 2 — Connect from Claude Code** (see config below — no manual step needed).

---

## Claude Code / MCP Configuration

Add to your `.mcp.json` (project or global):

```json
{
  "mcpServers": {
    "trackline": {
      "command": "uvx",
      "args": ["trackline-mcp"]
    }
  }
}
```

---

## How It Works

1. On first run (`--auth`), the client performs a Device Authorization Grant with Keycloak, opening a short URL for you to approve.
2. The token (including an offline refresh token) is cached at `~/.trackline/token.json`.
3. On subsequent runs, the client reads the cached token, refreshes it automatically if needed, then opens an SSE connection to the Trackline MCP server.
4. JSON-RPC messages from Claude Code arrive on stdin and are POSTed to the server; server SSE events are forwarded to stdout.
