Kimi Server

中文版 (Chinese)

What is This?

Kimi MCP Server is an MCP (Model Context Protocol) bridge that lets Claude Code consult Kimi (another AI model) in a Claude-led challenge loop. Claude forms a position first, Kimi challenges it as a skeptic, Claude adjudicates each objection, and a second round happens if disagreement remains. Kimi is a read-only code analyst with web research capabilities — it can read files and search the web, but it cannot execute commands or modify anything.

The key insight: this is not "ask Kimi for advice" — it's "let Kimi challenge Claude's proposal". Claude remains the final arbiter; Kimi's role is to find flaws, surface risks, and propose alternatives.

Why Build This?

Single-model AI coding assistants have blind spots. When Claude is deep in a debugging session or designing an architecture, it can develop tunnel vision — fixating on one approach while missing alternatives. This project addresses that by:

1. Breaking echo chambers — A second model reading the same code independently often catches what the first one missed
2. Structured disagreement — Instead of vague "review this" requests, each consultation has a specific role (skeptic, architect, debugger, judge) with structured input/output schemas, forcing rigorous analysis
3. Read-only safety — Kimi can read files and access the web, but it cannot execute commands, write files, or modify anything. Sensitive files (.env, credentials, keys) are explicitly blocked at the system prompt level
4. Evidence-based responses — Every consultation returns which files Kimi read and which web searches it performed, so you can verify the analysis is grounded in real code and up-to-date information, not hallucination

Design Philosophy

┌──────────────────────────────────────────────────────────┐
│  "Don't trust one model's opinion — get a second read."  │
└──────────────────────────────────────────────────────────┘

The core design principles:

• Structured over freeform — Each role has a defined context schema. No "just look at this code" — you must specify what you're asking, what you've tried, and what constraints exist. This forces the caller (Claude) to organize its thinking before consulting.
• Read-only by design — The Kimi agent is configured with ReadFile, Glob, Grep (code), and SearchWeb, FetchURL (web). No write, no exec. This is enforced at both the agent config level and the system prompt level.
• Transparent evidence chain — The response includes evidence (list of files Kimi read with tool traces) and parse_ok (whether the structured output parsed correctly). If parse_ok is false, you know something went wrong.
• Fail-safe over fail-silent — Retryable errors (exit code 75) are surfaced as retryable. Parse failures return the raw response preview so the caller can still extract value. The incomplete_trace flag warns when tool call/result pairs are missing.

Architecture

┌─────────────┐     MCP/stdio      ┌──────────────────┐    spawn     ┌──────────┐
│ Claude Code │ ◄──────────────►   │ kimi-mcp-server  │ ──────────►  │ Kimi CLI │
│  (client)   │                    │                  │   stdin/out  │ (agent)  │
└─────────────┘                    └──────────────────┘              └──────────┘
                                          │                               │
                                   ┌──────┴──────┐                 ┌─────┴──────┐
                                   │ Components: │                 │ Can:       │
                                   │• server.ts  │                 │• ReadFile  │
                                   │• kimi-client│                 │• Glob      │
                                   │• prompt-    │                 │• Grep      │
                                   │  builder    │                 │• SearchWeb │
                                   │• response-  │                 │• FetchURL  │
                                   │  parser     │                 │            │
                                   └─────────────┘                 │ Cannot:    │
                                                                   │• Write     │
                                                                   │• Execute   │
                                                                   └────────────┘

Data flow:

1. Claude Code calls the consult_kimi MCP tool with a role, message, and structured context
2. server.ts validates the input against role-specific Zod schemas
3. prompt-builder.ts assembles a role-tailored prompt with formatted context
4. kimi-client.ts spawns the Kimi CLI process, sends the prompt via stdin, and collects stream-json output
5. response-parser.ts parses the stream-json, extracts tool traces (file reads and web searches), and validates the final JSON response
6. The structured ConsultResult is returned to Claude Code

Module responsibilities:

Module	Responsibility
server.ts	MCP server lifecycle, tool registration, input validation, mode switching (auto/manual/disabled)
kimi-client.ts	Process spawning, stdin/stdout I/O, timeout handling (180s), error classification (retryable vs fatal)
prompt-builder.ts	Role templates (skeptic/architect/debugger/judge), context formatting, JSON output instructions
response-parser.ts	Stream-json line parsing, tool call/result pairing, JSON extraction from fenced/raw text, Zod validation

Challenge-Loop Protocol

Every consultation follows a structured multi-round protocol:

1. Claude forms a position first — no calls to Kimi without a defensible proposal
2. Round 1 — Claude sends its position to Kimi (default role: skeptic). Kimi challenges it with risks, flaws, and alternatives.
3. Claude adjudicates inline — each of Kimi's objections is marked ADOPT or REJECT with reasoning. Kimi's raw response is shown to the user verbatim.
4. Round 2 (mandatory unless Round 1 had zero rejections) — Claude's adjudication is sent back to Kimi via the prior_exchange field. Kimi challenges Claude's rejections.
5. Round 3 (optional) — only if Kimi raises genuinely new high-value arguments. Hard maximum.
6. Claude makes the final decision — unresolved disagreements are documented but Claude decides.

