# Trillian MCP

Ask an AI about the sky. This is a [Model Context Protocol](https://modelcontextprotocol.io)
server for [Trillian](https://api.trillianverse.org), a platform for discovery
and analysis across large, multi-archive astronomical datasets. Connect it to
Claude (or any MCP client) and plain questions become live queries against
real survey data — catalogs and image holdings, ultraviolet through infrared.

The demos below are replays of real sessions; every number and identifier is a
genuine response from the live API.

## A real session: finding the Crab Pulsar

One question — *"What do we know about the sky at the Crab Nebula?"* — and the
model, given only these six tools, identifies the Crab Pulsar's optical
counterpart in Gaia by matching its proper motion to the literature value,
then diagnoses the invisible synchrotron nebula from corrupted 2MASS
photometry flags. This is the unedited output of an actual session
([full transcript](transcripts/crab-pulsar-session.txt)):

![A real session: finding the Crab Pulsar](demos/svg/crab-pulsar.svg)

## Which images cover this spot?

One query, three archives, ultraviolet through infrared — every file addressed
by a stable [SciDD](https://api.trillianverse.org) identifier that resolves to
its home archive:

![File cone search across datasets](demos/svg/which-images.svg)

## It will not guess your units

Sexagesimal coordinates without units are ambiguous, and a wrong guess is a
wrong field on the sky. The server returns a structured question instead of an
assumption — the model relays it, the user decides:

![Ambiguous units are questioned, not guessed](demos/svg/wont-guess.svg)

## Tools

| Tool | What it does |
|---|---|
| `gaia_edr3_cone_search` | Cone search the Gaia EDR3 source catalog |
| `gaia_edr3_lookup` | Look up a single Gaia EDR3 source by `source_id` |
| `two_mass_cone_search` | Cone search the 2MASS All-Sky point source catalog |
| `two_mass_lookup` | Look up a single 2MASS source by designation |
| `file_cone_search` | Find image files overlapping a sky region, across datasets |
| `filename_search` | Find files by filename fragment |

Coordinates accept astronomer-friendly strings (`83.633d`, `05h34m32s`,
`-23:20:36`); inputs are normalized and validated against JSON schemas before
any request reaches the API. Ambiguous input produces a structured
clarification error rather than a guess.

The datasets exposed here — Gaia EDR3, 2MASS, and image holdings including
GALEX GR6, 2MASS, and WISE — are a demonstration slice of the platform's
index, not its full extent.

## Installation

Requires Python ≥ 3.10.

```sh
git clone https://github.com/demitri/trillian_mcp.git
cd trillian_mcp
pip install -r requirements.txt
```

Register with Claude Code:

```sh
claude mcp add trillian -- python3 /path/to/trillian_mcp/server.py
```

or add to any MCP client's server configuration:

```json
{
  "mcpServers": {
    "trillian": {
      "command": "python3",
      "args": ["/path/to/trillian_mcp/server.py"]
    }
  }
}
```

Then ask about the sky.

## Trying it without an MCP client

```sh
python3 demo_cli.py gaia-edr3-cone-search --ra "83.633d" --dec="+22.0145d" --radius "3m"
python3 demo_tests.py    # sanity checks against the live API
```

## About Trillian

Trillian organizes astronomical data spatially rather than by mission or
archive: one interface over files that remain distributed across their home
archives (MAST, IPAC, and others), backed by a metadata index of tens of
millions of files. Its development has been supported by a NASA Astrophysics
Data Analysis Program grant, an AWS Open Data resource award, and the Mozilla
Science Lab. This MCP server is a thin, public layer over its REST API.

## Regenerating the demos

The demo animations are scripted replays built from captured live responses
(no screen recording involved):

```sh
sh demos/render.sh    # rebuilds casts and renders SVGs (needs node for npx)
```