@sonenta/mcp 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonenta/mcp",
-  "version": "0.17.0",
+  "version": "0.18.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/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "verbumia-mcp"
-version = "0.17.0"
+version = "0.18.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"

package/python/verbumia_mcp/__init__.py

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

package/python/verbumia_mcp/tools.py

@@ -35,15 +35,24 @@ Tools (V1 MCP surface; glossary_* added 2026-05-24; reports + trash added 2026-0
 - list_a11y_gaps          — actionable a11y gaps (filtered items[] of a11y_report)
 - set_a11y_variant        — upsert one a11y variant override (key, language, surface)
 - delete_a11y_variant     — delete one a11y variant override (cell re-inherits base value)
+- list_surfaces           — list the project's configurable surfaces (device + a11y; #928)
+- create_surface          — create a custom DEVICE surface (a11y is a fixed set)
+- update_surface          — rename / toggle-active a surface (deactivate is soft)
+- delete_surface          — delete a custom surface (builtins: deactivate only)
+- get_variants            — full variant matrix for one key (every active surface x language; #928)
+- set_variant             — upsert one variant override for ANY active surface (device or a11y)
+- delete_variant          — delete one variant override for any surface (cell re-inherits base)
 
 A11y (accessibility) tools (a11y V1) extend the variant engine with four SEMANTIC
 surfaces — aria_label / alt_text / screen_reader / plain_language — orthogonal to
-the visible text. The report hits `/v1/mcp/projects/{id}/a11y-report`; set/delete
-use the mcp:* code-addressed route
-`/v1/mcp/projects/{id}/keys/{key_uuid}/a11y-variants/{language_code}/{surface}`
-(locale reinjected straight from an a11y_report item). estimate/generate/translate
-are billed in credits. All are thin HTTP wrappers surfaced verbatim. Every a11y
-tool is reachable with the same `mcp:*` key as the rest of the MCP surface.
+the visible text. The report hits `/v1/mcp/projects/{id}/a11y-report`. Variant
+writes (set_variant / delete_variant, and the a11y-named set_a11y_variant /
+delete_a11y_variant) use the mcp:* code-addressed GENERIC route
+`/v1/mcp/projects/{id}/keys/{key_uuid}/variants/{language_code}/{surface}`, which
+accepts any surface ACTIVE for the project (device or a11y; #928) — locale
+reinjected straight from a report/matrix item. estimate/generate/translate are
+billed in credits. All are thin HTTP wrappers surfaced verbatim. Every tool is
+reachable with the same `mcp:*` key as the rest of the MCP surface.
 
 list_keys and list_untranslated_keys accept `include_glossary_hints=true` to
 attach backend-matched `glossary_hints[]` per key. All glossary matching is
@@ -1287,6 +1296,216 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     "additionalProperties": False,
                 },
             ),
+            Tool(
+                name="list_surfaces",
+                description=(
+                    "List the project's configurable SURFACES (task 928): the device "
+                    "and a11y surfaces variants can be authored for. Returns "
+                    "{surfaces:[{slug, label, kind, builtin, active}]} where kind is "
+                    "'device' or 'a11y'. An un-customized project lazily defaults to the "
+                    "builtins — device: desktop/mobile/tablet; a11y: aria_label/alt_text/"
+                    "screen_reader/plain_language — all active. Only ACTIVE surfaces accept "
+                    "variant writes and get published to the CDN."
+                ),
+                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="create_surface",
+                description=(
+                    "Create a CUSTOM DEVICE surface for the project (task 928), e.g. "
+                    "'watch', 'tv', 'kiosk'. Device surfaces are extensible; a11y surfaces "
+                    "are a FIXED semantic set — creating an a11y slug (e.g. aria_label) is "
+                    "rejected with 422. Returns the updated surface catalog. Builtins need "
+                    "no creation (they exist lazily)."
+                ),
+                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.",
+                        },
+                        "slug": {
+                            "type": "string",
+                            "pattern": "^[a-z0-9_-]{1,40}$",
+                            "description": "Surface slug: lowercase letters, digits, '_' or '-', 1-40 chars (e.g. 'watch').",
+                        },
+                        "label": {
+                            "type": "string",
+                            "description": "Optional human-readable label (defaults from the slug).",
+                        },
+                    },
+                    "required": ["slug"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="update_surface",
+                description=(
+                    "Rename and/or toggle a surface (task 928): set its `label` and/or "
+                    "`active`. Deactivating is SOFT — existing variants are RETAINED but "
+                    "hidden and dropped from the CDN until reactivated (which republishes "
+                    "them); the response `affected_variants` reports how many are impacted. "
+                    "Builtins can be toggled/renamed but not deleted. Returns "
+                    "{surfaces, affected_variants}."
+                ),
+                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.",
+                        },
+                        "slug": {
+                            "type": "string",
+                            "description": "Slug of the surface to update.",
+                        },
+                        "label": {
+                            "type": "string",
+                            "description": "New human-readable label (rename).",
+                        },
+                        "active": {
+                            "type": "boolean",
+                            "description": "Activate (true) or soft-deactivate (false) the surface.",
+                        },
+                    },
+                    "required": ["slug"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="delete_surface",
+                description=(
+                    "Delete a CUSTOM surface (task 928). Builtins cannot be deleted — "
+                    "deactivate them with update_surface(active=false) instead (a 422/409 "
+                    "is returned if you try to delete a builtin). Deleting a custom surface "
+                    "removes it from the catalog."
+                ),
+                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.",
+                        },
+                        "slug": {
+                            "type": "string",
+                            "description": "Slug of the custom surface to delete.",
+                        },
+                    },
+                    "required": ["slug"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="get_variants",
+                description=(
+                    "Read the full VARIANT MATRIX for one key (task 928): every ACTIVE "
+                    "surface (device + a11y) x every project language, with each cell's "
+                    "{override, value, resolvedValue, status, drift, ...}. The response "
+                    "also lists `surfaces` (active) and `surfaceKinds` ({surface: "
+                    "'device'|'a11y'}). Address the key by key_uuid (from list_keys). "
+                    "Surfaced verbatim."
+                ),
+                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.",
+                        },
+                        "key_uuid": {
+                            "type": "string",
+                            "description": "Key UUID (from list_keys).",
+                        },
+                    },
+                    "required": ["key_uuid"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="set_variant",
+                description=(
+                    "Upsert ONE variant override for (key, language, surface) for ANY "
+                    "surface active on the project (task 928) — device (desktop / mobile / "
+                    "tablet / custom like watch / tv) OR a11y (aria_label / alt_text / "
+                    "screen_reader / plain_language). Address by key_uuid + locale CODE + "
+                    "surface slug (the fields get_variants / list_keys already give you). "
+                    "Stored as a draft. 422 if the surface is not active for the project "
+                    "(see list_surfaces); 409 if the cell is already reviewed/approved "
+                    "(never overwritten). Returns {key_uuid, surface, language_code, "
+                    "value, status}. (For a11y specifically you can also use "
+                    "set_a11y_variant.)"
+                ),
+                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.",
+                        },
+                        "key_uuid": {
+                            "type": "string",
+                            "description": "Key UUID (from list_keys / get_variants).",
+                        },
+                        "language_code": {
+                            "type": "string",
+                            "description": "Target locale CODE, e.g. 'fr'. Backend resolves it; 404 if unknown.",
+                        },
+                        "surface": {
+                            "type": "string",
+                            "description": "Surface slug — any surface ACTIVE for the project (device or a11y). See list_surfaces.",
+                        },
+                        "value": {
+                            "type": "string",
+                            "description": "The variant text value for this (key, language, surface).",
+                        },
+                    },
+                    "required": ["key_uuid", "language_code", "surface", "value"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="delete_variant",
+                description=(
+                    "Delete ONE variant override for (key, language, surface), for ANY "
+                    "surface (device or a11y) — task 928. The cell re-inherits the base "
+                    "value; a 404 means there was no override. Address by key_uuid + "
+                    "language_code + surface (same as set_variant)."
+                ),
+                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.",
+                        },
+                        "key_uuid": {
+                            "type": "string",
+                            "description": "Key UUID (from list_keys / get_variants).",
+                        },
+                        "language_code": {
+                            "type": "string",
+                            "description": "Target locale CODE, e.g. 'fr'.",
+                        },
+                        "surface": {
+                            "type": "string",
+                            "description": "Surface slug (device or a11y) to clear.",
+                        },
+                    },
+                    "required": ["key_uuid", "language_code", "surface"],
+                    "additionalProperties": False,
+                },
+            ),
         ]
 
     @server.call_tool()