Four Consultation Roles

Role	When to Use	What It Does
skeptic (default)	Challenging Claude's proposed approach	Finds flaws, surfaces risks, identifies hidden assumptions
architect	When Claude has no defensible proposal yet	Independent design input for scalability, maintainability, trade-offs
debugger	Debugging after 2+ failed attempts	Challenges Claude's root-cause hypothesis, traces code paths
judge	Comparing 2+ already-formed approaches	Objectively evaluates each option against criteria

Prerequisites

• Node.js >= 18
• Kimi CLI installed and available in PATH (or configure via KIMI_PATH)

Installation

git clone [email protected]:MichaelCecil/kimi-mcp-server.git
cd kimi-mcp-server
npm install
npm run build
npm test   # optional: verify parser tests pass

Configuration

Environment Variables

Variable	Default	Description
KIMI_BRIDGE_TOOL_ENABLED	0	Set to 1 to enable the consult_kimi tool
KIMI_BRIDGE_AUTO_ENABLED	0	Set to 1 to let Claude proactively call Kimi (otherwise manual only)
KIMI_BRIDGE_DEBUG	0	Set to 1 to enable debug logging to stderr
KIMI_BRIDGE_LANG	(unset)	Force Kimi output language (e.g., Chinese, English). When unset, Kimi matches the language of the consultation request.
KIMI_PATH	kimi	Path to the Kimi CLI binary

Claude Code MCP Setup

Add to your Claude Code MCP config (~/.claude/settings.json or project-level):

{
  "mcpServers": {
    "kimi-bridge": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/kimi-mcp-server/src/server.ts"],
      "env": {
        "KIMI_BRIDGE_TOOL_ENABLED": "1",
        "KIMI_BRIDGE_AUTO_ENABLED": "0"
      }
    }
  }
}

Two operating modes:

• Manual mode (AUTO_ENABLED=0): Claude only calls Kimi when you explicitly ask (e.g., "ask Kimi", "get a second opinion")
• Auto mode (AUTO_ENABLED=1): Claude proactively consults Kimi for complex design decisions, stuck debugging, and multi-option evaluations

Usage Examples

Ask Kimi to review an architecture decision

"Ask Kimi as an architect to review the current MCP server design"

Claude will call consult_kimi with role architect, providing the current design, requirements, alternatives, and constraints.

Get a skeptic's take before a risky change

"Have Kimi challenge our approach to the database migration"

Claude will call with role skeptic, providing the proposed approach, goals, constraints, and known risks.

Debug a stubborn bug with a second pair of eyes

"I've tried X, Y, Z and the bug persists — ask Kimi to debug it"

Claude will call with role debugger, providing symptoms, repro steps, logs, expected behavior, and tried approaches.

Compare two implementation options

"Ask Kimi to judge between approach A and approach B"

Claude will call with role judge, providing structured options with pros/cons and evaluation criteria.

Response Format

Every consultation returns a structured ConsultResult:

{
  "parse_ok": true,
  "response": "Detailed analysis grounded in code evidence...",
  "key_risks": ["risk 1", "risk 2"],
  "assumptions": ["assumption the analysis depends on"],
  "alternatives": ["approach not yet considered"],
  "evidence": [
    {
      "tool": "ReadFile",
      "tool_call_id": "call_abc",
      "args": { "path": "src/server.ts" },
      "summary": "First 800 chars of file content..."
    }
  ],
  "confidence": "high: analysis covers all relevant code paths",
  "raw_response_preview": "First 500 chars of raw output...",
  "incomplete_trace": false
}

Key fields to check:

• parse_ok — whether Kimi's output parsed into the expected JSON schema
• evidence — which files Kimi read and which web searches it performed (verify analysis is grounded)
• incomplete_trace — if true, some tool calls were missing results (may indicate timeout or error)

Project Structure

kimi-mcp-server/
├── src/
│   ├── server.ts             # MCP server, tool registration, input validation
│   ├── kimi-client.ts        # Kimi CLI spawning, I/O, timeout, error handling
│   ├── prompt-builder.ts     # Role templates and context formatting
│   └── response-parser.ts    # Stream-JSON parsing, tool trace extraction
├── tests/
│   ├── response-parser.test.ts   # Parser regression tests (brace-depth extraction, stream-json)
│   └── prompt-builder.test.ts    # Prompt template rendering tests
├── config/
│   ├── readonly-consultant.yaml  # Kimi agent config (read-only + web tools)
│   ├── system-prompt.md          # Kimi system prompt with security rules
│   └── empty-mcp.json            # Empty MCP config for isolated Kimi runs
├── CLAUDE.md                 # Developer onboarding and design decisions
├── package.json
├── tsconfig.json
├── README.md                 # English documentation
└── README_CN.md              # Chinese documentation

License

MIT