@sonenta/mcp 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verbumia
+
+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.

package/README.md

@@ -0,0 +1,89 @@
+# @verbumia/mcp
+
+MCP server for [Verbumia](https://verbumia.ca) — wires Claude Desktop and
+other Model Context Protocol clients into your translation project.
+
+This npm package **bundles the Python MCP server source** (no PyPI
+download). The launcher picks the best Python runtime on your host and
+runs the bundled `verbumia_mcp` directly.
+
+## Use it from Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "verbumia": {
+      "command": "npx",
+      "args": ["-y", "@verbumia/mcp"],
+      "env": {
+        "VERBUMIA_API_KEY": "vrb_live_<prefix>.<secret>",
+        "VERBUMIA_PROJECTS": "<project_uuid>",
+        "VERBUMIA_BASE_URL": "https://api.verbumia.dev"
+      }
+    }
+  }
+}
+```
+
+For **multiple projects** (v0.11+), comma-separate the UUIDs in
+`VERBUMIA_PROJECTS`. The LLM then has to pass `project_uuid` on every tool
+call:
+
+```json
+"env": {
+  "VERBUMIA_API_KEY": "vrb_live_<prefix>.<secret>",
+  "VERBUMIA_PROJECTS": "01993a..,01993b..,01993c.."
+}
+```
+
+Restart Claude Desktop. All thirteen Verbumia tools (`list_projects`,
+`get_project_info`, `list_keys`, `list_untranslated_keys`,
+`list_missing_keys`, `missing_keys_stats`, `acknowledge_missing_keys`,
+`create_key`, `propose_translation`, `publish_cdn`,
+`validate_translations`, `project_context_get`, `project_context_set`)
+become callable from your prompt.
+
+## How the launcher works
+
+The npm tarball ships the Python sources under `python/` plus a pre-built
+wheel under `python/dist/`. The Node bin tries these in order:
+
+1. **`uvx --from <bundled_wheel> verbumia-mcp`** — fastest, ephemeral
+   venv. Recommended.
+2. **`uv run --project <bundled_dir> verbumia-mcp`** — uv-managed,
+   resolves deps from `pyproject.toml`.
+3. **`pipx run --spec <bundled_wheel> verbumia-mcp`** — pipx-managed.
+4. **Ad-hoc venv at `~/.verbumia/mcp-venv-<wheelhash>/`** — last-resort
+   fallback that requires only `python3 >= 3.12`. Slow first run, fast
+   thereafter.
+
+Stdio is fully passthrough so the MCP JSON-RPC framing is preserved.
+
+## Environment variables (canonical)
+
+| Var                  | Required | Default                     | Notes                                                  |
+|----------------------|----------|-----------------------------|--------------------------------------------------------|
+| `VERBUMIA_API_KEY`   | yes      |                             | Bearer ApiKey token. `VERBUMIA_TOKEN` accepted (back-compat) |
+| `VERBUMIA_BASE_URL`  | no       | `https://api.verbumia.dev`   | Self-host / staging override. `VERBUMIA_API_BASE` accepted (back-compat) |
+| `VERBUMIA_PROJECTS`  | no       | (LLM picks per call)        | CSV of project UUIDs. When >1, the LLM MUST pass `project_uuid` per call. |
+| `VERBUMIA_PROJECT`   | no       | (legacy)                    | Singular fallback for v0.10.x users. Ignored when `VERBUMIA_PROJECTS` is set (warns). |
+
+## Requirements
+
+One of:
+
+- **uv** (recommended, https://docs.astral.sh/uv/)
+- **pipx** (https://pipx.pypa.io/)
+- **python3 >= 3.12** (for the venv fallback)
+
+## Self-check
+
+```bash
+npx -y @verbumia/mcp --self-check
+# -> @verbumia/mcp launchers detected: uvx, uv, python3
+# -> @verbumia/mcp bundled wheel: <node_modules>/.../python/dist/verbumia_mcp-…whl
+```
+
+## License
+
+MIT.

package/bin/sonenta-mcp.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * @sonenta/mcp launcher
+ *
+ * Ships the Python MCP server source bundled inside the npm tarball
+ * (no PyPI dependency). Spawns it via the first available Python launcher:
+ *
+ *   1. uvx --from <bundled_wheel>  — fastest, ephemeral venv
+ *   2. uv run --project <bundled_dir> verbumia-mcp  — uv-managed
+ *   3. pipx run --spec <bundled_wheel> verbumia-mcp  — pipx-managed
+ *   4. python3 + ad-hoc venv  — last-resort, slowest first run
+ *
+ * Stdio is fully passthrough so the MCP JSON-RPC framing is preserved.
+ */
+
+const { spawn, spawnSync, execSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const crypto = require("node:crypto");
+
+const BUNDLED_PY_DIR = path.resolve(__dirname, "..", "python");
+const BUNDLED_WHEEL = (() => {
+  const distDir = path.join(BUNDLED_PY_DIR, "dist");
+  if (!fs.existsSync(distDir)) return null;
+  const wheels = fs.readdirSync(distDir).filter((f) => f.endsWith(".whl"));
+  return wheels.length ? path.join(distDir, wheels[0]) : null;
+})();
+
+function which(cmd) {
+  const probe = spawnSync(cmd, ["--version"], { stdio: "ignore" });
+  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;
+}
+
+function tryUvx(passthroughArgs) {
+  if (!which("uvx") || !BUNDLED_WHEEL) return false;
+  runInherit("uvx", ["--from", BUNDLED_WHEEL, "verbumia-mcp", ...passthroughArgs]);
+  return true;
+}
+
+function tryUvRun(passthroughArgs) {
+  if (!which("uv")) return false;
+  runInherit(
+    "uv",
+    ["run", "--project", BUNDLED_PY_DIR, "verbumia-mcp", ...passthroughArgs],
+  );
+  return true;
+}
+
+function tryPipxRun(passthroughArgs) {
+  if (!which("pipx") || !BUNDLED_WHEEL) return false;
+  runInherit(
+    "pipx",
+    ["run", "--spec", BUNDLED_WHEEL, "verbumia-mcp", ...passthroughArgs],
+  );
+  return true;
+}
+
+/**
+ * Last-resort fallback: bootstrap an ad-hoc venv under
+ * ~/.verbumia/mcp-venv-<wheelhash> and reuse it on subsequent runs. Slow
+ * first run; subsequent runs reuse the venv (keyed by wheel sha so a
+ * future verbumia-mcp version triggers a fresh venv automatically).
+ */
+function tryAdhocVenv(passthroughArgs) {
+  if (!which("python3") || !BUNDLED_WHEEL) return false;
+  const wheelHash = crypto
+    .createHash("sha256")
+    .update(fs.readFileSync(BUNDLED_WHEEL))
+    .digest("hex")
+    .slice(0, 12);
+  const venvRoot = path.join(os.homedir(), ".verbumia", "mcp-venv-" + wheelHash);
+  const venvBin = path.join(venvRoot, "bin");
+  const venvPy = path.join(venvBin, "python");
+  const venvEntry = path.join(venvBin, "verbumia-mcp");
+
+  if (!fs.existsSync(venvEntry)) {
+    process.stderr.write(
+      "@sonenta/mcp: bootstrapping a venv at " + venvRoot + " (one-time install)\n",
+    );
+    try {
+      execSync("python3 -m venv " + JSON.stringify(venvRoot), { stdio: "ignore" });
+      execSync(
+        JSON.stringify(venvPy) +
+          " -m pip install --quiet --disable-pip-version-check " +
+          JSON.stringify(BUNDLED_WHEEL),
+        { stdio: "inherit" },
+      );
+    } catch (err) {
+      process.stderr.write("@sonenta/mcp: venv bootstrap failed: " + err.message + "\n");
+      return false;
+    }
+  }
+  runInherit(venvEntry, passthroughArgs);
+  return true;
+}
+
+function selfCheck() {
+  const hits = [];
+  if (which("uvx")) hits.push("uvx");
+  if (which("uv")) hits.push("uv");
+  if (which("pipx")) hits.push("pipx");
+  if (which("python3")) hits.push("python3");
+  process.stdout.write(
+    "@sonenta/mcp launchers detected: " + (hits.join(", ") || "none") + "\n",
+  );
+  process.stdout.write(
+    "@sonenta/mcp bundled wheel: " + (BUNDLED_WHEEL ?? "missing") + "\n",
+  );
+  process.stdout.write("@sonenta/mcp bundled source: " + BUNDLED_PY_DIR + "\n");
+  process.exit(0);
+}
+
+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" +
+      "  - pipx  https://pipx.pypa.io/\n" +
+      "  - python3 (>=3.12)\n",
+  );
+  process.exit(127);
+}
+
+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();
+}
+
+main();

