# kimi-acp-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub](https://img.shields.io/badge/GitHub-TuTouPower%2Fkimi--acp--mcp-blue)](https://github.com/TuTouPower/kimi-acp-mcp)

把 Claude Code 通过 MCP 接到本机已登录的 [Kimi Code](https://www.kimi.com/code) 的桥，走 Moonshot 官方 `kimi acp` ACP 协议，**非逆向**。让 Claude Code 把子任务委派给 Kimi 在指定 cwd 自主干活（读写文件、跑命令、多步推理）。

## 架构

```
Claude Code (MCP client)
    │ MCP / stdio
    ▼
kimi-acp-mcp (本项目)
    ├─ MCP server  ← 暴露工具：kimi_prompt / kimi_status / kimi_sessions
    └─ ACP client  ← 长驻子进程 spawn `kimi acp`
        │ ACP / stdio
        ▼
    Kimi K2.7 Code (256K 上下文)
```

完整设计见 `docs/blueprint/architecture.md`。

## 前置

- Node ≥ 18
- 本机已装 Kimi Code CLI 并完成 `kimi login`（验证：`kimi --version` 返回版本号）

## 安装与构建

```bash
cd ~/karson_ubuntu/kimi-acp-mcp
npm install
npm run build
```

## 配置到 Claude Code

Claude Code 的 MCP 配置在 `~/.claude.json`（user scope）或项目根 `.mcp.json`（project scope），**不是** `~/.claude/settings.json`。推荐用 `claude mcp add` CLI（user scope，全局可用）：

```bash
claude mcp add kimi-acp \
  -e KIMI_BIN=/home/<user>/.kimi-code/bin/kimi \
  -e KIMI_ACP_PERMISSION=readwrite \
  -- node /home/<user>/kimi-acp-mcp/dist/index.js
```

或在项目根建 `.mcp.json`：

```json
{
  "mcpServers": {
    "kimi-acp": {
      "command": "node",
      "args": ["/home/<user>/kimi-acp-mcp/dist/index.js"],
      "env": {
        "KIMI_BIN": "/home/<user>/.kimi-code/bin/kimi",
        "KIMI_ACP_PERMISSION": "readwrite"
      }
    }
  }
}
```

`KIMI_BIN` 可省略（默认从 PATH 找 `kimi`）。`KIMI_ACP_PERMISSION` 可选 `readonly` / `readwrite`。

重启 Claude Code 后，`/mcp` 应能看到 `kimi-acp`。

详细配置、env 说明、故障排查见 [`docs/guides/claude-code-setup.md`](docs/guides/claude-code-setup.md)。

## 配置到 opencode

[opencode](https://opencode.ai/) 1.17+ 也支持，配置位置和键名与 Claude Code 不同：

```bash
opencode mcp add kimi-acp \
  --env KIMI_BIN=/home/<user>/.kimi-code/bin/kimi \
  --env KIMI_ACP_PERMISSION=readwrite \
  -- node /home/<user>/kimi-acp-mcp/dist/index.js
```

写入 `~/.config/opencode/opencode.json` 的 `mcp` 字段。验证：`opencode mcp list` 应显示 `kimi-acp ✓ connected`。工具调用以 `kimi-acp_kimi_prompt` 暴露。

opencode 详细配置（含 Claude Code 与 opencode 格式差异表）见 [guide](docs/guides/claude-code-setup.md#opencode)。

## 测试

```bash
npm test                   # 单元 + 集成（默认排除 e2e）
KIMI_ACP_E2E=1 npm test    # e2e（需本机 kimi 已 kimi login；真实消耗 Kimi 配额）
```

e2e 会真实 spawn `kimi acp`，让 Kimi 在临时 cwd 创建文件验证全链路。已在本机验证通过。

## 文档入口

- Agent 工作规则：[`AGENTS.md`](AGENTS.md)
- 架构：[`docs/blueprint/architecture.md`](docs/blueprint/architecture.md)
- Claude Code 配置详细：[`docs/guides/claude-code-setup.md`](docs/guides/claude-code-setup.md)

## License

MIT