@lemonbeijing/lemonclaw-mcp-service 0.1.1

package/README.md

@@ -0,0 +1,37 @@
+# LemonClaw MCP Service
+
+Local STDIO MCP adapter for the existing LemonClaw CLI and portable Runtime. It does not copy business actions or move authentication/account state: the MCP process runs as the current operating-system user and reuses the same Runtime, token store, account context, documents, downloads, and local invoice files.
+
+Requires Node.js 20 or newer. The packaged LemonClaw CLI dependency installs and updates the portable Runtime through its existing launcher lifecycle.
+
+## Run from this repository
+
+```text
+npm install
+node bin/lemonclaw-mcp.js
+```
+
+Example MCP host configuration:
+
+```json
+{
+  "mcpServers": {
+    "lemonclaw": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["D:/VSProject/lemonscmskills/mcp-service/bin/lemonclaw-mcp.js"]
+    }
+  }
+}
+```
+
+After publication, the command can be changed to `npx -y @lemonbeijing/lemonclaw-mcp-service`.
+
+## Tool groups
+
+- Authentication: `lemon_auth_status`, `lemon_auth_save_api_key`, `lemon_auth_clear`
+- Account context: `lemon_account_current`, `lemon_account_list`, `lemon_account_switch`, `lemon_account_select`, `lemon_account_clear`
+- ACC/SCM/ERP actions: `lemon_action_search`, `lemon_action_show`, `lemon_action_read_doc`, `lemon_action_run`
+- Independent invoicing: `lemon_invoice_read_doc`, `lemon_invoice_api`, `lemon_invoice_run_helper`
+
+`stdout` is reserved for MCP JSON-RPC. CLI and Runtime output is captured and returned as MCP Tool content; service diagnostics use `stderr` only.

