STARWARCLOUD STARWAR.AI
返回市场
stk-MCP

stk-MCP

作者：alti320 星标更新：2025-10-09
安装使用来源：spider==github.com

项目介绍

STK-MCP

Python 版本 MCP 版本

STK-MCP 是一个设计用于使大型语言模型（LLMs）或其他 MCP 客户端与 Ansys/AGI STK（系统工具包）交互的 MCP（模型上下文协议）服务器。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 平台上自动禁用桌面模式。
  • 生命周期管理：STK 实例随 MCP 服务器启动和停止。
  • 工具发现：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 轮子必须可用。通常可以在您的 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 轮子（本地文件）：
    uv add ./agi.stk12-12.10.0-py3-none-any.whl
# 或：uv add path/to/your/STK/CodeSamples/Automation/Python/agi.stk1.2-*.whl

# 仅限 Windows：COM 桥接用于桌面自动化
uv add "pywin32; platform_system == 'Windows'"
  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

默认情况下，服务器将在 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 场景；设置时间段并重放动画。是是是
create_location工具创建/更新 Facility（默认）或 Place 在纬度/经度/海拔（千米）。是是是
create_satellite工具创建/配置卫星从远地点/近地点（千米），升交点赤经和倾角；两体传播。是是否

注：

  • Linux Engine 上的 create_satellite 尚未支持，因为它依赖于 COM 特定的转换；计划使用 Connect 的替代方案。

资源：

名称类型描述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 秒）：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）。
  • 长时间运行的内部操作使用 @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
  • pywin32（仅限 Windows）

注：

  • 在 macOS（Darwin）上，STK Engine/Desktop 不受支持。服务器将启动但 STK 依赖的工具/资源不可用。
  • 服务器通过全局锁序列化 STK 访问以避免 COM/Engine 调用的并发问题。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 文件获取指南。