kos-telnet-mcp

一个让 AI agent 通过 MCP 控制 Kerbal Space Program 里 kOS 计算机的 server。

Telnet 命令通道 + Archive 文件高带宽通道 + 本地混合检索文档引擎，110 个工具让 agent 能写、跑、调试 kerboscript，并即时拿到飞行反馈。

目录

• 架构
• 安装
• 配置 KSP
• 配置 MCP 客户端
• 快速跑通
• 110 个工具一览
• 更多文档

架构

flowchart LR
    Agent["AI Agent<br/>(Cursor / Claude)"]
    Agent -- "MCP / stdio" --> MCP

    subgraph MCP["kos-telnet-mcp (Node + TS)"]
        direction TB
        Telnet["Telnet Bridge<br/>+ XTERM emulator"]
        Lifecycle["Program Lifecycle<br/>eval / run / write_file"]
        Recorder["Recorder Toolkit<br/>(自治采样)"]
        Sim["KUniverse / Timewarp"]
        Inspect["Craft Inspect<br/>+ 分组 Snapshot"]
        Watch["Watch / Bg / Repl"]
        Authoring["Lint / Format"]
        Docs["Docs Engine<br/>BM25 + MiniLM"]
        KB["Agent KB"]
        Scaffold["任务模板"]
        KspIO["KSP Player.log"]
    end

    MCP -- "TCP 5410" --> Game["KSP + kOS"]
    MCP -- "FS R/W" --> Archive["Ships/Script/<br/>(Archive 卷)"]
    MCP -- "FS read" --> UnityLog["Player.log"]
    Game --- Archive
    Game --- UnityLog

    subgraph Vessel["飞船"]
        CPU1["主 CPU"]
        CPU2["Recorder CPU<br/>boot 自启"]
    end
    Game --- Vessel
    CPU2 -- "WRITE / READ" --> Archive

设计要点：

• Telnet 命令通道——所有交互（输入、读屏、求值、上传小文件）都走它；MCP 进程独占连接，工具调用全局串行化（mutex），不会互相打断。
• Archive 高带宽通道——大文件、recorder 数据、KB 都走 KSP 的 Ships/Script/ 文件系统；agent 调 kos_recorder_tail 完全不占 telnet。
• 本地文档检索——167 个 RST 解析后落到 .cache/docs/：BM25（minisearch）+ MiniLM 量化向量（@xenova/transformers）混合，无需联网。
• 试错友好——kos_kuniverse_quicksave/quickload 让 agent 自由失败重来；kos_timewarp_warp_to 拉时间。

安装

需要 Node ≥ 20。

# 1. 装依赖
npm install

# 2. 编译 TypeScript（输出到 dist/）
npm run build

# 3. 一次性建文档索引（RST → BM25 + 向量；约 1 分钟，落到 .cache/docs/）
npm run docs:build

第 3 步是可选的（不建索引也能跑，但 kos_docs_* 会返回 docs_index_missing）。也可以让 agent 跑 kos_docs_rebuild_index。

配置 KSP

1. 打开游戏内 telnet

进游戏，随便上一艘有 kOS 处理器的船，打开 kOS 终端窗口（在该处理器零件的右键菜单里），输入：

SET CONFIG:TELNET TO TRUE.
SET CONFIG:TPORT TO 5410.
SET CONFIG:IPADDRESS TO "127.0.0.1".

也可以从 KSP 主菜单的 Settings → kOS 里改。

2. 让 telnet 在每次启动游戏时自启（推荐）

在 Ships/Script/boot/auto_telnet.ks 写：

SET CONFIG:TELNET TO TRUE.
SET CONFIG:TPORT TO 5410.
SET CONFIG:IPADDRESS TO "127.0.0.1".

然后在 VAB/SPH 里把任意一艘船的 kOS 处理器 boot file 设为 auto_telnet.ks。

3. 验证

游戏内随意操控，回到桌面执行：

node dist/index.js

stderr 应该输出：

[kos-telnet-mcp] ready - telnet=127.0.0.1:5410 archive=...\Kerbal Space Program\Ships\Script tools=110

tools=110 说明所有命名空间都注册成功。

配置 MCP 客户端

完整示例：config/mcp.client.example.json

Cursor

把以下内容写入 ~/.cursor/mcp.json（或 Cursor 的 Settings → MCP）：

{
  "mcpServers": {
    "kos-telnet": {
      "command": "node",
      "args": ["c:/Users/liet/project/moeru/ksp/kos-telnet-mcp/dist/index.js"],
      "env": {
        "KOS_MCP_CONFIG": "c:/Users/liet/project/moeru/ksp/kos-telnet-mcp/config/kos-mcp.config.json"
      }
    }
  }
}

Claude Desktop

写入 %APPDATA%/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "kos-telnet": {
      "command": "node",
      "args": ["c:/Users/liet/project/moeru/ksp/kos-telnet-mcp/dist/index.js"]
    }
  }
}

server 端配置（kos-mcp.config.json）

参考 config/kos-mcp.config.example.json：

