@sonenta/mcp 0.21.3 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonenta/mcp",
-  "version": "0.21.3",
+  "version": "0.23.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 = "sonenta-mcp"
-version = "0.21.3"
+version = "0.23.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.3"
+__version__ = "0.23.0"

package/python/verbumia_mcp/tools.py

@@ -1535,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=(
@@ -1750,6 +1823,154 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     "additionalProperties": False,
                 },
             ),
+            # --- a11y conformance reports + remediation plan (sprint 111c4658, B5 MCP twins) ---
+            Tool(
+                name="wcag_report",
+                description=(
+                    "Read-only WCAG 2.2 CONFORMANCE report for the content layer Sonenta "
+                    "governs (strings, alt text, accessible names, a11y variants, reading "
+                    "level), evaluated PER LOCALE with a level-AA score. Reports the "
+                    "success criteria decidable from content (1.1.1, 1.3.1, 2.4.4, 2.4.9, "
+                    "3.1.1, 3.1.2, 3.1.5, 4.1.2); SC requiring the rendered DOM (contrast, "
+                    "keyboard, focus) appear ONLY under scope.out_of_scope_sc and are NEVER "
+                    "counted as pass. AAA criteria (2.4.9, 3.1.5) are shown but EXCLUDED "
+                    "from the AA score. conformance.score_pct is the headline AA number "
+                    "(with per-locale breakdown). Read scope.content_layer_sc dynamically — "
+                    "do not hardcode the SC list. Defaults to the production version. "
+                    "0-credit, 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.",
+                        },
+                        "version_id": {
+                            "type": "string",
+                            "description": "Optional version UUID; defaults to the production version.",
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="eaa_statement",
+                description=(
+                    "Read-only EAA / EN 301 549 accessibility conformance STATEMENT for the "
+                    "content layer, per project x locale set (JSON). Maps each covered WCAG "
+                    "2.2 SC to its EN 301 549 clause (e.g. 1.1.1 -> 9.1.1.1) and reports "
+                    "{org, product, version, level:'AA', score_aa_percent, generated_at, "
+                    "standard, criteria_summary[], scope_statement:{attested[], "
+                    "out_of_scope[]}, contact}. Honest scope: attests alt-text / labels / "
+                    "language / plain-language per locale; the rendered-DOM audit is out of "
+                    "scope. Defaults to the production version. 0-credit, 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.",
+                        },
+                        "version_id": {
+                            "type": "string",
+                            "description": "Optional version UUID; defaults to the production version.",
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="a11y_remediation_plan_get",
+                description=(
+                    "Read the a11y REMEDIATION PLAN for the project (or null if none "
+                    "exists). The plan is authored/approved in the dashboard; this tool "
+                    "OBSERVES it. Shape: {version_uuid, status (draft|approved), "
+                    "approved_at, plan:{items:[{key_uuid, locale, surface, decision "
+                    "(apply|ignore), reason?, value?}]}}. The backend mutates nothing on "
+                    "PUT/approve — once status=approved, call a11y_remediation_plan_apply "
+                    "to bulk-execute it. Defaults to the production version. 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.",
+                        },
+                        "version_id": {
+                            "type": "string",
+                            "description": "Optional version UUID; defaults to the production version.",
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="a11y_remediation_plan_apply",
+                description=(
+                    "EXECUTE the APPROVED a11y remediation plan — the agent's bulk-execute "
+                    "entrypoint. Only acts on a plan whose status=approved (poll "
+                    "a11y_remediation_plan_get first); a draft/absent plan is rejected. For "
+                    "each 'apply' item it writes the a11y variant (the item's value, else "
+                    "the current draft override) via the normal variant overlay — "
+                    "non-destructive and reversible (trashable/restorable). 'ignore' items "
+                    "persistently suppress that (key, locale, surface) cell. Returns the "
+                    "execution summary. 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="score_cognitive_local",
+                description=(
+                    "Compute and persist cognitive-difficulty scores from a VALIDATED, "
+                    "deterministic READABILITY metric — the local-first, **0-credit**, "
+                    "no-AI path (SC 3.1.5). English uses Flesch-Kincaid; every other "
+                    "language uses LIX, both normalised to difficulty 0-100 (higher = "
+                    "harder) with a per-language threshold. Writes cognitive_score for the "
+                    "scoped keys; a key enters the reading_level_high queue once its score "
+                    ">= the project threshold. Prefer this over analyze_cognitive (billed "
+                    "AI) for difficulty scoring. Scope with key_uuids and/or namespace_uuid "
+                    "(omit both = whole project). Returns the scoring summary."
+                ),
+                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_uuids": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Restrict scoring to these keys. Omit to scope the whole project (or a namespace).",
+                        },
+                        "namespace_uuid": {
+                            "type": "string",
+                            "description": "Restrict scoring to one namespace by its UUID.",
+                        },
+                        "overwrite": {
+                            "type": "boolean",
+                            "description": "Re-score keys that already have a cognitive_score (default false = only score unscored keys).",
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+            ),
             # --- Source Health: duplicate source strings (#1116; backend #1114, PR #147) ---
             Tool(
                 name="list_source_duplicates",
@@ -2339,6 +2560,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")
@@ -2419,6 +2663,48 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     f"/v1/mcp/projects/{project_uuid}/cognitive/analyze", json=body
                 )
                 return _text(data)
+            # --- a11y conformance reports + remediation plan (sprint 111c4658, B5) ---
+            if name in ("wcag_report", "eaa_statement"):
+                project_uuid = _project_uuid(args, client)
+                params: dict[str, Any] = {}
+                if args.get("version_id"):
+                    params["version_id"] = args["version_id"]
+                segment = "wcag-report" if name == "wcag_report" else "eaa-statement"
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/{segment}", params=params
+                )
+                return _text(data)
+            if name == "a11y_remediation_plan_get":
+                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}/a11y/remediation-plan", params=params
+                )
+                return _text(data)
+            if name == "a11y_remediation_plan_apply":
+                project_uuid = _project_uuid(args, client)
+                body: dict[str, Any] = {}
+                if args.get("version_id"):
+                    body["version_id"] = args["version_id"]
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/a11y/remediation-plan/apply",
+                    json=body,
+                )
+                return _text(data)
+            if name == "score_cognitive_local":
+                project_uuid = _project_uuid(args, client)
+                body: dict[str, Any] = {}
+                for opt in ("key_uuids", "namespace_uuid"):
+                    if args.get(opt):
+                        body[opt] = args[opt]
+                if args.get("overwrite"):
+                    body["overwrite"] = True
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/cognitive/score-local", json=body
+                )
+                return _text(data)
             # --- Source Health: duplicates (#1116; backend #1114, PR #147) ---
             if name == "list_source_duplicates":
                 project_uuid = _project_uuid(args, client)