STK-MCP

STK-MCP

STK-MCP 是一款 MCP（Model Context Protocol）服务，旨在让大语言模型（LLM）或其他 MCP 客户端与 Ansys/AGI STK（Systems Tool Kit）交互。STK 是领先的数字任务工程软件。

本项目通过 MCP 服务控制 STK，同时支持 STK Desktop（仅限 Windows）和 STK Engine（Windows 和 Linux）。本项目使用官方 MCP Python SDK 中的 FastMCP。

概述

本项目的主要目标是弥合程序化交互与 STK 强大仿真能力之间的差距。通过使用功能完善的 CLI 和 MCP 服务公开 STK 功能，用户可以通过简单命令或由 LLM 驱动的应用来控制 STK 仿真。

MCP 应用定义在 src/stk_mcp/app.py 中，它将 STK 操作公开为 MCP 工具，并由 src/stk_mcp/cli.py 中的 CLI 入口点动态管理。

功能

• 由 Typer 驱动的 CLI 入口点。
• 双模式运行：STK Engine（Windows/Linux）和 STK Desktop（Windows）。
• 感知操作系统：在非 Windows 平台上自动禁用 Desktop 模式。
• 生命周期管理：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 实例。

使用 uv run 运行，这样就无需将软件包安装到 site-packages 中。

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 客户端连接，例如 MCP Inspector。

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 Scenario；设置时间段并将动画倒回起点。	是	是	是
create_location	工具	在纬度/经度/高度（km）处创建/更新 Facility（默认）或 Place。	是	是	是
create_satellite	工具	根据远地点/近地点（km）、RAAN 和倾角创建/配置卫星；使用 TwoBody 推进。	是	是	否

资源：

名称	类型	描述	Desktop (Windows)	Engine (Windows)	Engine (Linux)
resource://stk/objects	资源	列出活动场景中的所有对象。返回 JSON 记录：{name, type}。	是	是	是
resource://stk/objects/{type}	资源	按 type 筛选对象（例如 satellite、facility、place、sensor）。返回 JSON 记录。	是	是	是
resource://stk/health	资源	报告基本状态：模式、场景名称和对象计数。	是	是	是
resource://stk/analysis/access/{object1}/{object2}	资源	计算两个对象之间的访问时间段。提供路径，例如 Satellite/SatA 和 Facility/FacB（可带或不带前导 */）。	是	是	是
resource://stk/reports/lla/{satellite}	资源	返回场景开始/结束时间段内的卫星 LLA 星历。提供路径，例如 Satellite/SatA（可带或不带前导 */）。	是	是	是

示例：

• 读取所有对象：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 参数）

配置和日志记录

配置集中在 src/stk_mcp/stk_logic/config.py 中，使用 pydantic-settings。 默认值可通过环境变量（前缀为 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（safe_stk_command）中使用重试逻辑（tenacity）执行。
• 使用 @timed_operation 为长时间运行的内部操作计时，以便进行诊断。

依赖项

使用 uv 管理：

• agi.stk12（来自 STK 安装的本地 wheel）
• 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，以避免多线程访问 STK Engine/Desktop 实例时出现并发问题。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 文件了解相关指南。