ladder-mcp 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -4,6 +4,58 @@ 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.2] - 2026-06-28
+
+Security and robustness patch release addressing findings from an external
+adversarial review of `src/`.
+
+### Fixed
+
+- **`isAuthenticated` false-positive on corrupt credentials** (`environment.ts`):
+  a credentials file that exists but is unreadable or invalid JSON was previously
+  reported as authenticated. It now fails closed and returns `false`, satisfying
+  NFR-5 honest diagnostics.
+- **Unbounded `stdout`/`stderr` capture in `runKimi`** (`kimi-runner.ts`): CLI
+  output is now accumulated through `appendCapped` with a hard ceiling
+  (`MAX_CAPTURE_CHARS`), preventing memory exhaustion on runaway output.
+- **Unvalidated `max_output_tokens` and `work_dir`** (`input-validation.ts`):
+  non-finite, zero, or negative token counts are clamped to the default budget;
+  `work_dir` must be an absolute path to an existing directory before Kimi is
+  spawned. Used by `kimi_analyze` and `kimi_resume`.
+
+### Security
+
+- **Arbitrary command persisted to `mcp.json`** (`kimi-mcp-config.ts`):
+  `kimi_generate_mcp_config` now validates `command` against an allow-list of
+  `node`, `npx`, or an absolute path to an existing file. Other values (e.g.
+  `powershell`) are rejected and nothing is written.
+
+## [1.0.1] - 2026-06-28
+
+Bug-fix release. Issues found by exercising all 20 tools live against a real
+Kimi CLI (the mock-only unit tests had missed them).
+
+### Fixed
+
+- **ACP responses lost spaces** (`kimi_chat`): streamed token chunks were each
+  trimmed and newline-joined, so `"Two plus two equals four."` came back as
+  `"Twoplustwoequalsfour."`. Text fragments are now concatenated as-is and only
+  the final string is trimmed. (CLI tools `kimi_analyze`/`kimi_resume` were never
+  affected.)
+- **`kimi_export_session` silently no-op'd** while reporting `ok: true`: when no
+  session id was given, `kimi export` defaults to the most recent session and asks
+  `Export previous session …? [Y/n]` — a prompt that `-y` does not suppress in Kimi
+  CLI 0.20.1, so with stdin closed it exited 0 without writing. The tool now
+  resolves the most recent session id itself and passes it explicitly (skipping the
+  prompt), always passes `-y`, and verifies the output file exists before reporting
+  success.
+
+### Changed
+
+- `kimi_acp_sessions` now accepts `limit` (default 20) and `work_dir` filters,
+  for parity with `kimi_list_sessions`; previously it dumped every ACP session
+  across all projects in one response.
+
 ## [1.0.0] - 2026-06-27
 
 First release. Windows-first MCP bridge for Kimi Code CLI v24, rebuilt in a

package/README.md

