Mcp Stargazing

mcp-stargazing

计算地球上任意位置的天体（太阳、月亮、行星、恒星和深空天体）的高度角、升起和落下时间，并可选择进行光污染分析。

功能

• 高度角／方位角计算：获取任意天体的仰角和罗盘方向。
• 升起／落下时间：确定天体何时升出或落至地平线以下。
• 光污染分析：加载并分析光污染地图（GeoTIFF 格式）。
• 综合规划：综合地点质量、天气、月光和优选目标，生成按排名排列的观测计划。
• 工具发现：通过 get_tool_catalog 以编程方式检查已注册的 MCP 工具。
• 可直接执行代码：
  • 可序列化的返回值：所有工具均返回可序列化为 JSON 的数据（日期使用 ISO 字符串），可直接供大模型使用。
  • 分页：analysis_area 支持分页（page、page_size），可高效处理大型数据集。
  • 稳定的结果句柄：analysis_area.resource_id 用于标识缓存的非分页查询，使 Agent 能够安全地获取多个页面。
  • 标准化响应：调用成功时返回 { "data": ..., "_meta": ... }；业务验证失败时返回 { "error": ..., "_meta": ... }。
• 性能：
  • 异步执行：非阻塞式天体计算。
  • 缓存：为 Simbad 查询和区域分析提供智能缓存。
  • 代理支持：原生支持 HTTP/HTTPS 代理（便于下载天文数据）。
• 时区感知：支持本地时间或 UTC 时间。
• 数据驱动：集成了包含 10,000+ 个深空天体（梅西耶和 NGC）的数据库，可用于智能推荐。

安装

本项目使用 uv 管理依赖项。

本地安装

1. 安装 uv：

   pip install uv
   

2. 同步依赖项：

   uv sync
   

   这将在 .venv 中创建虚拟环境，并安装 pyproject.toml 中定义的所有依赖项。

3. 激活环境：

   source .venv/bin/activate
   

4. 初始化数据（夜间规划器必需）： 这会将最新的梅西耶和 NGC 星表数据下载到 src/data/objects.json。

   python scripts/download_data.py
   

   注意：如果你使用防火墙，请确保在运行此脚本前设置 HTTP_PROXY 环境变量。

Docker 安装

你也可以使用 Docker 运行服务，它会自动处理所有依赖项和数据初始化。

1. 构建镜像：

   docker build -t mcp-stargazing .
   

   注意：如果你使用代理，请在构建时传入代理 URL：

   docker build --build-arg HTTP_PROXY=http://127.0.0.1:7890 -t mcp-stargazing .
   

2. 运行容器：

   # Basic run (MCP on :3001 + SPF web UI on :5001)
   docker run -p 3001:3001 -p 5001:5001 mcp-stargazing
   
   # With Environment Variables
   docker run -p 3001:3001 -p 5001:5001 \
     -e QWEATHER_API_KEY=your_key \
     -e STARGAZING_DB_CONFIG=your_db_config \
     mcp-stargazing
   

3. 访问：

   • MCP 服务 → http://localhost:3001/shttp（供 AI Agent／MCP 客户端使用）
   • SPF 网页界面 → http://localhost:5001/（观星地点查找器前端）

Docker 架构

容器通过 supervisord 管理两个服务，两者通过 uv run 共用同一个 Python 虚拟环境：

Container
├── supervisord
│   ├── program:mcp      → uv run mcp-stargazing --mode shttp --port 3001
│   └── program:spf-web  → uv run uvicorn server.main:app --port 5001
│
Dependency resolution (single venv, no duplication):
  stargazing-core>=0.2.0  ←  resolved once from PyPI
  stargazing-place-finder>=0.9.1
  fastapi, uvicorn, ...   ←  SPF's transitive deps

MCP 服务用法

启动 MCP 服务，将工具提供给 AI Agent 或其他客户端使用。

Agent 优先方向

plan_stargazing_session 是第三方 Agent 首选的复合决策入口。 它接受地点名称、中心点和半径或精确边界；解析 Seestar S50、 HOPE D60 + ASI2600MC Air 或自定义光学配置；将数据提供方和数据库的选择保留在 服务端；并返回一项一等决策、备选方案、精确的评分组成部分、证据、 不确定性、重要的缺失输入、可能改变排名的条件以及后续操作。

get_best_stargazing_plan 和 get_multiday_stargazing_plan 仍作为兼容入口注册， 供现有以 bbox 为先的调用方使用。注册主入口前，确定性的 10 种场景门槛测试和 具有代表性的 Codex/Claude 黑盒冒烟测试均已通过。新的独立天文查询工具仍暂缓推出， 待长时间运行任务语义和 1.0 契约完成后再行考虑。

