Starfetch

Starfetch

Starfetch 让 AI Agent 能够通过 Model Context Protocol (MCP)， 安全、可复现地访问公开天文目录。

用自然语言提出天文学问题。启用 Starfetch 的 Agent 可以选择合适的服务，检查其实时表和列，构建有界的 ADQL 查询，执行查询，并返回结果以及所用的确切服务、表、查询、限制、单位和假设。

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

具有代表性的捕获结果：

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、NASA Exoplanet Archive 和 IRSA 均提供内置服务预设。Agent 也可以通过 URL 发现并查询其他公开 TAP 服务。Starfetch 保持 TAP 原生特性，并让 ADQL 清晰可见，因此 Agent 工作流既便捷，也不会变成科学黑箱。

从这里开始

• 连接 Agent
• Agent 的工作方式
• 为什么选择 Starfetch？
• 在不隐藏假设的前提下确保可靠性
• 可选的 Starfetch 技能
• 支持范围
• CLI 和 TypeScript
• 运行 Gaia 自行演示
• 开发

连接 Agent

本地 npm 服务是 Starfetch 稳定的公共连接方式。它在你的计算机上运行，可注册到任何兼容的 MCP 客户端。

本地 npm 服务

在将启动 Starfetch 的 Agent 客户端中注册 Starfetch。单独运行 MCP 包只会启动一个 stdio 服务；它不会将该服务连接到 Agent。Starfetch 也可以通过官方 MCP Registry发现。

Codex

为 Codex CLI、IDE 扩展和 ChatGPT 桌面应用注册 Starfetch：

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

这些 Codex 界面共用 MCP 配置。请参阅 Codex 官方 MCP 文档。

Claude Code

在用户范围内注册 Starfetch：

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

请参阅 Claude Code 官方 MCP 文档。

Cursor

全局使用时，将此服务条目添加到 ~/.cursor/mcp.json；仅用于某个项目时，添加到 .cursor/mcp.json：

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

请参阅 Cursor 官方 MCP 文档。

其他 MCP 客户端可通过各自的服务注册界面，使用相同的 stdio 命令和参数：

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

注册后，重启或重新加载客户端，然后提出常规天文学问题。你无需在提示词中编写 ADQL 或提及 Starfetch 工具。Starfetch 要求 Node.js 版本为 22 或更高。

远程 MCP

远程 MCP 服务运行于互联网，可通过 HTTPS 接受 MCP 连接。用户的计算机无需安装或启动 Starfetch 软件包。兼容的客户端可连接到生产环境端点：

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

远程服务是公开的、无需身份验证的、有限制的，并按尽力而为原则提供服务。请勿发送凭据、私有档案 URL、敏感个人数据或无界工作负载。若你需要本地控制，或客户端不支持远程 Streamable HTTP MCP，则本地 npm 服务仍是默认选择。

请参阅远程服务的概述、 隐私声明、 支持和 使用条款。

Agent 的工作方式

对于特定服务的星表问题，Starfetch 指引会教 Agent：

1. 选择明确的服务预设或公共 TAP URL；
2. 在适当情况下检查服务是否可用；
3. 检查相关表以及所选表的列；
4. 仅根据已发现的架构信息构建 ADQL；
5. 使用 ADQL TOP、TAP MAXREC，或两者同时使用，限制探索性查询；
6. 执行最小且有用的查询；
7. 返回服务、表、完整 ADQL、实际生效的限制、格式、单位和相关假设；
8. 遇到架构或语法错误时，回到元数据检查，而不是猜测。

Agent 绝不能将超时、可用性故障、解析错误或查询错误说成没有科学结果。成功返回零行与请求失败是不同的结果。

Starfetch 提供完整工作流所需的工具：

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

查询工具会分别返回结果数据和诊断信息。它们会保留提交的完整 ADQL 和实际生效的行数限制，以便复现和审查。若未提供 maxrec，同步查询和异步提交都会发送 TAP MAXREC=100。