package/bin/verbumia-mcp.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Deprecated alias for `sonenta-mcp` (@sonenta/mcp) — kept functional.
+console.error(
+  "[deprecated] `verbumia-mcp` is now `sonenta-mcp` (@sonenta/mcp). This alias still works but will be removed in a future major.",
+);
+require("./sonenta-mcp.js");

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@sonenta/mcp",
+  "version": "0.16.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/verbumia/verbumia-tools.git",
+    "directory": "mcp/npm"
+  },
+  "bugs": {
+    "url": "https://github.com/verbumia/verbumia-tools/issues"
+  },
+  "keywords": [
+    "mcp",
+    "sonenta",
+    "verbumia",
+    "i18n",
+    "translations",
+    "claude",
+    "anthropic"
+  ],
+  "author": "Sonenta",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "sonenta-mcp": "bin/sonenta-mcp.js",
+    "verbumia-mcp": "bin/verbumia-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "python/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node bin/sonenta-mcp.js --self-check",
+    "prepublishOnly": "cd python && uv build && rm -f dist/verbumia_mcp-*.tar.gz && printf '' > dist/.npmignore"
+  }
+}

package/python/README.md

@@ -0,0 +1,109 @@
+# Verbumia MCP server
+
+Model Context Protocol server for [Verbumia](https://verbumia.ca) — exposes
+your translation project to Claude Desktop and other MCP clients.
+
+## Status
+
+Thirteen tools wired: `list_projects`, `get_project_info`, `list_keys`,
+`list_untranslated_keys`, `list_missing_keys`, `missing_keys_stats`,
+`acknowledge_missing_keys`, `create_key`, `propose_translation`,
+`publish_cdn`, `validate_translations`, `project_context_get`,
+`project_context_set`.
+
+### Project context document (V1.2)
+
+`project_context_get` / `project_context_set` read and write a free-form
+markdown blob attached to the project — terminology, brand voice, domain
+notes (religious, legal, medical, gaming, etc.). The content is intended
+as ambient context for human translators **and** for AI agents producing
+translations: prepend it to your translation prompts so every output stays
+consistent with the project's vocabulary and tone. Hard cap 100 KiB.
+
+Scopes:
+- `project_context_get` requires `project:read` (existing scope).
+- `project_context_set` requires `project:settings:write` (new scope, narrower
+  than `project:write` since settings changes propagate to every translator's
+  prompt context).
+
+Note: the blanket `mcp:*` scope is **not** sufficient for these tools — grant
+the precise scope on the key.
+
+## Install
+
+```bash
+# Recommended (zero-install, used by Claude Desktop's mcp.json):
+npx -y @verbumia/mcp
+
+# Or from PyPI:
+pipx install verbumia-mcp
+```
+
+A Homebrew tap (`brew install verbumia/tap/verbumia-mcp`) is coming once we
+publish to npm.
+
+## Configure (Claude Desktop)
+
+Open **Settings → Developer → Edit Config**, then:
+
+Single-project setup:
+
+```json
+{
+  "mcpServers": {
+    "verbumia": {
+      "command": "npx",
+      "args": ["-y", "@verbumia/mcp"],
+      "env": {
+        "VERBUMIA_API_KEY": "vrb_live_<prefix>.<secret>",
+        "VERBUMIA_PROJECTS": "<project_uuid>",
+        "VERBUMIA_BASE_URL": "https://api.verbumia.dev"
+      }
+    }
+  }
+}
+```
+
+Multi-project setup (v0.11+) — comma-separate the UUIDs and Claude will pass
+`project_uuid` on each tool call:
+
+```json
+"env": {
+  "VERBUMIA_API_KEY": "vrb_live_<prefix>.<secret>",
+  "VERBUMIA_PROJECTS": "01993a..,01993b..,01993c.."
+}
+```
+
+Restart Claude Desktop. Tools show up in the prompt UI.
+
+## Environment
+
+| Variable             | Required | Default                        | Description                                                                                |
+|----------------------|----------|--------------------------------|--------------------------------------------------------------------------------------------|
+| `VERBUMIA_API_KEY`   | yes      |                                | API key from Org Settings → API Keys (`VERBUMIA_TOKEN` also accepted, back-compat)         |
+| `VERBUMIA_PROJECTS`  | no       | (LLM passes per call)          | CSV of project UUIDs. When >1, the LLM MUST pass `project_uuid` on each tool call.         |
+| `VERBUMIA_PROJECT`   | no       | (legacy)                       | Singular fallback for v0.10.x users. Ignored when `VERBUMIA_PROJECTS` is set (warns).      |
+| `VERBUMIA_BASE_URL`  | no       | `https://api.verbumia.dev`      | Override for self-host or staging (`VERBUMIA_API_BASE` also accepted, back-compat)         |
+
+The token format is `vrb_live_<prefix>.<secret>` and must carry the `mcp:*`
+scope. For the `project_context_*` tools, also grant `project:read` and/or
+`project:settings:write` — see the **Project context document** section
+above. Treat the token like any other secret — keychain or `.env`, never
+commit.
+
+If your API key is pinned to a single project (its `project_uuid` is set
+server-side), listing additional UUIDs in `VERBUMIA_PROJECTS` will surface
+as a `403 API key is scoped to a different project` from the backend on
+any call targeting one of the others.
+
+## Local development
+
+```bash
+cd mcp
+uv sync
+uv run verbumia-mcp        # stdio transport — pipe MCP frames over stdin/stdout
+```
+
+## License
+
+MIT.

package/python/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "verbumia-mcp"
+version = "0.16.0"
+description = "Model Context Protocol server for Verbumia — list projects, missing keys, propose translations from Claude Desktop and other MCP clients."
+readme = "README.md"
+requires-python = ">=3.12,<3.14"
+license = { text = "MIT" }
+authors = [{ name = "Verbumia" }]
+keywords = ["mcp", "verbumia", "i18n", "translations", "claude"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Internationalization",
+]
+dependencies = [
+    "mcp>=1.0",
+    "httpx>=0.28",
+    "pydantic>=2.9",
+]
+
+[project.scripts]
+verbumia-mcp = "verbumia_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://verbumia.ca"
+Documentation = "https://verbumia.ca/docs/mcp/setup"
+Source = "https://github.com/verbumia/verbumia-tools"
+Issues = "https://github.com/verbumia/verbumia-tools/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8",
+]
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "ASYNC", "RUF"]
+ignore = ["E501"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["verbumia_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "-q --strict-markers"

package/python/verbumia_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Verbumia MCP server (MIT)."""
+
+__version__ = "0.16.0"

package/python/verbumia_mcp/__main__.py

@@ -0,0 +1,23 @@
+"""Entrypoint for `verbumia-mcp` (and `python -m verbumia_mcp`)."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+
+def main() -> None:
+    from .server import run
+
+    try:
+        asyncio.run(run())
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except RuntimeError as exc:
+        # Configuration errors (missing token, etc.) — print a friendly hint.
+        print(f"verbumia-mcp: {exc}", file=sys.stderr)
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

package/python/verbumia_mcp/client.py

@@ -0,0 +1,85 @@
+"""Async HTTP client wrapping the Verbumia REST API.
+
+The MCP tools are thin adapters over this client — they translate MCP
+arguments to API calls and shape the response. Authentication is the
+`Authorization: ApiKey vrb_live_<prefix>.<secret>` header read from
+`SONENTA_API_KEY` (or `SONENTA_TOKEN` for back-compat).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .config import Config
+
+
+class VerbumiaApiError(Exception):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(self, status: int, body: str | dict[str, Any]) -> None:
+        self.status = status
+        self.body = body
+        super().__init__(f"Verbumia API error {status}: {body}")
+
+
+class VerbumiaClient:
+    """Tiny async REST client. Reuse across tool calls — open once at startup."""
+
+    def __init__(
+        self, config: Config, *, transport: httpx.AsyncBaseTransport | None = None
+    ) -> None:
+        self._config = config
+        self._http = httpx.AsyncClient(
+            base_url=config.api_base,
+            headers={
+                "Authorization": f"ApiKey {config.token}",
+                "User-Agent": config.user_agent,
+                "Accept": "application/json",
+            },
+            timeout=httpx.Timeout(15.0, connect=5.0),
+            transport=transport,
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    @property
+    def config(self) -> Config:
+        return self._config
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        r = await self._http.get(path, params=params)
+        return _unpack(r)
+
+    async def post(self, path: str, json: dict[str, Any]) -> Any:
+        r = await self._http.post(path, json=json)
+        return _unpack(r)
+
+    async def put(self, path: str, json: dict[str, Any]) -> Any:
+        r = await self._http.put(path, json=json)
+        return _unpack(r)
+
+    async def patch(self, path: str, json: dict[str, Any]) -> Any:
+        r = await self._http.patch(path, json=json)
+        return _unpack(r)
+
+    async def delete(self, path: str) -> Any:
+        r = await self._http.delete(path)
+        return _unpack(r)
+
+    async def health(self) -> dict[str, Any]:
+        return await self.get("/health")
+
+
+def _unpack(r: httpx.Response) -> Any:
+    if r.status_code >= 400:
+        try:
+            body: str | dict[str, Any] = r.json()
+        except ValueError:
+            body = r.text
+        raise VerbumiaApiError(r.status_code, body)
+    if r.status_code == 204 or not r.content:
+        return None
+    return r.json()