STK-MCP

STK-MCP

STK-MCP は、LLM（大規模言語モデル）やその他の MCP クライアントが、主要なデジタルミッションエンジニアリングソフトウェアである Ansys/AGI STK（Systems Tool Kit）と連携できるようにするために設計された MCP（Model Context Protocol）サーバーです。

このプロジェクトでは、MCP サーバーを介して STK を制御でき、STK Desktop（Windows のみ）と STK Engine（Windows および Linux）の両方をサポートしています。公式の MCP Python SDK に含まれる FastMCP を使用しています。

概要

このプロジェクトの主な目的は、プログラムによる操作と STK の強力なシミュレーション機能の間をつなぐことです。堅牢な CLI と MCP サーバーを通じて STK の機能を公開することで、ユーザーはシンプルなコマンドや LLM 駆動型アプリケーションを使って STK シミュレーションを実行できます。

src/stk_mcp/app.py で定義されている MCP アプリケーションは、STK の操作を MCP ツールとして公開します。これらのツールは、src/stk_mcp/cli.py の CLI エントリーポイントによって動的に管理されます。

機能

• Typer を使用した CLI エントリーポイント。
• 2 つの動作モード：STK Engine（Windows/Linux）および STK Desktop（Windows）。
• OS 対応：Windows 以外のプラットフォームでは、デスクトップモードが自動的に無効になります。
• ライフサイクル管理：MCP サーバーの起動時に STK インスタンスを起動し、停止時に終了します。
• ツールの検出：list-tools コマンドで利用可能な MCP ツールを列挙します。
• モジュール式アーキテクチャ：CLI（cli.py）、MCP（app.py）、STK ロジック（stk_logic/）、MCP ツール（tools/）。

前提条件

• オペレーティングシステム： Windows または Linux。STK Desktop モードには Windows が必要です。
• Python： バージョン 3.12 以降。
• Ansys/AGI STK： バージョン 12.x の Desktop または Engine がインストールされていること。
• STK Python API： STK のインストールに対応する agi.stk12 Python wheel が利用可能である必要があります。通常、STK のインストール先にある CodeSamples\Automation\Python にあります。

インストール

1. リポジトリをクローンします

   git clone <repository-url>
   cd stk-mcp
   

2. 仮想環境を作成して有効化します

   # 仮想環境を作成
   uv venv
   
   # 有効化
   # Windows の場合（PowerShell/CMD）:
   # .venv\Scripts\activate
   # Linux の場合（bash/zsh）:
   source .venv/bin/activate
   

3. uv で依存関係を追加します（推奨）
   • STK のインストール先にある STK Python wheel（ローカルファイル）を追加します：

   uv add ./agi.stk12-12.10.0-py3-none-any.whl
   # または: uv add path/to/your/STK/CodeSamples/Automation/Python/agi.stk12-*.whl
   

4. 環境を同期します（pyproject.toml から依存関係をインストールします）

   uv sync
   

使用方法

このプロジェクトはコマンドラインアプリケーションです。コマンドを実行する前に、仮想環境が有効になっていることを確認してください。

利用可能なツールの一覧表示

uv run -m stk_mcp.cli list-tools

ツール名と説明の一覧を表示します。

MCP サーバーの実行

run コマンドを使って MCP サーバーを起動します。サーバーは STK インスタンスを自動的に起動して管理します。

パッケージを site-packages にインストールする必要がないよう、uv run を使って実行してください。

1) STK Engine（自動化に推奨、Windows/Linux）：

uv run -m stk_mcp.cli run --mode engine

2) STK Desktop（Windows のみ、GUI を表示）： STK Desktop が終了していることを確認してください。サーバーが独自のインスタンスを起動して管理します。

uv run -m stk_mcp.cli run --mode desktop

サーバーが起動して STK を初期化し、デフォルトでは http://127.0.0.1:8765 で MCP 接続を待ち受けます。

3. コマンドオプション： --help フラグですべてのオプションを確認できます：

stk-mcp run --help

サーバーとの連携

サーバーの起動後、MCP Inspector などの任意の MCP クライアントを使って接続できます。

1. コンソールに表示された MCP Inspector の URL を開きます（例：http://127.0.0.1:8765）。
2. 一覧から「STK Control」サーバーを見つけます。
3. 「Tools」セクションを使って setup_scenario、create_location、create_satellite を実行します。

サーバーの停止

サーバーを実行しているターミナルで Ctrl+C を押します。ライフサイクルマネージャーが STK Engine または Desktop インスタンスを自動的に閉じます。

