astronomy-mcp-server

<div align="center"> <h1>天文学计算服务器</h1> <p><b>计算天体的位置 - 离线计算天体位置、升降时间、相位、月食、日食和季节信息，支持通过MCP协议的STDIO或流式HTTP访问。</b> <div>7 个工具 • 1 个资源 • 1 个提示</div> </p> </div> <div align="center"> [](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/astronomy-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/astronomy-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/) </div> <div align="center"> [](https://github.com/cyanheads/astronomy-mcp-server/releases/latest/download/astronomy-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=astronomy-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvYXN0cm9ub215LW1jcC1zZXJ2ZXIiXX0=) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22astronomy-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fastronomy-mcp-server%22%5D%7D) [](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) </div> --- ## 工具列表 七个工具 - 五个核心工具形成无密钥、离线、确定性的核心（始终注册）；两个网络支持的扩展工具仅在配置门控启用时注册。 | 工具 | 描述 | |:---|:---| | `astronomy_get_sky_position` | 天体的视位置 - 赤道坐标（RA/Dec）、地平坐标（alt/az）、黄道坐标，以及距离、星等、角直径、相位和星座。 | | `astronomy_get_rise_set` | 天体的升降时间 - 包括太阳的三种暮光对（民用、航海、天文）。 | | `astronomy_get_moon_phase` | 月球相位 - 照明分数、相位名称、月龄、相位角度和接下来的四个月相时间戳。 | | `astronomy_find_events` | 搜索下一个天体事件 - 日食、月食、春分、夏至、月球四分之一、冲日、合日、最大伸长和近地点/远地点。 | | `astronomy_list_visible` | 可见天体列表 - 排名、注释和门控的太阳系天体（和可选的亮星），按太阳高度分为日光/暮光/黑暗。 | | `astronomy_get_ephemeris` | *( gated extension )* 小行星/彗星/航天器的时序星历数据 - 通过JPL Horizons API，默认关闭。 | | `astronomy_get_satellite_passes` | *( gated extension )* 卫星的可见通过 - 通过CelesTrak TLE传播，默认关闭。 | 该服务器计算天体的几何位置 - 而不是天体物理学。核心工具封装了 [`astronomy-engine`](https://github.com/cosinekitty/astronomy) （亚弧度精度，≈1900–2100），因此给定相同的 `(body, time, observer)`，每个核心工具返回相同的输出，无需网络、速率限制或API密钥。它不执行地理编码：请在上游解析位置名称为纬度/经度（例如，通过OpenStreetMap服务器），并传递IANA `timezone`以接收观察者本地时间以及UTC时间。 ### `astronomy_get_sky_position` 天体的视顶心位置。 - 赤道坐标（RA/Dec）、地平坐标（altitude/azimuth）和黄道坐标 - 距离、视星等、角直径、相位角、照明分数和天体所属星座 - 默认海拔0米，默认时间为当前时间 - 如果引擎无法计算，则`null`星等 / 角直径 / 相位字段 - 绝不会伪造 --- ### `astronomy_get_rise_set` 天体的升降时间，以及太阳的暮光。 - 从 `start` 开始搜索并返回接下来的 `count` 个周期（默认为1，最大31） - 对于 `body: "sun"`，包含三种暮光对（民用 -6°，航海 -12°，天文 -18°），因此单个调用即可回答“太阳何时落山，何时真正黑暗？” - 环极/从不升起的情况报告为 `null` 升降字段，并附有解释性 `note` - 事实就是答案 - 可选的观察者本地时间，当提供IANA `timezone` 时 --- ### `astronomy_find_events` 在单个 `event` 枚举下，搜索九类事件。 - `solar_eclipse`, `lunar_eclipse`, `equinox`, `solstice`, `moon_quarter`, `opposition`, `conjunction`, `max_elongation`, `perigee_apogee` - 太阳食需要观察者（`latitude`/`longitude`）并报告本地可见性和接触时间；月食是地心的，不需要位置 - 与天体相关的事件（`opposition`, `conjunction`, `max_elongation`, `perigee_apogee`）需要一个 `body`；`max_elongation` 仅对水星和金星定义 - 返回接下来的 `count` 次事件（默认为1，最大20） --- ### `astronomy_list_visible` 工作流旗舰 - 一个调用返回排名、条件门控的“当前可见”列表。 - 遍历每个裸眼太阳系天体（和 `include_stars` 包含的亮星），保留高于地平线的天体，并按亮度和高度排名靠前 - 为每个天体附加一个纯语言的 `visibility_note`，根据实际星等和高度计算 - 没有合成置信度评分 - 返回整个天空条件（`daylight` / `civil_twilight` / `nautical_twilight` / `astronomical_twilight` / `dark`）和太阳高度以及列表 - `time` 是一个单独的评估瞬间，而不是一个窗口 - 对于“今晚”，请传递一个天文黄昏之后的时间（使用 `astronomy_get_rise_set` 找到它） - 使用 `min_altitude` 跳过接近地平线的天体 --- ### `astronomy_get_ephemeris` *( gated extension )* 通过无密钥的JPL Horizons API获取小行星/彗星/航天器的时序星历数据。仅在设置 `ASTRONOMY_ENABLE_HORIZONS` 时注册。 - 涵盖进程内主要天体引擎无法看到的小行星、彗星和航天器 - 指定传递给Horizons原样，必须解析为单个记录： - **编号小行星** - 尾随分号记录查找：`"433;"` （Eros），`"1;"` （Ceres） - **周期性彗星** - DES + 最近接近标志：`"DES=1P;CAP"` （哈雷），`"DES=2P;CAP"` （恩克） - **航天器** - 负SPK-ID：`"-48"` （哈勃） - 裸名称如 `"433 Eros"` 或 `"1P/Halley"` 返回无匹配或模糊记录列表，并被拒绝。 在 [ssd.jpl.nasa.gov/tools/sbdb_lookup.html](https://ssd.jpl.nasa.gov/tools/sbdb_lookup.html) 处查找指定 - `start`/`stop` 为ISO 8601 UTC；`step` 为Horizons步骤字符串（`"1d"` ， `"1h"` ， `"10m"` ） - 提供观察者 `latitude`/`longitude` 可获得地心坐标并添加alt/az - 大跨度内联截断为200行，并附有披露 - 加宽步骤以减少行数 --- ### `astronomy_get_satellite_passes` *( gated extension )* 卫星在观察者上方的可见通过。仅在设置 `ASTRONOMY_ENABLE_SATELLITES` 时注册。 - 通过NORAD目录编号（例如ISS的 `25544` ）从CelesTrak获取当前的TLE，并在进程中使用SGP4传播 - 返回每个通过的升降时间和方位角以及峰值海拔 - 仅返回裸眼似然通过 - 卫星在峰值时必须被阳光照亮，而观察者的天空必须黑暗 - NORAD目录编号在 [celestrak.org](https://celestrak.org) 或 [heavens-above.com](https://heavens-above.com) - 搜索接下来的 `days` （默认为7，最大10）；可选的观察者本地通过时间 ## 资源和提示 | 类型 | 名称 | 描述 | |:---|:---|:---| | 资源 | `astronomy://body/{body}` | 太阳系天体的静态参考卡 - 规范名称、类型、平均半径（公里）和裸眼可见性。 `{body}` 是 `sun` 、 `moon` 、 `mercury` 等之一。 | | 提示 | `astronomy_stargazing_plan` | 构建一个“今晚在 \<place\> 观星”的工作流，按顺序链接工具并命名跨服务器的地理编码和天气步骤。 | 所有资源数据也可以通过工具访问 - `astronomy_get_sky_position` 内联返回相同的天体元数据 - 因此仅使用工具的客户端不会损失任何功能。 设计参考： [`docs/design.md`](./docs/design.md)。 ## 功能 构建于 [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core): - 声明式工具、资源和提示定义 - 每个基元一个文件，框架处理注册和验证 - 统一错误处理 - 处理程序抛出，框架捕获、分类和格式化 - 可插拔身份验证： `none` 、 `jwt` 、 `oauth` - 可交换存储后端： `in-memory` 、 `filesystem` 、 `Supabase` 、 `Cloudflare KV/R2/D1` - 带有可选OpenTelemetry跟踪的结构化日志记录 - STDIO和Streamable HTTP传输；核心无密钥，是Cloudflare Workers可移植的（纯JS，无原生依赖） 天文学特定： - 无密钥、离线、确定性核心 - `astronomy-engine` 是位置天文学的源头；无网络、速率限制或API密钥用于五个核心工具 - 提供 `timezone` 时，每个输出都有UTC和观察者本地时间；服务器从不根据坐标猜测时区 - 捆绑的亮星目录，因此 `astronomy_list_visible` 和 `astronomy_get_sky_position` 回答命名星的问题 - 两个门控扩展（默认关闭）超出主要天体集 - JPL Horizons小行星和CelesTrak卫星通过，每个都有自己的超时/重试边界；它们大声降级，从不无声回落到核心 代理友好输出： - 保留不确定性 - 星等、角直径、相位和照明为 `null` （不是0，不是省略）时不可用，并且 `format()` 渲染“不可用”而不是编造值 - 服务器计算的可见性说明是根据实际星等和高度的确定性散文 - 没有合成置信度评分 - 类型错误合约带有恢复提示（范围外时间、缺少观察者/天体、无法解析的指定）以便调用者可以纠正并重试 - `format()` 在每个工具上都是内容完整的 - `content[]`-only 客户端看到与 `structuredContent` 客户端相同的数据 ## 入门指南 将以下内容添加到MCP客户端配置文件中。五个核心工具不需要配置；设置 `ASTRONOMY_ENABLE_HORIZONS` 和/或 `ASTRONOMY_ENABLE_SATELLITES` 为 `true` 以注册门控扩展。 ```json { "mcpServers": { "astronomy-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/astronomy-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } } } ``` 或使用npx（不需要Bun）： ```json { "mcpServers": { "astronomy-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/astronomy-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } } } ``` 或使用Docker： ```json { "mcpServers": { "astronomy-mcp-server": { "type": "stdio", "command": "docker", "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/astronomy-mcp-server:latest"] } } } ``` 流式HTTP，设置传输并启动服务器： ```sh MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http # 服务器监听 http://localhost:3010/mcp ``` ### 先决条件 - [Bun v1.3.0](https://bun.sh/) 或更高版本（或Node.js v24+）。 - 无需API密钥 - 核心和两个无密钥扩展（JPL Horizons，CelesTrak）不需要凭证。 ### 安装 1. **克隆仓库： ```sh git clone https://github.com/cyanheads/astronomy-mcp-server.git` ``` 2. **导航到目录： ```sh cd astronomy-mcp-server` ``` 3. **安装依赖： ```sh bun install` ``` ## 配置 所有配置都是可选的，并在 `src/config/server-config.ts` 中通过Zod模式验证。核心运行没有任何配置。 | 变量 | 描述 | 默认值 | |:---|:---|:---| | `ASTRONOMY_ENABLE_HORIZONS` | 注册 `|astronomymcp-server` 工具（JPL Horizons）。 | `false` | | `ASTRONOMY_ENABLE_SATELLITES` | 注册 `astronomy_get_satellite_passes` 工具（CelesTrak + SGP4）。 | `false` | | `ASTRONOMY_HORIZONS_BASE_URL` | 覆盖JPL Horizons API端点。 | `https://ssd.jpl.nasa.gov/api/horizons.api` | | `ASTRONOMY_CELESTRAK_BASE_URL` | 覆盖CelesTrak GP/TLE端点。 | `https://celestrak.org/NORAD/elements/gp.php` | | `ASTRONOMY_DEFAULT_TIMEZONE` | 默认IANA时区，当工具调用省略 `timezone` 时。设置为 `None` = 仅UTC输出。 | 无 | | `ASTRONOMY_REQUEST_TIMEOUT_MS` | Horizons和CelesTrak请求的HTTP超时（毫秒）。 | `15000` | | `ASTRONOMY_TLE_CACHE_TTL_MS` | 进程内TLE缓存TTL（毫秒）- 尊重CelesTrak的重新获取指导（约每2小时一次）。 | `7200000` | | `MCP_TRANSPORT_TYPE` | 传输： `stdio` 或 `http`。 | `stdio` | | `MCP_HTTP_PORT` | HTTP服务器的端口。 | `3010` | | `MCP_AUTH_MODE` | 认证模式： `none` ， `jwt` 或 `oauth`。 | `none` | | `MCP_LOG_LEVEL` | 日志级别（RFC 5424）。 | `info` | | `LOGS_DIR` | 日志文件目录（仅限Node.js）。 | `<project-root>/logs` | | `STORAGE_PROVIDER_TYPE` | 存储后端。 | `in-memory` | | `OTEL_ENABLED` | 启用 [OpenTelemetry 仪表盘](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry)。 | `false` | 参见 [.env.example](https://github.com/cyanheads/astronomy-mcp-server/blob/main/.env.example) 获取完整的覆盖项列表。 ## 运行服务器 ### 本地开发 - **构建并运行：** ```sh # 一次性构建 bun run rebuild # 运行构建的服务器 bun run start:stdio # 或 bun run start:http ``` - **运行检查和测试：** ```sh bun run devcheck # 校验、格式化、类型检查、安全检查 bun run test # Vitest 测试套件 bun run lint:mcp # 验证MCP定义是否符合规范 ``` ### Docker ```sh docker build -t astronomy-mcp-server . docker run --rm -e MCP_TRANSPORT_TYPE=stdio astronomy-mcp-server ``` Dockerfile 默认使用HTTP传输、无状态会话模式，并将日志输出到 `/var/log/astronomy-mcp-server`。OpenTelemetry对等依赖项已默认安装 - 构建时添加 `--build-arg OTEL_ENABLED=false` 以省略它们。 ## 项目结构 | 目录 | 用途 | |:---|:---| | `src/index.ts` | `createApp()` 入口点 - 注册工具/资源/提示并初始化服务。 | | `src/config` | 服务器特定的环境变量解析和验证，带有Zod。 | | `src/mcp-server/tools` | 工具定义（ `*.tool.ts` ）。五个核心工具加上两个门控扩展。 | | `src/mcp-server/resources` | 资源定义（ `*.resource.ts` ）。天体参考卡。 | | `src/mcp-server/prompts` | 提示定义（ `*.prompt.ts` ）。观星计划。 | | `src/services/ephemeris` | 离线计算核心 - `astronomy-engine` 包装器、天体半径表和捆绑的亮星目录。 | | `src/services/horizons` | JPL Horizons HTTP客户端（门控扩展）。 | | `src/services/satellite` | CelesTrak TLE获取 + SGP4传播（门控扩展）。 | | `tests/` | 单元测试和集成测试，镜像 `src/`。 | ## 开发指南 参见 [CLAUDE.md](https://github.com/cyanheads/astronomy-mcp-server/blob/main/CLAUDE.md) 获取开发指南和架构规则。简而言之： - 处理程序抛出，框架捕获 - 工具逻辑中没有 `try/catch` - 使用 `ctx.log` 进行请求范围内的日志记录，使用 `ctx.state` 进行租户范围内的存储 - 在 `src/index.ts` 中的 `createApp()` 数组中注册新工具和资源 - 标准化原始引擎/API值到域类型；保留不确定性为 `null`，绝不伪造缺失字段 ## 贡献 问题和拉取请求均受欢迎。运行检查和测试： ```sh bun run devcheck bun run test ``` ## 许可证 Apache-2.0 - 详情请参见 [LICENSE](https://github.com/cyanheads/astronomy-mcp-server/blob/main/LICENSE) 。