远程 HTTP 服务会在每次异步提交时返回一个不透明的 jobCapability。每次远程状态查询、等待、获取或删除调用时，都应原样提供该值。只要远程作业仍存在且服务签名密钥未变，此能力值就仍然有效。远程删除会标记为破坏性操作，以便 MCP 客户端征求用户批准。stdio MCP 服务和 CLI 保持现有的作业引用行为，不会公布仅适用于远程服务的字段。

为什么选择 Starfetch？

当 Agent 需要实时公共星表数据，同时又不希望工作流变成黑箱时，Starfetch 是实用的中间层：

• 它检查实时架构，而不是猜测表名和列名；
• 它默认限制公共服务查询，并保留服务故障信息；
• 它返回完整 ADQL、限制、单位和假设，以便复现；
• 它通过一个以元数据为先的界面，统一访问多个 TAP 服务；并且
• 它的 CLI 和 TypeScript 库可在 Agent 客户端之外复现 Agent 的查询。

如果你需要访问经身份验证的私有档案、大规模本地分析、图像数据处理或权威的天体物理解释，则应改用档案自身的界面、PyVO/Astropy 或本地分析工具。

无隐藏假设的可靠性

MCP 服务无需安装文件系统技能即可运行。Starfetch 通过三个相互补充的层，提供相同的规范指南：

层	作用
MCP 工具描述	为每个 MCP 客户端提供以元数据为先且查询范围受限的最低约定
MCP 提示词和资源	可发现的工作流、ADQL 指南、服务说明和示例
可选的 Starfetch 技能	支持 Agent 在较长交互中执行丰富的多步骤操作

该服务提供可检索的提示词 query_astronomy_catalog、 explore_service、run_cone_search 和 troubleshoot_adql。规范 Markdown 资源位于 starfetch://guides/、 starfetch://services/ 和 starfetch://examples/ 下。

提示词和资源的支持情况取决于 MCP 客户端。当客户端只提供工具时，工具描述仍足以支持基本的安全操作。可选技能包含完整工作流、服务参考和示例。

可选的 Starfetch 技能

如果 Agent 客户端支持文件系统技能，且你希望获得更强大的多轮交互能力，请安装该技能。MCP 服务不要求安装此技能，但我们建议安装。

通过 skills.sh 直接从 GitHub 安装规范技能：

npx skills add https://github.com/starfetch-js/starfetch/tree/main/packages/skill/skill/starfetch

检查或安装打包好的技能：

npx -y @starfetch-js/cli skill print
npx -y @starfetch-js/cli skill install --target codex
npx -y @starfetch-js/cli skill install --target claude-code --scope project
npx -y @starfetch-js/cli skill install --target cursor

使用以下命令将技能安装到自定义目标目录：

npx -y @starfetch-js/cli skill install --path ./starfetch-skill

使用 --dry-run 预览文件操作。默认目标位置如下：

• Codex 用户范围：~/.codex/skills/starfetch
• Claude Code 用户范围：~/.claude/skills/starfetch
• Codex 项目范围：.codex/skills/starfetch
• Claude Code 项目范围：.claude/skills/starfetch
• Cursor 项目范围：.cursor/rules/starfetch.mdc

Codex 和 Claude Code 默认使用用户范围。Cursor 默认使用项目范围，因为其规则属于项目文件。

支持范围

Starfetch 专为公共天文表格访问协议服务而设计。 目前提供：

• 内置 gaia、simbad、vizier、exoplanetarchive 和 irsa 预设；
• 搜索 VO 注册表以查找其他 TAP 端点；
• VOSI 可用性、功能、表和列元数据；
• 有界同步 ADQL 查询；
• 明确的 TAP/UWS 异步作业提交、状态查询、等待、获取和删除；
• VOTable、CSV 和 TSV 请求，以及安全的 JSON 和 JSONL 转换；
• 精确的查询和限制诊断。

Starfetch 不接受凭据，也不实现经过身份验证的 TAP 工作流。 MCP 服务不会执行 shell 命令，也不会写入本地结果文件。 Starfetch 会检索星表数据；它不会验证天体物理解释，也不会协调不同星表之间的科学差异。