{
  "telnet": {
    "host": "127.0.0.1",
    "port": 5410,
    "terminal": "XTERM",
    "rows": 24,
    "cols": 80
  },
  "archive": {
    "ksp_install_dir": null,
    "auto_detect": true
  },
  "session": {
    "history_kb": 100,
    "default_wait_timeout_ms": 10000
  }
}

字段说明：

• telnet.host/port：和 KSP CONFIG:IPADDRESS / CONFIG:TPORT 对齐。
• archive.ksp_install_dir：KSP 安装根目录（含 Ships/、GameData/ 的那个）。null + auto_detect:true 会扫 Steam/GOG/Epic 常见路径。
• archive.auto_detect：是否自动扫描；找到的 Ships/Script/ 会用作 archive_root。
• session.history_kb：内存里 telnet 滚动历史的最大字节数。
• session.default_wait_timeout_ms：kos_session_wait_for 等阻塞工具的默认超时。

加载顺序：KOS_MCP_CONFIG env → ./kos-mcp.config.json → ./config/kos-mcp.config.json → 内置默认。

快速跑通（三步）

1. 启动 server

   node dist/index.js
   

   或者通过 MCP 客户端拉起。

2. 从客户端列工具

   在 Cursor 里 @kos-telnet 应能看到 110 个 tool。或在程序里调 tools/list。

   Cursor 自 2025-11 起强制工具名只能用 [a-zA-Z0-9_]。本项目所有工具的 wire-name 都是下划线形式（kos_session_connect），调用时直接用下划线名即可。源码注释里偶尔出现的 dot 形式（kos.session.connect）只是文档惯例，runtime 已自动 normalize。

3. 第一次列 CPU 并 attach

   先确保 KSP 跑着，飞船可控，然后 agent 调：

   kos_session_list_cpus()
   → { ok:true, cpus:[ { index:1, vessel:"Test Rocket", cpu_tag:"main", ... } ], count:1 }
   
   kos_session_connect({ index:1 })
   → { ok:true, mode:"attached", attached_cpu:{...} }
   
   kos_program_eval({ expr:"SHIP:ALTITUDE" })
   → { ok:true, result:"123.4", ... }
   

接下来怎么干完全交给 agent。AGENTS.md 是给它看的指南。

110 个工具一览

命名空间	数量	一句话作用
kos_session_*	11	telnet 终端：list/connect/detach、send_input、read_screen、history、wait_for、interrupt、sync_state
kos_program_*	10	程序生命周期：eval、双模式 write/read_file、list、delete、run/terminate/compile、disk_status、power_status
kos_recorder_*	8	自治飞行记录仪：install_and_start 一键部署、tail/dump/status/stop/clear/uninstall/list_sessions
kos_kuniverse_*	10	模拟控制：quicksave/quickload(_list)、pause、revert(_to_launch/_to_editor/can)、active_vessel/force_set/debug_log
kos_timewarp_*	7	set/set_index、warp_to、cancel、status、mode、wait_until_settled
kos_craft_*	8	飞船检视：parts、engines、resources、staging、crew、delta_v_budget、mass_summary、tag_lookup
kos_maneuver_*	5	机动节点：list/add/remove/clear/execute
kos_snapshot_*	9	分组遥测：orbit/fuel/attitude/thermal/throttle/target/surface/body/all
kos_watch_*	5	流式监控：add/remove/list/clear/read
kos_bg_*	4	后台触发器（基于 WHEN）：start/list/kill/kill_all
kos_repl_*	5	持久状态会话：execute/set/print/get_globals/reset
ksp_log_*	6	KSP Player.log tail/grep/marker 三件套
kos_authoring_*	3	kerboscript lint、format、lint_file
kos_kb_*	5	Agent 跨会话知识库：write/read/list/delete/search
kos_scaffold_*	2	任务模板：templates、generate（launch/hohmann/suicide_burn 等 8 个）
kos_docs_*	12	文档检索：search、get_topic/structure/method/function/keyword、list_examples、cheatsheet、related、symbol_at、index_status、rebuild_index

每个工具都有完整的 zod schema 描述，agent 能直接读到入参/返回结构。

更多文档

• AGENTS.md —— 给 LLM agent 看的速查 + 典型工作流 + kerboscript 雷区，先读这个。
• 设计方案 —— 项目原始设计 plan，含架构图、决策依据、未实现项。
• 各模块源码 src/<ns>/register.ts 是命名空间真相之源，描述就是 zod .describe()。

已知限制

• ksp_screenshot 暂未实现（plan 中标为可选）；建议 agent 直接用 kos_snapshot_* 获取数值数据。
• kos_docs_* 首次使用前必须 npm run docs:build 或 kos_docs_rebuild_index；否则返回 docs_index_missing。
• archive 路径未配置时，kos_recorder_*、kos_kb_*、kos_authoring_lint_file 会返回 no_archive_root；编辑 kos-mcp.config.json 设置 archive.ksp_install_dir。
• kOS 1KB 本地盘：写大程序请用 kos_program_write_file 的 mode:"fs"（直接写 archive，绕过 1KB 限制），或 mode:"auto" 让 server 按大小决定。

许可

MIT。