# Kimi Code MCP

`kimi-code-mcp` 是一个面向 Codex Desktop 的本地 direct-control 桥接器。
Codex 仍是主控，通过一个 `kimi` MCP 工具直接操作本机已经安装、登录的
官方 Kimi Code CLI。

```text
Codex Desktop -> MCP `kimi` -> `kimi acp` / `kimi <args...>` -> Kimi Code
```

它不会把 Kimi 加进 Codex 模型菜单，不会把 Kimi 伪装成 GPT，也不替代
CCSwitch 或 LiteLLM。Kimi 使用本地配置选择的账号和供应商；官方 OAuth
登录对应 Coding Plan 会员额度，不走 Moonshot API 余额。

## 一个工具，七个 action

| action | 用途 |
| --- | --- |
| `prompt` | 发送 ACP prompt；省略 `session_id` 新建会话，提供则继续会话 |
| `status` | 查询或长轮询任务、结果及 Kimi 交互 |
| `cancel` | 取消任务并停止对应 ACP 进程 |
| `respond` | 回答 Kimi 原生问题或 Plan 评审 |
| `sessions` | 列出官方 Kimi 持久化会话 |
| `cli` | 用完整 `args:string[]` 运行官方 `kimi` CLI |
| `health` | 检查二进制；deep 模式再检查 ACP 初始化与登录 |

唯一 MCP resource 是 `kimi://manual`，包含完整参数、能力映射和风险边界。

MCP 启动时还会自动常驻 `kimi vis`：默认监听
`http://127.0.0.1:58631`，首次启动自动打开浏览器，意外退出后自动重启。
它只负责显示 Kimi 会话，不增加新的 MCP 工具。

## 重要边界

这是刻意精简的直接控制，不是安全沙箱：

- `prompt` 默认 `mode=yolo`。
- 不固定模型或 Thinking；需要 K3 时显式传 `model=kimi-code/k3`、
  `thinking=on` 和 effort。
- 不使用 bridge 路径守卫、敏感文件过滤、环境白名单、任务时限或持久会话
  cwd 核验；只限制同一个已知 `session_id` 同时一轮，不同 session 可并发。
- ACP 文本回调可以直接读写 Kimi 请求的路径；Bash 使用当前用户权限。
- Kimi 自己的 MCP、Skills、Plugins、Hooks、权限规则和项目指令仍会加载。
- `cli` 没有命令白名单、超时或 TTY；argv 不经过 shell，但官方命令本身
  可以修改凭据、供应商、安装、会话和外部状态。
- Agent/AgentSwarm 和并行 prompt 会快速消耗 Coding Plan 额度。

对不可信仓库、生产凭据、危险命令或外部副作用，请使用容器、VM、受限
账号或一次性工作树，而不是依赖提示词。

## 前置条件

- Node.js `>=22.19.0`
- 官方 Kimi Code CLI 已安装并登录
- 可用的 Kimi Coding Plan 或本地配置供应商
- 支持本地 stdio MCP 的 Codex Desktop

桌面应用可能不继承终端 PATH，推荐直接使用绝对路径：

```bash
$HOME/.kimi-code/bin/kimi --version
node --version
```

## 安装

发布版本：

```bash
codex mcp add kimi_code -- "$(command -v npx)" --yes --package=github:lxq020801/kimi-code-mcp#v0.2.1 kimi-code-mcp
```

本地开发：

```bash
git clone https://github.com/lxq020801/kimi-code-mcp.git
cd kimi-code-mcp
npm install
npm run check
npm test
npm run build
```

修改源码后必须重新构建 `dist`，再重启 Codex Desktop。

## Desktop 配置

```toml
[mcp_servers.kimi_code]
command = "/node/绝对路径"
args = ["/kimi-code-mcp/绝对路径/dist/index.js"]
startup_timeout_sec = 30
tool_timeout_sec = 3600
enabled = true

[mcp_servers.kimi_code.env]
KIMI_MCP_KIMI_COMMAND = "/Users/example/.kimi-code/bin/kimi"
KIMI_MCP_SHUTDOWN_GRACE_MS = "3000"
KIMI_MCP_DEBUG = "0"
KIMI_MCP_AUTO_VIS = "1"
KIMI_MCP_VIS_HOST = "127.0.0.1"
KIMI_MCP_VIS_PORT = "58631"
```

TOML 不展开 `$HOME`。修改配置后完全退出并重新打开 Desktop，再新建任务以
重新加载 MCP 工具和 resource。

## 使用

新建一个 K3 编码会话：

```json
{
  "action": "prompt",
  "prompt": "实现这个独立功能，运行聚焦测试，并报告修改文件和验证命令。不要访问凭据或外部服务。",
  "cwd": "/项目/绝对路径",
  "model": "kimi-code/k3",
  "thinking": "on",
  "effort": "high",
  "mode": "yolo"
}
```

随后使用返回的 `task_id` 长轮询：

```json
{ "action": "status", "task_id": "...", "wait_ms": 30000 }
```

继续同一个 Kimi 会话：

```json
{
  "action": "prompt",
  "session_id": "session_...",
  "prompt": "根据 code review 修复这些问题：...",
  "cwd": "/项目/绝对路径",
  "mode": "yolo"
}
```

读取额度或供应商信息等非交互 CLI 输出：

```json
{ "action": "cli", "args": ["provider", "list", "--json"] }
```

`cli` 也返回异步 task id；用相同的 `status` / `cancel` 查询 stdout/stderr 或
停止命令。输出在内存中累积，没有 bridge 大小上限。

不要用 `cli` 启动 TUI、裸 `acp` 或其他等待 stdin/TTY 的流程。登录、更新、
迁移、供应商修改、导出、server/web 和额外的 raw `vis` 实例等操作必须得到
用户当前请求的明确授权。默认 visualizer 已由安装行为持续授权。

## 模型与额度

direct mode 默认不改 Kimi 的 model/Thinking/effort，只有 `mode` 在 MCP schema
中默认 `yolo`。需要可复现的 K3 行为时显式传：

```text
model=kimi-code/k3
thinking=on
effort=low|high|max
```

`low` 适合短审查和小任务，`high` 适合常规实现，`max` 只用于明确值得的复杂
任务。Kimi 子 Agent 会额外消耗 Coding Plan；主控 GPT 的规划和复核也会消耗
当前 Codex/中转供应商额度。

## 验证

```bash
npm run check
npm test
npm run build
npm audit --omit=dev
```

Desktop 中先调用浅 `health`。`deep=true` 不发送模型 prompt，但会检查 ACP
初始化/认证并创建一个无法由 ACP 自动关闭的空诊断会话；它不验证 K3 或
Thinking。真实 prompt 测试会消耗少量 Coding Plan。

## 文档

- [完整使用手册](docs/使用手册.md)
- [Codex Desktop 接入](docs/Codex-Desktop接入.md)
- [环境变量模板](.env.example)

官方资料：

- [Kimi Code CLI](https://github.com/MoonshotAI/kimi-code)
- [Kimi ACP](https://moonshotai.github.io/kimi-code/zh/reference/kimi-acp)
- [Kimi 内置工具](https://moonshotai.github.io/kimi-code/zh/reference/tools)
- [Codex MCP](https://developers.openai.com/codex/mcp)

## 许可证

[MIT](LICENSE)。本项目是本地桥接实现，不是 Moonshot AI 或 OpenAI 官方产品。