@sonenta/mcp 0.16.0

package/python/verbumia_mcp/tools.py

@@ -0,0 +1,1284 @@
+"""V1 MCP tool registrations.
+
+Tools (V1 MCP surface; glossary_* added 2026-05-24; reports + trash added 2026-05-25):
+- list_projects           — list projects accessible to the API key
+- get_project_info        — project metadata: source_language, languages, namespaces
+- list_keys               — keys + source value + per-language translations (bulk-translate)
+- list_untranslated_keys  — keys WITHOUT a valid translation in a target language
+- list_missing_keys       — pending missing-key events (cursor paginated)
+- 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_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_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)
+- publish_cdn             — trigger a CDN release (closes the dogfood loop)
+- validate_translations   — lint a JSON i18next blob server-side
+- project_context_get     — read the project's markdown context document
+- project_context_set     — upsert the project's markdown context document
+- glossary_list           — list glossary entries (filters rule_type/q/limit)
+- glossary_create         — create a glossary entry (409 on duplicate rule_type+term)
+- glossary_update         — update an entry by uuid (term/translations/case_sensitive/note)
+- 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)
+- 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)
+
+list_keys and list_untranslated_keys accept `include_glossary_hints=true` to
+attach backend-matched `glossary_hints[]` per key. All glossary matching is
+backend-side; these tools carry ZERO glossary logic client-side.
+
+Trash is UUID-addressed (key_uuids[]) — get key_uuid from list_keys (active) or
+list_trash (trashed). No hard-delete/purge over MCP (human-only JWT). reports +
+trash tools are thin HTTP wrappers, surfaced verbatim.
+
+The tool surface mirrors the canonical contract published in
+`docs/mcp/setup`. Argument names use the LLM-friendly `key` / `namespace` /
+`language_code` rather than uuids — the backend resolves uuids server-side.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mcp.server import Server
+from mcp.types import TextContent, Tool
+
+from .client import VerbumiaApiError, VerbumiaClient
+
+
+def _project_uuid(arguments: dict | None, client: VerbumiaClient) -> str:
+    """Resolve project_uuid from per-call args or the configured env scope.
+
+    Rules (multi-project aware, 0.11+):
+      1. Explicit `project_uuid` in args wins. If `SONENTA_PROJECTS` is set
+         and the value isn't in that allowlist, raise early — better UX than
+         a backend 404/403 after a round-trip.
+      2. No explicit arg + exactly one configured project → use that one.
+      3. No explicit arg + multiple configured projects → raise asking the
+         caller to pass `project_uuid` and listing the allowed UUIDs.
+      4. No explicit arg + nothing configured → raise asking the caller to
+         pass `project_uuid` or set SONENTA_PROJECTS / SONENTA_PROJECT.
+    """
+    allowed = client.config.allowed_project_uuids
+    if arguments and arguments.get("project_uuid"):
+        requested = str(arguments["project_uuid"])
+        if allowed and requested not in allowed:
+            raise ValueError(
+                f"project_uuid {requested!r} is not in SONENTA_PROJECTS allowlist "
+                f"({', '.join(allowed)})"
+            )
+        return requested
+    if client.config.default_project_uuid:
+        return client.config.default_project_uuid
+    if allowed:
+        raise ValueError(
+            "project_uuid is required when multiple projects are configured "
+            "via SONENTA_PROJECTS (or the legacy SONENTA_PROJECT singular). "
+            f"Pass one of: {', '.join(allowed)}"
+        )
+    raise ValueError(
+        "project_uuid is required (pass it explicitly or set SONENTA_PROJECTS / SONENTA_PROJECT)"
+    )
+
+
+def _filter_projects_by_allowlist(data: Any, allowed: tuple[str, ...]) -> Any:
+    """Restrict a list_projects response to the SONENTA_PROJECTS allowlist so
+    `see == touch`: the backend returns everything the API key can reach, but
+    when the human has set an allowlist we only surface those projects — the
+    same scope `_project_uuid` enforces for get_project_info / writes. No
+    allowlist set → return `data` unchanged.
+    """
+    if allowed and isinstance(data, dict) and isinstance(data.get("items"), list):
+        return {**data, "items": [p for p in data["items"] if p.get("uuid") in allowed]}
+    return data
+
+
+def _text(payload: Any) -> list[TextContent]:
+    return [TextContent(type="text", text=json.dumps(payload, indent=2, default=str))]
+
+
+def _err(msg: str) -> list[TextContent]:
+    return [TextContent(type="text", text=f"error: {msg}")]
+
+
+def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
+    @server.list_tools()
+    async def _list_tools() -> list[Tool]:
+        return [
+            Tool(
+                name="list_projects",
+                description=(
+                    "List projects accessible to the configured Verbumia API key. "
+                    "Project-scoped keys return a single project; org-scoped keys "
+                    "return all projects in the org."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="get_project_info",
+                description=(
+                    "Fetch a project's metadata: source language, all configured "
+                    "languages, namespaces, key count. Use before list_missing_keys "
+                    "or propose_translation to learn what namespace + language codes "
+                    "are valid."
+                ),
+                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="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)."
+                ),
+                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.",
+                        },
+                        "namespace": {"type": "string", "description": "Namespace slug filter"},
+                        "language_code": {
+                            "type": "string",
+                            "description": "Restrict translations[] to one BCP-47 code (e.g. fr).",
+                        },
+                        "status_filter": {
+                            "type": "string",
+                            "enum": ["missing", "draft", "translated", "reviewed", "approved"],
+                            "description": "Include only keys with at least one translation in this status.",
+                        },
+                        "include_glossary_hints": {
+                            "type": "boolean",
+                            "default": False,
+                            "description": "When true, attach matched glossary_hints[] to each key (backend-matched against the source string). Default false.",
+                        },
+                        "cursor": {"type": "string"},
+                        "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50},
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="list_untranslated_keys",
+                description=(
+                    "List keys that DON'T yet have a valid translation in the "
+                    "target language. A key is untranslated when ANY of: no "
+                    "translation row exists, value is empty, or status is "
+                    "missing. Compact response (no translations[]) so Claude "
+                    "can iterate a long list and propose translations from "
+                    "source_value."
+                ),
+                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.",
+                        },
+                        "language_code": {
+                            "type": "string",
+                            "description": "Required: target BCP-47 language code (e.g. fr).",
+                        },
+                        "namespace": {"type": "string", "description": "Namespace slug filter"},
+                        "include_glossary_hints": {
+                            "type": "boolean",
+                            "default": False,
+                            "description": "When true, attach matched glossary_hints[] to each key (term, rule_type, target_translation, matched_text) — backend-matched against the source string. Default false.",
+                        },
+                        "cursor": {"type": "string"},
+                        "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50},
+                    },
+                    "required": ["language_code"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="list_missing_keys",
+                description=(
+                    "List pending missing-key events captured from the SDK runtime. "
+                    "Cursor paginated (default page = 50). Filters: namespace slug, "
+                    "language_code, status. CALL missing_keys_stats FIRST to learn how "
+                    "many events exist so you know whether to keep paginating."
+                ),
+                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.",
+                        },
+                        "namespace": {"type": "string"},
+                        "language_code": {"type": "string"},
+                        "status": {
+                            "type": "string",
+                            "enum": ["open", "acknowledged", "resolved"],
+                        },
+                        "cursor": {"type": "string"},
+                        "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50},
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="missing_keys_stats",
+                description=(
+                    "Count-only summary of missing-key events for a project. Returns "
+                    "{total, by_status, by_language, by_namespace}. Lightweight (no row "
+                    "payloads). Use this BEFORE list_missing_keys so you know how many "
+                    "pages remain and whether to keep paginating. Filters mirror "
+                    "list_missing_keys; status defaults to `open` (pass `all` to count "
+                    "every status)."
+                ),
+                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.",
+                        },
+                        "namespace": {"type": "string"},
+                        "language_code": {"type": "string"},
+                        "status": {
+                            "type": "string",
+                            "description": "Defaults to `open`. Pass `all` to count every status.",
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="acknowledge_missing_keys",
+                description=(
+                    "Batch-resolve a set of missing-event uuids. Use this to clean up "
+                    "the dashboard after deciding events are noise (typo, dead code, "
+                    "locale mismatch) — the project's `missing_keys_stats` total drops "
+                    "by the count returned. Idempotent: rows already resolved are "
+                    "counted under `already_resolved`; unknown uuids under `not_found`. "
+                    "Auto-resolution on key creation already covers the happy path; "
+                    "this is for the events you want to dismiss without creating a key."
+                ),
+                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.",
+                        },
+                        "uuids": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "minItems": 1,
+                            "maxItems": 500,
+                            "description": "Missing-event uuids to mark resolved.",
+                        },
+                    },
+                    "required": ["uuids"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="create_namespace",
+                description=(
+                    "Create a namespace (the container for keys). Idempotent on "
+                    "(project, slug): returns created=false if it already exists. "
+                    "slug must be lowercase letters/digits with internal hyphens "
+                    "(no leading/trailing hyphen, no underscore); an invalid slug "
+                    "returns a slug_invalid error rather than 'namespace not found'. "
+                    "Use this before create_key/propose_translation when the target "
+                    "namespace does not exist yet."
+                ),
+                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": "Namespace slug: lowercase letters/digits + internal hyphens (e.g. common, marketing-site).",
+                        },
+                        "name": {"type": "string", "description": "Human-readable namespace name."},
+                        "description": {"type": "string"},
+                    },
+                    "required": ["slug", "name"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="create_key",
+                description=(
+                    "Create a translation key, idempotent on (namespace, name). "
+                    "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."
+                ),
+                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.",
+                        },
+                        "namespace": {
+                            "type": "string",
+                            "description": "Namespace slug (LLM-friendly).",
+                        },
+                        "name": {
+                            "type": "string",
+                            "description": "Dot-notation key name (e.g. hero.title).",
+                        },
+                        "source_value": {
+                            "type": "string",
+                            "description": "Optional source-language value to seed.",
+                        },
+                        "description": {"type": "string"},
+                        "plurals": {"type": "boolean", "default": False},
+                        "max_length": {"type": "integer", "minimum": 1},
+                    },
+                    "required": ["namespace", "name"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="propose_translation",
+                description=(
+                    "Submit a translation value. Auto-creates the key if it "
+                    "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."
+                ),
+                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.",
+                        },
+                        "namespace": {"type": "string"},
+                        "key": {"type": "string"},
+                        "language_code": {
+                            "type": "string",
+                            "description": "BCP-47 code (e.g. fr, fr-CA, es).",
+                        },
+                        "value": {"type": "string"},
+                        "status": {
+                            "type": "string",
+                            "enum": ["draft", "translated"],
+                            "default": "draft",
+                        },
+                    },
+                    "required": ["namespace", "key", "language_code", "value"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="create_keys_bulk",
+                description=(
+                    "Batch version of create_key: create up to 500 keys in one "
+                    "call, idempotent per item (existing keys return created=false). "
+                    "Returns a per-item results array + a summary roll-up; valid "
+                    "items commit even if siblings fail. Intra-batch duplicates "
+                    "(same namespace+name twice) error per item; the whole call is "
+                    "rejected if the new keys would exceed the org plan cap. NO "
+                    "server-side translation — this only batches the writes. Use "
+                    "this instead of N create_key calls for a backlog."
+                ),
+                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.",
+                        },
+                        "items": {
+                            "type": "array",
+                            "minItems": 1,
+                            "maxItems": 500,
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "namespace": {"type": "string", "description": "Namespace slug."},
+                                    "name": {"type": "string", "description": "Dot-notation key name (e.g. hero.title)."},
+                                    "source_value": {"type": "string", "description": "Optional source-language value to seed."},
+                                    "description": {"type": "string"},
+                                    "plurals": {"type": "boolean", "default": False},
+                                    "max_length": {"type": "integer", "minimum": 1},
+                                },
+                                "required": ["namespace", "name"],
+                                "additionalProperties": False,
+                            },
+                        },
+                    },
+                    "required": ["items"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="update_key",
+                description=(
+                    "Edit a key's SOURCE-language value in place. 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 "
+                    "value ACTUALLY changes, the key's reviewed/approved target "
+                    "translations are demoted to needs-review (\"translated\"); "
+                    "missing/draft/translated targets are untouched, and "
+                    "stale_flagged reports how many were demoted. Submitting the "
+                    "current value is a no-op (result=unchanged, not billed). A "
+                    "real source change (or a description-only change) bills 1 unit."
+                ),
+                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 to update (preferred addressing; get it from list_keys). Mutually exclusive with namespace+name.",
+                        },
+                        "namespace": {
+                            "type": "string",
+                            "description": "Namespace slug (use with name as an alternative to key_uuid).",
+                        },
+                        "name": {
+                            "type": "string",
+                            "description": "Dot-notation key name (use with namespace as an alternative to key_uuid).",
+                        },
+                        "source_value": {
+                            "type": "string",
+                            "description": "New source-language value to write.",
+                        },
+                        "description": {
+                            "type": "string",
+                            "description": "Optional: also update the key's description.",
+                        },
+                    },
+                    "required": ["source_value"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="update_keys_bulk",
+                description=(
+                    "Batch version of update_key: edit up to 500 keys' SOURCE "
+                    "values in one call. Returns a per-item results array + a "
+                    "summary roll-up; valid items commit even if siblings fail "
+                    "(status ok | unchanged | error per item). Each item addresses "
+                    "its key by EITHER key_uuid OR namespace + name (exactly one). "
+                    "Same staleness, no-op and billing semantics as update_key "
+                    "(1 unit per key actually changed; no-ops and errors are free). "
+                    "Use this instead of N update_key calls for a backlog."
+                ),
+                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.",
+                        },
+                        "items": {
+                            "type": "array",
+                            "minItems": 1,
+                            "maxItems": 500,
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "key_uuid": {"type": "string", "description": "Key uuid (preferred). Mutually exclusive with namespace+name."},
+                                    "namespace": {"type": "string", "description": "Namespace slug (use with name)."},
+                                    "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."},
+                                },
+                                "required": ["source_value"],
+                                "additionalProperties": False,
+                            },
+                        },
+                    },
+                    "required": ["items"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="propose_translations_bulk",
+                description=(
+                    "Batch version of propose_translation: submit up to 500 "
+                    "translation values in one call. Auto-creates missing keys "
+                    "(write-through). Returns a per-item results array + summary; "
+                    "an item whose value AND status already match returns "
+                    "status=unchanged (no-op). Intra-batch duplicates "
+                    "(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."
+                ),
+                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.",
+                        },
+                        "items": {
+                            "type": "array",
+                            "minItems": 1,
+                            "maxItems": 500,
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "namespace": {"type": "string"},
+                                    "key": {"type": "string"},
+                                    "language_code": {"type": "string", "description": "BCP-47 code (e.g. fr, fr-CA, es)."},
+                                    "value": {"type": "string"},
+                                    "status": {"type": "string", "enum": ["draft", "translated"], "default": "draft"},
+                                },
+                                "required": ["namespace", "key", "language_code", "value"],
+                                "additionalProperties": False,
+                            },
+                        },
+                    },
+                    "required": ["items"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="publish_cdn",
+                description=(
+                    "Trigger a CDN release for the project. Builds bundles "
+                    "for every (language, namespace) combo (or restricted to "
+                    "the ones you pass) and pushes them to the public CDN. "
+                    "Idempotent: re-running with no content changes returns "
+                    "the same bundles as `reused`. Subscribed SDKs receive a "
+                    "Centrifugo `translations_published` event for every "
+                    "newly created bundle and can refresh in-place."
+                ),
+                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.",
+                        },
+                        "language_code": {
+                            "type": "string",
+                            "description": "Restrict to one BCP-47 language. Omit for ALL.",
+                        },
+                        "namespace": {
+                            "type": "string",
+                            "description": "Restrict to one namespace slug. Omit for ALL.",
+                        },
+                        "version_slug": {
+                            "type": "string",
+                            "description": "Project version slug. Defaults to the production version.",
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="validate_translations",
+                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."
+                ),
+                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.",
+                        },
+                        "language_code": {"type": "string"},
+                        "namespace": {
+                            "type": "string",
+                            "description": "Restrict to one namespace (default: all).",
+                        },
+                        "payload": {
+                            "type": "object",
+                            "description": "The translation tree to validate.",
+                        },
+                    },
+                    "required": ["language_code", "payload"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="project_context_get",
+                description=(
+                    "Read the project's markdown context document. The document is "
+                    "free-form prose attached to the project (terminology, brand "
+                    "voice, constraints, domain — e.g. religious, technical, "
+                    "medical, gaming, legal) and is intended as ambient context for "
+                    "human translators AND for AI agents producing translations. "
+                    "Call this BEFORE batch-translating: prepend the content to your "
+                    "translation prompts so every output stays consistent with the "
+                    "project's terminology and tone. Empty content means the project "
+                    "owner hasn't authored a context yet — that's not an error. "
+                    "Requires API-key scope: project:read."
+                ),
+                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="project_context_set",
+                description=(
+                    "Upsert the project's markdown context document. Replaces the "
+                    "entire document — fetch first with project_context_get if you "
+                    "want to append rather than overwrite. Use this to memorise "
+                    "terminology choices, glossary entries, domain framing (e.g. "
+                    "'this is a Catholic-liturgy app — use traditional vocabulary, "
+                    "avoid neologisms'), tone guidance, and translation constraints "
+                    "you discover while working the project. Hard cap: 100 KiB. "
+                    "Requires API-key scope: project:settings:write (narrower than "
+                    "project:write — settings changes propagate to every translator's "
+                    "prompt context)."
+                ),
+                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.",
+                        },
+                        "content": {
+                            "type": "string",
+                            "description": "New markdown content (UTF-8, ≤ 100 KiB).",
+                        },
+                    },
+                    "required": ["content"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="glossary_list",
+                description=(
+                    "List a project's glossary entries — the terminology rules the "
+                    "backend applies when matching source strings. Filters: rule_type "
+                    "(translation | do_not_translate | forbidden), q (case-insensitive "
+                    "substring on the term), limit (1..500, default 200). Returns "
+                    "{items: [GlossaryEntry], total}. Matching itself is backend-side; "
+                    "this only lists the rules."
+                ),
+                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.",
+                        },
+                        "rule_type": {
+                            "type": "string",
+                            "enum": ["translation", "do_not_translate", "forbidden"],
+                            "description": "Filter to one rule type.",
+                        },
+                        "q": {
+                            "type": "string",
+                            "description": "Case-insensitive substring filter on the term.",
+                        },
+                        "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 200},
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="glossary_create",
+                description=(
+                    "Create a glossary entry. rule_type is one of translation | "
+                    "do_not_translate | forbidden and defaults to 'translation'. "
+                    "`translations` ({<locale>: value}) is honored only for "
+                    "rule_type='translation' (cleared otherwise by the backend). "
+                    "Returns the created GlossaryEntry. Errors 409 if an entry with "
+                    "the same (rule_type, term) already exists — use glossary_update "
+                    "to change an existing one."
+                ),
+                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.",
+                        },
+                        "rule_type": {
+                            "type": "string",
+                            "enum": ["translation", "do_not_translate", "forbidden"],
+                            "default": "translation",
+                            "description": "Rule type. Defaults to 'translation'.",
+                        },
+                        "term": {
+                            "type": "string",
+                            "description": "The source term/phrase the rule applies to.",
+                        },
+                        "translations": {
+                            "type": "object",
+                            "description": "Per-locale target translations, e.g. {\"fr\": \"tableau de bord\"}. Only used for rule_type='translation'.",
+                        },
+                        "case_sensitive": {
+                            "type": "boolean",
+                            "default": False,
+                            "description": "Match the term case-sensitively.",
+                        },
+                        "note": {"type": "string", "description": "Optional human note."},
+                    },
+                    "required": ["term"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="glossary_update",
+                description=(
+                    "Update a glossary entry by its uuid (entry_id). Send only the "
+                    "fields to change: term, translations, case_sensitive, note. "
+                    "rule_type is immutable — delete and recreate to change it. "
+                    "Returns the updated GlossaryEntry; 404 if entry_id is unknown, "
+                    "409 on a term clash with another entry of the same rule_type."
+                ),
+                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.",
+                        },
+                        "entry_id": {
+                            "type": "string",
+                            "description": "The GlossaryEntry uuid to update.",
+                        },
+                        "term": {"type": "string"},
+                        "translations": {
+                            "type": "object",
+                            "description": "Per-locale target translations (rule_type='translation' only).",
+                        },
+                        "case_sensitive": {"type": "boolean"},
+                        "note": {"type": "string"},
+                    },
+                    "required": ["entry_id"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="glossary_delete",
+                description=(
+                    "Delete a glossary entry by its uuid (entry_id). Returns "
+                    "{deleted: true, entry_id}. A missing entry_id returns 404."
+                ),
+                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.",
+                        },
+                        "entry_id": {
+                            "type": "string",
+                            "description": "The GlossaryEntry uuid to delete.",
+                        },
+                    },
+                    "required": ["entry_id"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="health_report",
+                description=(
+                    "Read-only SOURCE-HEALTH report for the project (#752): issues in the "
+                    "source strings with by_issue / by_severity rollups + per-key items. "
+                    "Defaults to the production version; pass version_id for a specific "
+                    "version. Surfaced verbatim (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="coverage_report",
+                description=(
+                    "Read-only translation-COVERAGE report for the project (#752): global "
+                    "completeness, total key count, and per-language coverage. Defaults to "
+                    "the production version; pass version_id for a specific version. "
+                    "Surfaced verbatim (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="delete_keys_bulk",
+                description=(
+                    "Soft-delete (move to TRASH) up to 500 keys by their key_uuid. "
+                    "Restorable via restore_keys_bulk. Idempotent: already-trashed keys "
+                    "are reported unchanged, unknown uuids not_found. Trashed keys "
+                    "disappear from list_keys, list_untranslated_keys, the CDN, and the "
+                    "reports. Get key_uuid from list_keys. NO hard-delete/purge over MCP "
+                    "(purge is human-only via the dashboard)."
+                ),
+                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"},
+                            "minItems": 1,
+                            "maxItems": 500,
+                            "description": "Key uuids to trash (get them from list_keys).",
+                        },
+                    },
+                    "required": ["key_uuids"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="restore_keys_bulk",
+                description=(
+                    "Restore up to 500 trashed keys by their key_uuid (from list_trash). "
+                    "Idempotent: already-active keys are reported unchanged, unknown uuids "
+                    "not_found; a key whose name was re-created while it was trashed is "
+                    "reported as a conflict. Get key_uuid from list_trash."
+                ),
+                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"},
+                            "minItems": 1,
+                            "maxItems": 500,
+                            "description": "Key uuids to restore (get them from list_trash).",
+                        },
+                    },
+                    "required": ["key_uuids"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="list_trash",
+                description=(
+                    "List trashed (soft-deleted) keys: items of {key_uuid, namespace, "
+                    "name, deleted_at}, cursor-paginated. Feed key_uuid to "
+                    "restore_keys_bulk to bring them back."
+                ),
+                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.",
+                        },
+                        "cursor": {"type": "string"},
+                        "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50},
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+        ]
+
+    @server.call_tool()
+    async def _call(name: str, arguments: dict | None) -> list[TextContent]:
+        try:
+            args = arguments or {}
+            if name == "list_projects":
+                data = await client.get(
+                    "/v1/mcp/projects", params={"limit": args.get("limit", 50)}
+                )
+                data = _filter_projects_by_allowlist(
+                    data, client.config.allowed_project_uuids
+                )
+                return _text(data)
+            if name == "get_project_info":
+                project_uuid = _project_uuid(args, client)
+                data = await client.get(f"/v1/mcp/projects/{project_uuid}")
+                return _text(data)
+            if name == "list_keys":
+                project_uuid = _project_uuid(args, client)
+                params = {
+                    k: v
+                    for k, v in {
+                        "namespace": args.get("namespace"),
+                        "language_code": args.get("language_code"),
+                        "status_filter": args.get("status_filter"),
+                        "include_glossary_hints": (
+                            "true" if args.get("include_glossary_hints") else None
+                        ),
+                        "cursor": args.get("cursor"),
+                        "limit": args.get("limit", 50),
+                    }.items()
+                    if v is not None
+                }
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/keys", params=params
+                )
+                return _text(data)
+            if name == "list_untranslated_keys":
+                project_uuid = _project_uuid(args, client)
+                if "language_code" not in args:
+                    return _err("language_code is required")
+                params = {
+                    k: v
+                    for k, v in {
+                        "language_code": args["language_code"],
+                        "namespace": args.get("namespace"),
+                        "include_glossary_hints": (
+                            "true" if args.get("include_glossary_hints") else None
+                        ),
+                        "cursor": args.get("cursor"),
+                        "limit": args.get("limit", 50),
+                    }.items()
+                    if v is not None
+                }
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/untranslated-keys", params=params
+                )
+                return _text(data)
+            if name == "list_missing_keys":
+                project_uuid = _project_uuid(args, client)
+                params = {
+                    k: v
+                    for k, v in {
+                        "namespace": args.get("namespace"),
+                        "language_code": args.get("language_code"),
+                        "status": args.get("status"),
+                        "cursor": args.get("cursor"),
+                        "limit": args.get("limit", 50),
+                    }.items()
+                    if v is not None
+                }
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/missing-keys", params=params
+                )
+                return _text(data)
+            if name == "missing_keys_stats":
+                project_uuid = _project_uuid(args, client)
+                params = {
+                    k: v
+                    for k, v in {
+                        "namespace": args.get("namespace"),
+                        "language_code": args.get("language_code"),
+                        "status": args.get("status"),
+                    }.items()
+                    if v is not None
+                }
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/missing-keys/stats",
+                    params=params,
+                )
+                return _text(data)
+            if name == "acknowledge_missing_keys":
+                project_uuid = _project_uuid(args, client)
+                uuids = args.get("uuids") or []
+                if not uuids:
+                    return _err("uuids must be a non-empty list")
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/missing-keys/acknowledge",
+                    json={"uuids": uuids},
+                )
+                return _text(data)
+            if name == "create_namespace":
+                project_uuid = _project_uuid(args, client)
+                if "slug" not in args or "name" not in args:
+                    return _err("slug and name are required")
+                body: dict[str, Any] = {"slug": args["slug"], "name": args["name"]}
+                if "description" in args:
+                    body["description"] = args["description"]
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/namespaces", json=body
+                )
+                return _text(data)
+            if name == "create_key":
+                project_uuid = _project_uuid(args, client)
+                if "namespace" not in args or "name" not in args:
+                    return _err("namespace and name are required")
+                body: dict[str, Any] = {
+                    "namespace": args["namespace"],
+                    "name": args["name"],
+                }
+                for opt in ("source_value", "description", "plurals", "max_length"):
+                    if opt in args:
+                        body[opt] = args[opt]
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/keys", json=body
+                )
+                return _text(data)
+            if name == "propose_translation":
+                project_uuid = _project_uuid(args, client)
+                body = {
+                    "namespace": args["namespace"],
+                    "key": args["key"],
+                    "language_code": args["language_code"],
+                    "value": args["value"],
+                }
+                if "status" in args:
+                    body["status"] = args["status"]
+                data = await client.put(
+                    f"/v1/mcp/projects/{project_uuid}/translations", json=body
+                )
+                return _text(data)
+            if name == "create_keys_bulk":
+                project_uuid = _project_uuid(args, client)
+                items = args.get("items")
+                if not isinstance(items, list) or not items:
+                    return _err("items must be a non-empty list")
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/keys/bulk", json={"items": items}
+                )
+                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")
+                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"):
+                    if opt in args:
+                        body[opt] = args[opt]
+                data = await client.patch(
+                    f"/v1/mcp/projects/{project_uuid}/keys", json=body
+                )
+                return _text(data)
+            if name == "update_keys_bulk":
+                project_uuid = _project_uuid(args, client)
+                items = args.get("items")
+                if not isinstance(items, list) or not items:
+                    return _err("items must be a non-empty list")
+                data = await client.patch(
+                    f"/v1/mcp/projects/{project_uuid}/keys/bulk", json={"items": items}
+                )
+                return _text(data)
+            if name == "propose_translations_bulk":
+                project_uuid = _project_uuid(args, client)
+                items = args.get("items")
+                if not isinstance(items, list) or not items:
+                    return _err("items must be a non-empty list")
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/translations/bulk",
+                    json={"items": items},
+                )
+                return _text(data)
+            if name == "publish_cdn":
+                project_uuid = _project_uuid(args, client)
+                body: dict[str, Any] = {}
+                for opt in ("language_code", "namespace", "version_slug"):
+                    if opt in args and args[opt]:
+                        body[opt] = args[opt]
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/cdn/releases", json=body
+                )
+                return _text(data)
+            if name == "validate_translations":
+                project_uuid = _project_uuid(args, client)
+                body = {
+                    "language_code": args["language_code"],
+                    "payload": args.get("payload", {}),
+                }
+                if "namespace" in args:
+                    body["namespace"] = args["namespace"]
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/validate", json=body
+                )
+                return _text(data)
+            if name == "project_context_get":
+                project_uuid = _project_uuid(args, client)
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/context"
+                )
+                return _text(data)
+            if name == "project_context_set":
+                project_uuid = _project_uuid(args, client)
+                if "content" not in args:
+                    return _err("content is required")
+                data = await client.put(
+                    f"/v1/mcp/projects/{project_uuid}/context",
+                    json={"content": args["content"]},
+                )
+                return _text(data)
+            if name == "glossary_list":
+                project_uuid = _project_uuid(args, client)
+                params = {
+                    k: v
+                    for k, v in {
+                        "rule_type": args.get("rule_type"),
+                        "q": args.get("q"),
+                        "limit": args.get("limit", 200),
+                    }.items()
+                    if v is not None
+                }
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/glossary", params=params
+                )
+                return _text(data)
+            if name == "glossary_create":
+                project_uuid = _project_uuid(args, client)
+                if "term" not in args:
+                    return _err("term is required")
+                body: dict[str, Any] = {"term": args["term"]}
+                for opt in ("rule_type", "translations", "case_sensitive", "note"):
+                    if opt in args:
+                        body[opt] = args[opt]
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/glossary", json=body
+                )
+                return _text(data)
+            if name == "glossary_update":
+                project_uuid = _project_uuid(args, client)
+                if "entry_id" not in args:
+                    return _err("entry_id is required")
+                body: dict[str, Any] = {}
+                for opt in ("term", "translations", "case_sensitive", "note"):
+                    if opt in args:
+                        body[opt] = args[opt]
+                if not body:
+                    return _err(
+                        "nothing to update: pass at least one of term, translations, "
+                        "case_sensitive, note"
+                    )
+                data = await client.patch(
+                    f"/v1/mcp/projects/{project_uuid}/glossary/{args['entry_id']}",
+                    json=body,
+                )
+                return _text(data)
+            if name == "glossary_delete":
+                project_uuid = _project_uuid(args, client)
+                if "entry_id" not in args:
+                    return _err("entry_id is required")
+                await client.delete(
+                    f"/v1/mcp/projects/{project_uuid}/glossary/{args['entry_id']}"
+                )
+                return _text({"deleted": True, "entry_id": args["entry_id"]})
+            if name == "health_report":
+                project_uuid = _project_uuid(args, client)
+                params = {
+                    k: v
+                    for k, v in {"version_id": args.get("version_id")}.items()
+                    if v is not None
+                }
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/source-health", params=params
+                )
+                return _text(data)
+            if name == "coverage_report":
+                project_uuid = _project_uuid(args, client)
+                params = {
+                    k: v
+                    for k, v in {"version_id": args.get("version_id")}.items()
+                    if v is not None
+                }
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/coverage", params=params
+                )
+                return _text(data)
+            if name == "delete_keys_bulk":
+                project_uuid = _project_uuid(args, client)
+                key_uuids = args.get("key_uuids")
+                if not isinstance(key_uuids, list) or not key_uuids:
+                    return _err("key_uuids must be a non-empty list")
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/keys/bulk/delete",
+                    json={"key_uuids": key_uuids},
+                )
+                return _text(data)
+            if name == "restore_keys_bulk":
+                project_uuid = _project_uuid(args, client)
+                key_uuids = args.get("key_uuids")
+                if not isinstance(key_uuids, list) or not key_uuids:
+                    return _err("key_uuids must be a non-empty list")
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/keys/bulk/restore",
+                    json={"key_uuids": key_uuids},
+                )
+                return _text(data)
+            if name == "list_trash":
+                project_uuid = _project_uuid(args, client)
+                params = {
+                    k: v
+                    for k, v in {
+                        "cursor": args.get("cursor"),
+                        "limit": args.get("limit", 50),
+                    }.items()
+                    if v is not None
+                }
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/keys/trashed", params=params
+                )
+                return _text(data)
+            return _err(f"unknown tool: {name}")
+        except VerbumiaApiError as exc:
+            return _err(f"API {exc.status}: {exc.body}")
+        except KeyError as exc:
+            return _err(f"missing required argument: {exc}")
+        except Exception as exc:  # pragma: no cover
+            return _err(f"{type(exc).__name__}: {exc}")
+
+    return _list_tools, _call