XHelio-SPICE

xhelio-spice

宇宙機のエフェメリスを簡単に取得 — 太陽物理学ミッション向けの SPICE カーネルを自動管理します。

xhelio-spice は SpiceyPy をラップし、カーネルの自動ダウンロード、キャッシュ、読み込みを行います。宇宙機の位置を問い合わせるだけで、xhelio-spice が適切な NAIF カーネルのダウンロード、正しい順序での読み込み、Python の辞書または pandas DataFrame での結果返却まで処理します。

インストール

pip install xhelio-spice

MCP サーバーのサポート（Claude Desktop、Claude Code、Cursor など）を利用する場合：

pip install xhelio-spice[mcp]

クイックスタート

from xhelio_spice import get_position, get_trajectory

# Where is Parker Solar Probe right now?
pos = get_position("PSP", observer="SUN", time="2024-01-15", frame="ECLIPJ2000")
print(f"PSP is {pos['r_au']:.3f} AU from the Sun")

# Get a month of trajectory data as a DataFrame
df = get_trajectory(
    "PSP", observer="SUN",
    time_start="2024-01-01", time_end="2024-01-31",
    step="1h", frame="ECLIPJ2000",
)
print(df[["r_au"]].describe())

カーネルは初回使用時に NAIF から自動的にダウンロードされ、~/.xhelio_spice/kernels/ にキャッシュされます。

サポート対象のミッション

SPICE カーネルを使用（自動ダウンロード）

• PSP（Parker Solar Probe）— 2018-2030
• Solar Orbiter（SOLO）— 2020-2030
• STEREO-A — 2017-2031
• Juno — 2011-現在（定期的に更新）
• Voyager 1/2 — 1981-2100 / 1989-2100
• New Horizons — 2019-2030

NAIF ID のみ（自動ダウンロードは未対応）

• ACE、Wind、DSCOVR、MMS（1-4）— 公開 SPK カーネルはありません
• Cassini、MAVEN — 複数セグメントのカーネル読み込みが必要（対応予定）
• Galileo、Pioneer 10/11、Ulysses、MESSENGER、STEREO-B

天体

Sun、Earth、Moon、Mercury、Venus、Mars、Jupiter、Saturn、Uranus、Neptune、Pluto

API リファレンス

位置と軌道

from xhelio_spice import get_position, get_trajectory, get_state

# Single position
pos = get_position("ACE", observer="EARTH", time="2024-06-01", frame="GSE")

# Full state (position + velocity)
state = get_state("PSP", observer="SUN", time="2024-01-15", frame="ECLIPJ2000")

# Trajectory timeseries (returns pandas DataFrame)
df = get_trajectory(
    "Cassini", observer="SATURN",
    time_start="2010-01-01", time_end="2010-12-31",
    step="6h", frame="ECLIPJ2000",
    include_velocity=True,
)

座標変換

from xhelio_spice import transform_vector, list_available_frames

# J2000 to Ecliptic
v_ecl = transform_vector([1.0, 0.0, 0.0], "2024-01-15", "J2000", "ECLIPJ2000")

# RTN transform (requires spacecraft)
v_rtn = transform_vector(
    [5.0, -3.0, 1.0], "2024-01-15",
    from_frame="ECLIPJ2000", to_frame="RTN",
    spacecraft="PSP",
)

# List all frames
print(list_available_frames())

ミッションレジストリ

from xhelio_spice import resolve_mission, list_supported_missions

# Resolve name aliases
naif_id, key = resolve_mission("Parker Solar Probe")  # -> (-96, "PSP")

# List all spacecraft
missions = list_supported_missions()

カーネル管理

from xhelio_spice import get_kernel_manager

km = get_kernel_manager()
km.ensure_mission_kernels("PSP")  # Download + load
print(km.get_cache_info())        # Cache stats
km.unload_all()                    # Free memory

設定

方法	説明
XHELIO_SPICE_KERNEL_DIR env var	カーネルキャッシュディレクトリを上書き
KernelManager(kernel_dir=...)	インスタンスごとの上書き
デフォルト	~/.xhelio_spice/kernels/

MCP サーバー

xhelio-spice には、LLM のツール利用向けの MCP サーバーが含まれています：

# Run directly
xhelio-spice-mcp

# Or via Python
python -m xhelio_spice.server

Claude Desktop の設定

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "xhelio-spice": {
      "command": "xhelio-spice-mcp"
    }
  }
}

利用可能な MCP ツール

ツール	説明
get_ephemeris	位置／速度 — 単一時刻（インライン）または時系列（CSV）
compute_distance	2つの天体間の距離
transform_coordinates	座標フレーム変換
list_spice_missions	サポート対象のミッション
list_coordinate_frames	説明付きの利用可能なフレーム
manage_kernels	カーネルキャッシュ管理

MCP スモークテスト

カーネルのダウンロードを要求しない、CI で安全に実行できる MCP チェックを行うには、次を実行します：

uv run --extra mcp python scripts/smoke_mcp_list_tools.py --json

スモークテストでは、分離された一時カーネルキャッシュを使って stdio サーバーを起動し、 MCP の initialize と list_tools を実行して、公開されているツール名を検証します。

ライセンス

MIT