StarWhisper Observatory Calculator

一个用于计算天文目标可观测性的Python包，支持恒星、深空天体和太阳系天体。提供MCP（Model Context Protocol）服务接口，可与支持MCP的AI助手集成。

🌟 主要特性

• 🔭 多目标支持: 恒星、深空天体、太阳系天体
• 📍 灵活观测站: 支持自定义观测站位置
• 🌙 月距约束: 考虑月球干扰的可观测性分析
• 📊 高度曲线: 生成24小时高度变化曲线
• 🌐 Web API: 提供RESTful API接口
• 🤖 MCP服务: 标准MCP协议，支持AI助手集成
• 📱 命令行工具: 简单易用的CLI界面

🚀 快速开始

安装

# 基本安装
pip install starwhisper-observation-calculator

# 或使用 uv
uv pip install starwhisper-observation-calculator

# 安装Web服务支持
pip install starwhisper-observation-calculator[web]

# 安装完整功能
pip install starwhisper-observation-calculator[all]

基本使用

from starwhisper_observation_calculator import ObservabilityCalculator

# 创建计算器（默认兴隆观测站）
calculator = ObservabilityCalculator(
    latitude=40.393333,
    longitude=117.575278,
    altitude=900.0
)

# 计算Vega可观测性
result = calculator.calculate_observability("Vega")
print(result)

命令行使用

# 基本使用
observability-calculator Vega

# 指定观测站
observability-calculator moon --latitude 40.393333 --longitude 117.575278

# 自定义约束条件
observability-calculator M31 --min-altitude 20 --min-moon-separation 45

🤖 MCP服务

本包提供完整的MCP服务，可与支持MCP的AI助手（如Claude Desktop、Cursor等）集成。

启动MCP服务

方法一：使用 uvx（推荐，无需安装）

# 直接运行MCP服务
uvx starwhisper-observation-calculator

# 运行计算器
uvx starwhisper-observation-calculator --calculator Vega

# 启动Web服务
uvx starwhisper-observation-calculator --web --port 8080

方法二：本地安装后使用

# 启动MCP服务
observability-mcp

# 或直接使用python模块
python -m starwhisper_observation_calculator.mcp_server

MCP配置

方法一：使用 uvx（推荐）

{
  "mcpServers": {
    "starwhisper-observation": {
      "command": "uvx",
      "args": ["starwhisper-observation-calculator"],
      "env": {}
    }
  }
}

方法二：本地安装后使用

{
  "mcpServers": {
    "starwhisper-observation": {
      "command": "observability-mcp",
      "args": [],
      "env": {}
    }
  }
}

在AI助手中使用

安装并配置MCP服务后，你可以直接与AI助手对话：

用户: 请计算Vega在兴隆观测站的可观测性
AI助手: 我来为您计算Vega在兴隆观测站的可观测性...

[自动调用MCP工具: calculate_observability]
参数: latitude=40.393333, longitude=117.575278, target_name="Vega"

结果: 
🌟 Vega 可观测性分析报告

📍 观测站: 40.393333°, 117.575278°, 900.0m
🌌 坐标: 18:36:56.3363, +38:47:01.280  
📊 当前高度: 45.23°
✅ 可观测性: 可观测
🎯 约束条件: 高度✅ 月距✅

🌐 Web服务

启动Web服务

# 启动Web服务
observability-web

# 或指定端口
observability-web --port 8080

API接口

• GET / - Web界面
• GET /docs - API文档
• POST /observability - 计算可观测性
• POST /observability/batch - 批量计算
• GET /targets/supported - 获取支持的目标
• GET /observatories - 获取预设观测站

使用示例

# 计算Vega可观测性
curl -X POST "http://localhost:8000/observability" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 40.393333,
    "longitude": 117.575278,
    "target_name": "Vega"
  }'

📊 支持的目标

太阳系天体

• sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto

恒星

• Vega, Sirius, Polaris, Rigel, Betelgeuse, Altair, Deneb, Arcturus, Spica, Antares

深空天体

• M31, M42, M13, M57, M27, M51, M104, M87

📍 预设观测站

• 兴隆观测站: 40.393333°, 117.575278°, 900m
• 新昌观测站: 29.501784°, 120.905740°, 0m
• 帕洛马天文台: 33.3563°, -116.8650°, 1712m

🔧 高级配置

自定义观测站

from starwhisper_observation_calculator import ObservabilityCalculator

calculator = ObservabilityCalculator(
    latitude=your_latitude,
    longitude=your_longitude,
    altitude=your_altitude,
    timezone="Asia/Shanghai"
)

约束条件

result = calculator.calculate_observability(
    target_name="Vega",
    min_altitude=20.0,        # 最小地平高度
    min_moon_separation=45.0, # 最小月距
    time_range_hours=48       # 检查时间范围
)

🛠️ 开发

安装开发依赖

# 克隆项目
git clone https://github.com/wangcunshi/StarWhisper-observation-calculator.git
cd StarWhisper-observation-calculator

# 安装开发依赖
pip install -e .[dev]

# 或使用 uv
uv pip install -e .[dev]

运行测试

# 测试核心功能
python -c "from starwhisper_observation_calculator import ObservabilityCalculator; print('✅ 导入成功')"

# 测试MCP服务
observability-mcp

# 测试Web服务
observability-web

代码格式化

# 格式化代码
black src tests
isort src tests

# 类型检查
mypy src

📄 许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

📞 支持

• 📧 邮箱: wangcunshi@nao.cas.cn
• 🐛 Issues: GitHub Issues
• 📖 文档: GitHub README

📝 更新日志

v1.0.0

• 🎉 首次发布
• ✨ 支持恒星、深空天体和太阳系天体
• 🤖 MCP服务支持
• 🌐 Web API接口
• 📱 命令行工具
• 📊 高度曲线生成
• 🌙 月距约束检查

⭐ 如果这个项目对你有帮助，请给它一个 Star！