VOTable TABLEDATA 和内嵌的 base64 BINARY/BINARY2 行可以转换。 VOTable FITS 行、远程流和压缩流仍会直接传递，或不支持在本地转换行数据。

CLI 和 TypeScript

MCP 是 Agent 的主要接口。CLI 适用于编写脚本、在 Agent 之外检查查询，以及复现 Agent 报告的确切请求。TypeScript 库适用于应用程序和自定义适配器。

CLI 快速入门

安装或运行一次 CLI：

npm install -g @starfetch-js/cli
npx -y @starfetch-js/cli tap tables --service gaia

编写特定于服务的 ADQL 之前，先检查元数据：

starfetch tap availability --service gaia
starfetch tap tables --service gaia
starfetch tap columns --service gaia --table gaiadr3.gaia_source

运行有界查询：

starfetch tap query \
  --service gaia \
  --query "SELECT TOP 5 source_id, ra, dec FROM gaiadr3.gaia_source" \
  --format json

ADQL 可以来自 --query、文件或 stdin。可使用 --out 写入结果数据：

starfetch tap query --service gaia --file query.sql --format csv --out result.csv
cat query.sql | starfetch tap query --service gaia --format jsonl

使用 --service 指定预设，或使用 --url 指定明确的 TAP 基础 URL。如果两者都提供， 则由 --url 选择端点，而服务名称仍会作为诊断上下文保留。

通过 VO 注册表发现其他服务：

starfetch tap registry search gaia --maxrec 5 --format json

异步作业

对于规模较大且有充分理由的查询，请使用显式异步作业：

starfetch tap jobs submit \
  --service gaia \
  --query "SELECT TOP 10 source_id, ra, dec FROM gaiadr3.gaia_source" \
  --maxrec 10

starfetch tap jobs status <job-url>
starfetch tap jobs wait --interval 2000 --timeout 120000 <job-url>
starfetch tap jobs fetch <job-url> --format votable --out result.xml
starfetch tap jobs delete <job-url>

后续命令使用完整作业 URL 即可。裸作业 ID 需要搭配 --service 或 --url，以便 Starfetch 解析 TAP /async 端点。

TypeScript API

当脚本、应用或自定义 Agent 适配器需要直接访问 TAP 时，请安装 @starfetch-js/core：

npm install @starfetch-js/core

import { registry, tap } from "@starfetch-js/core";

const client = tap("gaia");
const columns = await client.columns("gaiadr3.gaia_source");
const result = await client.query(
  "SELECT TOP 5 source_id, ra, dec FROM gaiadr3.gaia_source",
  { format: "votable", maxrec: 5 },
);

console.log(columns.length);
console.log(await result.fields());
console.log(await result.overflow());
console.log(await result.json());

const services = await registry().searchTapServices({
  query: "gaia",
  maxrec: 5,
});
console.log(services[0]?.accessUrl);

tap(target) 接受已知预设、TAP 基础 URL，或包含 service 和/或 URL 的对象。元数据方法会读取 TAP /availability、/capabilities 和 /tables；同步查询使用 /sync，显式作业使用 /async。

运行 Gaia 自行运动演示

重现该演示中以元数据为先的 Gaia 查询，并打印确切的 ADQL、 有效限制值和返回行：

git clone https://github.com/starfetch-js/starfetch.git
cd starfetch
npm ci
npm run build
node examples/quickstart/run.mjs

此命令会查询公开的 Gaia TAP 服务。有关更多 CLI、TypeScript API、 实时 TAP 和 MCP Inspector 工作流，请参阅 starfetch-js/examples。每个示例 都包含确切的 ADQL、预期列和跨平台 Node.js 运行器。

git clone https://github.com/starfetch-js/examples.git
cd examples
npm ci
node 01-gaia-nearby-stars/run.mjs

从该仓库启动 MCP Inspector：

npm run inspect:mcp

软件包

• @starfetch-js/mcp：主要的 stdio MCP 服务和打包的 Agent 指南。
• @starfetch-js/skill：可选的 Starfetch Agent 技能分发包。
• @starfetch-js/cli：用于脚本编写、TAP 检查、查询、异步作业和技能 安装的命令。
• @starfetch-js/core：可复用的 TAP、VOSI、UWS、VOTable、注册表和输出 转换基础功能。