package/bin/lemonclaw-mcp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../src/index.js";

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@lemonbeijing/lemonclaw-mcp-service",
+  "version": "0.1.1",
+  "description": "Local stdio MCP adapter for LemonClaw CLI and Runtime.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "lemonclaw-mcp": "bin/lemonclaw-mcp.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "start": "node bin/lemonclaw-mcp.js"
+  },
+  "dependencies": {
+    "@lemonbeijing/lemonclaw-cli": "1.0.5",
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/cli-runner.js

@@ -0,0 +1,29 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { runProcess } from "./process-runner.js";
+
+const require = createRequire(import.meta.url);
+
+export function resolveCliLauncher(env = process.env) {
+  const override = String(env.LEMONCLAW_CLI_LAUNCHER || "").trim();
+  if (override) return path.resolve(override);
+
+  const packageJson = require.resolve("@lemonbeijing/lemonclaw-cli/package.json");
+  return path.join(path.dirname(packageJson), "dist", "lemonclaw-cli.cjs");
+}
+
+export function createCliRunner(options = {}) {
+  const launcherPath = options.launcherPath || resolveCliLauncher(options.env || process.env);
+  const nodeExecutable = options.nodeExecutable || process.execPath;
+  const baseEnv = options.env || process.env;
+
+  return async function runCli(args, runOptions = {}) {
+    return runProcess(nodeExecutable, [launcherPath, ...args], {
+      stdin: runOptions.stdin,
+      timeoutMs: runOptions.timeoutMs,
+      maxOutputBytes: runOptions.maxOutputBytes,
+      env: runOptions.env || baseEnv,
+    });
+  };
+}

package/src/index.js

@@ -0,0 +1,5 @@
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+
+import { createLemonClawServer } from "./server.js";
+
+serveStdio(() => createLemonClawServer());

package/src/invoice-runtime.js

@@ -0,0 +1,156 @@
+import { mkdtemp, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { runProcess } from "./process-runner.js";
+import {
+  isPathWithin,
+  requireFile,
+  resolveRuntimeEnvironment,
+} from "./runtime-environment.js";
+
+const INVOICE_HELPERS = Object.freeze({
+  customer_service_link: "scripts/customer_service_link.py",
+  preview_server: "scripts/preview_http_server.py",
+  query_customer: "scripts/query_customer.py",
+  read_excel_simple: "scripts/read_excel_simple.py",
+  read_excel_utf8: "scripts/read_excel_utf8.py",
+  render_preview: "scripts/render_invoice_preview_switchable.py",
+  validate_json: "scripts/validate_json.py",
+});
+
+const API_ARGUMENT_FLAGS = Object.freeze({
+  eiscid: "--eiscid",
+  filter_word: "--filter-word",
+  company_name: "--company-name",
+  company_id: "--company-id",
+  personal_account: "--personal-account",
+  uscic: "--uscic",
+  auth_company_id: "--auth-company-id",
+  company_detail_id: "--company-detail-id",
+  api_key_last_four: "--api-key-last-four",
+  ai_tool: "--ai-tool",
+  model: "--model",
+  feedback_contact: "--feedback-contact",
+  feedback_version: "--feedback-version",
+  feedback_type: "--feedback-type",
+  feedback_files: "--feedback-files",
+  feedback_text: "--feedback-text",
+  message_id: "--message-id",
+  context: "--context",
+  upload_file_path: "--upload-file-path",
+});
+
+export async function resolveInvoiceRuntime(runCli) {
+  const runtime = await resolveRuntimeEnvironment(runCli);
+  const invoiceRoot = path.join(runtime.skillRoot, "invoice");
+  const invoiceInfo = await stat(invoiceRoot).catch(() => null);
+  if (!invoiceInfo?.isDirectory()) {
+    throw new Error("Installed Runtime does not contain the invoice workflow.");
+  }
+
+  return {
+    ...runtime,
+    invoiceRoot,
+  };
+}
+
+export async function readInvoiceDocument(runCli, relativePath) {
+  const runtime = await resolveInvoiceRuntime(runCli);
+  const requested = String(relativePath || "").replaceAll("\\", "/");
+  if (!requested || path.isAbsolute(requested) || requested.split("/").includes("..")) {
+    throw new Error("Invoice document path must be relative to the invoice directory.");
+  }
+  if (![".md", ".json", ".txt"].includes(path.extname(requested).toLowerCase())) {
+    throw new Error("Invoice document must be Markdown, JSON, or text.");
+  }
+
+  const rootReal = await realpath(runtime.invoiceRoot);
+  const targetReal = await realpath(path.join(runtime.invoiceRoot, requested));
+  if (!isPathWithin(rootReal, targetReal)) {
+    throw new Error("Invoice document path escapes the invoice directory.");
+  }
+  const content = await readFile(targetReal, "utf8");
+  return content.replace(/^\uFEFF/, "");
+}
+
+function requireValue(args, key, operation) {
+  const value = args[key];
+  if (value === undefined || value === null || String(value).trim() === "") {
+    throw new Error(`${operation} requires ${key}.`);
+  }
+}
+
+function appendApiArguments(command, args) {
+  for (const [key, flag] of Object.entries(API_ARGUMENT_FLAGS)) {
+    const value = args[key];
+    if (value !== undefined && value !== null && String(value) !== "") {
+      command.push(flag, String(value));
+    }
+  }
+}
+
+async function withPayloadPath(args, callback) {
+  if (args.payload !== undefined && args.payload_path) {
+    throw new Error("Use either payload or payload_path, not both.");
+  }
+  if (args.payload === undefined) return callback(args.payload_path || null);
+
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "lemonclaw-mcp-"));
+  const payloadPath = path.join(tempRoot, "payload.json");
+  try {
+    await writeFile(payloadPath, JSON.stringify(args.payload), "utf8");
+    return await callback(payloadPath);
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+export async function runInvoiceApi(runCli, args) {
+  const runtime = await resolveInvoiceRuntime(runCli);
+  const script = path.join(runtime.invoiceRoot, "assets", "lemon_acc_api.py");
+  await requireFile(script, "Installed Runtime invoice API script is missing.");
+
+  const operation = String(args.operation || "");
+  if (operation === "SkillInvoiceIssue") {
+    if (args.user_confirmed !== true) {
+      throw new Error("SkillInvoiceIssue requires explicit user confirmation.");
+    }
+    for (const key of ["eiscid", "api_key_last_four", "ai_tool", "model"]) {
+      requireValue(args, key, operation);
+    }
+    if (args.payload === undefined && !args.payload_path) {
+      throw new Error("SkillInvoiceIssue requires payload or payload_path.");
+    }
+  }
+
+  return withPayloadPath(args, async (payloadPath) => {
+    const command = [script, "--action", operation];
+    appendApiArguments(command, args);
+    if (payloadPath) command.push("--payload-path", String(payloadPath));
+    if (operation === "SkillInvoiceIssue") command.push("--issue-confirm", "1");
+    return runProcess(runtime.python, command, {
+      cwd: runtime.runtimeRoot,
+      env: runtime.env,
+      timeoutMs: Number(args.timeout_seconds || 120) * 1000,
+    });
+  });
+}
+
+export async function runInvoiceHelper(runCli, args) {
+  const runtime = await resolveInvoiceRuntime(runCli);
+  const relativeScript = INVOICE_HELPERS[String(args.operation || "")];
+  if (!relativeScript) throw new Error("Unsupported invoice helper operation.");
+
+  const script = path.join(runtime.invoiceRoot, relativeScript);
+  await requireFile(script, "Installed Runtime invoice helper script is missing.");
+  const commandArgs = Array.isArray(args.arguments) ? args.arguments.map(String) : [];
+  return runProcess(runtime.python, [script, ...commandArgs], {
+    cwd: runtime.runtimeRoot,
+    env: runtime.env,
+    stdin: args.stdin,
+    timeoutMs: Number(args.timeout_seconds || 120) * 1000,
+  });
+}
+
+export const invoiceHelperNames = Object.freeze(Object.keys(INVOICE_HELPERS));

package/src/process-runner.js

@@ -0,0 +1,86 @@
+import { spawn } from "node:child_process";
+
+// Stay below the common 10 MiB STDIO message limit after JSON-RPC encoding.
+const DEFAULT_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+
+export function runProcess(command, args, options = {}) {
+  const timeoutMs = Math.max(1, Number(options.timeoutMs || 120_000));
+  const maxOutputBytes = Math.max(
+    1024,
+    Number(options.maxOutputBytes || DEFAULT_MAX_OUTPUT_BYTES),
+  );
+
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env || process.env,
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+    });
+
+    const stdout = [];
+    const stderr = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let spawnError;
+    let timedOut = false;
+    let outputLimitExceeded = false;
+    let settled = false;
+
+    const stop = () => {
+      if (!child.killed) {
+        child.kill("SIGTERM");
+      }
+    };
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      stop();
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes <= maxOutputBytes) {
+        stdout.push(chunk);
+      } else {
+        outputLimitExceeded = true;
+        stop();
+      }
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderrBytes += chunk.length;
+      if (stderrBytes <= maxOutputBytes) {
+        stderr.push(chunk);
+      } else {
+        outputLimitExceeded = true;
+        stop();
+      }
+    });
+
+    child.once("error", (error) => {
+      spawnError = error;
+    });
+
+    child.once("close", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({
+        code: Number.isInteger(code) ? code : 1,
+        signal: signal || null,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+        timedOut,
+        outputLimitExceeded,
+        spawnError,
+      });
+    });
+
+    child.stdin.on("error", () => {
+      // The child may reject input and exit before stdin is fully written.
+    });
+    child.stdin.end(options.stdin === undefined ? "" : String(options.stdin));
+  });
+}