MCP ツールとリソース

サーバーは、以下の MCP ツール／リソースを公開します。

名前	種類	説明	Desktop (Windows)	Engine (Windows)	Engine (Linux)
setup_scenario	ツール	STK シナリオを作成／設定し、期間を設定してアニメーションを巻き戻します。	Yes	Yes	Yes
create_location	ツール	緯度／経度／高度（km）を指定して、Facility（デフォルト）または Place を作成／更新します。	Yes	Yes	Yes
create_satellite	ツール	遠地点／近地点（km）、RAAN、傾斜角から衛星を作成／設定します。伝播には TwoBody を使用します。	Yes	Yes	No

リソース：

名前	種類	説明	Desktop (Windows)	Engine (Windows)	Engine (Linux)
resource://stk/objects	リソース	アクティブなシナリオ内のすべてのオブジェクトを一覧表示します。{name, type} の JSON レコードを返します。	Yes	Yes	Yes
resource://stk/objects/{type}	リソース	type で絞り込んだオブジェクトを一覧表示します（例：satellite、facility、place、sensor）。JSON レコードを返します。	Yes	Yes	Yes
resource://stk/health	リソース	モード、シナリオ名、オブジェクト数などの基本状態を報告します。	Yes	Yes	Yes
resource://stk/analysis/access/{object1}/{object2}	リソース	2 つのオブジェクト間のアクセス時間帯を計算します。Satellite/SatA や Facility/FacB のようなパスを指定します（先頭の */ は省略可能です）。	Yes	Yes	Yes
resource://stk/reports/lla/{satellite}	リソース	シナリオの開始／終了区間における衛星の LLA エフェメリスを返します。Satellite/SatA のようなパスを指定します（先頭の */ は省略可能です）。	Yes	Yes	Yes

例：

• すべてのオブジェクトを読み取る：resource://stk/objects
• 衛星のみを読み取る：resource://stk/objects/satellite
• 地上位置を読み取る：resource://stk/objects/location（施設とプレースのエイリアス）

アクセスと LLA の例：

• アクセスを計算する：resource://stk/analysis/access/Satellite/ISS/Facility/Boulder
• ISS の LLA を取得する（60 s）：resource://stk/reports/lla/Satellite/ISS（省略可能な step_sec 引数）

設定とロギング

設定は pydantic-settings を使用して src/stk_mcp/stk_logic/config.py に集約されています。 環境変数（プレフィックス STK_MCP_）でデフォルト値を上書きできます。

• STK_MCP_DEFAULT_HOST（デフォルト 127.0.0.1）
• STK_MCP_DEFAULT_PORT（デフォルト 8765）
• STK_MCP_LOG_LEVEL（デフォルト INFO）
• STK_MCP_DEFAULT_SCENARIO_NAME（デフォルト MCP_STK_Scenario）
• STK_MCP_DEFAULT_START_TIME（デフォルト 20 Jan 2020 17:00:00.000）
• STK_MCP_DEFAULT_DURATION_HOURS（デフォルト 48.0）

ロギングは src/stk_mcp/stk_logic/logging_config.py で標準化されています。CLI では この設定を使用し、タイムスタンプ、レベル、コンテキストを含む構造化ログを生成します。

実装上の注意

• 並行処理の問題を避けるため、STK へのアクセスはグローバルロックで直列化されます。
• STK の可用性に関する共通チェックは、 src/stk_mcp/stk_logic/decorators.py のデコレーター（@require_stk_tool と @require_stk_resource）で処理されます。
• 一時的に不安定になる可能性のある STK Connect コマンドは、src/stk_mcp/stk_logic/utils.py の再試行ロジック （tenacity、safe_stk_command）を使用して実行されます。
• 実行時間の長い内部処理は、診断のために @timed_operation で計測されます。

依存関係

uv で管理されています：

• agi.stk12（STK のインストールから取得したローカルホイール）
• mcp[cli]>=1.6.0
• uvicorn>=0.30（CLI サーバーで明示的に使用）
• rich>=13.7（CLI のテーブル出力）
• typer>=0.15.2
• pydantic>=2.11.7

注意：

• macOS（Darwin）では、STK Engine/Desktop はサポートされていません。サーバーは起動しますが、STK に依存するツールやリソースは利用できません。
• STK Engine/Desktop インスタンスへのマルチスレッドアクセスによる競合を避けるため、サーバーはグローバルロックを使用して STK へのアクセスを直列化します。

コントリビューション

コントリビューションを歓迎します！ガイドラインについては、CONTRIBUTING.md をご覧ください。