mcp-stargazing

地球上のあらゆる場所について、天体（太陽、月、惑星、恒星、深宇宙天体）の高度、出没時刻を計算します。オプションで光害分析も可能です。

機能

• 高度/方位角の計算: あらゆる天体の仰角と方位を算出します。

• 出没時刻: 天体が地平線上に現れる、または沈む時刻を特定します。

• 光害分析: 光害マップ（GeoTIFF形式）を読み込み、分析します。

• コード実行対応:

  • シリアライズ可能な戻り値: すべてのツールはJSONシリアライズ可能なデータ（日付はISO文字列）を返すため、LLMで直接利用可能です。

  • ページネーション: analysis_area はページング（page, page_size）をサポートしており、大規模なデータセットを効率的に処理できます。

  • 標準化されたレスポンス: { "data": ..., "_meta": ... } という統一されたレスポンス形式により、可観測性とエラーハンドリングが向上しています。

• パフォーマンス:

  • 非同期実行: 天体計算をノンブロッキングで実行します。

  • キャッシュ: Simbadクエリや地域分析のためのインテリジェントなキャッシュ機能。

  • プロキシサポート: HTTP/HTTPSプロキシをネイティブサポート（天体データのダウンロードに便利）。

• タイムゾーン対応: ローカル時間またはUTCで動作します。

• データ駆動: 10,000以上の深宇宙天体（メシエ天体およびNGC）のデータベースを統合し、スマートな推奨機能を提供します。

Related MCP server: Celestial Position MCP Server

インストール

このプロジェクトでは、依存関係管理に 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 (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-stargazing

MCPサーバーの使用方法

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. サーバーの起動

Streamable 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:7890

SSEモード:

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

3. レスポンス形式

すべてのツールは標準化された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: 星座の中心位置（高度/方位角）を検索します。

• get_nightly_forecast: 今夜観測に最適な天体（惑星＋深宇宙天体）の厳選リストを返すスマートプランナー。

• get_weather_by_name / get_weather_by_position: 現在の天気を取得します。

• get_local_datetime_info: 現在のローカル時刻情報を取得します。

• analysis_area: 地域内の最適な星空観測スポットを検索します。

  • 入力: top_left, bottom_right, time, page, page_size。

  • 戻り値: 観測条件を含むスポットのリスト、およびページネーションメタデータ（total, resource_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 を使用して、大規模な結果セットをページごとに取得する方法を実演します。

プロジェクト構造

プロジェクトは、保守性とコード実行サポートを向上させるためにモジュール化されています:

.
├── 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をモック化し、ツールチェーン全体を検証します。

貢献

1. Code Execution with MCP のベストプラクティスに従ってください。

2. すべての新しいツールが src.response.format_response を使用して標準JSONレスポンスを返すようにしてください。

3. 新しい機能については tests/ にテストを追加してください。