userFRM · Jun 24, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -9,20 +9,18 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-
     strategy:
+      fail-fast: false
       matrix:
-        node-version: [20.x, 22.x]
-
+        node-version: [20.x, 22.x, 24.x]
     steps:
       - uses: actions/checkout@v4
-
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
           cache: npm
-
       - run: npm ci
+      - run: npm run typecheck
       - run: npm run build
       - run: npm test
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -0,0 +1,25 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # npm provenance
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          registry-url: https://registry.npmjs.org
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0]
+
+Complete rewrite. The previous line mirrored Kimi's internal file/shell/web
+tools (14 of them), duplicating capabilities the MCP client already has. This
+release replaces that with a thin, generic wrapper over the Kimi CLI.
+
+### Added
+
+- `kimi_run` — send a prompt to the Kimi CLI agent (headless print mode) and
+  return its final answer; optionally scoped to a working directory.
+- `kimi_resume` — continue a prior session by id.
+- `kimi_status` — installation, binary origin, version, and auth health check.
+- Native-binary detection: `~/.kimi-code/bin/kimi` (from the official
+  installer) preferred, with legacy `~/.local/bin/kimi` and `$PATH` fallbacks.
+- Outcome classification on Kimi's documented exit codes (0/1/75), with
+  retry-and-backoff for transient failures and a process-group timeout kill.
+- Quota/balance failure detection even when the CLI exits `0`.
+- Safe-by-default tool approval: `-y`/--yolo is OFF unless opted in per-call
+  (`yolo`) or via `KIMI_YOLO`, so an unsupervised Kimi cannot mutate a repo or
+  run shell without explicit consent.
+
+### Removed
+
+- All 14 file/shell/web passthrough tools from the previous design.
diff --git a/CLAUDE.md b/CLAUDE.md
diff --git a/README.md b/README.md
@@ -1,80 +1,110 @@
 # kimi-code-mcp
 
 [![npm version](https://img.shields.io/npm/v/kimi-code-mcp.svg)](https://www.npmjs.com/package/kimi-code-mcp)
-[![CI](https://github.com/userfrm/kimi-code-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/userfrm/kimi-code-mcp/actions/workflows/ci.yml)
+[![CI](https://github.com/userFRM/kimi-code-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/userFRM/kimi-code-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-MCP server wrapping [Kimi Code CLI](https://github.com/MoonshotAI/kimi-cli) (kimi-k2.5) — 14 tools for filesystem, shell, web, and agent operations.
+An [MCP](https://modelcontextprotocol.io) server that exposes the [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) as a tool for Claude (or any MCP client). Send a prompt to Kimi's agent and get its answer back — a thin, generic wrapper around the CLI's headless mode. No prompt engineering, no opinions: you supply the prompt, Kimi runs it.
 
 ## Prerequisites
 
-- Node.js >= 18
-- [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) installed and authenticated
+- Node.js >= 20
+- The Kimi CLI, installed and authenticated:
 
-## Usage with Claude Desktop
+```bash
+curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
+kimi login
+```
+
+The server auto-detects the binary in this order: `$KIMI_BIN` → `~/.kimi-code/bin/kimi` (native installer) → `~/.local/bin/kimi` (legacy `uv` install) → `kimi` on `$PATH`.
+
+## Install
+
+```bash
+npm install -g kimi-code-mcp
+```
+
+Or run on demand with `npx kimi-code-mcp` (used in the configs below).
 
-Add to your Claude Desktop configuration:
+### Claude Code / Claude Desktop
+
+Add to `~/.claude/mcp.json` (global) or a project `.mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "kimi": {
       "command": "npx",
-      "args": ["-y", "kimi-code-mcp@latest"]
+      "args": ["-y", "kimi-code-mcp"]
     }
   }
 }
 ```
 
-## Usage with VS Code
-
-Install the Kimi Code MCP server in VS Code:
+Run `/mcp` in Claude Code to verify — you should see `kimi` with three tools.
 
-[<img alt="Install in VS Code" src="https://img.shields.io/badge/VS_Code-Install_Server-0078d4?style=flat-square&logo=visualstudiocode&logoColor=white">](https://insiders.vscode.dev/redirect/mcp/install?name=kimi&inputs=%5B%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22kimi-code-mcp%40latest%22%5D%7D)
+### VS Code
 
-Or add to `.vscode/mcp.json`:
+Add to `.vscode/mcp.json`:
 
 ```json
 {
   "servers": {
     "kimi": {
       "command": "npx",
-      "args": ["-y", "kimi-code-mcp@latest"]
+      "args": ["-y", "kimi-code-mcp"]
     }
   }
 }
 ```
 
 ## Tools
 
-| Tool | Description |
-|------|-------------|
-| `kimi_read_file` | Read a text file (up to 1000 lines) |
-| `kimi_read_media` | Analyze images and videos |
-| `kimi_write_file` | Create or overwrite a file |
-| `kimi_edit_file` | Find-and-replace edit in a file |
-| `kimi_glob` | Find files matching a glob pattern |
-| `kimi_grep` | Search for regex patterns in files |
-| `kimi_shell` | Execute shell commands |
-| `kimi_web_search` | Search the web (up to 20 results) |
-| `kimi_fetch_url` | Fetch and extract webpage content |
-| `kimi_agent` | Autonomous agent for complex tasks |
-| `kimi_think` | Extended reasoning and analysis |
-| `kimi_review` | Code review (bugs, security, perf, style) |
-| `kimi_research` | Research with 256K context window |
-| `kimi_test` | Generate or fix tests with edge cases |
-
-## Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `KIMI_CLI_PATH` | Absolute path to kimi binary | `kimi` (from PATH) |
-| `MCP_KIMI_DEBUG` | Enable debug logging to stderr | unset |
+| Tool | What it does |
+|------|--------------|
+| `kimi_run` | Send a prompt to Kimi (headless print mode) and return its final answer. Optional working directory so Kimi can read a codebase. |
+| `kimi_resume` | Continue a previous session by id (returned in earlier output) with a follow-up prompt. |
+| `kimi_status` | Is Kimi installed, which binary (native vs legacy), what version, authenticated? Call this first when other tools fail. |
+
+### `kimi_run` parameters
+
+| Param | Type | Notes |
+|-------|------|-------|
+| `prompt` | string (required) | The prompt to send to Kimi. |
+| `path` | string | Working directory Kimi runs in. Defaults to the server cwd. |
+| `model` | string | Override the Kimi model. |
+| `thinking` | boolean | Enable extended thinking. |
+| `yolo` | boolean | Auto-approve Kimi's tool actions so it can edit files / run shell unsupervised. **Default off** — opt in per-call or via `KIMI_YOLO`. |
+
+> **Safety:** without `yolo`, Kimi answers and reads but will not be auto-approved to mutate your repo or run shell. Turn it on only when you want an autonomous agent acting on the working directory.
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `KIMI_BIN` / `KIMI_CLI_PATH` | auto-detect | Absolute path to the kimi binary. |
+| `KIMI_MODEL` | CLI default | Default model passed to `kimi -m`. |
+| `KIMI_TIMEOUT_MS` | `600000` | Wall-clock budget per invocation. |
+| `KIMI_MAX_OUTPUT_CHARS` | `120000` | Output cap; truncated at a clean boundary beyond it. |
+| `KIMI_MAX_RETRIES` | `2` | Retries for transient (exit 75 / rate-limit) failures. |
+| `KIMI_RETRY_BACKOFF_MS` | `2000` | Base backoff, doubled each attempt. |
+| `KIMI_YOLO` | `false` | Default auto-approval of Kimi's tool actions (per-call `yolo` overrides). |
+| `MCP_KIMI_DEBUG` | unset | Mirror Kimi's stderr to this process's stderr. |
+
+## How it works
+
+```
+Claude ──tool call──▶ kimi-code-mcp ──spawn──▶ kimi --print --output-format text
+                                                     --final-message-only -y -w <dir> -m <model>
+       ◀──answer───            ◀──stdout──
+```
+
+The server spawns Kimi in print (headless) mode, classifies the outcome against Kimi's documented exit codes (`0` ok, `1` permanent, `75` transient), retries transient failures with backoff, enforces a wall-clock timeout with a process-group kill, detects quota/balance failures even when the CLI exits `0`, and returns the final assistant message (with a resume `session` id when one is available).
 
 ## Development
 
 ```bash
-git clone https://github.com/userfrm/kimi-code-mcp.git
+git clone https://github.com/userFRM/kimi-code-mcp.git
 cd kimi-code-mcp
 npm install
 npm run build