package/src/runtime-auth.js

@@ -0,0 +1,43 @@
+import { runProcess } from "./process-runner.js";
+import { resolveRuntimeEnvironment } from "./runtime-environment.js";
+
+const AUTH_PROGRAM = String.raw`
+import json
+import sys
+
+operation = sys.argv[1]
+skill_root = sys.argv[2]
+sys.path.insert(0, skill_root)
+from auth import auth as lemon_auth
+
+if operation == "status":
+    result = lemon_auth.auth_status()
+elif operation == "save_api_key":
+    result = lemon_auth.save_api_key(sys.stdin.read())
+elif operation == "clear":
+    result = lemon_auth.clear_auth()
+else:
+    raise SystemExit("unsupported auth operation")
+
+print(json.dumps(result, ensure_ascii=False, separators=(",", ":")))
+`;
+
+export async function runRuntimeAuth(runCli, args, options = {}) {
+  const resolveRuntime = options.resolveRuntime || resolveRuntimeEnvironment;
+  const run = options.run || runProcess;
+  const runtime = await resolveRuntime(runCli);
+  const operation = String(args.operation || "");
+  if (!["status", "save_api_key", "clear"].includes(operation)) {
+    throw new Error("Unsupported Runtime authentication operation.");
+  }
+  if (operation === "save_api_key" && !String(args.api_key || "").trim()) {
+    throw new Error("API Key is required.");
+  }
+
+  return run(runtime.python, ["-c", AUTH_PROGRAM, operation, runtime.skillRoot], {
+    cwd: runtime.runtimeRoot,
+    env: runtime.env,
+    stdin: operation === "save_api_key" ? String(args.api_key) : undefined,
+    timeoutMs: Math.max(1, Number(args.timeout_seconds || 60)) * 1000,
+  });
+}

