@sonenta/mcp 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonenta/mcp",
-  "version": "0.20.0",
+  "version": "0.21.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.20.0"
+version = "0.21.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.20.0"
+__version__ = "0.21.0"

package/python/verbumia_mcp/tools.py

@@ -25,6 +25,8 @@ Tools (V1 MCP surface; glossary_* added 2026-05-24; reports + trash added 2026-0
 - glossary_delete         — delete an entry by uuid
 - health_report           — read-only project source-health report (#752)
 - coverage_report         — read-only project translation-coverage report (#752)
+- list_source_duplicates  — read-only list of duplicate-source-value groups (#1116)
+- set_duplicate_status    — triage a duplicate group: to_fix | allowed | resolved (#1116)
 - delete_keys_bulk        — soft-delete (trash) keys by key_uuid; restorable
 - restore_keys_bulk       — restore trashed keys by key_uuid
 - list_trash              — list trashed (soft-deleted) keys (cursor paginated)
@@ -111,6 +113,38 @@ KEY_TYPES = (
     "meta_description",
 )
 
+# Human/LLM guidance for choosing a key's `type`. Embedded in the create_key /
+# update_key tool descriptions so an agent types keys correctly instead of
+# leaving everything as the "text" default. The type DRIVES which a11y
+# treatments + cognitive (plain-language) scoring a key gets, so it is the input
+# that makes the a11y tooling work.
+KEY_TYPE_GUIDANCE = (
+    "Set this at CREATION — do NOT leave everything as 'text'. The type drives "
+    "which a11y treatments the key offers (and whether it gets cognitive / "
+    "plain-language scoring), so correct typing is what lets the a11y tooling "
+    "work. Pick by the string's UI role:\n"
+    "- text — body / paragraph copy (offers plain_language, screen_reader)\n"
+    "- heading — a title or section heading (plain_language, screen_reader)\n"
+    "- label — a standalone short label (plain_language, screen_reader)\n"
+    "- caption — image caption / helper / secondary text (plain_language, screen_reader)\n"
+    "- button — a button's label (offers aria_label, screen_reader)\n"
+    "- link — a hyperlink / anchor label (aria_label, screen_reader)\n"
+    "- menu_item — a navigation / menu entry (aria_label, screen_reader)\n"
+    "- input_placeholder — a form input placeholder (aria_label)\n"
+    "- input_label — a form field's label (aria_label)\n"
+    "- tooltip — tooltip text (screen_reader)\n"
+    "- badge — a small status / count badge (screen_reader)\n"
+    "- error_message — a validation / error message (screen_reader)\n"
+    "- toast — a transient toast / snackbar notification (screen_reader)\n"
+    "- image — an image; THIS key's value IS the alt text\n"
+    "- icon — an icon; THIS key's value IS the accessible name (aria)\n"
+    "- meta_title — an SEO page <title> (no a11y treatment)\n"
+    "- meta_description — an SEO meta description (no a11y treatment)\n"
+    "Default 'text'. Reclassify existing keys later with update_key / "
+    "update_keys_bulk (type-only, no source_value needed). The current type is "
+    "returned by list_keys so you can audit and fix mis-typed keys."
+)
+
 
 def _project_uuid(arguments: dict | None, client: VerbumiaClient) -> str:
     """Resolve project_uuid from per-call args or the configured env scope.
@@ -208,13 +242,16 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
             Tool(
                 name="list_keys",
                 description=(
-                    "List translation keys with their source-language value and "
-                    "per-language translations. Designed for bulk translation: "
-                    "Claude can scan the result and propose translations for "
-                    "every key that's still missing in a target language. "
-                    "Filters: namespace slug, status_filter (only keys with at "
-                    "least one translation in that status), language_code "
-                    "(restrict translations[] to a single language)."
+                    "List translation keys with their source-language value, their "
+                    "semantic `type`, and per-language translations. Designed for "
+                    "bulk translation: Claude can scan the result and propose "
+                    "translations for every key that's still missing in a target "
+                    "language. Each key's `type` lets you AUDIT typing and reclassify "
+                    "mis-typed keys (e.g. a button left as 'text') via update_key / "
+                    "update_keys_bulk so the a11y treatments apply. Filters: "
+                    "namespace slug, status_filter (only keys with at least one "
+                    "translation in that status), language_code (restrict "
+                    "translations[] to a single language)."
                 ),
                 inputSchema={
                     "type": "object",
@@ -398,8 +435,11 @@ 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. Pass `type` (default 'text') to "
-                    "set the key's semantic type, which decides its a11y treatments."
+                    "translation in the same call. ALWAYS set `type` to the key's "
+                    "semantic role (button / link / heading / image / icon / "
+                    "input_label / …) — do NOT leave it as the default 'text'; the "
+                    "type drives the key's a11y treatments. See the `type` field for "
+                    "the full 17-type taxonomy and when to use each."
                 ),
                 inputSchema={
                     "type": "object",
@@ -427,7 +467,7 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                             "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).",
+                            "description": "Semantic key type. " + KEY_TYPE_GUIDANCE,
                         },
                     },
                     "required": ["namespace", "name"],
@@ -441,7 +481,11 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     "doesn't exist (write-through). Status is set to draft (or "
                     "translated if explicitly requested); reviewer/approved "
                     "promotion requires a human reviewer. Identifies the key "
-                    "by namespace + key name + language_code — no uuids needed."
+                    "by namespace + key name + language_code — no uuids needed. "
+                    "The response carries `variable_warnings: {missing, extra}` "
+                    "(null when interpolation variables match the source) — a "
+                    "non-blocking flag for placeholder drift; check it and fix the "
+                    "value if set."
                 ),
                 inputSchema={
                     "type": "object",
@@ -499,7 +543,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."},
+                                    "type": {"type": "string", "enum": list(KEY_TYPES), "default": "text", "description": "Semantic key type — set per item by the string's UI role (button / image / heading / …); do NOT default everything to 'text'. See create_key's `type` field for the full taxonomy and why it matters for a11y."},
                                 },
                                 "required": ["namespace", "name"],
                                 "additionalProperties": False,
@@ -615,7 +659,10 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     "(same namespace+key+language twice) error per item; status is "
                     "draft (or translated if requested), reviewed/approved require "
                     "a human reviewer. NO server-side translation — values come "
-                    "from you. Use this instead of N propose_translation calls."
+                    "from you. Use this instead of N propose_translation calls. "
+                    "Each result carries `variable_warnings: {missing, extra}` "
+                    "(null when interpolation variables match the source) flagging "
+                    "placeholder drift, non-blocking."
                 ),
                 inputSchema={
                     "type": "object",
@@ -685,7 +732,10 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                 description=(
                     "Lint a JSON i18next blob against the project: checks for "
                     "missing keys, extra keys, and placeholder parity ({var}, "
-                    "{{var}}, %{var}) vs the source language."
+                    "{{var}}, %{var}) vs the source language. Each "
+                    "`placeholder_mismatches[]` item carries `expected` / `got` plus "
+                    "`missing` (source variables absent from the translation) and "
+                    "`extra` (variables in the translation unknown to the source)."
                 ),
                 inputSchema={
                     "type": "object",
@@ -1666,6 +1716,81 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     "additionalProperties": False,
                 },
             ),
+            # --- Source Health: duplicate source strings (#1116; backend #1114, PR #147) ---
+            Tool(
+                name="list_source_duplicates",
+                description=(
+                    "List groups of keys that SHARE an identical source-language "
+                    "value (Source Health duplicates, #1116). Each group = "
+                    "{source_value, key_count, key_names[], key_uuids[], status, note}. "
+                    "Duplicates inflate translation cost and drift (the same string "
+                    "translated N ways), so this is the worklist the "
+                    "sonenta-source-health agent repairs. Status is tracked PROJECT-WIDE "
+                    "per source_value: to_fix (needs attention; the default), allowed "
+                    "(intentional duplicate — listed+flagged but excluded from "
+                    "total_issues), resolved (already fixed — re-scan confirms). Filter "
+                    "by status to focus. READ-ONLY."
+                ),
+                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.",
+                        },
+                        "status": {
+                            "type": "string",
+                            "enum": ["to_fix", "allowed", "resolved"],
+                            "description": "Filter to duplicate groups in this triage status. Omit for all.",
+                        },
+                        "version_id": {
+                            "type": "string",
+                            "description": "Optional version UUID; defaults to the production version.",
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="set_duplicate_status",
+                description=(
+                    "Set the triage STATUS of one duplicate group, addressed by its "
+                    "shared source_value (Source Health duplicates, #1116). status ∈ "
+                    "to_fix (this duplication should be repaired — the default; "
+                    "clears any override), allowed (an intentional, sanctioned "
+                    "duplicate — kept but EXCLUDED from total_issues, stop flagging "
+                    "it), resolved (the duplication has been fixed — removed from the "
+                    "list, a re-scan confirms). An invalid status returns 422. Status "
+                    "persists PROJECT-WIDE per source_value. Use this after the "
+                    "sonenta-source-health agent has de-duplicated the keys, to mark "
+                    "the group resolved, or to whitelist a legitimate duplicate as "
+                    "allowed. An optional note records WHY (audit trail)."
+                ),
+                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-language value identifying the duplicate group (from list_source_duplicates).",
+                        },
+                        "status": {
+                            "type": "string",
+                            "enum": ["to_fix", "allowed", "resolved"],
+                            "description": "New triage status for the group.",
+                        },
+                        "note": {
+                            "type": "string",
+                            "description": "Optional human/agent note recording why the status was set (audit trail).",
+                        },
+                    },
+                    "required": ["source_value", "status"],
+                    "additionalProperties": False,
+                },
+            ),
         ]
 
     @server.call_tool()
@@ -2246,6 +2371,39 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     f"/v1/mcp/projects/{project_uuid}/cognitive/analyze", json=body
                 )
                 return _text(data)
+            # --- Source Health: duplicates (#1116; backend #1114, PR #147) ---
+            if name == "list_source_duplicates":
+                project_uuid = _project_uuid(args, client)
+                params = {
+                    k: v
+                    for k, v in {
+                        "status": args.get("status"),
+                        "version_id": args.get("version_id"),
+                    }.items()
+                    if v is not None
+                }
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/source-duplicates",
+                    params=params,
+                )
+                return _text(data)
+            if name == "set_duplicate_status":
+                project_uuid = _project_uuid(args, client)
+                if not args.get("source_value"):
+                    return _err("source_value is required")
+                if not args.get("status"):
+                    return _err("status is required")
+                body: dict[str, Any] = {
+                    "source_value": args["source_value"],
+                    "status": args["status"],
+                }
+                if args.get("note"):
+                    body["note"] = args["note"]
+                data = await client.put(
+                    f"/v1/mcp/projects/{project_uuid}/source-duplicates/status",
+                    json=body,
+                )
+                return _text(data)
             return _err(f"unknown tool: {name}")
         except VerbumiaApiError as exc:
             return _err(f"API {exc.status}: {exc.body}")