@@ -6,7 +6,8 @@ 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**.
+> Status: **v1.0.1** ([npm](https://www.npmjs.com/package/ladder-mcp)).
+> Supported platform is **Windows 11 only**.
 
 ## Requirements
 
@@ -15,40 +16,58 @@ without hardcoded POSIX assumptions.
 - Kimi Code CLI installed (`kimi.exe` on PATH or at `~/.kimi-code/bin/kimi.exe`),
   authenticated (`~/.kimi-code/`)
 
-## Install & build
+## Quick start (from npm)
 
-```bash
-npm install
-npm run build      # compiles src/ -> dist/ (tests excluded)
-```
+You don't need to clone or build — the package is published on npm and your MCP
+client launches it via `npx`.
 
-Quick checks:
+**Claude Code (one command):**
 
 ```bash
-npm test           # vitest (44 tests)
-npm run typecheck  # tsc --noEmit (incl. tests)
-npm run dev        # run the server from source via tsx
+claude mcp add kimi-code -- npx -y ladder-mcp
 ```
 
-## Run as an MCP server
-
-The server speaks MCP over stdio. Point your MCP client at the built entry:
+**Or add it manually to your MCP config:**
 
 ```jsonc
-// e.g. Claude Code MCP config
 {
   "mcpServers": {
     "kimi-code": {
-      "command": "node",
-      "args": ["C:\\path\\to\\Ladder_mcp\\dist\\index.js"]
+      "command": "npx",
+      "args": ["-y", "ladder-mcp"]
     }
   }
 }
 ```
 
+Then in Claude Code run `/mcp` (should show `kimi-code: connected`) and call
+`kimi_status` to confirm the environment is detected.
+
+> The server speaks MCP over **stdio**: it is launched and managed by the client,
+> not run by hand. Running `npx ladder-mcp` directly will appear to "hang" — that
+> is the server correctly waiting for a client. Exit with Ctrl+C.
+
+Prefer a global install? `npm install -g ladder-mcp`, then use `ladder-mcp` as the
+command instead of `npx -y ladder-mcp`.
+
 To let Kimi Code itself host this server, use the `kimi_generate_mcp_config`
 tool to produce/merge a `.kimi-code/mcp.json` entry.
 
+## Build from source (contributors)
+
+```bash
+npm install
+npm run build      # compiles src/ -> dist/ (tests excluded)
+```
+
+Quick checks:
+
+```bash
+npm test           # vitest (50 tests)
+npm run typecheck  # tsc --noEmit (incl. tests)
+npm run dev        # run the server from source via tsx
+```
+
 ## Tools
 
 **Core (v1)** — `kimi_analyze`, `kimi_query`, `kimi_verify`, `kimi_resume`,

package/dist/environment.js

@@ -126,7 +126,10 @@ export function isAuthenticated(options) {
         return Boolean(data.access_token || data.refresh_token || data.id_token || data.token);
     }
     catch {
-        return true;
+        // A corrupt or unreadable credentials file is NOT proof of authentication.
+        // Returning true here produced a false-positive "authenticated" status that
+        // misled diagnostics (NFR-5). Fail closed.
+        return false;
     }
 }
 export function isKimiInstalled(options) {

package/dist/index.js

@@ -2,6 +2,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import { maxChars, validateWorkDir } from './input-validation.js';
 import { getKimiStatus } from './environment.js';
 import { runKimiApi, isApiConfigured } from './kimi-api.js';
 import { runKimi } from './kimi-runner.js';
@@ -13,9 +14,8 @@ import { generateMcpConfig } from './kimi-mcp-config.js';
 import { buildBudgetProbeGuide, getDesktopStatus } from './desktop-work.js';
 const server = new McpServer({
     name: 'kimi-code',
-    version: '1.0.0',
+    version: '1.0.2',
 });
-const DEFAULT_MAX_OUTPUT_CHARS = 60_000;
 const FORMAT_INSTRUCTIONS = {
     summary: `
 OUTPUT FORMAT CONSTRAINTS:
@@ -42,9 +42,6 @@ IMPORTANT: Your response will be consumed by another AI model with limited conte
 function wrapPrompt(prompt, detailLevel) {
     return `${prompt}\n${FORMAT_INSTRUCTIONS[detailLevel]}\n${AI_CONSUMER_NOTICE}`;
 }
-function maxChars(maxOutputTokens) {
-    return maxOutputTokens ? maxOutputTokens * 4 : DEFAULT_MAX_OUTPUT_CHARS;
-}
 function textResponse(text, isError = false) {
     return { content: [{ type: 'text', text }], isError };
 }
@@ -60,6 +57,9 @@ server.tool('kimi_analyze', 'Send a prompt to Kimi Code for codebase analysis. D
     max_output_tokens: z.number().optional(),
     include_thinking: z.boolean().optional(),
 }, async ({ prompt, work_dir, session_id, new_session, detail_level, max_output_tokens, include_thinking }) => {
+    const workDirError = validateWorkDir(work_dir);
+    if (workDirError)
+        return textResponse(`Error: ${workDirError}`, true);
     const result = await runKimi({
         prompt: wrapPrompt(prompt, detail_level ?? 'normal'),
         workDir: work_dir,
@@ -107,6 +107,9 @@ server.tool('kimi_resume', 'Resume an explicit Kimi Code session with a new prom
     max_output_tokens: z.number().optional(),
     include_thinking: z.boolean().optional(),
 }, async ({ session_id, prompt, work_dir, detail_level, max_output_tokens, include_thinking }) => {
+    const workDirError = validateWorkDir(work_dir);
+    if (workDirError)
+        return textResponse(`Error: ${workDirError}`, true);
     const result = await runKimi({
         prompt: wrapPrompt(prompt, detail_level ?? 'normal'),
         workDir: work_dir,
@@ -219,8 +222,11 @@ server.tool('kimi_chat', 'Send a prompt through Kimi ACP over stdio. Set backgro
     });
     return textResponse(JSON.stringify(result, null, 2), !result.ok);
 });
-server.tool('kimi_acp_sessions', 'List Kimi ACP sessions through `session/list`.', {}, async () => {
-    const result = await listAcpSessions();
+server.tool('kimi_acp_sessions', 'List Kimi ACP sessions through `session/list`.', {
+    limit: z.number().int().positive().optional(),
+    work_dir: z.string().optional(),
+}, async ({ limit, work_dir }) => {
+    const result = await listAcpSessions({ limit, workDir: work_dir });
     return textResponse(result.ok ? result.text : `Error: ${result.error}`, !result.ok);
 });
 server.tool('kimi_cancel', 'Cancel an active Ladder task by task_id or a Kimi ACP session by session_id.', {

package/dist/input-validation.js

@@ -0,0 +1,29 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export const DEFAULT_MAX_OUTPUT_CHARS = 60_000;
+// Convert an untrusted max_output_tokens into a character budget. NaN/Infinity/zero/
+// negative/non-integer would otherwise produce a nonsensical budget (e.g. NaN) handed
+// to truncation, so clamp those to the default.
+export function maxChars(maxOutputTokens) {
+    if (typeof maxOutputTokens !== 'number' || !Number.isFinite(maxOutputTokens) || maxOutputTokens <= 0) {
+        return DEFAULT_MAX_OUTPUT_CHARS;
+    }
+    return Math.floor(maxOutputTokens) * 4;
+}
+// Reject a work_dir before spawning Kimi: a relative or non-existent directory would
+// otherwise be passed to the CLI as cwd and fail opaquely. Returns an error string when
+// invalid, or undefined when the path is an existing absolute directory.
+export function validateWorkDir(workDir) {
+    if (!path.isAbsolute(workDir))
+        return 'work_dir must be an absolute path.';
+    let stat;
+    try {
+        stat = fs.statSync(workDir);
+    }
+    catch {
+        return `work_dir does not exist: ${workDir}`;
+    }
+    if (!stat.isDirectory())
+        return `work_dir is not a directory: ${workDir}`;
+    return undefined;
+}

package/dist/kimi-mcp-config.js

@@ -44,6 +44,19 @@ function assertWritableProjectTarget(projectDir) {
         throw new Error('Refusing to write MCP config under read-only kimi-code-mcp reference tree.');
     }
 }
+const ALLOWED_BARE_COMMANDS = new Set(['node', 'npx']);
+// Constrain the launcher written into mcp.json. Without this, an arbitrary `command`
+// (e.g. "powershell") would be persisted and later executed when Kimi loads the
+// server config. Allow only the known Node launchers by bare name, or an absolute
+// path to an existing file (a vetted local binary).
+function assertSafeCommand(command) {
+    const value = command.trim();
+    if (ALLOWED_BARE_COMMANDS.has(value))
+        return;
+    if (path.isAbsolute(value) && fs.existsSync(value) && fs.statSync(value).isFile())
+        return;
+    throw new Error(`command must be one of [${[...ALLOWED_BARE_COMMANDS].join(', ')}] or an absolute path to an existing file; got "${command}".`);
+}
 function readMcpServers(existing) {
     const value = existing.mcpServers;
     if (value === undefined || value === null)
@@ -66,8 +79,10 @@ export function generateMcpConfig(options = {}) {
         throw new Error('server_name must contain only letters, digits, underscores, and hyphens.');
     }
     const defaults = defaultServerCommand();
+    const command = options.command ?? defaults.command;
+    assertSafeCommand(command);
     const serverConfig = {
-        command: options.command ?? defaults.command,
+        command,
         args: options.args ?? defaults.args,
         env: {},
     };

package/dist/kimi-runner.js

@@ -1,6 +1,16 @@
 import { spawn } from 'node:child_process';
 import * as path from 'node:path';
 import { buildKimiEnv, resolveKimiPaths } from './environment.js';
+const MAX_CAPTURE_CHARS = 16 * 1024 * 1024;
+// Append to a captured stream while enforcing a hard ceiling so a runaway CLI cannot
+// grow the buffer without bound. Once the cap is reached, further data is dropped (the
+// stream is still drained by Node, just not stored).
+export function appendCapped(current, addition, max) {
+    if (current.length >= max)
+        return current;
+    const next = current + addition;
+    return next.length > max ? next.slice(0, max) : next;
+}
 export function buildKimiArgs(config) {
     const args = ['-p', config.prompt, '--output-format', 'stream-json'];
     if (config.sessionId) {
@@ -120,8 +130,8 @@ export function runKimi(config) {
             killProcessTree(proc.pid);
             finish({ ok: false, text: '', error: `Kimi timed out after ${Math.round(timeoutMs / 1000)}s` });
         }, timeoutMs);
-        proc.stdout?.on('data', (chunk) => { stdout += chunk.toString('utf-8'); });
-        proc.stderr?.on('data', (chunk) => { stderr += chunk.toString('utf-8'); });
+        proc.stdout?.on('data', (chunk) => { stdout = appendCapped(stdout, chunk.toString('utf-8'), MAX_CAPTURE_CHARS); });
+        proc.stderr?.on('data', (chunk) => { stderr = appendCapped(stderr, chunk.toString('utf-8'), MAX_CAPTURE_CHARS); });
         proc.on('error', (err) => {
             finish({ ok: false, text: '', error: err instanceof Error ? err.message : String(err) });
         });

package/dist/transports/acp.js

@@ -153,7 +153,11 @@ function extractTextDeep(value) {
     return [...direct, ...nested];
 }
 export function extractAcpText(value) {
-    return extractTextDeep(value).map((part) => part.trim()).filter(Boolean).join('\n');
+    // Concatenate text fragments as-is. Kimi streams the answer as many small
+    // agent_message_chunk tokens (e.g. "Two", " plus", " two"); trimming each
+    // fragment or joining on newlines would drop the spaces between tokens and
+    // run words together. Callers trim the final assembled string.
+    return extractTextDeep(value).join('');
 }
 // Keep the trailing portion of `text` within a UTF-8 *byte* budget. Slicing by
 // String length (UTF-16 code units) under-counts multibyte characters, so the
@@ -217,7 +221,7 @@ export class AcpClient extends EventEmitter {
     async initialize() {
         return this.request('initialize', {
             protocolVersion: 1,
-            clientInfo: { name: 'ladder-mcp', version: '1.0.0' },
+            clientInfo: { name: 'ladder-mcp', version: '1.0.2' },
             capabilities: {},
         }, 30_000);
     }
@@ -357,7 +361,9 @@ export async function runAcpPrompt(options) {
             sessionId = extractSessionId(await client.newSession(options.workDir));
         }
         const result = await client.prompt(sessionId, options.prompt, options.workDir);
-        let text = extractAcpText(result) || client.getUpdateText();
+        // extractAcpText no longer trims fragments (to preserve inter-token spaces),
+        // so trim the fully assembled string here. getUpdateText already trims.
+        let text = extractAcpText(result).trim() || client.getUpdateText();
         if (!text) {
             try {
                 text = JSON.stringify(result, null, 2);
@@ -385,11 +391,28 @@ export async function runAcpPrompt(options) {
         client.close();
     }
 }
-export async function listAcpSessions() {
+const DEFAULT_ACP_SESSION_LIMIT = 20;
+function normalizePath(value) {
+    return value.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+}
+export async function listAcpSessions(options = {}) {
     const client = new AcpClient(60_000);
     try {
         await client.initialize();
         const result = await client.listSessions();
+        // Filter by working directory and cap the count for parity with kimi_list_sessions;
+        // session/list otherwise returns every ACP session across all projects in one blob.
+        const sessions = result?.sessions;
+        if (Array.isArray(sessions)) {
+            let filtered = sessions;
+            if (options.workDir) {
+                const target = normalizePath(options.workDir);
+                filtered = filtered.filter((s) => typeof s?.cwd === 'string' && normalizePath(s.cwd) === target);
+            }
+            const limit = options.limit ?? DEFAULT_ACP_SESSION_LIMIT;
+            const limited = limit > 0 ? filtered.slice(0, limit) : filtered;
+            return { ok: true, text: JSON.stringify({ sessions: limited, total: filtered.length }, null, 2) };
+        }
         return { ok: true, text: JSON.stringify(result, null, 2) };
     }
     catch (error) {

package/dist/transports/cli-admin.js

@@ -3,6 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { promisify } from 'node:util';
 import { buildKimiEnv, getKimiStatus, resolveKimiPaths } from '../environment.js';
+import { listSessions } from '../session-store.js';
 const execFileAsync = promisify(execFile);
 const ADMIN_TIMEOUT_MS = 30_000;
 // Quote a single argument for the human-readable preview command. This string is
@@ -76,8 +77,12 @@ export function buildExportArgs(options) {
     if (options.sessionId)
         args.push(options.sessionId);
     args.push('-o', options.outputPath);
-    if (options.overwriteExisting === true)
-        args.push('-y');
+    // Always auto-confirm. `kimi export` prompts "Export previous session …? [Y/n]"
+    // even for a brand-new path; since we close stdin, that prompt would get EOF and
+    // the export would silently no-op while still exiting 0. Overwrite safety is
+    // enforced by our own pre-check (assertSafeOutputPath + statSync + overwrite_existing),
+    // so unconditionally passing -y is safe.
+    args.push('-y');
     if (options.includeGlobalLog !== true)
         args.push('--no-include-global-log');
     return args;
@@ -179,6 +184,18 @@ export async function exportKimiSession(options) {
             error: error instanceof Error ? error.message : String(error),
         };
     }
+    // Resolve an explicit session id ourselves when the caller omitted one. `kimi export`
+    // otherwise defaults to "the most recent session" and asks "Export previous session …?
+    // [Y/n]" — a prompt that `-y` does NOT suppress in Kimi CLI 0.20.1, so with stdin closed
+    // it hangs/aborts and writes nothing. Passing an explicit id skips that prompt entirely.
+    let sessionId = options.sessionId;
+    if (!sessionId) {
+        const recent = listSessions({ limit: 1 })[0];
+        if (!recent) {
+            return { ok: false, stdout: '', stderr: '', error: 'No Kimi session found to export. Provide an explicit session_id.' };
+        }
+        sessionId = recent.id;
+    }
     const outputPath = path.resolve(options.outputPath);
     let existingStat;
     try {
@@ -207,7 +224,18 @@ export async function exportKimiSession(options) {
             };
         }
     }
-    return runKimiCommand(buildExportArgs({ ...options, outputPath }), 120_000);
+    const result = await runKimiCommand(buildExportArgs({ ...options, sessionId, outputPath }), 120_000);
+    // The CLI can exit 0 without producing the archive (e.g. a declined/aborted prompt).
+    // Verify the file actually exists so we never report success for a no-op export.
+    if (result.ok && !fs.existsSync(outputPath)) {
+        return {
+            ok: false,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            error: 'Kimi export exited without creating the output file. No archive was written.',
+        };
+    }
+    return result;
 }
 export function visualizeSession(options) {
     const binary = requireBinary();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ladder-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Windows-first MCP bridge for Kimi Code CLI v24",
   "license": "MIT",
   "type": "module",
@@ -19,7 +19,8 @@
     "build": "tsc -p tsconfig.build.json",
     "start": "node dist/index.js",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
   },
   "engines": {
     "node": ">=18.0.0"