starfetch

# Starfetch

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/starfetch-logo-dark.svg" />
    <source media="(prefers-color-scheme: light)" srcset="assets/starfetch-logo-light.svg" />
    <img src="assets/starfetch-logo-light.svg" width="420" alt="Starfetch" />
  </picture>
</p>

<p align="center">
  <a href="https://github.com/starfetch-js/starfetch/actions/workflows/ci.yml"><img src="https://github.com/starfetch-js/starfetch/actions/workflows/ci.yml/badge.svg?branch=main&amp;event=push" alt="CI" /></a>
  <a href="https://codecov.io/gh/starfetch-js/starfetch"><img src="https://codecov.io/gh/starfetch-js/starfetch/graph/badge.svg?branch=main" alt="Coverage" /></a>
  <a href="https://registry.modelcontextprotocol.io/?search=io.github.starfetch-js%2Fstarfetch"><img src="https://img.shields.io/badge/MCP_Registry-listed-6f42c1" alt="MCP Registry" /></a>
  <a href="https://www.skills.sh/starfetch-js/starfetch/starfetch"><img src="https://img.shields.io/badge/skills.sh-starfetch-111827" alt="skills.sh" /></a>
  <a href="https://www.npmjs.com/package/@starfetch-js/mcp"><img src="https://img.shields.io/npm/v/@starfetch-js/mcp?label=npm" alt="npm version" /></a>
</p>

Starfetch gives AI agents safe, reproducible access to public astronomy
catalogs through the
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro).

Ask an astronomy question in natural language. A Starfetch-enabled agent can
select an appropriate service, inspect its live tables and columns, construct
a bounded ADQL query, execute it, and return the result with the exact service,
table, query, limit, units, and assumptions it used.

<p align="center">
  <img src="assets/demo.gif" width="900" alt="A Starfetch-enabled agent inspecting Gaia metadata, ranking high-proper-motion sources near the Pleiades, and summarizing the results" />
</p>

```text
You: Find the 10 Gaia DR3 sources with the highest proper motion within 0.5
     degrees of the Pleiades center at RA 56.75°, Dec +24.12°. What stands out?

Agent: selects Gaia → inspects metadata → runs bounded ADQL →
       returns catalog rows, exact ADQL, units, and assumptions
```

Representative captured result:

```text
Service: ESA Gaia Archive
Table: gaiadr3.gaia_source
Rows returned: 10
Query limit: TOP 10 / MAXREC 10

Highest returned proper motions:
- Gaia DR3 66780900298410496: 244.48 mas/yr
- Gaia DR3 66524409149512064: 184.50 mas/yr

Exact ADQL:
SELECT TOP 10 source_id, ra, dec, pm, pmra, pmdec, parallax, parallax_error,
  phot_g_mean_mag, bp_rp, ruwe
FROM gaiadr3.gaia_source
WHERE CONTAINS(POINT('ICRS', ra, dec), CIRCLE('ICRS', 56.75, 24.12, 0.5)) = 1
  AND pm IS NOT NULL
ORDER BY pm DESC
```

Gaia, SIMBAD, VizieR, the NASA Exoplanet Archive, and IRSA are available as
built-in service presets. Agents can also discover and query other public TAP
services by URL. Starfetch remains TAP-native and keeps ADQL visible, so the
agent workflow is convenient without becoming a scientific black box.

## Start here