@@ -1726,11 +1945,13 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     return _err("key_uuid, language_code and surface are required")
                 if surface not in A11Y_SURFACES:
                     return _err(f"surface must be one of {', '.join(A11Y_SURFACES)}")
-                # mcp:* code-addressed route: backend resolves the locale code -> uuid
-                # and validates the a11y surface server-side.
+                # mcp:* code-addressed GENERIC variant route (covers a11y + device;
+                # task 928). Backend resolves the locale code -> uuid and validates the
+                # surface is active server-side. (The legacy /a11y-variants/ path still
+                # works for back-compat, but /variants/ is canonical.)
                 path = (
                     f"/v1/mcp/projects/{project_uuid}/keys/{key_uuid}"
-                    f"/a11y-variants/{language_code}/{surface}"
+                    f"/variants/{language_code}/{surface}"
                 )
                 if name == "delete_a11y_variant":
                     await client.delete(path)
@@ -1746,6 +1967,79 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     return _err("value is required")
                 data = await client.put(path, json={"value": args["value"]})
                 return _text(data)
+            if name == "list_surfaces":
+                project_uuid = _project_uuid(args, client)
+                data = await client.get(f"/v1/mcp/projects/{project_uuid}/surfaces")
+                return _text(data)
+            if name == "create_surface":
+                project_uuid = _project_uuid(args, client)
+                if not args.get("slug"):
+                    return _err("slug is required")
+                body: dict[str, Any] = {"slug": args["slug"]}
+                if "label" in args:
+                    body["label"] = args["label"]
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/surfaces", json=body
+                )
+                return _text(data)
+            if name == "update_surface":
+                project_uuid = _project_uuid(args, client)
+                slug = args.get("slug")
+                if not slug:
+                    return _err("slug is required")
+                body: dict[str, Any] = {}
+                for opt in ("label", "active"):
+                    if opt in args:
+                        body[opt] = args[opt]
+                if not body:
+                    return _err("nothing to update: pass label and/or active")
+                data = await client.put(
+                    f"/v1/mcp/projects/{project_uuid}/surfaces/{slug}", json=body
+                )
+                return _text(data)
+            if name == "delete_surface":
+                project_uuid = _project_uuid(args, client)
+                slug = args.get("slug")
+                if not slug:
+                    return _err("slug is required")
+                await client.delete(f"/v1/mcp/projects/{project_uuid}/surfaces/{slug}")
+                return _text({"deleted": True, "slug": slug})
+            if name == "get_variants":
+                project_uuid = _project_uuid(args, client)
+                key_uuid = args.get("key_uuid")
+                if not key_uuid:
+                    return _err("key_uuid is required")
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/keys/{key_uuid}/variants"
+                )
+                return _text(data)
+            if name in ("set_variant", "delete_variant"):
+                project_uuid = _project_uuid(args, client)
+                key_uuid = args.get("key_uuid")
+                language_code = args.get("language_code")
+                surface = args.get("surface")
+                if not key_uuid or not language_code or not surface:
+                    return _err("key_uuid, language_code and surface are required")
+                # generic variant route: backend validates the surface is active (422)
+                # and guards reviewed/approved cells (409).
+                path = (
+                    f"/v1/mcp/projects/{project_uuid}/keys/{key_uuid}"
+                    f"/variants/{language_code}/{surface}"
+                )
+                if name == "delete_variant":
+                    await client.delete(path)
+                    return _text(
+                        {
+                            "deleted": True,
+                            "key_uuid": key_uuid,
+                            "language_code": language_code,
+                            "surface": surface,
+                        }
+                    )
+                if "value" not in args:
+                    return _err("value is required")
+                data = await client.put(path, json={"value": args["value"]})
+                return _text(data)
             return _err(f"unknown tool: {name}")
         except VerbumiaApiError as exc:
             return _err(f"API {exc.status}: {exc.body}")