@sonenta/mcp 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonenta/mcp",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "MCP server for Sonenta translation management \u2014 wires Claude Desktop and other MCP clients into your project's keys, missing-key feed, and translation drafts.",
   "license": "MIT",
   "homepage": "https://sonenta.com",

package/python/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "verbumia-mcp"
-version = "0.19.0"
+version = "0.20.0"
 description = "Model Context Protocol server for Verbumia — list projects, missing keys, propose translations from Claude Desktop and other MCP clients."
 readme = "README.md"
 requires-python = ">=3.12,<3.14"

package/python/verbumia_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Verbumia MCP server (MIT)."""
 
-__version__ = "0.19.0"
+__version__ = "0.20.0"

package/python/verbumia_mcp/tools.py

@@ -42,6 +42,9 @@ Tools (V1 MCP surface; glossary_* added 2026-05-24; reports + trash added 2026-0
 - get_variants            — full variant matrix for one key (every active surface x language; #928)
 - set_variant             — upsert one variant override for ANY active surface (device or a11y)
 - delete_variant          — delete one variant override for any surface (cell re-inherits base)
+- list_cognitive_candidates — text keys eligible for plain-language (cognitive) scoring
+- set_cognitive_score     — record a key's cognitive score (0-100) + plain-language suggestion (0 credit)
+- analyze_cognitive       — server AI cognitive analysis (billed; opt-in fallback to local scoring)
 
 A11y (accessibility) tools (a11y V1) extend the variant engine with four SEMANTIC
 surfaces — aria_label / alt_text / screen_reader / plain_language — orthogonal to
@@ -1553,6 +1556,116 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     "additionalProperties": False,
                 },
             ),
+            Tool(
+                name="list_cognitive_candidates",
+                description=(
+                    "List keys that are CANDIDATES for plain-language (cognitive) scoring: "
+                    "text-relevant keys (a type that offers plain_language — text / heading "
+                    "/ label / caption) whose source value clears a small word floor. This "
+                    "is a scope filter, NOT a difficulty judgement — score them to find the "
+                    "hard ones. Pass only_unanalyzed=true to skip keys already scored. Each "
+                    "item carries key_uuid + source_value so you can score it locally with "
+                    "set_cognitive_score."
+                ),
+                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.",
+                        },
+                        "only_unanalyzed": {
+                            "type": "boolean",
+                            "description": "Only return keys with no cognitive_score yet (not analyzed).",
+                        },
+                        "namespace_uuid": {
+                            "type": "string",
+                            "description": "Restrict to one namespace by its UUID.",
+                        },
+                        "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100},
+                        "offset": {"type": "integer", "minimum": 0, "default": 0},
+                    },
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="set_cognitive_score",
+                description=(
+                    "Record a key's cognitive-difficulty SCORE (0-100, higher = harder to "
+                    "read) and an optional plain-language SUGGESTION — the local-first, "
+                    "**0-credit** path. Use this after scoring a candidate YOURSELF: you "
+                    "(the agent) judge the difficulty and write a clearer rewrite, then "
+                    "persist both here (marked by_bot). A key only enters the review queue "
+                    "(reading_level_high) once its score is >= the project threshold "
+                    "(default 60). The suggestion is a draft for a human to apply/approve."
+                ),
+                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 (from list_cognitive_candidates / list_keys).",
+                        },
+                        "score": {
+                            "type": "number",
+                            "minimum": 0,
+                            "maximum": 100,
+                            "description": "Cognitive difficulty score, 0 (easy) to 100 (hard).",
+                        },
+                        "suggestion": {
+                            "type": "string",
+                            "description": "Optional plain-language rewrite of the source value (draft).",
+                        },
+                    },
+                    "required": ["key_uuid", "score"],
+                    "additionalProperties": False,
+                },
+            ),
+            Tool(
+                name="analyze_cognitive",
+                description=(
+                    "Server-side AI cognitive analysis — the BILLED, opt-in FALLBACK to "
+                    "local scoring. Rates the cognitive difficulty of candidate keys and "
+                    "suggests plain-language rewrites server-side. Prefer scoring locally "
+                    "with set_cognitive_score (0 credits); use this only for very large "
+                    "volumes or on explicit request. Bills credits (standard=1, premium=4 "
+                    "per key; 402 if insufficient, 503 if AI unavailable). Returns "
+                    "{requested, analyzed, credits_charged, credits_refunded}."
+                ),
+                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.",
+                        },
+                        "tier": {
+                            "type": "string",
+                            "enum": ["standard", "premium"],
+                            "default": "standard",
+                            "description": "Quality tier (credit_cost per key: standard=1, premium=4).",
+                        },
+                        "key_uuids": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Restrict to these keys (from list_cognitive_candidates). Omit to scope the whole project (or a namespace).",
+                        },
+                        "namespace_uuid": {
+                            "type": "string",
+                            "description": "Restrict to one namespace by its UUID.",
+                        },
+                        "idempotency_key": {
+                            "type": "string",
+                            "description": "Stable token making this billable call safe to retry: reuse the SAME value to avoid a double-charge. A random one is generated if omitted.",
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+            ),
         ]
 
     @server.call_tool()
@@ -2089,6 +2202,50 @@ def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
                     return _err("value is required")
                 data = await client.put(path, json={"value": args["value"]})
                 return _text(data)
+            if name == "list_cognitive_candidates":
+                project_uuid = _project_uuid(args, client)
+                params = {
+                    k: v
+                    for k, v in {
+                        "only_unanalyzed": ("true" if args.get("only_unanalyzed") else None),
+                        "namespace_uuid": args.get("namespace_uuid"),
+                        "limit": args.get("limit", 100),
+                        "offset": args.get("offset", 0),
+                    }.items()
+                    if v is not None
+                }
+                data = await client.get(
+                    f"/v1/mcp/projects/{project_uuid}/cognitive/candidates", params=params
+                )
+                return _text(data)
+            if name == "set_cognitive_score":
+                project_uuid = _project_uuid(args, client)
+                key_uuid = args.get("key_uuid")
+                if not key_uuid:
+                    return _err("key_uuid is required")
+                if "score" not in args:
+                    return _err("score is required")
+                body: dict[str, Any] = {"score": args["score"]}
+                if "suggestion" in args:
+                    body["suggestion"] = args["suggestion"]
+                data = await client.put(
+                    f"/v1/mcp/projects/{project_uuid}/keys/{key_uuid}/cognitive-score",
+                    json=body,
+                )
+                return _text(data)
+            if name == "analyze_cognitive":
+                project_uuid = _project_uuid(args, client)
+                body: dict[str, Any] = {
+                    "tier": args.get("tier", "standard"),
+                    "idempotency_key": args.get("idempotency_key") or str(uuid.uuid4()),
+                }
+                for opt in ("key_uuids", "namespace_uuid"):
+                    if args.get(opt):
+                        body[opt] = args[opt]
+                data = await client.post(
+                    f"/v1/mcp/projects/{project_uuid}/cognitive/analyze", json=body
+                )
+                return _text(data)
             return _err(f"unknown tool: {name}")
         except VerbumiaApiError as exc:
             return _err(f"API {exc.status}: {exc.body}")