kos-telnet-mcp

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

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

目录

• 架构

• 安装

• 配置 KSP

• 配置 MCP 客户端

• 快速跑通

• 110 个工具一览

• 更多文档

Related MCP server: MCP Tools

架构

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 个工具一览

每个工具都有完整的 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。