package/src/runtime-environment.js

@@ -0,0 +1,51 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+export function isPathWithin(root, candidate) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedCandidate = path.resolve(candidate);
+  const normalize = (value) => (process.platform === "win32" ? value.toLowerCase() : value);
+  return normalize(resolvedCandidate).startsWith(normalize(`${resolvedRoot}${path.sep}`));
+}
+
+export async function requireFile(filePath, message) {
+  const info = await stat(filePath).catch(() => null);
+  if (!info?.isFile()) throw new Error(message);
+}
+
+export async function resolveRuntimeEnvironment(runCli) {
+  const discovery = await runCli(["skill-root", "--check"], { timeoutMs: 120_000 });
+  if (discovery.code !== 0 || discovery.timedOut || discovery.spawnError) {
+    const detail = String(discovery.stdout || discovery.stderr || "runtime discovery failed").trim();
+    throw new Error(detail.slice(0, 2000));
+  }
+
+  const skillRoot = path.resolve(String(discovery.stdout || "").trim());
+  const runtimeRoot = path.resolve(skillRoot, "..", "..", "..");
+  const metadataPath = path.join(runtimeRoot, "runtime.json");
+  const metadata = JSON.parse(await readFile(metadataPath, "utf8"));
+  const pythonRelative = String(metadata.pythonPath || "").replaceAll("/", path.sep);
+  const python = path.resolve(runtimeRoot, pythonRelative);
+
+  if (!isPathWithin(runtimeRoot, python)) {
+    throw new Error("Installed Runtime Python path escapes the Runtime directory.");
+  }
+  await requireFile(python, "Installed Runtime Python executable is missing.");
+
+  const appRoot = path.join(runtimeRoot, "app");
+  return {
+    skillRoot,
+    runtimeRoot,
+    python,
+    env: {
+      ...process.env,
+      PYTHONUTF8: "1",
+      PYTHONIOENCODING: "utf-8",
+      PYTHONNOUSERSITE: "1",
+      PYTHONDONTWRITEBYTECODE: "1",
+      PYTHONPATH: appRoot,
+      SSL_CERT_FILE: path.join(appRoot, "certifi", "cacert.pem"),
+      LEMONCLAW_RUNTIME_ROOT: runtimeRoot,
+    },
+  };
+}

package/src/server.js

