@sonenta/mcp 0.21.2 → 0.22.0

package/README.md

@@ -18,7 +18,7 @@ runs the bundled `sonenta-mcp` directly.
       "env": {
         "SONENTA_API_KEY": "vrb_live_<prefix>.<secret>",
         "SONENTA_PROJECTS": "<project_uuid>",
-        "SONENTA_BASE_URL": "https://api.sonenta.dev"
+        "SONENTA_BASE_URL": "https://api.sonenta.com"
       }
     }
   }
@@ -64,7 +64,7 @@ Stdio is fully passthrough so the MCP JSON-RPC framing is preserved.
 | Var                  | Required | Default                     | Notes                                                  |
 |----------------------|----------|-----------------------------|--------------------------------------------------------|
 | `SONENTA_API_KEY`   | yes      |                             | Bearer ApiKey token. `SONENTA_TOKEN` accepted (back-compat) |
-| `SONENTA_BASE_URL`  | no       | `https://api.sonenta.dev`   | Self-host / staging override. `SONENTA_API_BASE` accepted (back-compat) |
+| `SONENTA_BASE_URL`  | no       | `https://api.sonenta.com`   | Self-host / staging override. `SONENTA_API_BASE` accepted (back-compat) |
 | `SONENTA_PROJECTS`  | no       | (LLM picks per call)        | CSV of project UUIDs. When >1, the LLM MUST pass `project_uuid` per call. |
 | `SONENTA_PROJECT`   | no       | (legacy)                    | Singular fallback for v0.10.x users. Ignored when `SONENTA_PROJECTS` is set (warns). |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonenta/mcp",
-  "version": "0.21.2",
+  "version": "0.22.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",

package/python/README.md

@@ -57,7 +57,7 @@ Single-project setup:
       "env": {
         "SONENTA_API_KEY": "vrb_live_<prefix>.<secret>",
         "SONENTA_PROJECTS": "<project_uuid>",
-        "SONENTA_BASE_URL": "https://api.sonenta.dev"
+        "SONENTA_BASE_URL": "https://api.sonenta.com"
       }
     }
   }
@@ -83,7 +83,7 @@ Restart Claude Desktop. Tools show up in the prompt UI.
 | `SONENTA_API_KEY`   | yes      |                                | API key from Org Settings → API Keys (`SONENTA_TOKEN` also accepted, back-compat)         |
 | `SONENTA_PROJECTS`  | no       | (LLM passes per call)          | CSV of project UUIDs. When >1, the LLM MUST pass `project_uuid` on each tool call.         |
 | `SONENTA_PROJECT`   | no       | (legacy)                       | Singular fallback for v0.10.x users. Ignored when `SONENTA_PROJECTS` is set (warns).      |
-| `SONENTA_BASE_URL`  | no       | `https://api.sonenta.dev`      | Override for self-host or staging (`SONENTA_API_BASE` also accepted, back-compat)         |
+| `SONENTA_BASE_URL`  | no       | `https://api.sonenta.com`      | Override for self-host or staging (`SONENTA_API_BASE` also accepted, back-compat)         |
 
 > Migrating from `verbumia-mcp`? The legacy `VERBUMIA_API_KEY` / `VERBUMIA_TOKEN`
 > / `VERBUMIA_PROJECTS` / `VERBUMIA_BASE_URL` env vars are still accepted, so

package/python/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sonenta-mcp"
-version = "0.21.2"
+version = "0.22.0"
 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"

package/python/verbumia_mcp/__init__.py

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

package/python/verbumia_mcp/config.py

@@ -15,7 +15,7 @@ import os
 import sys
 from dataclasses import dataclass
 
-DEFAULT_API_BASE = "https://api.sonenta.dev"
+DEFAULT_API_BASE = "https://api.sonenta.com"
 
 
 @dataclass(frozen=True)

package/python/verbumia_mcp/tools.py

@@ -239,6 +239,40 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     "additionalProperties": False,
                 },
             ),
+            Tool(
+                name="distribution_info",
+                description=(
+                    "Get the project's CDN distribution status: the public CDN base "
+                    "URL + bundle URL template, the production version, which "
+                    "(language, namespace) bundles are currently published, and any "
+                    "gaps (bundles not yet published). Use to see what client SDKs "
+                    "can fetch right now."
+                ),
+                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.",
+                        }
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="sonenta_guide",
+                description=(
+                    "Get the Sonenta usage guide: a concise, up-to-date overview of "
+                    "how this Sonenta instance works — core concepts, the translation "
+                    "workflow, how to publish to the CDN, and the available MCP tools. "
+                    "Takes no arguments. Call this first when unsure how to use Sonenta."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {},
+                    "additionalProperties": False,
+                },
+            ),
             Tool(
                 name="list_keys",
                 description=(
@@ -1501,6 +1535,79 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     "additionalProperties": False,
                 },
             ),