后台区域分析支持有界执行、重复提交处理、取消、截止时间、保留期限和分页结果检索。 任务工具会启用可选的 task_id / progress 元数据；运行中进度未知，运行时丢失则需要重新提交。有关 工作流、限制和恢复语义，请参阅任务生命周期。

请参阅第三方 Agent 契约、 工作区技术图谱和 Agent 演进清单。当前 21 个工具的路由和 参数审查记录在工具接口审计中。评估材料 和两个客户端的证据位于evaluations/下。

1.0 之前的公开架构基线记录了现有工具 架构以及详细的规划/区域模型。SDK 和真实的 tools/list 测试会在添加新工具前检测契约偏差。

独立的 1.0 契约和迁移指南冻结了全部 21 个工具、 任务模型、详细负载、注解和信封语义，同时保留该历史快照。两个以 bbox 为先的规划器仍受支持， 目前没有生效的弃用通知。未来若要移除，至少需要提前 90 天通知、经过两个后续次要版本，并在之后发布主版本。 包版本和响应 _meta.version 相互独立；冻结此契约并不代表发布版本。 要使用完整的主规划器客户端，请保存指南中的一条 JSON 请求并运行：

uv run python examples/agent_planning_demo.py --request request.json --url http://localhost:3001/shttp

1. 环境设置

创建 .env 文件或导出变量：

# Weather tools
# 推荐：使用你账号专属的 API Host（公共域名将从 2026 年起逐步停止服务）
export QWEATHER_API_HOST="abc1234xyz.def.qweatherapi.com"

# 鉴权（二选一）
# 1) API KEY（兼容旧用法）
export QWEATHER_API_KEY="your_api_key"
# 2) JWT（推荐，更安全）
# export QWEATHER_JWT_TOKEN="your_jwt_token"

# 如需临时兼容旧公共域名（不推荐），显式开启：
# export QWEATHER_ALLOW_PUBLIC_HOST=1

# Geocoding（默认零付费、零 key）
# CJK 查询默认使用内置离线行政区划数据；未命中时回退 Photon / Nominatim。
# 可选 provider 顺序覆盖（全部支持：gazetteer, photon, nominatim, amap）
# export GEOCODER_PROVIDERS="gazetteer,photon,nominatim"

# 仅当你希望显式启用付费的 Amap 地理编码时才需要：
# export GEOCODER_PROVIDERS="amap,gazetteer,photon,nominatim"
# export AMAP_KEY="your_amap_key"

# Optional: Proxy for downloading astronomical data (Simbad/IERS)
# Highly recommended if you are in a restricted network environment
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

2. 启动服务

Streamable HTTP（SHTTP）模式（推荐大多数 Agent 使用）：

# Basic start
python -m src.main --mode shttp --port 3001 --path /shttp

# With proxy explicitly passed (overrides env vars)
python -m src.main --mode shttp --port 3001 --path /shttp --proxy http://127.0.0.1:7890

SSE 模式：

python -m src.main --mode sse --port 3001 --path /sse

由于当前 FastMCP 版本已不再提供 run_dev()，因此不再支持 dev 模式。请使用 local、shttp 或 sse。

3. 响应格式

成功的业务响应会以标准化 JSON 格式返回数据：

{
  "data": {
    // Tool-specific return data
    "altitude": 45.5,
    "azimuth": 180.0
  },
  "_meta": {
    "version": "1.0.0",
    "status": "success"
  }
}

业务验证失败时使用相同的信封格式：

{
  "error": {
    "code": "INVALID_TIME_FORMAT",
    "message": "Invalid time format: invalid-time-format",
    "details": {
      "time_string": "invalid-time-format"
    }
  },
  "_meta": {
    "version": "1.0.0",
    "status": "error"
  }
}

在 MCP 协议层，tools/list 和 get_tool_catalog 保持一致；SHTTP 和 SSE 传输测试中均会保留 JSON-RPC 请求 ID。

每个工具的标准 MCP 描述都包含 适用场景、不适用场景、所需输入、 返回内容和后续操作指引。这些指引解释了主规划器与兼容入口、事实信息与观测决策、 同步与后台区域搜索，以及服务端本地时间和星座中心查询等常见范围陷阱。封装后的目录保留其摘要 description 和完整的 docstring；显式装饰器描述完整且优先适用。请参阅工具路由审计。