开发

使用已提交的锁定文件安装依赖：

npm ci

使用以下命令运行私有 Streamable HTTP 开发应用：

npm run dev:http

它在 http://127.0.0.1:3000/mcp 提供 MCP 服务，并在 http://127.0.0.1:3000/health 提供进程健康状态。每个 MCP 请求都会创建一个全新的无状态 @starfetch-js/mcp 服务。HTTP 接口保留 12 个规范 Starfetch 工具不变，并通过不可变的 ui://starfetch/table/v1 MCP Apps 资源添加两个与 UI 关联的工具。starfetch_render_table 会展示 已有的表格视图，而不会提交 TAP 请求。 starfetch_query_table 会为交互式科学表格运行同步 JSON 查询；完整加载的表格仅供小组件使用，而模型会收到 20 行预览。普通 MCP 客户端无需加载小组件，仍可继续使用规范的文本和结构化结果。配置仅通过 环境变量设置：

• HOST 默认为 127.0.0.1；如需监听所有接口，请显式设置为 0.0.0.0。
• PORT 默认为 3000。
• ALLOWED_ORIGINS 是以逗号分隔的精确浏览器源列表，默认不允许任何源。
• SHUTDOWN_GRACE_MS 默认为 10000，接受 1 到 60000。
• STARFETCH_JOB_CAPABILITY_SECRET 是至少 32 字节的 base64url 密钥。 当 HOST 不是回环地址时，此密钥为必填项；若未设置，回环开发环境会使用 每个进程独有的临时密钥。

匿名 HTTP 策略是固定且经过测试的产品配置，而非一组可独立调整的环境变量。它将 MCP 请求限制为 2 MiB、TAP 响应限制为 8 MiB、内联上传限制为 1 MiB、MAXREC 限制为 10,000、重定向限制为 3、出站请求限制为 4 个并发操作，工具运行时间限制为 60 秒。规范同步查询的默认值仍为 MAXREC=100；交互式表格查询的默认值为 MAXREC=1000，并将其小组件负载限制为 6 MiB。 作业等待默认时长为 30 秒，最长为 45 秒，轮询间隔为 1 到 10 秒。该进程每分钟全局最多接受 100 个 MCP 请求；需要按客户端实施限制的部署应在可信的 HTTPS 入口处执行。

HTTP 主机仅接受不含凭据且完整 DNS 解析结果均为公有地址的 HTTPS TAP 目标，并会为每个请求跳转固定已验证的地址、确保重定向保持同源、不自动跟随写入重定向，并拒绝远程 URI TAP 上传。这些限制适用于匿名 HTTP 应用，不适用于本地 stdio MCP、CLI 或 TypeScript API。 如需在不打开小组件的情况下验证协议接口，请启动应用，并在另一个 shell 中运行 MCP Inspector 的 CLI：

npx -y @modelcontextprotocol/inspector@latest --cli http://127.0.0.1:3000/mcp --transport http --method tools/list
npx -y @modelcontextprotocol/inspector@latest --cli http://127.0.0.1:3000/mcp --transport http --method tools/call --tool-name starfetch_list_presets

如需在 MCP Inspector 的 Apps 标签页中渲染小组件：

1. 保持 npm run dev:http 持续运行，然后启动 Inspector UI，不要指定 stdio 服务命令：

   npx -y @modelcontextprotocol/inspector@latest
   

2. 在 Inspector 中选择 Via Proxy，选择 Streamable HTTP，输入 http://127.0.0.1:3000/mcp，将身份验证留空，然后连接。

3. 打开 Apps，选择 Refresh Apps，然后选择 starfetch_render_table。Apps 标签页列出的是关联 UI 的工具，而不是 服务名称。

