@sonenta/mcp 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonenta/mcp",
-  "version": "0.18.0",
+  "version": "0.19.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.18.0"
+version = "0.19.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.18.0"
+__version__ = "0.19.0"

package/python/verbumia_mcp/tools.py

@@ -9,9 +9,9 @@ Tools (V1 MCP surface; glossary_* added 2026-05-24; reports + trash added 2026-0
 - missing_keys_stats      — count-only summary of missing events (drives pagination)
 - acknowledge_missing_keys— batch-resolve missing events (cleanup the dashboard)
 - create_namespace        — idempotent namespace creation (slug validated, slug_invalid on bad input)
-- create_key              — idempotent key creation, optionally seeds source value
+- create_key              — idempotent key creation; optionally seeds source value + sets semantic `type`
 - create_keys_bulk        — batch create_key (up to 500/call, per-item results)
-- update_key              — edit a key's SOURCE value in place (PATCH); demotes reviewed/approved targets to needs-review
+- update_key              — edit a key's SOURCE value / `type` / description in place (PATCH); demotes reviewed/approved targets to needs-review
 - update_keys_bulk        — batch update_key (up to 500/call, per-item results)
 - propose_translation     — submit a translation value (auto-creates the key if missing)
 - propose_translations_bulk— batch propose_translation (up to 500/call, per-item results)
@@ -84,6 +84,30 @@ from .client import VerbumiaApiError, VerbumiaClient
 # visible text. `surfaceKinds` in the variants matrix tags each as a11y.
 A11Y_SURFACES = ("aria_label", "alt_text", "screen_reader", "plain_language")
 
+# Key semantic types (a11y key.type pivot). Default "text". The type decides
+# which a11y treatments a key offers (e.g. an `image` key's base value IS its
+# alt text; a `button` offers aria_label) — the engine gates variant/a11y tools
+# by type server-side, so listing these here is just for create/update_key.
+KEY_TYPES = (
+    "text",
+    "heading",
+    "label",
+    "caption",
+    "badge",
+    "tooltip",
+    "error_message",
+    "toast",
+    "button",
+    "link",
+    "menu_item",
+    "input_placeholder",
+    "input_label",
+    "image",
+    "icon",
+    "meta_title",
+    "meta_description",
+)
+
 
 def _project_uuid(arguments: dict | None, client: VerbumiaClient) -> str:
     """Resolve project_uuid from per-call args or the configured env scope.
@@ -371,7 +395,8 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     "Returns created=false if the key already exists. When "
                     "source_value is supplied AND the project has a source "
                     "language, the value is also written as a source-language "
-                    "translation in the same call."
+                    "translation in the same call. Pass `type` (default 'text') to "
+                    "set the key's semantic type, which decides its a11y treatments."
                 ),
                 inputSchema={
                     "type": "object",
@@ -395,6 +420,12 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                         "description": {"type": "string"},
                         "plurals": {"type": "boolean", "default": False},
                         "max_length": {"type": "integer", "minimum": 1},
+                        "type": {
+                            "type": "string",
+                            "enum": list(KEY_TYPES),
+                            "default": "text",
+                            "description": "Semantic key type (default 'text'). Decides which a11y treatments apply — e.g. 'image' (base value is the alt text), 'icon' (base is the accessible name), 'button'/'link' (offer aria_label), 'heading'/'label' (plain_language/screen_reader).",
+                        },
                     },
                     "required": ["namespace", "name"],
                     "additionalProperties": False,
@@ -465,6 +496,7 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                                     "description": {"type": "string"},
                                     "plurals": {"type": "boolean", "default": False},
                                     "max_length": {"type": "integer", "minimum": 1},
+                                    "type": {"type": "string", "enum": list(KEY_TYPES), "default": "text", "description": "Semantic key type (default 'text'); see create_key."},
                                 },
                                 "required": ["namespace", "name"],
                                 "additionalProperties": False,
@@ -478,7 +510,8 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
             Tool(
                 name="update_key",
                 description=(
-                    "Edit a key's SOURCE-language value in place. Preserves the "
+                    "Edit a key in place — its SOURCE-language value, its `type`, "
+                    "and/or its description (pass at least one). Preserves the "
                     "key and its history (version bump + history revision + audit). "
                     "Address the key by EITHER key_uuid (preferred; from list_keys) "
                     "OR namespace + name — exactly one of the two. When the source "
@@ -516,8 +549,13 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                             "type": "string",
                             "description": "Optional: also update the key's description.",
                         },
+                        "type": {
+                            "type": "string",
+                            "enum": list(KEY_TYPES),
+                            "description": "Optional: reclassify the key's semantic type (see create_key). Changing the type re-gates which a11y treatments the key offers.",
+                        },
                     },
-                    "required": ["source_value"],
+                    "required": [],
                     "additionalProperties": False,
                 },
             ),
@@ -552,8 +590,9 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                                     "name": {"type": "string", "description": "Dot-notation key name (use with namespace)."},
                                     "source_value": {"type": "string", "description": "New source-language value to write."},
                                     "description": {"type": "string", "description": "Optional: also update the key's description."},
+                                    "type": {"type": "string", "enum": list(KEY_TYPES), "description": "Optional: reclassify the key's semantic type (see create_key)."},
                                 },
-                                "required": ["source_value"],
+                                "required": [],
                                 "additionalProperties": False,
                             },
                         },
@@ -1135,6 +1174,9 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     "locale lacks it), alt_missing (image key with no source alt_text), "
                     "reading_level_high (hard source text + no plain_language), "
                     "a11y_variant_absent (a require_surface is missing in the source). "
+                    "Gaps are TYPE-AWARE: only treatments relevant to each key's type are "
+                    "reported (e.g. alt_missing only on image keys, aria gaps only on "
+                    "buttons/links/inputs), so a text key is never flagged for aria/alt. "
                     "Defaults to the production version. Surfaced verbatim — use "
                     "list_a11y_gaps for just the actionable item list."
                 ),
@@ -1409,12 +1451,15 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
             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 "
+                    "Read the full VARIANT MATRIX for one key (task 928): every surface "
+                    "OFFERED for the key 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."
+                    "lists `surfaces` and `surfaceKinds` ({surface: 'device'|'a11y'}) — "
+                    "these are the key's offered surfaces only: the project's active "
+                    "device surfaces plus the a11y treatments relevant to the key's TYPE "
+                    "(e.g. a text key shows no aria/alt). This is the source of truth for "
+                    "which surfaces set_variant will accept. Address by key_uuid (from "
+                    "list_keys). Surfaced verbatim."
                 ),
                 inputSchema={
                     "type": "object",
@@ -1440,11 +1485,13 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     "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.)"
+                    "Stored as a draft. 422 unless the surface is OFFERED for this key — "
+                    "an active device surface (see list_surfaces) OR an a11y treatment "
+                    "relevant to the key's TYPE (e.g. no aria_label on a text key; see "
+                    "get_variants for the key's offered 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",
@@ -1627,7 +1674,7 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     "namespace": args["namespace"],
                     "name": args["name"],
                 }
-                for opt in ("source_value", "description", "plurals", "max_length"):
+                for opt in ("source_value", "description", "plurals", "max_length", "type"):
                     if opt in args:
                         body[opt] = args[opt]
                 data = await client.post(
@@ -1659,16 +1706,18 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                 return _text(data)
             if name == "update_key":
                 project_uuid = _project_uuid(args, client)
-                if "source_value" not in args:
-                    return _err("source_value is required")
+                if not any(k in args for k in ("source_value", "type", "description")):
+                    return _err(
+                        "nothing to update: pass at least one of source_value, type, description"
+                    )
                 has_uuid = bool(args.get("key_uuid"))
                 has_name = bool(args.get("namespace")) and bool(args.get("name"))
                 if has_uuid == has_name:
                     return _err(
                         "address the key by exactly one of key_uuid OR (namespace + name)"
                     )
-                body: dict[str, Any] = {"source_value": args["source_value"]}
-                for opt in ("key_uuid", "namespace", "name", "description"):
+                body: dict[str, Any] = {}
+                for opt in ("source_value", "key_uuid", "namespace", "name", "description", "type"):
                     if opt in args:
                         body[opt] = args[opt]
                 data = await client.patch(