Starfetch Examples

Runnable examples for querying astronomy TAP services with Starfetch, plus an MCP Inspector walkthrough for exploring Starfetch's tools, prompts, and resources through a real MCP client.

The examples cover these TAP and ADQL workflows:

• service, table, and column discovery;
• bounded synchronous ADQL queries;
• explicit asynchronous TAP job lifecycle commands;
• VOTable, CSV, TSV, JSON, and JSONL output;
• Gaia, SIMBAD, VizieR, NASA Exoplanet Archive, and IRSA;
• the Starfetch CLI, TypeScript API, and MCP server.

Setup

Node.js 22.13 or newer is required.

Install the exact Starfetch versions recorded in the lockfile:

npm ci

Run an example

Every example has its exact ADQL in a .sql file, expected output columns, and a cross-platform Node.js runner:

node 01-gaia-nearby-stars/run.mjs

Generated result files are written to the example's ignored out/ directory. Run all live examples with:

npm run examples:live

Live examples contact public TAP services. Default CI omits them because remote availability, rate limits, and network conditions are outside this repository's control.

Explore the MCP server

Launch MCP Inspector against the installed Starfetch server:

npm run inspect:mcp

Follow the Inspector walkthrough to retrieve Starfetch resources and prompts, inspect metadata, execute a bounded query, and examine failure recovery against public TAP services.

Examples

• 01-gaia-nearby-stars: nearby Gaia DR3 sources.
• 02-gaia-high-proper-motion: high proper-motion Gaia DR3 sources.
• 03-gaia-hr-diagram-table: starter table for downstream HR diagrams.
• 04-simbad-field-object-types: SIMBAD object types in a sky region.
• 05-simbad-identifiers-join: SIMBAD basic to ident join.
• 06-vizier-catalog-field-query: VizieR Gaia DR3 field query.
• 07-vizier-filtered-catalog-query: bounded VizieR catalog query.
• 08-exoplanet-target-shortlist: NASA Exoplanet Archive shortlist export.
• 09-exoplanet-transiting-hosts: known transiting exoplanet hosts.
• 10-irsa-wise-region-query: IRSA AllWISE cone query.
• 11-irsa-spatial-query-cookbook: IRSA cone, box, and polygon queries.
• 12-gaia-async-large-query: Gaia TAP async submit/status/wait/fetch/delete.

Development checks

npm run format:check
npm run lint
npm run typecheck
npm run smoke

The smoke test starts the installed Starfetch MCP server over stdio and checks that representative tools, prompts, and resources are discoverable without querying a remote TAP service.

License

MIT