Metadata-Version: 2.4
Name: grandline-mcp
Version: 0.1.0
Summary: MCP server for Grandline — empirical maritime distances + port lookups for LLM agents.
Project-URL: Homepage, https://grandline.luzomi.com
Project-URL: Source, https://github.com/dmsnavin/luzomi/tree/main/grandline/mcp
Project-URL: Issues, https://github.com/dmsnavin/luzomi/issues
Author-email: Navin Thakur <39754091+dmsnavin@users.noreply.github.com>
License: MIT
Keywords: ais,anthropic,claude,distance,maritime,mcp,shipping
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# grandline-mcp

[![PyPI](https://img.shields.io/pypi/v/grandline-mcp.svg)](https://pypi.org/project/grandline-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/grandline-mcp.svg)](https://pypi.org/project/grandline-mcp/)

MCP server that gives Claude / Cursor / any MCP-capable LLM access to the **Grandline maritime distance API** — empirical sea distances derived from real AIS vessel tracks, four route variants (primary / via-Suez / via-Panama / via-Cape), 43M cached port-pair distances.

## Install

```bash
pip install grandline-mcp
```

## Use with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```jsonc
{
  "mcpServers": {
    "grandline": {
      "command": "grandline-mcp",
      "env": {
        "GRANDLINE_API_KEY": "gl_live_…"   // from grandline.luzomi.com/signup; omit for anonymous tier
      }
    }
  }
}
```

Restart Claude Desktop. Ask: *"What's the empirical sea distance from Sabine Pass to Yokohama via Panama?"* — Claude will call the right tools.

## Tools exposed

| Tool | What it does |
|---|---|
| `port_lookup` | Resolve a port name, UN-LOCODE, or lat/lon string into a canonical port record. |
| `nearest_ports` | Return the N nearest cataloged ports to a lat/lon coordinate. |
| `find_route` | Empirical sea distance between two ports for one of four route variants. |
| `compare_routes` | All four variants side-by-side with canal transits and steaming days. |

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `GRANDLINE_API_URL` | `https://grandline.luzomi.com/api/v1` | Override the base URL (e.g. for self-hosted). |
| `GRANDLINE_API_KEY` | _(unset)_ | Bearer token from signup; without it you're on the anonymous tier (10/day, 100/month per IP). |
| `GRANDLINE_LOG_LEVEL` | `WARNING` | Verbosity. Logs go to stderr so they don't corrupt the stdio protocol stream. |

## Status

Alpha. The HTTP backend is stable; the MCP tool descriptions are still being tuned for LLM-friendliness.

## License

MIT.
