@sonenta/mcp 0.33.0 → 0.34.1

package/bin/sonenta-mcp.js

@@ -32,32 +32,81 @@ function which(cmd) {
   return !probe.error && probe.status === 0;
 }
 
-function runInherit(cmd, args) {
-  const child = spawn(cmd, args, { stdio: "inherit" });
-  child.on("exit", (code) => process.exit(code ?? 1));
-  return child;
+// A runner that exits non-zero almost immediately never actually started the
+// server — the usual cause is a Python-interpreter mismatch (e.g. the wheel's
+// requires-python floor is unmet, so uv reports the resolution "unsatisfiable").
+// Below this many ms, a non-zero exit is treated as "this launcher can't run
+// it" and we hand off to the next one instead of dying. A real server runs far
+// longer (it blocks on stdin until the MCP client disconnects).
+const FAST_FAIL_MS = 4000;
+
+// Give uv the freedom to pick/provision a compatible interpreter rather than
+// hard-failing on the ambient python3, and never silence its errors.
+const UV_ENV = {
+  ...process.env,
+  // Prefer a uv-managed interpreter, but still accept a compatible system one.
+  UV_PYTHON_PREFERENCE: process.env.UV_PYTHON_PREFERENCE || "managed",
+  // Allow uv to download a matching interpreter when none on PATH satisfies the
+  // wheel's requires-python (no-op in offline/locked-down envs — the lowered
+  // >=3.11 floor is what makes the common ambient interpreter satisfy).
+  UV_PYTHON_DOWNLOADS: process.env.UV_PYTHON_DOWNLOADS || "automatic",
+};
+
+/**
+ * Spawn a runner with stdio passthrough. Calls onFastFail(code) if the child
+ * dies non-zero within FAST_FAIL_MS (so the caller can try the next launcher);
+ * otherwise propagates the child's exit code. Runners fail fast BEFORE reading
+ * stdin, so stdin is untouched and handing off is safe.
+ */
+function runOrHandoff(cmd, args, env, onFastFail) {
+  const started = Date.now();
+  const child = spawn(cmd, args, { stdio: "inherit", env });
+  let settled = false;
+  child.on("error", (err) => {
+    if (settled) return;
+    settled = true;
+    process.stderr.write("@sonenta/mcp: " + cmd + " failed to start: " + err.message + "\n");
+    onFastFail(1);
+  });
+  child.on("exit", (code, signal) => {
+    if (settled) return;
+    settled = true;
+    const elapsed = Date.now() - started;
+    if (code === 0 || elapsed >= FAST_FAIL_MS || signal) {
+      process.exit(code ?? (signal ? 1 : 0));
+    }
+    process.stderr.write(
+      "@sonenta/mcp: " + cmd + " exited " + code + " after " + elapsed +
+        "ms (interpreter/launch problem) — trying the next launcher...\n",
+    );
+    onFastFail(code);
+  });
 }
 
-function tryUvx(passthroughArgs) {
+function tryUvx(passthroughArgs, next) {
   if (!which("uvx") || !BUNDLED_WHEEL) return false;
-  runInherit("uvx", ["--from", BUNDLED_WHEEL, "sonenta-mcp", ...passthroughArgs]);
+  runOrHandoff("uvx", ["--from", BUNDLED_WHEEL, "sonenta-mcp", ...passthroughArgs], UV_ENV, next);
   return true;
 }
 
-function tryUvRun(passthroughArgs) {
+function tryUvRun(passthroughArgs, next) {
   if (!which("uv")) return false;
-  runInherit(
+  runOrHandoff(
     "uv",
     ["run", "--project", BUNDLED_PY_DIR, "sonenta-mcp", ...passthroughArgs],
+    UV_ENV,
+    next,
   );
   return true;
 }
 
-function tryPipxRun(passthroughArgs) {
+function tryPipxRun(passthroughArgs, next) {
   if (!which("pipx") || !BUNDLED_WHEEL) return false;
-  runInherit(
+  runOrHandoff(
     "pipx",
     ["run", "--spec", BUNDLED_WHEEL, "sonenta-mcp", ...passthroughArgs],
+    process.env,
+    next,
   );
   return true;
 }
@@ -68,7 +117,7 @@ function tryPipxRun(passthroughArgs) {
  * first run; subsequent runs reuse the venv (keyed by wheel sha so a
  * future sonenta-mcp version triggers a fresh venv automatically).
  */
-function tryAdhocVenv(passthroughArgs) {
+function tryAdhocVenv(passthroughArgs, next) {
   if (!which("python3") || !BUNDLED_WHEEL) return false;
   const wheelHash = crypto
     .createHash("sha256")
@@ -93,14 +142,24 @@ function tryAdhocVenv(passthroughArgs) {
         { stdio: "inherit" },
       );
     } catch (err) {
-      process.stderr.write("@sonenta/mcp: venv bootstrap failed: " + err.message + "\n");
+      process.stderr.write(
+        "@sonenta/mcp: venv bootstrap failed (python3 " + pythonVersion() +
+          " may be older than the required >=3.11): " + err.message + "\n",
+      );
+      if (typeof next === "function") return next(1), true;
       return false;
     }
   }
-  runInherit(venvEntry, passthroughArgs);
+  runOrHandoff(venvEntry, passthroughArgs, process.env, next || (() => process.exit(1)));
   return true;
 }
 
+// Best-effort ambient python3 version string for diagnostics.
+function pythonVersion() {
+  const probe = spawnSync("python3", ["--version"], { encoding: "utf8" });
+  return (probe.stdout || probe.stderr || "unknown").trim();
+}
+
 function selfCheck() {
   const hits = [];
   if (which("uvx")) hits.push("uvx");
@@ -119,11 +178,13 @@ function selfCheck() {
 
 function fail() {
   process.stderr.write(
-    "@sonenta/mcp: no usable Python launcher found.\n" +
-      "Install one of these on PATH and retry:\n" +
-      "  - uv    (recommended): https://docs.astral.sh/uv/\n" +
+    "@sonenta/mcp: could not start the MCP server with any Python launcher.\n" +
+      "Every available launcher failed — the most common cause is an ambient\n" +
+      "python3 older than the required >=3.11 (detected: " + pythonVersion() + ").\n" +
+      "Install or expose one of these on PATH and retry:\n" +
+      "  - uv    (recommended, auto-provisions Python): https://docs.astral.sh/uv/\n" +
       "  - pipx  https://pipx.pypa.io/\n" +
-      "  - python3 (>=3.12)\n",
+      "  - python3 (>=3.11)\n",
   );
   process.exit(127);
 }
@@ -132,11 +193,17 @@ function main() {
   const argv = process.argv.slice(2);
   if (argv.includes("--self-check")) return selfCheck();
 
-  if (tryUvx(argv)) return;
-  if (tryUvRun(argv)) return;
-  if (tryPipxRun(argv)) return;
-  if (tryAdhocVenv(argv)) return;
-  fail();
+  // Chain the launchers: each hands off to the next when it can't actually run
+  // the server (e.g. Python-floor mismatch), so one unusable launcher on PATH
+  // never causes a silent total failure.
+  const chain = [tryUvx, tryUvRun, tryPipxRun, tryAdhocVenv];
+  const step = (i) => {
+    for (let j = i; j < chain.length; j++) {
+      if (chain[j](argv, () => step(j + 1))) return;
+    }
+    fail();
+  };
+  step(0);
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonenta/mcp",
-  "version": "0.33.0",
+  "version": "0.34.1",
   "description": "MCP server for Sonenta translation management \u2014 wires Claude Desktop and other MCP clients into your project's keys, missing-key feed, and translation drafts.",
   "license": "MIT",
   "homepage": "https://sonenta.com",

package/python/pyproject.toml

@@ -1,14 +1,15 @@
 [project]
 name = "sonenta-mcp"
-version = "0.33.0"
+version = "0.34.1"
 description = "Model Context Protocol server for Sonenta — list projects, missing keys, propose translations from Claude Desktop and other MCP clients."
 readme = "README.md"
-requires-python = ">=3.12,<3.14"
+requires-python = ">=3.11,<3.14"
 license = { text = "MIT" }
 authors = [{ name = "Sonenta" }]
 keywords = ["mcp", "sonenta", "i18n", "translations", "claude"]
 classifiers = [
     "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Topic :: Software Development :: Internationalization",
 ]

package/python/verbumia_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Sonenta MCP server (MIT)."""
 
-__version__ = "0.33.0"
+__version__ = "0.34.1"

package/python/verbumia_mcp/tools.py

@@ -2388,6 +2388,79 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     "additionalProperties": False,
                 },
             ),
+            Tool(
+                name="set_duplicate_status_bulk",
+                description=(
+                    "Set ONE triage status across MANY duplicate groups at once (coarse "
+                    "triage). Body {source_values[], status, note?}. Intentionally NO "
+                    "files_modified (a single status over many groups). Use it to bulk-mark "
+                    "a batch as allowed (sanctioned) or to_fix; use the per-group "
+                    "set_duplicate_status for anything that records code changes."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "project_uuid": {
+                            "type": "string",
+                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
+                        },
+                        "source_values": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "The shared source values identifying the duplicate groups.",
+                        },
+                        "status": {
+                            "type": "string",
+                            "enum": ["neutral", "allowed", "to_fix", "resolved"],
+                            "description": "New triage status applied to every listed group (neutral clears the override).",
+                        },
+                        "note": {"type": "string", "description": "Optional human/agent note (same on all)."},
+                    },
+                    "required": ["source_values", "status"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="propose_duplicate_merge_plan",
+                description=(
+                    "OPT-IN, METERED second opinion: a server-side LLM reads a duplicate "
+                    "group (keys + translations + glossary + context) and PROPOSES a plan — "
+                    "recommendation merge | split | keep_separate + a well-formed merge_plan "
+                    "(null when keep_separate) + a one-line reason. PROPOSE-ONLY: it does NOT "
+                    "change status; apply via set_source_duplicate_merge_plan + "
+                    "apply_new_key_cluster / mark_cluster_applied / set_duplicate_status. "
+                    "You are already an LLM and decide locally at 0 credit — use this only "
+                    "as a tie-breaker or when the dev wants the AI's take. Costs 1 credit per "
+                    "generation UNLESS a valid cached proposal exists (cached=true → free); "
+                    "regenerate=true forces a fresh one. 402 when credits are insufficient. "
+                    "The persisted proposal also surfaces on list_source_duplicates "
+                    "(ai_proposed_plan / ai_diagnosis, free to read)."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "project_uuid": {
+                            "type": "string",
+                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
+                        },
+                        "source_value": {
+                            "type": "string",
+                            "description": "The shared source value identifying the duplicate group.",
+                        },
+                        "namespace_slug": {
+                            "type": "string",
+                            "description": "Required only if the value spans namespaces (groups are intra-namespace).",
+                        },
+                        "regenerate": {
+                            "type": "boolean",
+                            "description": "Force a fresh diagnosis (1 credit) even if a valid cached one exists. Default false.",
+                        },
+                        "version_id": {"type": "string", "description": "Optional version UUID; defaults to the live version."},
+                    },
+                    "required": ["source_value"],
+                    "additionalProperties": False,
+                },
+            ),
         ]
 
     @server.call_tool()
@@ -3187,6 +3260,35 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     json=body,
                 )
                 return _text(data)
+            if name == "set_duplicate_status_bulk":
+                project_uuid = _project_uuid(args, client)
+                source_values = args.get("source_values")
+                if not isinstance(source_values, list) or not source_values:
+                    return _err("source_values must be a non-empty list")
+                if not args.get("status"):
+                    return _err("status is required")
+                body = {"source_values": source_values, "status": args["status"]}
+                if args.get("note") is not None:
+                    body["note"] = args["note"]
+                data = await client.put(
+                    f"/v1/mcp/projects/{project_uuid}/source-duplicates/status/bulk",
+                    json=body,
+                )
+                return _text(data)
+            if name == "propose_duplicate_merge_plan":
+                project_uuid = _project_uuid(args, client)
+                if not args.get("source_value"):
+                    return _err("source_value is required")
+                body = {"source_value": args["source_value"]}
+                if args.get("namespace_slug"):
+                    body["namespace_slug"] = args["namespace_slug"]
+                if args.get("regenerate"):
+                    body["regenerate"] = True
+                url = f"/v1/mcp/projects/{project_uuid}/source-duplicates/propose-plan"
+                if args.get("version_id"):
+                    url += f"?version_id={args['version_id']}"
+                data = await client.post(url, json=body)
+                return _text(data)
             return _err(f"unknown tool: {name}")
         except VerbumiaApiError as exc:
             return _err(f"API {exc.status}: {exc.body}")