ladder-mcp 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to Ladder_mcp are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); this project uses
+[Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-06-27
+
+First release. Windows-first MCP bridge for Kimi Code CLI v24, rebuilt in a
+fresh `./src` application (package `ladder-mcp`). Logic is ported from the
+read-only `kimi-code-mcp/` reference; the legacy `CacheManager`/warmup layer is
+not carried over.
+
+### Added — v1 core (Epics 1-3)
+
+- Robust environment resolver (`environment.ts`): discovers `kimi.exe` via PATH
+  and `~/.kimi-code/bin/`, resolves the `~/.kimi-code/` catalog, credentials and
+  version with no hardcoded POSIX paths; no silent fallback to legacy `~/.kimi/`.
+- CLI adapter (`kimi-runner.ts`): correct Kimi CLI v24 arguments
+  (`-p`, `--output-format stream-json`, `-S`, `-C`, `--auto`), `stream-json`
+  parsing, native session resume, Windows process-tree termination on timeout.
+- API adapter (`kimi-api.ts`): contextless `kimi_query` / `kimi_verify` reading
+  key/endpoint from `KIMICODE_API_KEY` or `~/.kimi-code/config.toml`.
+- Six v1 MCP tools: `kimi_analyze`, `kimi_query`, `kimi_verify`, `kimi_resume`,
+  `kimi_list_sessions`, `kimi_status`.
+
+### Added — vNext expansion (Epic 4)
+
+- **CLI admin & capabilities** (`transports/cli-admin.ts`): `kimi_capabilities`,
+  `kimi_doctor`, `kimi_provider_list`, `kimi_export_session`,
+  `kimi_visualize_session`. Export requires an explicit `output_path`, is
+  confined to the working directory, and excludes the global diagnostic log by
+  default.
+- **ACP MVP over stdio** (`transports/acp.ts`): JSON-RPC client for `kimi acp`
+  with newline-delimited and `Content-Length` framing; `kimi_chat`,
+  `kimi_acp_sessions`, `kimi_cancel`.
+- **Background task lifecycle** (`task-store.ts`): in-process task store with
+  `kimi_chat background=true`, `kimi_task_status`, `kimi_task_output`,
+  `kimi_task_cancel`.
+- **Kimi-hosted MCP config + read-only desktop probes**
+  (`kimi-mcp-config.ts`, `desktop-work.ts`): `kimi_generate_mcp_config`,
+  `kimi_desktop_status`, `kimi_budget_probe`. Desktop access is
+  experimental/read-only — no token-store reads, no web-auth replay, no desktop
+  Work task submission.
+
+### Security & robustness (adversarial review)
+
+Hardened against path traversal/TOCTOU on export, writes under the read-only
+reference tree, unbounded ACP frame/task memory, process crash on malformed ACP
+JSON, non-idempotent task cancellation, and UTF-8 byte-boundary truncation.
+
+The remaining lower-risk review findings (W1-W12) were also resolved before
+release: raw ACP response-id matching (no `NaN` coercion), bounded ACP update
+buffer, clamped ACP request timeouts, smaller buffers for parallel capability
+probes, a timeout around task cancel hooks, a size cap on the desktop status
+probe body, validated `kimi_chat` timeout input, and `kimi_cancel` rejecting
+ambiguous task_id+session_id calls. Regression tests added (49 total).
+
+### Known limitations
+
+- Windows 11 only (NFR-1); POSIX branches are not a target.
+
+[1.0.0]: https://semver.org/

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Sherstnev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project ports logic from the kimi-code-mcp reference
+(MIT License, Copyright (c) 2026 howardpen9), retained as a read-only
+reference under ./kimi-code-mcp/.

package/README.md

@@ -0,0 +1,85 @@
+# Ladder_mcp
+
+Windows-first [MCP](https://modelcontextprotocol.io/) bridge for the
+[Kimi Code](https://kimi.com) CLI (v24). It exposes Kimi Code as MCP tools so a
+client like Claude Code can run codebase analysis, native sessions, API
+queries, ACP chat, background tasks, and CLI admin/diagnostics — all on Windows
+without hardcoded POSIX assumptions.
+
+> Status: **v1.0.0**. Supported platform is **Windows 11 only**.
+
+## Requirements
+
+- Windows 11
+- Node.js ≥ 18
+- Kimi Code CLI installed (`kimi.exe` on PATH or at `~/.kimi-code/bin/kimi.exe`),
+  authenticated (`~/.kimi-code/`)
+
+## Install & build
+
+```bash
+npm install
+npm run build      # compiles src/ -> dist/ (tests excluded)
+```
+
+Quick checks:
+
+```bash
+npm test           # vitest (44 tests)
+npm run typecheck  # tsc --noEmit (incl. tests)
+npm run dev        # run the server from source via tsx
+```
+
+## Run as an MCP server
+
+The server speaks MCP over stdio. Point your MCP client at the built entry:
+
+```jsonc
+// e.g. Claude Code MCP config
+{
+  "mcpServers": {
+    "kimi-code": {
+      "command": "node",
+      "args": ["C:\\path\\to\\Ladder_mcp\\dist\\index.js"]
+    }
+  }
+}
+```
+
+To let Kimi Code itself host this server, use the `kimi_generate_mcp_config`
+tool to produce/merge a `.kimi-code/mcp.json` entry.
+
+## Tools
+
+**Core (v1)** — `kimi_analyze`, `kimi_query`, `kimi_verify`, `kimi_resume`,
+`kimi_list_sessions`, `kimi_status`
+
+**CLI admin & capabilities** — `kimi_capabilities`, `kimi_doctor`,
+`kimi_provider_list`, `kimi_export_session`, `kimi_visualize_session`
+
+**ACP (chat over stdio)** — `kimi_chat`, `kimi_acp_sessions`, `kimi_cancel`
+
+**Background tasks** — `kimi_task_status`, `kimi_task_output`, `kimi_task_cancel`
+(set `background=true` on `kimi_chat`)
+
+**Kimi-hosted config & desktop (read-only)** — `kimi_generate_mcp_config`,
+`kimi_desktop_status`, `kimi_budget_probe`
+
+## Safety boundaries
+
+- `kimi_export_session` requires an explicit `output_path`, stays within the
+  working directory, and excludes the global diagnostic log by default.
+- Desktop Work tools are **experimental and read-only**: they do not read the
+  desktop token store, replay web auth, or submit desktop Work tasks.
+- The vendored `kimi-code-mcp/` is a **read-only reference** and is never edited
+  or written to by the tools.
+
+## Project layout
+
+- `src/` — the Ladder_mcp application (package `ladder-mcp`)
+- `kimi-code-mcp/` — upstream reference (read-only, MIT)
+- `_bmad-output/` — planning & implementation artifacts (BMAD workflow)
+
+## License
+
+[MIT](./LICENSE). Ports logic from the MIT-licensed `kimi-code-mcp` reference.

package/dist/desktop-work.js

@@ -0,0 +1,102 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export const MAX_PROBE_BODY_BYTES = 256 * 1024;
+// Read a fetch response body but stop once MAX_PROBE_BODY_BYTES is reached, so a
+// misbehaving or hostile local endpoint cannot stream an unbounded body into memory.
+// The surrounding AbortController still bounds total time.
+export async function readBodyCapped(response) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        return { text: await response.text(), truncated: false };
+    const decoder = new TextDecoder();
+    let text = '';
+    let total = 0;
+    let truncated = false;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > MAX_PROBE_BODY_BYTES) {
+            text += decoder.decode(value.slice(0, Math.max(0, MAX_PROBE_BODY_BYTES - (total - value.byteLength))));
+            truncated = true;
+            await reader.cancel();
+            break;
+        }
+        text += decoder.decode(value, { stream: true });
+    }
+    if (!truncated)
+        text += decoder.decode();
+    return { text, truncated };
+}
+export async function getDesktopStatus() {
+    const safety = [
+        'Experimental/read-only probe only.',
+        'Does not read desktop token-store files.',
+        'Does not replay web auth.',
+        'Does not submit desktop Work tasks.',
+    ];
+    const status = { experimental: true, readOnly: true, safety };
+    try {
+        // Resolved from PATH. This is safe by construction: execFile runs the binary
+        // directly (no shell, so no metacharacter injection), the only argument is the
+        // fixed read-only `status` verb, and a missing binary simply rejects below.
+        const { stdout, stderr } = await execFileAsync('kimi-webbridge', ['status'], {
+            timeout: 5000,
+            windowsHide: true,
+        });
+        status.bridgeCommand = { ok: true, stdout: String(stdout), stderr: String(stderr) };
+    }
+    catch (error) {
+        status.bridgeCommand = { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 3000);
+        try {
+            const response = await fetch('http://127.0.0.1:10086/status', { signal: controller.signal });
+            const { text, truncated } = await readBodyCapped(response);
+            let body = text;
+            if (!truncated) {
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    // Keep raw text.
+                }
+            }
+            status.bridgeHttp = { ok: response.ok, status: response.status, body, ...(truncated ? { truncated: true } : {}) };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch (error) {
+        status.bridgeHttp = { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    return status;
+}
+export function buildBudgetProbeGuide(includeCliProbe) {
+    const lines = [
+        '## Kimi Budget Probe (experimental evidence workflow)',
+        '',
+        'Safety boundaries:',
+        '- This probe does not read desktop token-store files.',
+        '- This probe does not replay web auth.',
+        '- This probe does not submit desktop Work tasks.',
+        '- Treat budget separation as unproven until visible counters confirm it.',
+        '',
+        'Manual evidence steps:',
+        '1. Record visible Kimi Code CLI usage/billing counters.',
+        '2. Record visible Desktop/OK Computer/Kimi Work counters from the app UI.',
+        '3. Run one tiny CLI prompt.',
+        '4. Run one tiny Desktop Work task manually in the visible app.',
+        '5. Compare which counters moved after refresh.',
+        '6. Repeat once to rule out delayed accounting.',
+    ];
+    if (includeCliProbe) {
+        lines.push('', 'CLI probe requested: run a tiny `kimi_chat`/`kimi_analyze` prompt separately and compare visible counters.');
+    }
+    return lines.join('\n');
+}

package/dist/environment.js

@@ -0,0 +1,193 @@
+import { execFile } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const DEFAULT_BASE_URL = 'https://api.kimi.com/coding/v1';
+function getEnv(options) {
+    return options?.env ?? process.env;
+}
+function exists(candidate, options) {
+    return options?.existsSync ? options.existsSync(candidate) : fs.existsSync(candidate);
+}
+function readText(candidate, options) {
+    return (options?.readFileSync ?? fs.readFileSync)(candidate, 'utf-8');
+}
+export function getWindowsHome(env = process.env) {
+    if (env.USERPROFILE)
+        return env.USERPROFILE;
+    if (env.HOMEDRIVE && env.HOMEPATH)
+        return `${env.HOMEDRIVE}${env.HOMEPATH}`;
+    throw new Error('USERPROFILE is not set; Ladder_mcp v1 supports Windows only.');
+}
+function splitWindowsPath(pathValue) {
+    return (pathValue ?? '').split(';').map((part) => part.trim()).filter(Boolean);
+}
+export function findKimiOnPath(env = process.env, existsSync = fs.existsSync) {
+    for (const entry of splitWindowsPath(env.PATH ?? env.Path)) {
+        const exe = path.join(entry, 'kimi.exe');
+        if (existsSync(exe))
+            return exe;
+    }
+    return undefined;
+}
+export function resolveKimiPaths(options) {
+    const env = getEnv(options);
+    const homeDir = getWindowsHome(env);
+    const kimiDir = path.join(homeDir, '.kimi-code');
+    const defaultBinary = path.join(kimiDir, 'bin', 'kimi.exe');
+    const pathBinary = findKimiOnPath(env, (candidate) => exists(candidate, options));
+    const binaryPath = pathBinary ?? (exists(defaultBinary, options) ? defaultBinary : undefined);
+    return {
+        homeDir,
+        kimiDir,
+        configPath: path.join(kimiDir, 'config.toml'),
+        credentialsPath: path.join(kimiDir, 'credentials', 'kimi-code.json'),
+        sessionsDir: path.join(kimiDir, 'sessions'),
+        sessionIndexPath: path.join(kimiDir, 'session_index.jsonl'),
+        legacyDir: path.join(homeDir, '.kimi'),
+        pathBinary,
+        defaultBinary,
+        binaryPath,
+    };
+}
+export function interpolateEnv(value, env = process.env) {
+    return value.replace(/\$\{(\w+)\}/g, (_, name) => env[name] ?? '');
+}
+function readTomlString(raw, key) {
+    const pattern = new RegExp(`^\\s*${key}\\s*=\\s*["']([^"']*)["']`, 'm');
+    return raw.match(pattern)?.[1];
+}
+export function loadApiAuth(options) {
+    const env = getEnv(options);
+    const paths = resolveKimiPaths(options);
+    let apiKey = env.KIMICODE_API_KEY ?? '';
+    let baseUrl = env.KIMI_BASE_URL ?? '';
+    if ((!apiKey || !baseUrl) && exists(paths.configPath, options)) {
+        try {
+            const raw = readText(paths.configPath, options);
+            if (!apiKey)
+                apiKey = readTomlString(raw, 'api_key') ?? '';
+            if (!baseUrl)
+                baseUrl = readTomlString(raw, 'base_url') ?? '';
+            if (!apiKey || !baseUrl) {
+                const providers = parseProviderBlocks(raw);
+                const coding = providers.find((provider) => provider.baseUrl?.includes('/coding'));
+                const chosen = coding ?? providers.find((provider) => provider.apiKey) ?? providers[0];
+                if (chosen) {
+                    if (!apiKey && chosen.apiKey)
+                        apiKey = chosen.apiKey;
+                    if (!baseUrl && chosen.baseUrl)
+                        baseUrl = chosen.baseUrl;
+                }
+            }
+        }
+        catch {
+            // Environment variables are sufficient; malformed config simply means no file-based auth.
+        }
+    }
+    apiKey = interpolateEnv(apiKey, env).trim();
+    baseUrl = interpolateEnv(baseUrl || DEFAULT_BASE_URL, env).trim().replace(/\/$/, '');
+    return apiKey ? { apiKey, baseUrl } : null;
+}
+function parseProviderBlocks(raw) {
+    const providers = [];
+    let current = null;
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const section = trimmed.match(/^\[(.+?)]$/);
+        if (section) {
+            current = section[1].startsWith('providers.') ? {} : null;
+            if (current)
+                providers.push(current);
+            continue;
+        }
+        if (!current)
+            continue;
+        const kv = trimmed.match(/^(\w+)\s*=\s*["']([^"']*)["']/);
+        if (!kv)
+            continue;
+        if (kv[1] === 'api_key')
+            current.apiKey = kv[2];
+        if (kv[1] === 'base_url')
+            current.baseUrl = kv[2];
+    }
+    return providers;
+}
+export function isAuthenticated(options) {
+    const paths = resolveKimiPaths(options);
+    if (!exists(paths.credentialsPath, options))
+        return false;
+    try {
+        const raw = readText(paths.credentialsPath, options);
+        const data = JSON.parse(raw);
+        return Boolean(data.access_token || data.refresh_token || data.id_token || data.token);
+    }
+    catch {
+        return true;
+    }
+}
+export function isKimiInstalled(options) {
+    return Boolean(resolveKimiPaths(options).binaryPath);
+}
+export async function getKimiVersion(binaryPath, env = process.env) {
+    try {
+        const { stdout } = await execFileAsync(binaryPath, ['--version'], {
+            env: buildKimiEnv(env),
+            timeout: 5000,
+            windowsHide: true,
+        });
+        return String(stdout).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function buildKimiEnv(env = process.env) {
+    const paths = resolveKimiPaths({ env });
+    const currentPath = env.PATH ?? env.Path ?? '';
+    const binDir = path.dirname(paths.defaultBinary);
+    const pathName = env.PATH !== undefined ? 'PATH' : 'Path';
+    const nextEnv = { ...env };
+    const entries = splitWindowsPath(currentPath);
+    if (!entries.some((entry) => path.normalize(entry).toLowerCase() === path.normalize(binDir).toLowerCase())) {
+        nextEnv[pathName] = `${binDir}${currentPath ? `;${currentPath}` : ''}`;
+    }
+    return nextEnv;
+}
+export async function getKimiStatus(options) {
+    const paths = resolveKimiPaths(options);
+    const catalogFound = exists(paths.kimiDir, options);
+    const credentialsFound = exists(paths.credentialsPath, options);
+    const configFound = exists(paths.configPath, options);
+    const apiConfigured = loadApiAuth(options) !== null;
+    const installed = Boolean(paths.binaryPath);
+    const authenticated = isAuthenticated(options);
+    let error;
+    if (!catalogFound) {
+        error = exists(paths.legacyDir, options)
+            ? 'Found legacy ~/.kimi but not ~/.kimi-code. Update Kimi CLI to the current kimi-code version.'
+            : 'Kimi catalog ~/.kimi-code was not found. Install or update Kimi Code CLI.';
+    }
+    else if (!installed) {
+        error = 'Kimi CLI binary was not found on PATH or at ~/.kimi-code/bin/kimi.exe.';
+    }
+    else if (!authenticated) {
+        error = 'Kimi CLI is not authenticated. Run: kimi login';
+    }
+    const version = paths.binaryPath ? await getKimiVersion(paths.binaryPath, getEnv(options)) : undefined;
+    return {
+        installed,
+        binPath: paths.binaryPath ?? paths.defaultBinary,
+        version,
+        authenticated,
+        catalogFound,
+        catalogPath: paths.kimiDir,
+        configFound,
+        credentialsFound,
+        apiConfigured,
+        error,
+    };
+}