4. 将有效的有界表格视图粘贴到 App Input，然后选择 Open App。 这个最小预设视图可在不发起实时 TAP 请求的情况下测试小组件：

   {
     "contractVersion": 1,
     "resultKind": "presets",
     "title": "TAP service presets",
     "columns": [
       { "key": "name", "label": "Name" },
       { "key": "url", "label": "TAP URL" }
     ],
     "rows": [
       {
         "name": "gaia",
         "url": "https://gea.esac.esa.int/tap-server/tap"
       }
     ],
     "source": { "tool": "starfetch_list_presets" },
     "state": "populated",
     "clipping": {
       "reasons": [],
       "sourceRows": 1,
       "sourceColumns": 2
     }
   }
   

Apps 标签页需要 Streamable HTTP 端点；规范的 stdio 服务会公开核心 Starfetch 工具，但不包含 UI 资源。Inspector 的 Via Proxy 模式可使用默认来源策略。如需使用 Direct 模式， 请在启动应用时明确允许 Inspector 的浏览器来源：

ALLOWED_ORIGINS=http://localhost:6274,http://127.0.0.1:6274 npm run dev:http

小组件使用标准 MCP Apps 主机桥接来处理工具结果、主题变量、显示模式请求、模型上下文更新和文件下载。 它也会在 ChatGPT 的初始工具全局变量存在时读取这些变量，并且仅在下载时回退使用 ChatGPT 的 文件 API。其 React UI 使用语义化表格标记、全局 TanStack Table 排序、按页选择行、桌面端每页 100 行、 移动端每页 10 行，以及针对精确 ADQL 的细粒度 Shiki SQL 高亮。 桌面端表格使用有上限的双轴滚动视口；移动端表格会扩展至页面高度，并保留宽结果的水平滚动。操作工具栏中有一个仅显示图标的控件，可请求全屏或内嵌显示模式。另一个操作可将所选行或当前页提供给模型，以供下一轮使用；它不会公开整个已加载表格。该操作始终可用，每次按下都会替换之前待处理的模型上下文快照。该资源不声明任何网络或静态资源域名，仅请求 clipboard-write 权限。

运行其单元测试、单文件构建和浏览器主机验收检查：

npm --workspace @starfetch-js/mcp-app run check
npm --workspace @starfetch-js/mcp-app run test:browser

使用 Docker 构建并对生产 Linux 容器进行冒烟测试：

npm run smoke:container

镜像工作流会将不可变容器发布到 ghcr.io/starfetch-js/starfetch-mcp-app。

如需使用 ChatGPT Developer Mode 或其他远程 MCP Apps 主机，请通过 HTTPS 暴露本地 MCP 端点，将生成的 /mcp URL 添加到主机，调用元数据工具检查目标，然后调用 starfetch_query_table。请验证浅色和深色主题、全屏和内嵌模式、水平滚动、 排序、分页、高亮显示与复制 ADQL、当前页模型上下文，以及 TSV、CSV 和 JSON 的复制与下载操作。 主机特有的视觉差异应通过桥接主题变量处理，而不是另行实现一套组件。

如需临时远程 URL，开发机器可以运行：

cloudflared tunnel --url http://127.0.0.1:3000 --http-host-header 127.0.0.1:3000

HTTP 应用不设身份验证。它采用粗粒度的进程级固定窗口限流，每分钟限制 100 个 MCP 请求，并非针对每个客户端的滥用防护。快速隧道是公开且临时的：仅用于非敏感测试流量，测试后立即停止。这款开发应用并非生产部署基础设施。

该工作区需要 Node.js >=22.13.0。运行：

npm run format:check
npm run lint
npm run typecheck
npm test
npm run coverage
npm run build
npm run smoke:cli

对发布敏感的 Agent 接口检查包括：

npm --workspace packages/mcp run typecheck
npm --workspace packages/mcp run test
npm --workspace packages/mcp run build
npm --workspace packages/mcp run smoke

npm --workspace @starfetch-js/mcp-app run check

npm --workspace packages/skill run typecheck
npm --workspace packages/skill run test
npm --workspace packages/skill run build

默认测试仅使用本地固定数据和模拟。可选的实时 TAP 检查需显式运行：

npm run test:live:tap

许可证

MIT