+            Tool(
+                name="recommend_surfaces",
+                description=(
+                    "Read-only per-key A11Y SURFACE RECOMMENDATIONS (#2): for each key, "
+                    "the a11y surfaces implied by its semantic TYPE, derived from the "
+                    "backend's authoritative key.type -> treatment mapping "
+                    "(A11Y_TREATMENTS_BY_TYPE) — the single source of truth; do NOT "
+                    "reimplement the mapping in the client. Returns {project_uuid, "
+                    "version_uuid, active_a11y_surfaces[], keys_scanned, keys_with_gaps, "
+                    "gaps_by_surface{surface:int}, items:[{key_uuid, key_name, "
+                    "namespace_slug, type, base_role (visible_text|alt_text|"
+                    "accessible_name), recommended_surfaces:[{surface, active, "
+                    "present_in_source}], has_gap}]}. A recommended surface that is "
+                    "active && !present_in_source is a config-satisfied GAP to AUTHOR — "
+                    "hand the actual text off to sonenta-a11y (set_a11y_variant), this "
+                    "tool only tells you WHERE. DEVICE surfaces are not included here. "
+                    "Defaults to the production version."
+                ),
+                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.",
+                        },
+                        "version_id": {
+                            "type": "string",
+                            "description": "Optional version UUID; defaults to the production version.",
+                        },
+                        "namespace_id": {
+                            "type": "string",
+                            "description": "Optional namespace UUID to scope the scan.",
+                        },
+                        "key_id": {
+                            "type": "string",
+                            "description": "Optional single key UUID to scope the scan.",
+                        },
+                        "only_gaps": {
+                            "type": "boolean",
+                            "description": "When true, return only keys that have a gap (has_gap=true).",
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="surface_coverage",
+                description=(
+                    "Read-only COVERAGE BY SURFACE (#3): per active surface, how complete "
+                    "it is. Returns {project_uuid, version_uuid, languages[], keys_total, "
+                    "surfaces:[{surface, label, kind, meaning, eligible_keys, "
+                    "eligible_cells, present_cells, pct, by_language:[{code, eligible, "
+                    "present, pct}]}]}. The `meaning` field tells you how to read `pct`: "
+                    "'a11y_completeness' for a11y surfaces (eligible = type-relevant keys; "
+                    "pct = real fill of NEEDED a11y gaps), 'override_density' for device "
+                    "surfaces (un-overridden cells fall back to the base value — that is "
+                    "NOT broken, just un-customized). Defaults to the production version."
+                ),
+                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.",
+                        },
+                        "version_id": {
+                            "type": "string",
+                            "description": "Optional version UUID; defaults to the production version.",
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+            ),
             Tool(
                 name="get_variants",
                 description=(
@@ -1814,6 +1921,15 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                 project_uuid = _project_uuid(args, client)
                 data = await client.get(f"/v1/mcp/projects/{project_uuid}")
                 return _text(data)
+            if name == "distribution_info":
+                project_uuid = _project_uuid(args, client)
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/distribution"
+                )
+                return _text(data)
+            if name == "sonenta_guide":
+                data = await client.get("/v1/mcp/guide")
+                return _text(data)
             if name == "list_keys":
                 project_uuid = _project_uuid(args, client)
                 params = {
@@ -2296,6 +2412,29 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     return _err("slug is required")
                 await client.delete(f"/v1/mcp/projects/{project_uuid}/surfaces/{slug}")
                 return _text({"deleted": True, "slug": slug})
+            if name == "recommend_surfaces":
+                project_uuid = _project_uuid(args, client)
+                params: dict[str, Any] = {}
+                for opt in ("version_id", "namespace_id", "key_id"):
+                    if args.get(opt):
+                        params[opt] = args[opt]
+                if args.get("only_gaps"):
+                    params["only_gaps"] = "true"
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/recommend-surfaces",
+                    params=params,
+                )
+                return _text(data)
+            if name == "surface_coverage":
+                project_uuid = _project_uuid(args, client)
+                params: dict[str, Any] = {}
+                if args.get("version_id"):
+                    params["version_id"] = args["version_id"]
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/surface-coverage",
+                    params=params,
+                )
+                return _text(data)
             if name == "get_variants":
                 project_uuid = _project_uuid(args, client)
                 key_uuid = args.get("key_uuid")