4. 可用工具

• get_celestial_pos：计算高度角和方位角。

• get_celestial_rise_set：计算升起和落下时间（返回 ISO 字符串）。使用 event_scope="calendar_day" 可采用历史上的完整本地日期行为；使用 event_scope="next_events" 可查找给定 time 之后的首次升起和首次落下，必要时跨越午夜。

• get_moon_info：获取详细的月相、照明度和月龄信息。

• list_visible_planets：列出当前位于地平线之上的所有行星及其位置。

• get_constellation：查找星座中心的位置（高度角/方位角）。

• get_nightly_forecast：智能规划工具，返回今晚最适合观测的精选天体列表（行星 + 深空天体），以及本地民用天文黑夜的 night_window，其中包含黄昏、黎明、时长、日期和时区。

• get_weather_by_name / get_weather_by_position：获取当前天气，网络故障时自动重试。

• get_local_datetime_info：获取当前本地时间信息。

• get_tool_catalog：发现可用的 MCP 工具元数据和参数。

• plan_stargazing_session：首选的端到端入口，用于确定一至七晚的观测时间、地点和目标。

  • 输入：一个 request 对象，包含 location（必须且只能指定 place_name、center 或 bounds 之一）、start_date、可选的 time_zone、nights、observation_style、equipment、候选项/目标数量限制以及人气偏好。
  • 设备：稳定预设为 seestar_s50 和 hope_d60_asi2600mc_air；高级调用方可以使用 custom，或覆盖单个光学参数。
  • 返回值：规范化后的请求和解析出的地理位置、首选方案 decision、排序后的 alternatives、可追溯的 evidence、uncertainties、重要的 missing_inputs、would_change_if 条件以及具体的 next_actions。
  • 路由：需要完整观测决策时使用此工具。需要查询具体事实时，直接使用天气、天体、望远镜或地点工具。

• get_best_stargazing_plan：生成排序后的区域观测计划，包含候选地点、天气摘要、最佳观测时段和优先目标。

  • 输入：south、west、north、east、time、time_zone、candidate_limit、target_limit、weather_provider、max_locations、min_height_diff、road_radius_km、network_type、observation_style、avoid_popular_spots、prefer_quiet_at_night、popularity_radius_km、db_config_path。
  • 候选项召回：candidate_limit 是返回的排序候选项数量。服务会先评估一个有上限的召回池，再进行最终截断，因此天气更好的地点可以超过静态排名更高的地点。
  • 成本感知评估：召回池首先进行低成本天气筛选；之后，仅对内部排名最高的候选项进行黑夜时段和目标预报评估，再生成最终排名。
  • 区域天气信号：如果可用，服务端会对整个 bbox 一次性采样 stargazing-core 空间云量网格，并将其纳入区域比较；空间模型故障时会降级处理，不会导致计划生成失败。
  • 返回值：包含 query、summary 和 candidates；其中 query.analysis_resource_id 可在可用时将计划关联到下层的中性 analysis_area 搜索。启用人气偏好后，MCP 会依据返回的启发式字段进行一次调整，在 candidates[*].recommendation_reasons 中列出相关原因，并在 summary.popularity_preferences_enabled、summary.primary_recommendation_drivers 和 summary.recommended_location_reason_summary 中概述首选推荐。每个候选项的 score_breakdown.factor_contributions 会显示用于排名的地点、天气、人气和交通便利性贡献值（含正负号）；说明原因时使用相同的有效因素。驱动因素取值为稳定枚举：dark_sky、high_place_score、clear_weather、good_visibility、observation_style_fit、low_popularity_risk、quiet_at_night 和 strong_targets。
  • 人气偏好归属：所有复合规划工具（单夜、多夜和 plan_stargazing_session）请求 SPF 地点评分时都会设置 avoid_popular_spots=false 和 prefer_quiet_at_night=false，同时保留 popularity_radius_km 和启发式依据。MCP 单独应用所请求的偏好；筛选和最终评估均从中性评分开始。请求回显会保留用户的偏好。要重现 query.analysis_resource_id（或主规划工具的地点 evidence.resource_id），请使用两个偏好标志都禁用的相同区域搜索。独立的 analysis_area 仍会将偏好转发给 SPF，并在启用偏好时使用单独的缓存条目。
  • 观测风格：balanced 保留默认行为。deep_sky 更重视暗夜天空和低月光，visual 提高天气权重，planetary 降低月光惩罚并优先考虑行星，beginner 还会优先考虑靠近道路的地点。
  • 黑夜时段：如果可以确定民用天文黑夜，每个候选项都会包含 night_window，其中包含本地日期、民用黄昏、次日民用黎明、时长和时区。只要逐小时数据允许，best_observation_window 现在表示连续的暗夜天空时段；start_time、天气字段以及新增的 end_time、duration_hours 和 quality_score 会一并返回。

