内容
# krpc-mcp
[](https://github.com/MaiaJP-AIXplain/krpc-mcp/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](LICENSE)
**模型上下文协议（MCP）服务器，适用于 kRPC** — 让 Claude（以及任何支持 MCP 的 AI）通过 [kRPC 模组](https://krpc.github.io/krpc/) 控制《Kerbal 空间计划》。
```
KSP + kRPC 模组 ←──gRPC──→ krpc-mcp 服务器 ←──MCP──→ Claude 桌面版 / Claude 代码
```
## 功能
默认情况下，`krpc-mcp` 暴露了一个精选的副驾驶表面：AI 代理所需的工具，用于飞行器状态、安全控制、任务规划和 MechJeb 自动化。设置 `KRPC_MCP_TOOL_MODE=full` 时，您需要用于调试或开发的低级 1:1 kRPC API。
| 类别 | 工具 |
|---|---|
| 任务辅助 | `mission_assist_flight_snapshot`, `mission_assist_plan_goal` |
| 飞行器/身体信息 | `space_center_get_active_vessel`, `space_center_get_vessels`, `space_center_get_bodies`, `space_center_set_active_vessel`, `space_center_set_target_body`, `space_center_vessel_get_name`, `space_center_vessel_get_mass`, `space_center_vessel_get_situation` |
| 飞行控制 | `space_center_control_set_throttle`, `space_center_control_activate_next_stage`, `space_center_control_set_sas`, `space_center_control_set_rcs`, `space_center_control_set_gear`, `space_center_control_set_brakes`, `space_center_auto_pilot_target_pitch_and_heading`, `space_center_auto_pilot_disengage` |
| 轨道力学 | `space_center_vessel_get_orbit`, `space_center_control_add_node`, `space_center_control_get_nodes`, `space_center_node_remove`, `space_center_warp_to`, `space_center_get_ut` |
| 资源 | `space_center_vessel_get_resources`, `space_center_resources_get_names`, `space_center_resources_amount`, `space_center_resources_max` |
### MechJeb 集成
当安装了 [kRPC.MechJeb](https://github.com/Genhis/KRPC.MechJeb) 模组时，任务级代理应优先使用精选的 `mech_jeb_*` 工具进行发射、机动规划、节点执行、着陆、停靠和交会。直接 `space_center_*` 控制仍然可用作备用。
| 类别 | 暴露的服务 |
|---|---|
| 自动驾驶仪 | `AscentAutopilot`, `LandingAutopilot`, `DockingAutopilot`, `RendezvousAutopilot` |
| 姿态和执行 | `SmartASS` 模式/接口 + `Update()`, `NodeExecutor` (`ExecuteOneNode/AllNodes/Abort`) |
| 机动规划 | `ManeuverPlanner`，用于环化、远地点、近地点、行星际转移、转移、平面/倾角、Lambert 和航向修正操作；`MakeNode(s)` + 节点执行路径 |
| 控制器 | `ThrustController`, `StagingController`, `RCSController` |
**安全保证：**
- 在每次调用 MechJeb 工具之前，都会检查 `MechJeb.APIReady`。如果模组尚未初始化，服务器会返回清晰的错误信息，而不是神秘的 RPC 失败信息。
- `OperationException`（例如“未设置目标”，“无效轨道”）被捕获并作为结构化的 `MechJeb operation error:` 消息返回。
**示例工作流程 — 发射到 100 公里轨道：**
```
# 1. 获取 AscentAutopilot 句柄
mech_jeb_get_ascent_autopilot → AscentAutopilot(id=42)
# 2. 配置
mech_jeb_ascent_autopilot_set_desired_orbit_altitude this=42 value=100000
mech_jeb_ascent_autopilot_set_desired_inclination this=42 value=0
# 3. 启用
mech_jeb_ascent_autopilot_set_enabled this=42 value=true
```
**示例工作流程 — 在远地点环化：**
```
# 1. 获取 ManeuverPlanner 和环化操作
mech_jeb_get_maneuver_planner → ManeuverPlanner(id=10)
mech_jeb_maneuver_planner_get_operation_circularize this=10 → OperationCircularize(id=20)
# 2. 创建节点
mech_jeb_operation_circularize_make_nodes this=20
# 3. 执行
mech_jeb_get_node_executor → NodeExecutor(id=30)
mech_jeb_node_executor_set_autowarp this=30 value=true
mech_jeb_node_executor_execute_one_node this=30
```
## 要求
- Python 3.11+
- KSP 1.x，搭配以下任意一种设置：
- 安装了 [kRPC 模组](https://krpc.github.io/krpc/) 并在游戏中启动服务器
- kRPC + [MechJeb](https://github.com/MuMech/MechJeb2) + [KRPC.MechJeb](https://github.com/Genhis/KRPC.MechJeb)（适用于 MechJeb MCP 工具）
- 一个 MCP 主机：[Claude 桌面版](https://claude.ai/download) 或 Claude 代码 CLI
## 安装
### 快速入门（推荐，无需手动设置 Python 环境）
如果您有 [`uv`](https://docs.astral.sh/uv/)，可以直接从 PyPI 运行 MCP 服务器：
```bash
claude mcp add krpc -- uvx krpc-mcp
```
这样可以避免单独的 `pip install` 步骤，并简化升级。
### 替代安装方法
```bash
pip install krpc-mcp
```
或从源代码：
```bash
git clone https://github.com/MaiaJP-AIXplain/krpc-mcp
cd krpc-mcp
pip install -e .
```
有关从干净的机器到验证的实时控制的完整操作指南，请参阅 [`docs/operator-setup-guide.md`](docs/operator-setup-guide.md)。
有关适用于此 MCP 服务器的可重复使用的 Claude 代码操作技能，请参阅 [`docs/claude-code-krpc-skill.md`](docs/claude-code-krpc-skill.md)。
## 配置
### Claude 桌面版
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"krpc": {
"command": "uvx",
"args": ["krpc-mcp"],
"env": {
"KRPC_HOST": "127.0.0.1",
"KRPC_RPC_PORT": "50000",
"KRPC_STREAM_PORT": "50001"
}
}
}
}
```
### Claude 代码 CLI
推荐：
```bash
claude mcp add krpc -- uvx krpc-mcp
```
备用（如果您不使用 `uv`）：
```bash
pipx install krpc-mcp
claude mcp add krpc -- krpc-mcp
```
### 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `KRPC_HOST` | `127.0.0.1` | kRPC 服务器主机 |
| `KRPC_RPC_PORT` | `50000` | kRPC RPC 端口 |
| `KRPC_STREAM_PORT` | `50001` | kRPC 流端口 |
## 使用示例
配置完成后，询问 Claude：
> “我的当前轨道是什么？添加一个机动节点，将我的远地点提高到 100 公里。”
Claude 将使用 `get_orbit_info` 读取当前轨道，然后使用计算出的 delta-v 调用 `add_maneuver_node`。
## API 测试（Postman）
包含一个 Postman 集合，位于 [`docs/kRPC-Postman-Collection.json`](docs/kRPC-Postman-Collection.json)，用于探索和测试两个支持的 API：
- 基础 kRPC 端点
- kRPC + KRPC.MechJeb 端点
### 导入
1. 打开 Postman 桌面版并选择 **文件 → 导入**。
2. 选择 `docs/kRPC-Postman-Collection.json`。
### 协议说明
kRPC 通过 TCP 上的 Protocol Buffers 进行通信，而不是 HTTP。集合假设一个薄的 HTTP 代理，将 POST 请求转发到 kRPC 服务器。一个最小的代理，使用 `socat` 或一个简短的 Python 脚本就足够了：
```bash
# 示例：转发 localhost:8080 → localhost:50000 处的 kRPC TCP
python3 -c "
import http.server, urllib.request, json, socket, struct
class H(http.server.BaseHTTPRequestHandler):
def do_POST(self):
body = self.rfile.read(int(self.headers['Content-Length']))
# 将正文转发到 kRPC TCP 服务器并中继响应
# （完整代理实现：参见文档/http-proxy.md）
self.send_response(501); self.end_headers()
http.server.HTTPServer(('', 8080), H).serve_forever()
"
```
无需代理，直接探索时，请将 `{{krpc_host}}` 指向任何 HTTP 包装器或直接使用 kRPC Python/Lua 客户端库。
### 集合结构
| 文件夹 | 涵盖内容 |
|---|---|
| **KRPC 核心** | `GetStatus`, `GetServices`, 客户端标识 |
| **SpaceCenter / 飞行器** | 活动飞行器，所有飞行器，名称，MET，质量，情况，参考系 |
| **SpaceCenter / 控制** | 推力，SAS，RCS，齿轮，SAS 模式，阶段 |
| **SpaceCenter / 自动驾驶仪** | 启用/禁用，目标俯仰/航向/横滚，错误 |
| **SpaceCenter / 飞行** | 海拔，表面海拔，纬度/经度，速度，航向，俯仰，横滚，G 力 |
| **SpaceCenter / 轨道** | 远地点/近地点海拔，偏心率，倾角，周期，至远地点/近地点时间，SMA |
| **SpaceCenter / 资源** | 资源名称，数量和容量 |
| **MechJeb / 设置** | 获取 SmartASS、Ascent/Landing/Rendezvous 自动驾驶仪、NodeExecutor、ManeuverPlanner 的句柄 |
| **MechJeb / SmartASS** | 获取/设置接口模式和自动驾驶仪模式，更新 |
| **MechJeb / Ascent 自动驾驶仪** | 启用/禁用，期望海拔和倾角 |
| **MechJeb / 着陆自动驾驶仪** | 无目标着陆，在位置目标处着陆，停止 |
| **MechJeb / 节点执行器** | 执行一个/所有节点，终止 |
| **MechJeb / 机动规划器** | 环化，Hohmann，改变远地点/近地点 |
### 编码助手
所有 kRPC 参数/返回值都是原始的 protobuf 字节 base64 编码。集合的预请求脚本通过 `eval(pm.collectionVariables.get('_h'))` 将这些助手注入每个请求：
```javascript
kRPC_encodeFloat(v) // float32 → base64
kRPC_encodeDouble(v) // float64 → base64
kRPC_encodeBool(v) // bool → base64
kRPC_encodeUint64(v) // uint64 句柄 → base64 varint
kRPC_encodeString(s) // 字符串 → base64（varint 长度 + UTF-8）
kRPC_encodeInt32(v) // int32/枚举 → base64 varint
kRPC_decodeFloat(b64)
kRPC_decodeDouble(b64)
kRPC_decodeUint64(b64)
kRPC_decodeString(b64)
kRPC_decodeInt32(b64)
```
设置请求（获取活动飞行器、获取控制等）自动将返回的句柄存储到集合变量中（`{{vessel_id}}`、`{{control_id}}`等），因此后续请求无需手动复制粘贴。
## 开发
```bash
pip install -e ".[dev]"
pytest
ruff check src/ tests/
```
## 路线图
- [ ] 零件列表和动作组
- [ ] 科学实验
- [ ] CommNet / 天线状态
- [ ] Kerbal EVA 控制
- [ ] KSP 2 支持（通过兼容 kRPC 的分支）
## 许可证
MIT