- [Connect an agent](#connect-an-agent)
- [What the agent does](#what-the-agent-does)
- [Why Starfetch?](#why-starfetch)
- [Reliability without hidden assumptions](#reliability-without-hidden-assumptions)
- [Optional Starfetch skill](#optional-starfetch-skill)
- [Supported scope](#supported-scope)
- [CLI and TypeScript](#cli-and-typescript)
- [Run the Gaia proper-motion demo](#run-the-gaia-proper-motion-demo)
- [Development](#development)

## Connect an agent

The local npm server is Starfetch's stable public connection path. It runs on
your computer and can be registered with any compatible MCP client.

### Local npm server

Register Starfetch with the agent client that will launch it. Running the MCP
package by itself only starts a stdio server; it does not connect that server to
an agent. Starfetch is also discoverable through the
[official MCP Registry](https://registry.modelcontextprotocol.io/?search=io.github.starfetch-js%2Fstarfetch).

#### Codex

Register Starfetch for the Codex CLI, IDE extension, and ChatGPT desktop app:

```sh
codex mcp add starfetch -- npx -y @starfetch-js/mcp
codex mcp list
```

These Codex surfaces share MCP configuration. See the
[official Codex MCP documentation](https://developers.openai.com/codex/mcp).

#### Claude Code

Register Starfetch in user scope:

```sh
claude mcp add --scope user --transport stdio starfetch -- npx -y @starfetch-js/mcp
claude mcp get starfetch
```

See the
[official Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp).

#### Cursor

Add this server entry to `~/.cursor/mcp.json` for global use or
`.cursor/mcp.json` for one project:

```json
{
  "mcpServers": {
    "starfetch": {
      "command": "npx",
      "args": ["-y", "@starfetch-js/mcp"]
    }
  }
}
```

See the
[official Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol).

Other MCP clients can use the same stdio command and arguments through their
own server-registration interface:

```text
command: npx
args: -y @starfetch-js/mcp
```

Restart or reload the client after registration, then ask a normal astronomy
question. You should not need to write ADQL or name Starfetch tools in the
prompt. Starfetch requires Node.js 22 or newer.

### Remote MCP

A remote MCP service runs on the internet and accepts MCP connections over
HTTPS. No Starfetch package has to be installed or launched on the user's
computer. Compatible clients can connect to the production endpoint:

```text
https://starfetch-mcp-app-production-wumkqeiqaa-ew.a.run.app/mcp
```

The remote service is public, unauthenticated, bounded, and best effort. Do
not send credentials, private archive URLs, sensitive personal data, or
unbounded workloads. The local npm server remains the default when you want
local control or when a client does not support remote Streamable HTTP MCP.

See the remote service's [overview](apps/mcp-app/README.md),
[privacy notice](apps/mcp-app/PRIVACY.md),
[support](apps/mcp-app/SUPPORT.md), and
[terms of use](apps/mcp-app/TERMS.md).

## What the agent does

For a service-specific catalog question, Starfetch guidance teaches the agent
to:

1. choose an explicit service preset or public TAP URL;
2. check service availability when appropriate;
3. inspect relevant tables and the selected table's columns;
4. construct ADQL only from discovered schema information;
5. bound exploratory work with ADQL `TOP`, TAP `MAXREC`, or both;
6. execute the smallest useful query;
7. return the service, table, exact ADQL, effective limit, format, units, and
   relevant assumptions;
8. return to metadata after a schema or syntax failure instead of guessing.

The agent should never present a timeout, availability failure, parse error, or
query error as an empty scientific result. A successful zero-row result and a
failed request are different outcomes.

Starfetch exposes tools for the complete workflow:

```text
starfetch_list_presets
starfetch_registry_search
starfetch_tap_availability
starfetch_tap_capabilities
starfetch_tap_tables
starfetch_tap_columns
starfetch_tap_query
starfetch_tap_submit_job
starfetch_tap_job_status
starfetch_tap_job_wait
starfetch_tap_job_fetch
starfetch_tap_job_delete
```

Query tools return result data separately from diagnostics. They preserve the
exact submitted ADQL and effective row limit for reproduction and review.
Synchronous queries and async submissions send TAP `MAXREC=100` when `maxrec`
is omitted.

The remote HTTP service returns an opaque `jobCapability` with each async
submission. Supply that value unchanged to every remote status, wait, fetch,
or delete call. The capability remains usable while the remote job exists and
the service signing secret is unchanged. Remote deletion is marked destructive
so MCP clients can obtain user approval. The stdio MCP server and CLI keep
their existing job-reference behavior and do not advertise remote-only fields.

## Why Starfetch?

Starfetch is a useful middle layer when an agent needs live public catalog data
without turning the workflow into a black box:

- it inspects live schemas instead of guessing table and column names;
- it bounds public-service queries by default and preserves service failures;
- it returns exact ADQL, limits, units, and assumptions for reproduction;
- it provides one metadata-first interface across several TAP services; and
- its CLI and TypeScript library can reproduce an agent's query outside the
  agent client.

Use an archive's own interface, PyVO/Astropy, or local analysis tools instead
when you need authenticated/private archives, extensive local analysis, image
data processing, or authoritative astrophysical interpretation.

## Reliability without hidden assumptions

The MCP server works without installing a filesystem skill. Starfetch carries
the same canonical guidance through three overlapping layers:

| Layer                     | Role                                                                            |
| ------------------------- | ------------------------------------------------------------------------------- |
| MCP tool descriptions     | Minimum metadata-first and bounded-query contract available to every MCP client |
| MCP prompts and resources | Discoverable workflows, ADQL guidance, service notes, and examples              |
| Optional Starfetch skill  | Rich multi-step behavior across longer agent interactions                       |

The server exposes the retrievable prompts `query_astronomy_catalog`,
`explore_service`, `run_cone_search`, and `troubleshoot_adql`. Canonical
Markdown resources are available under `starfetch://guides/`,
`starfetch://services/`, and `starfetch://examples/`.

Prompt and resource support depends on the MCP client. Tool descriptions remain
self-sufficient for basic safe operation when a client exposes tools only. The
optional skill contains the full workflow, service references, and examples.

## Optional Starfetch skill