• get_multiday_stargazing_plan：比较连续一至七晚的观测条件，并返回区域内最佳的夜晚和地点。

  • 输入：south、west、north、east、start_date、time_zone、nights，以及与 get_best_stargazing_plan 相同的候选项、天气、街道网络和观测风格选项。
  • 返回值：包含 query、跨夜 summary（含 best_night_date、best_location_name 和 best_score），以及 nights[]；其中每晚都包含 night_window、当晚的 plan、错误和警告。
  • 降级处理：天气或预报子查询可能会降级为 summary.warnings 和每个候选项的 notes，但整体规划响应仍会成功。

• get_telescope_targets：将深空天体与望远镜光学参数匹配，找出最适合使用你的设备观测的天体。

  • 输入：focal_length_mm、lon、lat、time、time_zone，以及可选的光学参数，如 aperture_mm、传感器尺寸、像素大小、减焦镜/巴罗镜倍率、安装架类型、滤镜和 limit。
  • 返回值：按排名排列的目标，包含可见性评分、高度角/方位角、升起/落下/中天数据、视场匹配度、表面亮度、马赛克拍摄指引以及规范化后的望远镜配置。

• get_shooting_plan：为目标生成优化的成像计划，最大限度延长其高于高度角阈值的时间。

  • 输入：与 get_telescope_targets 相同的望远镜/观测者字段，以及可选的 limit 和 min_altitude。
  • 返回值：targets、moon、包含定时成像时段的单夜 plan、config 和 total。

• light_pollution_map：查询边界框区域的光污染数据。

  • 输入：south、west、north、east、zoom（默认值为 10）。
  • 返回值：包含波特尔等级、亮度和 SQM 值的数据点网格。

• analysis_area：查找区域内最佳的观星地点。

  • 输入：south、west、north、east、max_locations、min_height_diff、road_radius_km、network_type、avoid_popular_spots、prefer_quiet_at_night、popularity_radius_km、db_config_path、page、page_size。
  • 返回值：地点列表，包含分页元数据（total、page、page_size、total_pages）和一个用于标识缓存中非分页查询参数的 resource_id。每个条目还可能包含人气启发式字段，例如 static_popularity_risk_score、night_quiet_likelihood_score 和 popularity_notes。
  • 验证：page >= 1、page_size >= 1 且 popularity_radius_km > 0；无效参数会返回 CONFIGURATION_ERROR。 后台区域分析工具：

• submit_area_analysis：接受包含 bounds 和地点搜索偏好的 request；返回任务快照和规范化后的请求。max_locations 的取值范围为 1–100。部署路径和执行预算仍由服务端策略决定。

• get_area_analysis_task：接受 task_id；返回状态、时间戳、失败详情、execution_pending，以及成功时的 result_revision。查询失败任务的轮询请求仍会成功，并返回状态；请检查 data.state 和 data.failure。

• cancel_area_analysis_task：接受 task_id；记录幂等取消操作。正在运行的提供方调用会继续占用执行槽，直到完成；其后续结果将被丢弃。

• get_area_analysis_result：接受 task_id、page 和 page_size；返回现有的 AnalysisAreaResult 分页结构。绝不会在缺少数据时悄悄重新计算。发布内容过期或被替换后，必须重新提交。

工作流：提交 → 轮询直至 succeeded → 获取分页。完整的观测决策请使用 plan_stargazing_session；这些任务工具用于原始地点分析。现有的同步工具 analysis_area 仍可使用。

AI 恢复验收报告记录了两个客户端各自完成的十项只读状态／结果查询，并提供可审计的调用记录和明确的限制。该报告不评定 AI 提交／取消工作流，也不评定真实提供方的正常运行时间。单独的主动工作流报告评定了三个隔离工作流中每个客户端的提交、经状态确认后的分页、取消和活动查询复用。该报告使用受控提供方和真实工作进程；真实提供方的正常运行时间不在本验收范围内。

5. 错误处理

所有工具都会返回可序列化为 JSON 的数据，并采用结构化错误处理：