@@ -0,0 +1,516 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+
+import { createCliRunner } from "./cli-runner.js";
+import {
+  invoiceHelperNames,
+  readInvoiceDocument,
+  runInvoiceApi,
+  runInvoiceHelper,
+} from "./invoice-runtime.js";
+import { runRuntimeAuth } from "./runtime-auth.js";
+import { cliToolResult, toolError } from "./tool-result.js";
+
+const productSchema = z.enum(["acc", "scm", "erp"]);
+const timeoutSchema = z.number().int().min(1).max(600).default(120);
+const optionalText = z.string().min(1).optional();
+
+const readOnlyAnnotations = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true,
+};
+
+function commandTimeout(seconds) {
+  return (Number(seconds || 120) + 15) * 1000;
+}
+
+function addFlag(command, flag, value) {
+  if (value !== undefined && value !== null && String(value) !== "") {
+    command.push(flag, String(value));
+  }
+}
+
+function registerCliTool(server, runCli, name, config, build) {
+  server.registerTool(name, config, async (args) => {
+    try {
+      const invocation = build(args);
+      const result = await runCli(invocation.command, {
+        stdin: invocation.stdin,
+        timeoutMs: invocation.timeoutMs,
+      });
+      return cliToolResult(result, invocation.resultOptions);
+    } catch (error) {
+      return toolError(error);
+    }
+  });
+}
+
+export function createLemonClawServer(options = {}) {
+  const runCli = options.runCli || createCliRunner(options.cliOptions);
+  const server = new McpServer(
+    { name: "lemonclaw", version: "0.1.1" },
+    {
+      instructions:
+        "Use standard API Key authentication: check lemon_auth_status and, when unavailable, request the user's API Key and pass it only to lemon_auth_save_api_key. Never use browser or device-flow authentication. For ACC, SCM, and ERP, determine the product and account first, then use lemon_action_search, lemon_action_show, read every document exposed by show with lemon_action_read_doc, and only then call lemon_action_run. Never guess action parameters. Independent invoicing uses only the lemon_invoice_* tools and requires its Runtime documents.",
+    },
+  );
+
+  server.registerTool(
+    "lemon_auth_status",
+    {
+      title: "Check LemonClaw API Key authentication",
+      description:
+        "Check whether the current user's standard LemonClaw API Key can provide a token. This uses the Runtime authentication helper and never returns the API Key or token.",
+      inputSchema: z.object({
+        timeout_seconds: z.number().int().min(1).max(120).default(60),
+      }),
+      annotations: readOnlyAnnotations,
+    },
+    async (args) => {
+      try {
+        return cliToolResult(await runRuntimeAuth(runCli, { ...args, operation: "status" }));
+      } catch (error) {
+        return toolError(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "lemon_auth_save_api_key",
+    {
+      title: "Save LemonClaw API Key",
+      description:
+        "Save an API Key with the standard Runtime authentication helper for the current operating-system user. The key is sent to Runtime through stdin, is not placed in process arguments, and is never returned.",
+      inputSchema: z.object({
+        api_key: z.string().min(1),
+        timeout_seconds: z.number().int().min(1).max(120).default(60),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      try {
+        return cliToolResult(
+          await runRuntimeAuth(runCli, { ...args, operation: "save_api_key" }),
+        );
+      } catch (error) {
+        return toolError(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "lemon_auth_clear",
+    {
+      title: "Clear LemonClaw API Key authentication",
+      description:
+        "Clear the current user's standard LemonClaw API Key and token cache without clearing account context. Use only when the user explicitly requests it.",
+      inputSchema: z.object({
+        timeout_seconds: z.number().int().min(1).max(120).default(60),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      try {
+        return cliToolResult(await runRuntimeAuth(runCli, { ...args, operation: "clear" }));
+      } catch (error) {
+        return toolError(error);
+      }
+    },
+  );
+
+  registerCliTool(
+    server,
+    runCli,
+    "lemon_account_current",
+    {
+      title: "Get current Lemon account context",
+      description:
+        "Read the current product and selected account set from the existing local account context. Call this before ACC, SCM, or ERP business actions.",
+      inputSchema: z.object({ timeout_seconds: timeoutSchema }),
+      annotations: readOnlyAnnotations,
+    },
+    (args) => ({
+      command: ["account", "current", "--timeout", String(args.timeout_seconds)],
+      timeoutMs: commandTimeout(args.timeout_seconds),
+    }),
+  );
+
+  registerCliTool(
+    server,
+    runCli,
+    "lemon_account_list",
+    {
+      title: "List Lemon account sets",
+      description:
+        "List account-set candidates and cache their returned indexes for a later lemon_account_select call. Use only when switch has no usable candidates or the user asks to list accounts.",
+      inputSchema: z.object({
+        dry_run: z.boolean().default(false),
+        timeout_seconds: timeoutSchema,
+      }),
+      annotations: readOnlyAnnotations,
+    },
+    (args) => {
+      const command = ["account", "list", "--timeout", String(args.timeout_seconds)];
+      if (args.dry_run) command.push("--dry-run");
+      return { command, timeoutMs: commandTimeout(args.timeout_seconds) };
+    },
+  );
+
+  registerCliTool(
+    server,
+    runCli,
+    "lemon_account_switch",
+    {
+      title: "Switch Lemon account context",
+      description:
+        "Match a product or account clue and switch when unique. If candidates are returned, present them to the user and select from that same candidate set; do not refresh it with account list.",
+      inputSchema: z.object({
+        query: optionalText,
+        product: productSchema.optional(),
+        asid: optionalText,
+        serviceid: optionalText,
+        name: optionalText,
+        edition: optionalText,
+        dry_run: z.boolean().default(false),
+        timeout_seconds: timeoutSchema,
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    (args) => {
+      const command = ["account", "switch"];
+      if (args.query) command.push(args.query);
+      addFlag(command, "--product", args.product);
+      addFlag(command, "--asid", args.asid);
+      addFlag(command, "--serviceid", args.serviceid);
+      addFlag(command, "--name", args.name);
+      addFlag(command, "--edition", args.edition);
+      if (args.dry_run) command.push("--dry-run");
+      command.push("--timeout", String(args.timeout_seconds));
+      return { command, timeoutMs: commandTimeout(args.timeout_seconds) };
+    },
+  );
+
+  registerCliTool(
+    server,
+    runCli,
+    "lemon_account_select",
+    {
+      title: "Select a Lemon account set",
+      description:
+        "Select from the candidates cached by the most recent account switch or list. Prefer the returned index. Never invent an index or silently choose between duplicate names.",
+      inputSchema: z
+        .object({
+          index: z.number().int().positive().optional(),
+          product: productSchema.optional(),
+          asid: optionalText,
+          serviceid: optionalText,
+          name: optionalText,
+          timeout_seconds: timeoutSchema,
+        })
+        .refine(
+          (value) => value.index !== undefined || value.asid || value.serviceid || value.name,
+          "Provide index, asid, serviceid, or name from the latest candidate set.",
+        ),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    (args) => {
+      const command = ["account", "select"];
+      addFlag(command, "--index", args.index);
+      addFlag(command, "--product", args.product);
+      addFlag(command, "--asid", args.asid);
+      addFlag(command, "--serviceid", args.serviceid);
+      addFlag(command, "--name", args.name);
+      command.push("--timeout", String(args.timeout_seconds));
+      return { command, timeoutMs: commandTimeout(args.timeout_seconds) };
+    },
+  );
+
+  registerCliTool(
+    server,
+    runCli,
+    "lemon_account_clear",
+    {
+      title: "Clear Lemon account context",
+      description:
+        "Clear saved account context without clearing authentication. Use all_products only when the user explicitly requests clearing every product context.",
+      inputSchema: z.object({
+        product: productSchema.optional(),
+        all_products: z.boolean().default(false),
+        timeout_seconds: timeoutSchema,
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    (args) => {
+      const command = ["account", "clear"];
+      addFlag(command, "--product", args.product);
+      if (args.all_products) command.push("--all");
+      command.push("--timeout", String(args.timeout_seconds));
+      return { command, timeoutMs: commandTimeout(args.timeout_seconds) };
+    },
+  );
+
+  registerCliTool(
+    server,
+    runCli,
+    "lemon_action_search",
+    {
+      title: "Search Lemon business actions",
+      description:
+        "Search for ACC, SCM, or ERP action candidates in one explicit product. Search does not select an action, create parameters, or execute business requests.",
+      inputSchema: z.object({
+        product: productSchema,
+        query: z.string().min(1),
+        limit: z.number().int().min(1).max(20).default(5),
+      }),
+      annotations: readOnlyAnnotations,
+    },
+    (args) => ({
+      command: [
+        "action",
+        "search",
+        args.query,
+        "--product",
+        args.product,
+        "--limit",
+        String(args.limit),
+      ],
+      timeoutMs: 30_000,
+    }),
+  );
+
+  registerCliTool(
+    server,
+    runCli,
+    "lemon_action_show",
+    {
+      title: "Show a Lemon business action",
+      description:
+        "Show one action's public contract and the documents that actually exist. A successful show does not prove the action is the unique semantic match.",
+      inputSchema: z.object({
+        product: productSchema,
+        action: z.string().min(1),
+      }),
+      annotations: readOnlyAnnotations,
+    },
+    (args) => ({
+      command: ["action", "show", args.product, args.action],
+      timeoutMs: 30_000,
+    }),
+  );
+
+  registerCliTool(
+    server,
+    runCli,
+    "lemon_action_read_doc",
+    {
+      title: "Read a Lemon business action document",
+      description:
+        "Read one registered ACTION, input, or output Markdown document. Read every document exposed by lemon_action_show for the final selected action before run.",
+      inputSchema: z.object({
+        product: productSchema,
+        action: z.string().min(1),
+        document: z.enum(["action", "input", "output"]),
+      }),
+      annotations: readOnlyAnnotations,
+    },
+    (args) => ({
+      command: [
+        "action",
+        "doc",
+        args.product,
+        args.action,
+        "--doc",
+        args.document,
+      ],
+      timeoutMs: 30_000,
+    }),
+  );
+
+  registerCliTool(
+    server,
+    runCli,
+    "lemon_action_run",
+    {
+      title: "Run a Lemon business action",
+      description:
+        "Run one already-selected ACC, SCM, or ERP action with its documented nested query/body envelope. This tool never searches, guesses parameters, or executes independent invoicing. Set user_confirmed only after explicit confirmation of a documented write action.",
+      inputSchema: z.object({
+        product: productSchema,
+        action: z.string().min(1),
+        payload: z
+          .object({
+            query: z.record(z.string(), z.unknown()).optional(),
+            body: z.union([z.record(z.string(), z.unknown()), z.array(z.unknown())]).optional(),
+            _outputMode: z.enum(["basic", "full"]).optional(),
+            _extraDisplayFields: z.array(z.string().min(1)).min(1).optional(),
+          })
+          .strict(),
+        user_confirmed: z.boolean().default(false),
+        dry_run: z.boolean().default(false),
+        timeout_seconds: timeoutSchema,
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    (args) => {
+      const command = [
+        "action",
+        "run",
+        args.product,
+        args.action,
+        "--json-stdin",
+        "--timeout",
+        String(args.timeout_seconds),
+      ];
+      if (args.user_confirmed) command.push("--user-confirmed");
+      if (args.dry_run) command.push("--dry-run");
+      return {
+        command,
+        stdin: JSON.stringify(args.payload),
+        timeoutMs: commandTimeout(args.timeout_seconds),
+      };
+    },
+  );
+
+  server.registerTool(
+    "lemon_invoice_read_doc",
+    {
+      title: "Read Lemon independent-invoicing documentation",
+      description:
+        "Read a Runtime document relative to the invoice directory. Start with SKILL.md, then read only the immediate, batch, or feedback flow and shared documents it directs you to.",
+      inputSchema: z.object({
+        path: z.string().min(1).describe("For example SKILL.md or references/immediate/flow.md"),
+      }),
+      annotations: readOnlyAnnotations,
+    },
+    async ({ path }) => {
+      try {
+        const content = await readInvoiceDocument(runCli, path);
+        return { content: [{ type: "text", text: content }] };
+      } catch (error) {
+        return toolError(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "lemon_invoice_api",
+    {
+      title: "Call the Lemon independent-invoicing API adapter",
+      description:
+        "Execute one documented independent-invoicing operation with Runtime Python. Read and follow the invoice documents first. SkillInvoiceIssue is blocked unless user_confirmed is true and required context is supplied.",
+      inputSchema: z.object({
+        operation: z.enum([
+          "CompanyFullList",
+          "CompanyDetail",
+          "Customer",
+          "QixinbaoCompanyList",
+          "CheckLoginTaskState",
+          "AuthStatus",
+          "RemainingBalance",
+          "TaxItemBatchResolve",
+          "TaxBureauAuthChain",
+          "SkillInvoiceIssue",
+          "FeedbackSubmit",
+        ]),
+        eiscid: optionalText,
+        filter_word: optionalText,
+        company_name: optionalText,
+        company_id: optionalText,
+        personal_account: optionalText,
+        uscic: optionalText,
+        auth_company_id: optionalText,
+        company_detail_id: optionalText,
+        payload: z.record(z.string(), z.unknown()).optional(),
+        payload_path: optionalText,
+        api_key_last_four: optionalText,
+        ai_tool: optionalText,
+        model: optionalText,
+        feedback_contact: optionalText,
+        feedback_version: optionalText,
+        feedback_type: optionalText,
+        feedback_files: optionalText,
+        feedback_text: optionalText,
+        message_id: optionalText,
+        context: optionalText,
+        upload_file_path: optionalText,
+        user_confirmed: z.boolean().default(false),
+        timeout_seconds: timeoutSchema,
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      try {
+        return cliToolResult(await runInvoiceApi(runCli, args));
+      } catch (error) {
+        return toolError(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "lemon_invoice_run_helper",
+    {
+      title: "Run a Lemon independent-invoicing helper",
+      description:
+        "Run one whitelisted Runtime helper for invoice file parsing, validation, preview generation, preview serving, customer lookup, or customer-service output. Arguments must come from the invoice documents.",
+      inputSchema: z.object({
+        operation: z.enum(invoiceHelperNames),
+        arguments: z.array(z.string()).max(30).default([]),
+        stdin: z.string().optional(),
+        timeout_seconds: timeoutSchema,
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      try {
+        return cliToolResult(await runInvoiceHelper(runCli, args));
+      } catch (error) {
+        return toolError(error);
+      }
+    },
+  );
+
+  return server;
+}

package/src/tool-result.js

@@ -0,0 +1,40 @@
+function publicFailure(result) {
+  if (result.timedOut) return "LemonClaw command timed out.";
+  if (result.outputLimitExceeded) return "LemonClaw command output exceeded the MCP limit.";
+  if (result.spawnError) return `Unable to start LemonClaw: ${result.spawnError.message}`;
+  return String(result.stderr || "LemonClaw command failed.").trim().slice(0, 2000);
+}
+
+export function cliToolResult(result, options = {}) {
+  const infrastructureFailure =
+    Boolean(result.spawnError) ||
+    Boolean(result.timedOut) ||
+    Boolean(result.outputLimitExceeded);
+  const text = infrastructureFailure
+    ? publicFailure(result)
+    : String(result.stdout || "").trim() || publicFailure(result);
+  const failed =
+    infrastructureFailure || (result.code !== 0 && options.nonzeroIsError !== false);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text,
+      },
+    ],
+    ...(failed ? { isError: true } : {}),
+  };
+}
+
+export function toolError(error) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: error instanceof Error ? error.message : String(error),
+      },
+    ],
+    isError: true,
+  };
+}