@sonenta/mcp 0.22.0 → 0.24.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.com"
+        "SONENTA_BASE_URL": "https://api.sonenta.dev"
       }
     }
   }
@@ -63,8 +63,8 @@ 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.com`   | Self-host / staging override. `SONENTA_API_BASE` accepted (back-compat) |
+| `SONENTA_API_KEY`   | yes*    |                             | Bearer ApiKey token. `SONENTA_TOKEN` accepted (back-compat). *Optional if you ran `sonenta login` — the server reads `~/.sonenta/credentials`. |
+| `SONENTA_BASE_URL`  | no       | `https://api.sonenta.dev`   | 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.22.0",
+  "version": "0.24.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.com"
+        "SONENTA_BASE_URL": "https://api.sonenta.dev"
       }
     }
   }
@@ -80,10 +80,10 @@ Restart Claude Desktop. Tools show up in the prompt UI.
 
 | Variable             | Required | Default                        | Description                                                                                |
 |----------------------|----------|--------------------------------|--------------------------------------------------------------------------------------------|
-| `SONENTA_API_KEY`   | yes      |                                | API key from Org Settings → API Keys (`SONENTA_TOKEN` also accepted, back-compat)         |
+| `SONENTA_API_KEY`   | yes*    |                                | API key from Org Settings → API Keys (`SONENTA_TOKEN` also accepted). *Optional if you ran `sonenta login` — the server then reads `~/.sonenta/credentials`. |
 | `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.com`      | Override for self-host or staging (`SONENTA_API_BASE` also accepted, back-compat)         |
+| `SONENTA_BASE_URL`  | no       | `https://api.sonenta.dev`      | 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.22.0"
+version = "0.24.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.22.0"
+__version__ = "0.24.0"

package/python/verbumia_mcp/config.py

@@ -1,21 +1,69 @@
 """Runtime configuration loaded from environment variables.
 
 The MCP server is invoked by clients like Claude Desktop, which pass `env`
-entries through to the spawned process. We never read a config file — env
-vars are the only contract.
+entries through to the spawned process. Env vars are the primary contract.
 
 Canonical env vars are SONENTA_*. The legacy VERBUMIA_* names are still
 accepted (deprecate-not-remove) so existing MCP client configs keep working;
 the SONENTA_* name wins when both are set.
+
+One exception to "env only": when no API key is in the env, we fall back to
+the CLI credentials store (`~/.sonenta/credentials`, written by `sonenta
+login`). That lets the auto-wired `.mcp.json` carry NO secret — just the host
+and project — and the server resolves the key from the developer's login at
+startup. CI / headless still pass SONENTA_API_KEY explicitly.
 """
 
 from __future__ import annotations
 
+import json
 import os
 import sys
 from dataclasses import dataclass
-
-DEFAULT_API_BASE = "https://api.sonenta.com"
+from pathlib import Path
+
+DEFAULT_API_BASE = "https://api.sonenta.dev"
+
+# CLI credentials store (written by `sonenta login`). Canonical ~/.sonenta,
+# legacy ~/.verbumia read as a fallback. Shape:
+#   {"default": "<host>", "hosts": {"<host>": {"api_key": "...", ...}}}
+_CREDENTIALS_PATHS = (
+    Path.home() / ".sonenta" / "credentials",
+    Path.home() / ".verbumia" / "credentials",
+)
+
+
+def _credentials_token(api_base: str) -> str:
+    """Resolve an API key from the CLI credentials store for `api_base`.
+
+    Lets the MCP server work with NO secret in its env / `.mcp.json` when the
+    user has logged in via `sonenta login`: we read the same creds file the CLI
+    writes and pick the key for the configured host (falling back to the file's
+    `default` host, then a sole entry). Returns "" when nothing resolves.
+    """
+    target = api_base.rstrip("/")
+    for path in _CREDENTIALS_PATHS:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        hosts = data.get("hosts") if isinstance(data, dict) else None
+        if not isinstance(hosts, dict):
+            continue
+        for key in (target, api_base, data.get("default")):
+            entry = hosts.get(key) if isinstance(key, str) else None
+            if isinstance(entry, dict):
+                tok = str(entry.get("api_key", "")).strip()
+                if tok:
+                    return tok
+        # A single-account creds file: use it regardless of the host key.
+        if len(hosts) == 1:
+            entry = next(iter(hosts.values()))
+            if isinstance(entry, dict):
+                tok = str(entry.get("api_key", "")).strip()
+                if tok:
+                    return tok
+    return ""
 
 
 @dataclass(frozen=True)
@@ -59,24 +107,28 @@ def _env(*names: str) -> str:
 
 
 def load_config() -> Config:
-    # Auth key. Canonical: SONENTA_API_KEY. Accepted fallbacks (in order):
-    # SONENTA_TOKEN, then the legacy VERBUMIA_API_KEY / VERBUMIA_TOKEN.
-    token = _env("SONENTA_API_KEY", "SONENTA_TOKEN", "VERBUMIA_API_KEY", "VERBUMIA_TOKEN")
-    if not token:
-        raise RuntimeError(
-            "SONENTA_API_KEY is required. Generate one in Sonenta → Org Settings → "
-            "API Keys and add it to your MCP client config (e.g. Claude Desktop's "
-            "mcp.json `env`). SONENTA_TOKEN — and the legacy VERBUMIA_API_KEY / "
-            "VERBUMIA_TOKEN — are also accepted for back-compat."
-        )
-
-    # API base. Canonical: SONENTA_BASE_URL. Fallbacks: SONENTA_API_BASE, then
-    # legacy VERBUMIA_BASE_URL / VERBUMIA_API_BASE, then the default host.
+    # API base FIRST — the creds fallback below keys the API key on this host.
+    # Canonical: SONENTA_BASE_URL. Fallbacks: SONENTA_API_BASE, then legacy
+    # VERBUMIA_BASE_URL / VERBUMIA_API_BASE, then the default host.
     api_base = (
         _env("SONENTA_BASE_URL", "SONENTA_API_BASE", "VERBUMIA_BASE_URL", "VERBUMIA_API_BASE")
         or DEFAULT_API_BASE
     ).rstrip("/")
 
+    # Auth key. Canonical: SONENTA_API_KEY. Env fallbacks (in order): SONENTA_TOKEN,
+    # then legacy VERBUMIA_API_KEY / VERBUMIA_TOKEN. When NONE are set, fall back to
+    # the CLI credentials store (`sonenta login`) so .mcp.json needs no secret.
+    token = _env("SONENTA_API_KEY", "SONENTA_TOKEN", "VERBUMIA_API_KEY", "VERBUMIA_TOKEN")
+    if not token:
+        token = _credentials_token(api_base)
+    if not token:
+        raise RuntimeError(
+            "No Sonenta API key. Either run `sonenta login` (the server then reads "
+            "your key from ~/.sonenta/credentials) or set SONENTA_API_KEY in your MCP "
+            "client config (e.g. Claude Desktop's mcp.json `env`). SONENTA_TOKEN — and "
+            "the legacy VERBUMIA_API_KEY / VERBUMIA_TOKEN — are also accepted."
+        )
+
     # Multi-project scoping. Canonical: SONENTA_PROJECTS (CSV) / SONENTA_PROJECT
     # (singular). Legacy VERBUMIA_PROJECTS / VERBUMIA_PROJECT still accepted.
     projects_csv = _env("SONENTA_PROJECTS", "VERBUMIA_PROJECTS")

package/python/verbumia_mcp/tools.py

@@ -1823,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",
@@ -2515,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)