STK-MCP

STK-MCP 是一个 MCP（模型上下文协议）服务器，旨在使大型语言模型（LLMs）或其他 MCP 客户端能够与 Ansys/AGI STK（系统工具包）进行交互——这是领先的数字任务工程软件。

该项目允许通过 MCP 工具控制 STK 桌面版，利用了 STK Python API。它使用来自官方 MCP Python SDK 的 FastMCP。服务器逻辑位于 src/stk_mcp 包中。

概述

该项目的主要目标是在程序化或自然语言交互（通过 LLMs）与 STK 强大的仿真功能之间架起桥梁。通过将 STK 功能暴露给 MCP 服务器，用户可以使用 MCP 客户端或潜在的 LLM 驱动的应用程序来指挥 STK 仿真。

在 src/stk_mcp/server.py 中定义的 MCP 服务器管理 STK 交互并暴露功能，展示了如何：

• 连接到正在运行的 STK 桌面实例或通过服务器生命周期管理 (src/stk_mcp/stk_logic/core.py) 启动新的实例。
• 将 STK 操作作为 MCP 工具暴露（定义在 src/stk_mcp/tools/ 中）。
• 使用 setup_scenario 工具创建和配置 STK 场景。
• 使用 create_satellite 工具以编程方式添加和配置卫星对象。
• 使用常见的轨道参数定义卫星轨道。
• 在工具内使用 TwoBody 推进器进行轨道仿真。

特性（MCP 服务器）

• MCP 服务器实现： 在 src/stk_mcp/server.py 中使用 FastMCP。
• 模块化结构： 代码组织为服务器设置 (server.py)、STK 交互逻辑 (stk_logic/) 和 MCP 工具 (tools/)。
• STK 桌面集成： 当服务器启动时自动连接到或启动 STK 12（需要 Windows），并通过 MCP 生命周期管理。
• 场景管理工具 (setup_scenario)： 创建新场景，设置分析时间段，并关闭任何预先存在的场景。
• 卫星创建工具 (create_satellite)： 向当前活动场景中添加卫星对象。
• 轨道定义： 使用近地点/远地点高度、RAAN 和倾角配置卫星轨道。
• TwoBody 推进： 为创建的卫星设置并运行 TwoBody 推进器。

前提条件

• 操作系统: Windows（由于STK Desktop和win32com依赖）。
• Python: 3.12或更高版本。
• Ansys/AGI STK: 安装了12.x版本的Desktop版。
• STK Python API: 必须安装与您的STK安装相对应的agi.stk12 Python wheel文件。通常包括：
  • 在STK安装目录中找到wheel文件（例如，agi.stk12-py3-none-any.whl），通常位于CodeSamples\Automation\Python下。
  • 使用pip安装它：uv pip install path/to/agi.stk12-py3-none-any.whl
• 项目依赖: 需要mcp库（通过uv sync安装）。

安装

1. 克隆仓库:

   git clone <repository-url>
   cd stk-mcp
   

2. 确保满足先决条件: 按照上述说明安装Python、STK Desktop以及STK Python API的wheel文件。
3. 安装项目依赖:

   # 安装pyproject.toml中定义的依赖（包括mcp[cli]）
   uv sync
   

使用方法 (MCP服务器)

现在MCP服务器逻辑结构在src/stk_mcp目录内。你可以使用MCP客户端或开发工具与其交互。

1. 确保STK Desktop已关闭（服务器将通过生命周期管理器启动自己的实例）。
2. 以开发模式运行MCP服务器:
   • 选项A（使用辅助脚本）:

     python scripts/run_dev.py
     

   • 选项B（直接从项目根目录使用mcp命令）:

     mcp dev src/stk_mcp/server.py
     

   • 服务器将启动，尝试启动/连接到STK，并打印日志。
   • 应该可以看到STK Desktop界面。
   • 服务器监听MCP连接。
3. 与服务器交互（示例使用MCP Inspector）:
   • 打开控制台提供的MCP Inspector URL（例如，http://127.0.0.1:8765）。
   • 找到"STK Control"服务器。
   • 使用"Tools"部分来执行setup_scenario和create_satellite，如前所述。
4. 停止服务器: 在运行服务器的终端中按Ctrl+C。生命周期管理器会尝试关闭STK。

可用的MCP工具

• setup_scenario: (定义在src/stk_mcp/tools/scenario.py)
  • 描述：创建/配置一个STK场景。首先会关闭任何现有的场景。
  • 参数：scenario_name (str, 默认: "MCP_STK_Scenario"), start_time (str, 默认: "20 Jan 2020 17:00:00.000"), duration_hours (float, 默认: 48.0)。
• create_satellite: (定义在src/stk_mcp/tools/satellite.py)
  • 描述：创建或修改一个STK卫星。假设当前有一个活动场景。
  • 参数：name (str), apogee_alt_km (float), perigee_alt_km (float), raan_deg (float), inclination_deg (float)。

未来开发 (MCP服务器及扩展自动化)

计划中的增强功能包括：

• 添加地面位置： 使用MCP工具添加设施或地点对象。
• 资源端点： 添加MCP资源（例如，get_scenario_details，list_objects）以查询STK状态。
• 增强的卫星/对象定义： 更全面的配置选项。
• 访问分析工具： 计算并报告对象之间的访问情况。
• 错误处理： 向MCP客户端提供更强大的错误报告。

依赖

• agi.stk12：用于与STK桌面交互（需要从STK手动安装）。
• mcp[cli]>=1.6.0：模型上下文协议库。
• pywin32：在Windows上自动安装；通过win32com.client用于COM交互。

限制

• 仅限Windows： 严重依赖于通过COM实现的STK桌面自动化。
• 需要STK桌面： 当前不支持STK引擎。
• 基本功能： 目前仅限于场景设置和基本卫星创建。
• 单一场景焦点： 假设与由setup_scenario工具管理的单个活动场景进行交互。

贡献

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