• 标准错误代码：INVALID_COORDINATES、INVALID_TIMEZONE、INVALID_TIME_FORMAT、MISSING_API_KEY、API_AUTH_FAILURE、API_TIMEOUT、API_RATE_LIMIT、EXTERNAL_API_ERROR、NETWORK_ERROR、CONFIGURATION_ERROR
• 任务错误代码：TASK_NOT_FOUND、TASK_RUNTIME_CHANGED、TASK_CAPACITY_EXCEEDED、TASK_NOT_READY、TASK_UNAVAILABLE、TASK_RESULT_EXPIRED；参见任务恢复指南。
• 天气工具：网络故障时会自动重试（最多 3 次，采用指数退避）
• 业务错误响应：基于 MCPError 的结构化负载，其中包含可供调用 Agent 采取行动的消息
• 协议测试：协议级测试涵盖 tools/list、get_tool_catalog 和 SSE 请求 ID 行为
• 验证：处理前会验证输入参数，并提供清晰的错误消息

示例

• 后台区域分析：python examples/background_area_demo.py

  • 提交任务、轮询状态并获取结果分页；支持使用 --task-id 恢复轮询，或使用 --cancel --task-id ... 明确取消。

• 夜间规划器：python examples/nightly_forecast_demo.py

  • 展示今晚可见的精选行星和深空天体列表，并考虑月光影响。

• 可见行星：python examples/visible_planets_demo.py

  • 列出当前位于地平线上的行星。

• 月亮信息：python examples/moon_phase_demo.py

  • 输出 30 天月相日历。

• 编排：python examples/code_execution_orchestration.py

  • 演示完整工作流：获取时间 → 获取天体位置 → 检查天气 → 查找地点。
  • 展示如何以编程方式处理标准化响应格式。

• 分页：python examples/pagination_demo.py

  • 演示如何使用 resource_id 逐页获取大型结果集。

• 望远镜目标：python examples/telescope_targets_demo.py

  • 为 RedCat51 风格的光学配置排列深空目标的优先级。

• 拍摄计划：python examples/shooting_plan_demo.py

  • 生成按时间排序的单夜成像计划。

项目结构

.
├── src/
│   ├── functions/            # Tool implementations grouped by domain
│   │   ├── celestial/        # Celestial calculations (pos, rise/set)
│   │   ├── metadata/         # Tool discovery surface (`get_tool_catalog`)
│   │   ├── planning/         # Single-night and multi-night composite planning
│   │   ├── telescope/        # Telescope target matching + shooting plan
│   │   ├── weather/          # Weather API integration
│   │   ├── places/           # Location and area analysis
│   │   └── time/             # Time utilities
│   ├── services/             # Transport-independent application services
│   │   └── planning.py       # Single-night and multi-night planning orchestration
│   ├── schemas/              # Pydantic v2 data models
│   ├── analysis_cache.py     # Caching logic for analysis results
│   ├── response.py           # Standardized response formatting
│   ├── server_instance.py    # FastMCP server instance (avoids circular imports)
│   ├── main.py               # Entry point and tool registration
│   ├── celestial.py          # Core astronomy logic (Astropy wrappers)
│   ├── placefinder.py        # Place-finder bridge logic
│   └── qweather_interaction.py # Thin QWeather URL wrappers
├── tests/                    # Unified test suite covering every registered tool
├── examples/                 # Runnable usage examples, including both telescope tools
├── docs/                     # Design docs and roadmap
├── Dockerfile                # Multi-stage Docker build
├── supervisord.conf          # Dual-service process manager config
└── pyproject.toml            # Project configuration and dependencies

测试

运行统一测试套件：

uv run pytest -v tests/

主要测试包括：

• test_serialization.py：确保所有工具都返回符合正确架构的有效 JSON。
• test_integration.py：模拟外部 API，以验证整个工具链。
• test_mcp_client.py：验证 tools/list、tools/call 和 SSE 请求 ID 协议行为。
• test_structured_errors.py：验证业务校验失败仍保留在结构化响应封装中。

跨仓库兼容性通过可复用的 依赖链工作流进行检查。该工作流使用基线和候选 wheel 测试 stargazing-core → stargazing-place-finder → mcp-stargazing，并阻止引入下游故障的更改。

贡献

1. 遵循 使用 MCP 执行代码最佳实践。
2. 确保所有新工具都使用 src.response.format_response 返回标准 JSON 响应。
3. 为任何新功能在 tests/ 中添加测试。
4. 对所有 MCP 工具和面向 Agent 的更改，遵循 AGENTS.md 中的仓库 Agent 约定。
5. 参阅 docs/agent-contract.md 和 docs/ROADMAP.md，了解公开的 Agent 方向和实施路线图。