mcp观星
计算地球上任何位置的天体（太阳、月亮、行星、恒星和深空物体）的高度、上升和设定时间，并进行可选的光污染分析。
特性
- 高度/方位角计算：获取任何天体的仰角和指南针方向。
- 上升/设定时间：确定物体何时出现/消失在地平线上。
- 光污染分析：加载和分析光污染地图（GeoTIFF格式）。
- 代码执行就绪:
- 可序列化返回：所有工具都返回JSON可序列化数据（日期的ISO字符串），使LLM可以直接使用它们。 - 分页: analysis_area 支持分页(page, page_size)高效地处理大型数据集。 - 标准化响应：统一的响应格式 { "data": ..., "_meta": ... } 为了更好的可观察性和错误处理。
- 演出:
- 异步执行：非阻塞天体计算。 - 缓存：Simbad查询和区域分析的智能缓存。 - 代理支持：原生支持HTTP/HTTPS代理（可用于下载天文数据）。
- 时区感知：适用于当地时间或UTC时间。
- 数据驱动：10000多个深空天体（梅西耶和NGC）的综合数据库，用于智能推荐。
安装
此项目使用 紫外线 用于依赖性管理。
本地安装
- 安装
uv:
pip install uv- 同步依赖关系:
uv sync这将在中创建一个虚拟环境 .venv 并安装中定义的所有依赖项 pyproject.toml.
- 激活环境:
source .venv/bin/activate- 初始化数据 （夜间计划需要）：
这将下载最新的梅西耶和NGC目录数据到 src/data/objects.json.
python scripts/download_data.py*注意：如果你在防火墙后面，请确保 HTTP_PROXY 在运行此脚本之前设置env-var。*
Docker安装
您还可以使用Docker运行服务器，Docker会自动处理所有依赖关系和数据初始化。
- 塑造形象:
docker build -t mcp-stargazing .*注意：如果您在代理后面，请在构建过程中传递代理URL：*
docker build --build-arg HTTP_PROXY=http://127.0.0.1:7890 -t mcp-stargazing .- 运行容器:
# Basic run (SHTTP mode on port 3001)
docker run -p 3001:3001 mcp-stargazing
# With Environment Variables
docker run -p 3001:3001 \
-e QWEATHER_API_KEY=your_key \
-e STARGAZING_DB_CONFIG=your_db_config \
mcp-stargazingMCP服务器使用情况
启动MCP服务器，将工具暴露给AI代理或其他客户端。
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
# 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.启动服务器
流式HTTP（SHTTP）模式 （推荐给大多数代理商）：
# 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:7890SSE模式:
python -m src.main --mode sse --port 3001 --path /sse3.响应格式
所有工具都以标准化的JSON格式返回数据：
{
"data": {
// Tool-specific return data
"altitude": 45.5,
"azimuth": 180.0
},
"_meta": {
"version": "1.0.0",
"status": "success"
}
}4.可用工具
get_celestial_pos：计算高度/方位角。get_celestial_rise_set：计算上升/设定时间（返回ISO字符串）。get_moon_info：详细的月相、光照和年龄。get_visible_planets：目前地平线上所有行星的位置列表。get_constellation：找到星座中心的位置（Alt/Az）。get_nightly_forecast：智能规划师返回今晚最佳观赏对象的精选列表（行星+深空）。get_weather_by_name/get_weather_by_position：获取当前天气，并在网络故障时自动重试。get_local_datetime_info：获取当前本地时间信息。get_tool_catalog：发现可用的MCP工具元数据和参数。analysis_area：寻找一个地区最好的观星点。
- 输入: top_left, bottom_right, time, page, page_size. - 退货：具有观看条件的地点列表，以及分页元数据(total, resource_id).
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 - 天气工具：包括网络故障的自动重试逻辑（最多3次尝试，指数回退）
- 错误响应：具有可操作错误消息的结构化MCPError对象，用于调用代理
- 验证：在处理之前验证输入参数，并显示明确的错误消息
例子
- 夜间规划师:
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.
项目结构
该项目被模块化，以获得更好的可维护性和代码执行支持：
.
├── src/
│ ├── functions/ # Tool implementations grouped by domain
│ │ ├── celestial/ # Celestial calculations (pos, rise/set)
│ │ ├── weather/ # Weather API integration
│ │ ├── places/ # Location and area analysis
│ │ └── time/ # Time utilities
│ ├── 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 # Grid analysis logic
│ └── qweather_interaction.py # Weather API client
├── tests/ # Unified test suite
│ ├── test_celestial.py
│ ├── test_weather.py
│ ├── test_serialization.py # Validates JSON return formats
│ └── test_integration.py # End-to-end flow tests
├── examples/ # Usage examples
├── docs/ # Documentation and improvement plans
└── pyproject.toml # Project configuration and dependencies测试
运行统一测试套件：
pytest tests/关键测试包括：
test_serialization.py：确保所有工具返回具有正确模式的有效JSON。test_integration.py：模拟外部API以验证整个工具链。
贡献
- 跟随 使用MCP执行代码 最佳实践。
- 确保所有新工具使用以下命令返回标准JSON响应
src.response.format_response. - 在中添加测试
tests/对于任何新功能。 - 遵循中的存储库代理约定
AGENTS.md适用于所有面向MCP工具和代理的更改。 - 参见
docs/ROADMAP.md对于计划中的代理和线束功能路线图。