Ikenga iyke (control bridge)

重要

此仓库已迁移——请勿从此处构建

@ikenga/mcp-iyke 的开发已迁至 ikenga-pkgs monorepo：

→ Royalti-io/ikenga-pkgs/packages/mcp/iyke

此仓库最后更新于 15 May 2026，现已归档并设为只读。

如果你克隆了此仓库，请留意。 此处保留的状态既不是最新发布版本，也不是当前版本：其 package.json 声明的版本为 0.1.2，但源代码包含一组部分迁移的工具，来自代码移回 monorepo 之前的时期。从此目录构建会得到一个从未发布过的版本。从 npm 安装的内容不受影响。

• npm（未变，仍是正确的包）：@ikenga/mcp-iyke
• **问题和 PR：**请在 ikenga-pkgs 中提交

---

@ikenga/mcp-iyke

一个 Model Context Protocol 服务，用于开放 Ikenga 桌面应用的 iyke 控制桥接——这样，任何 MCP 客户端（Claude Code、Cursor、自定义 Agent）都能操控运行中的 Ikenga 会话，就像开发者在 shell 中输入 iyke 命令行一样。

这是什么

Ikenga 是一个基于 Tauri 的 AI 工作区 shell，采用清单驱动的包内核。应用运行时会开放一个 localhost HTTP 服务（其 bearer token 位于 control.json 中），供外部工具检查和操控运行中的 UI：切换窗格、导航路由、获取 DOM 快照、点击元素、读取日志、截取屏幕截图。

此包将该 HTTP 服务封装为 MCP，让大模型 Agent 能够原生使用它。工具与 iyke 命令行子命令相对应。

安装

通过 Claude Code（推荐）

npm install -g @ikenga/mcp-iyke
claude mcp add iyke -s user -- iyke-mcp

之后，任何 Claude Code 会话都可以调用 iyke_state、iyke_go、iyke_mode、iyke_open、iyke_split、iyke_focus、iyke_close，以及运行时检查工具（iyke_dom、iyke_logs、iyke_network、iyke_screenshot、iyke_wait、iyke_click、iyke_type、iyke_key、iyke_query_cache、iyke_devtools）、iframe 工具（iyke_iframe_state、iyke_iframe_send）和项目工具（iyke_project_create、iyke_project_update、iyke_project_list、iyke_project_archive、iyke_project_set_active、iyke_project_get_active）。

通过 npx（无需安装）

claude mcp add iyke -s user -- npx -y @ikenga/mcp-iyke

从源代码安装（面向贡献者）

git clone https://github.com/Royalti-io/ikenga-pkg-mcp-iyke.git
cd ikenga-pkg-mcp-iyke
npm install
npm run build

然后将 MCP 客户端指向 node /path/to/ikenga-pkg-mcp-iyke/dist/index.js。

工具

布局与导航

工具	用途
iyke_state	显示当前侧边栏模式、焦点窗格的路由以及完整窗格树。
iyke_go	将焦点窗格导航至指定路由路径。
iyke_mode	切换侧边栏活动模式。
iyke_open	在焦点窗格中打开新标签页（路由、终端、聊天、工件、迷你应用）。
iyke_split	水平或垂直拆分窗格。
iyke_focus	根据 ID 或从 1 开始的 DFS 叶节点索引（⌃1..⌃6）聚焦窗格。
iyke_close	关闭窗格（若省略 pane_id，则关闭焦点窗格）。

运行时检查与操控

工具	用途
iyke_dom	聚焦窗格的无障碍树快照（Playwright 风格的引用）。
iyke_logs	正在运行的 webview 中最近 500 条控制台和错误日志。
iyke_network	最近 100 条 fetch/XHR 网络记录，包含状态和耗时。
iyke_screenshot	窗口或指定窗格的 PNG 截图。
iyke_wait	等待某个谓词满足（文本/选择器/引用/消失）。
iyke_click	按引用、选择器或文本点击元素。
iyke_type	在输入框/文本区域/contenteditable 中输入内容。
iyke_key	触发键盘组合键（例如 Ctrl+S、Meta+K）。
iyke_query_cache	转储聚焦窗格的 TanStack Query 缓存。
iyke_devtools	打开 Chrome DevTools（仅限调试版本）。

Iframe 运行时状态

工具	用途
iyke_iframe_state	读取 iframe 窗格最近发布的状态对象。
iyke_iframe_send	向 iframe 窗格发送无需等待响应的 postMessage。

项目

工具	用途
iyke_project_create	创建项目（slug 和显示名称；可选 root_path、icon、color、description）。
iyke_project_update	更新现有项目的字段（display_name、root_path、icon、color、description、position）。
iyke_project_list	按切换器顺序列出项目；传入 include_archived=true 可显示已归档项目。
iyke_project_archive	软删除项目；拒绝归档内置的 Default 项目。
iyke_project_set_active	切换 shell 的活动项目；重新获取项目范围内的查询。
iyke_project_get_active	返回当前活动项目。

信任边界

MCP 服务会从特定于平台的应用本地数据目录读取 control.json（macOS 上为 ~/Library/Application Support/app.ikenga/control.json，Linux 上为 $XDG_DATA_HOME/app.ikenga/control.json，Windows 上为 %APPDATA%/app.ikenga/control.json）。控制文件包含：

• port — 应用内 HTTP 服务正在监听的 localhost 端口
• token — 每个请求都必须携带的 bearer token
• pid — 所属进程的 PID（用于检测过期文件）

被 kill -9 留下的过期 control.json 文件会在至少 5 分钟后自动删除；较新的过期文件会被报告（可能是启动竞争），以避免覆盖正在启动的应用。

如果 Ikenga 桌面应用未运行，每次工具调用都会返回结构化错误，而不会一直挂起——你的 Agent 会读取失败信息并报告，而不是默默等待。

MCP 服务始终只会使用 control.json 中的端口与 127.0.0.1 通信，并使用同一文件中的 bearer token。不会进行任何出站网络通信，也不会收集遥测数据。

兼容性

• **Ikenga shell：**任何公开 v1 control.json 架构的版本。
• Node.js：≥ 20。
• **Bun：**无需编译即可运行（bun src/index.ts）。
• MCP SDK：@modelcontextprotocol/sdk ^1.23.0。

版本管理

此软件包遵循 SemVer 2.0.0。主版本号升级可能会破坏 MCP 工具名称或参数结构；次版本号升级会添加新工具或提供不破坏兼容性的改进；补丁版本用于修复错误。

iyke HTTP 协议版本（应用内服务的 API 接口）独立管理，通过 control.json 中的 schema_version: 1 固定。此软件包目前仅支持协议 v1。

贡献

欢迎贡献。有关设置、约定和 DCO 的信息，请参阅 CONTRIBUTING.md。提交贡献即表示你同意按照 Apache 2.0 许可（与代码库一致）许可你的贡献。

如需报告错误或提出功能请求，请提交 issue。 如需报告安全问题，请参阅 SECURITY.md——请勿公开提交 issue。

许可证

Apache License 2.0 — Copyright (c) 2026 Royalti, Inc.

相关项目

• Ikenga shell — 此软件包驱动的桌面应用。
• @ikenga/contract — 共享的清单和 iyke 运行时常量。
• Model Context Protocol — 此服务使用的协议。