@sonenta/mcp 0.34.1 → 0.35.0

package/package.json

@@ -1,40 +1,60 @@
 {
   "name": "@sonenta/mcp",
-  "version": "0.34.1",
-  "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.",
+  "version": "0.35.0",
+  "description": "MCP server for Sonenta translation management — pure TypeScript, no Python. Wires Claude Desktop and other MCP clients into your project's keys, translations, accessibility, and source-health tools.",
   "license": "MIT",
   "homepage": "https://sonenta.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/sonenta/tools.git",
-    "directory": "mcp/npm"
+    "url": "https://github.com/verbumia/verbumia-tools.git",
+    "directory": "mcp-ts"
   },
   "bugs": {
-    "url": "https://github.com/sonenta/tools/issues"
+    "url": "https://github.com/verbumia/verbumia-tools/issues"
   },
   "keywords": [
-    "mcp",
     "sonenta",
+    "verbumia",
+    "mcp",
     "i18n",
     "translations",
-    "claude",
-    "anthropic"
+    "claude"
   ],
   "author": "Sonenta",
-  "engines": {
-    "node": ">=18.0.0"
-  },
+  "type": "module",
   "bin": {
     "sonenta-mcp": "bin/sonenta-mcp.js"
   },
   "files": [
     "bin/",
-    "python/",
+    "dist/",
     "README.md",
     "LICENSE"
   ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "scripts": {
-    "test": "node bin/sonenta-mcp.js --self-check",
-    "prepublishOnly": "cd python && uv build && rm -f dist/*.tar.gz && printf '' > dist/.npmignore"
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build",
+    "gen:schemas": "node scripts/gen-schemas.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "lossless-json": "^4.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   }
 }

package/python/README.md

@@ -1,114 +0,0 @@
-# Sonenta MCP server
-
-Model Context Protocol server for [Sonenta](https://sonenta.com) — exposes
-your translation project to Claude Desktop and other MCP clients.
-
-## Status
-
-Thirteen tools wired: `list_projects`, `get_project_info`, `list_keys`,
-`list_untranslated_keys`, `list_missing_keys`, `missing_keys_stats`,
-`acknowledge_missing_keys`, `create_key`, `propose_translation`,
-`publish_cdn`, `validate_translations`, `project_context_get`,
-`project_context_set`.
-
-### Project context document (V1.2)
-
-`project_context_get` / `project_context_set` read and write a free-form
-markdown blob attached to the project — terminology, brand voice, domain
-notes (religious, legal, medical, gaming, etc.). The content is intended
-as ambient context for human translators **and** for AI agents producing
-translations: prepend it to your translation prompts so every output stays
-consistent with the project's vocabulary and tone. Hard cap 100 KiB.
-
-Scopes:
-- `project_context_get` requires `project:read` (existing scope).
-- `project_context_set` requires `project:settings:write` (new scope, narrower
-  than `project:write` since settings changes propagate to every translator's
-  prompt context).
-
-Note: the blanket `mcp:*` scope is **not** sufficient for these tools — grant
-the precise scope on the key.
-
-## Install
-
-```bash
-# Recommended (zero-install, used by Claude Desktop's mcp.json):
-npx -y @sonenta/mcp
-
-# Or from PyPI:
-pipx install sonenta-mcp
-```
-
-A Homebrew tap (`brew install sonenta/tap/sonenta-mcp`) is coming once we
-publish to npm.
-
-## Configure (Claude Desktop)
-
-Open **Settings → Developer → Edit Config**, then:
-
-Single-project setup:
-
-```json
-{
-  "mcpServers": {
-    "sonenta": {
-      "command": "npx",
-      "args": ["-y", "@sonenta/mcp"],
-      "env": {
-        "SONENTA_API_KEY": "vrb_live_<prefix>.<secret>",
-        "SONENTA_PROJECTS": "<project_uuid>",
-        "SONENTA_BASE_URL": "https://api.sonenta.dev"
-      }
-    }
-  }
-}
-```
-
-Multi-project setup (v0.11+) — comma-separate the UUIDs and Claude will pass
-`project_uuid` on each tool call:
-
-```json
-"env": {
-  "SONENTA_API_KEY": "vrb_live_<prefix>.<secret>",
-  "SONENTA_PROJECTS": "01993a..,01993b..,01993c.."
-}
-```
-
-Restart Claude Desktop. Tools show up in the prompt UI.
-
-## Environment
-
-| Variable             | Required | Default                        | Description                                                                                |
-|----------------------|----------|--------------------------------|--------------------------------------------------------------------------------------------|
-| `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.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
-> existing MCP client configs keep working — switch to the `SONENTA_*` names
-> when convenient.
-
-The token format is `vrb_live_<prefix>.<secret>` and must carry the `mcp:*`
-scope. For the `project_context_*` tools, also grant `project:read` and/or
-`project:settings:write` — see the **Project context document** section
-above. Treat the token like any other secret — keychain or `.env`, never
-commit.
-
-If your API key is pinned to a single project (its `project_uuid` is set
-server-side), listing additional UUIDs in `SONENTA_PROJECTS` will surface
-as a `403 API key is scoped to a different project` from the backend on
-any call targeting one of the others.
-
-## Local development
-
-```bash
-cd mcp
-uv sync
-uv run sonenta-mcp        # stdio transport — pipe MCP frames over stdin/stdout
-```
-
-## License
-
-MIT.

package/python/pyproject.toml

@@ -1,59 +0,0 @@
-[project]
-name = "sonenta-mcp"
-version = "0.34.1"
-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.11,<3.14"
-license = { text = "MIT" }
-authors = [{ name = "Sonenta" }]
-keywords = ["mcp", "sonenta", "i18n", "translations", "claude"]
-classifiers = [
-    "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Topic :: Software Development :: Internationalization",
-]
-dependencies = [
-    "mcp>=1.0",
-    "httpx>=0.28",
-    "pydantic>=2.9",
-]
-
-[project.scripts]
-sonenta-mcp = "verbumia_mcp.__main__:main"
-
-[project.urls]
-Homepage = "https://sonenta.com"
-Documentation = "https://sonenta.com/docs/mcp/setup"
-Source = "https://github.com/sonenta/tools"
-Issues = "https://github.com/sonenta/tools/issues"
-
-[dependency-groups]
-dev = [
-    "pytest>=8.3",
-    "pytest-asyncio>=0.24",
-    "ruff>=0.8",
-]
-
-[tool.uv]
-package = true
-
-[tool.ruff]
-line-length = 100
-target-version = "py312"
-
-[tool.ruff.lint]
-select = ["E", "F", "W", "I", "B", "UP", "SIM", "ASYNC", "RUF"]
-ignore = ["E501"]
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.hatch.build.targets.wheel]
-packages = ["verbumia_mcp"]
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["tests"]
-addopts = "-q --strict-markers"

package/python/verbumia_mcp/__init__.py

@@ -1,3 +0,0 @@
-"""Sonenta MCP server (MIT)."""
-
-__version__ = "0.34.1"

package/python/verbumia_mcp/__main__.py

@@ -1,23 +0,0 @@
-"""Entrypoint for `sonenta-mcp` (and `python -m verbumia_mcp`)."""
-
-from __future__ import annotations
-
-import asyncio
-import sys
-
-
-def main() -> None:
-    from .server import run
-
-    try:
-        asyncio.run(run())
-    except KeyboardInterrupt:
-        sys.exit(130)
-    except RuntimeError as exc:
-        # Configuration errors (missing token, etc.) — print a friendly hint.
-        print(f"sonenta-mcp: {exc}", file=sys.stderr)
-        sys.exit(2)
-
-
-if __name__ == "__main__":
-    main()

package/python/verbumia_mcp/client.py

@@ -1,85 +0,0 @@
-"""Async HTTP client wrapping the Sonenta REST API.
-
-The MCP tools are thin adapters over this client — they translate MCP
-arguments to API calls and shape the response. Authentication is the
-`Authorization: ApiKey vrb_live_<prefix>.<secret>` header read from
-`SONENTA_API_KEY` (or `SONENTA_TOKEN` for back-compat).
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-import httpx
-
-from .config import Config
-
-
-class VerbumiaApiError(Exception):
-    """Raised when the API returns a non-2xx response."""
-
-    def __init__(self, status: int, body: str | dict[str, Any]) -> None:
-        self.status = status
-        self.body = body
-        super().__init__(f"Sonenta API error {status}: {body}")
-
-
-class VerbumiaClient:
-    """Tiny async REST client. Reuse across tool calls — open once at startup."""
-
-    def __init__(
-        self, config: Config, *, transport: httpx.AsyncBaseTransport | None = None
-    ) -> None:
-        self._config = config
-        self._http = httpx.AsyncClient(
-            base_url=config.api_base,
-            headers={
-                "Authorization": f"ApiKey {config.token}",
-                "User-Agent": config.user_agent,
-                "Accept": "application/json",
-            },
-            timeout=httpx.Timeout(15.0, connect=5.0),
-            transport=transport,
-        )
-
-    async def aclose(self) -> None:
-        await self._http.aclose()
-
-    @property
-    def config(self) -> Config:
-        return self._config
-
-    async def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
-        r = await self._http.get(path, params=params)
-        return _unpack(r)
-
-    async def post(self, path: str, json: dict[str, Any]) -> Any:
-        r = await self._http.post(path, json=json)
-        return _unpack(r)
-
-    async def put(self, path: str, json: dict[str, Any]) -> Any:
-        r = await self._http.put(path, json=json)
-        return _unpack(r)
-
-    async def patch(self, path: str, json: dict[str, Any]) -> Any:
-        r = await self._http.patch(path, json=json)
-        return _unpack(r)
-
-    async def delete(self, path: str) -> Any:
-        r = await self._http.delete(path)
-        return _unpack(r)
-
-    async def health(self) -> dict[str, Any]:
-        return await self.get("/health")
-
-
-def _unpack(r: httpx.Response) -> Any:
-    if r.status_code >= 400:
-        try:
-            body: str | dict[str, Any] = r.json()
-        except ValueError:
-            body = r.text
-        raise VerbumiaApiError(r.status_code, body)
-    if r.status_code == 204 or not r.content:
-        return None
-    return r.json()

package/python/verbumia_mcp/config.py

@@ -1,157 +0,0 @@
-"""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. 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
-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)
-class Config:
-    api_base: str
-    token: str
-    # Tuple of project UUIDs the operator scoped this MCP server to. Empty
-    # means "unrestricted — fall back to whatever the API key can see".
-    allowed_project_uuids: tuple[str, ...]
-    user_agent: str
-
-    @property
-    def default_project_uuid(self) -> str | None:
-        """The single project to use when none is passed explicitly.
-
-        Only defined when exactly one project is configured — otherwise the
-        caller MUST pass `project_uuid` per call (the resolver in tools.py
-        enforces this).
-        """
-        return self.allowed_project_uuids[0] if len(self.allowed_project_uuids) == 1 else None
-
-
-def _parse_projects_csv(raw: str) -> tuple[str, ...]:
-    """Split, strip, and de-duplicate a CSV of project UUIDs while preserving order."""
-    seen: list[str] = []
-    for token in raw.split(","):
-        v = token.strip()
-        if v and v not in seen:
-            seen.append(v)
-    return tuple(seen)
-
-
-def _env(*names: str) -> str:
-    """First non-empty env var among `names` (canonical SONENTA_* first,
-    legacy VERBUMIA_* fallback)."""
-    for n in names:
-        v = os.environ.get(n, "").strip()
-        if v:
-            return v
-    return ""
-
-
-def load_config() -> Config:
-    # 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")
-    project_single = _env("SONENTA_PROJECT", "VERBUMIA_PROJECT")
-    if projects_csv and project_single:
-        print(
-            "sonenta-mcp: both *_PROJECTS and *_PROJECT are set; the CSV "
-            "(*_PROJECTS) wins. Remove the singular var to silence this warning.",
-            file=sys.stderr,
-        )
-    if projects_csv:
-        allowed = _parse_projects_csv(projects_csv)
-    elif project_single:
-        allowed = (project_single,)
-    else:
-        allowed = ()
-
-    from . import __version__
-
-    user_agent = f"sonenta-mcp/{__version__}"
-    return Config(
-        api_base=api_base,
-        token=token,
-        allowed_project_uuids=allowed,
-        user_agent=user_agent,
-    )

package/python/verbumia_mcp/server.py

@@ -1,88 +0,0 @@
-"""MCP stdio server bootstrapping.
-
-`run()` is the async entrypoint: load config, open the HTTP client, register
-tools, then hand control to mcp's stdio transport. The MCP protocol uses
-JSON-RPC over stdin/stdout, so we never print to stdout for logging — all
-diagnostics go to stderr.
-"""
-
-from __future__ import annotations
-
-import sys
-from collections.abc import AsyncIterator
-from contextlib import asynccontextmanager
-
-from mcp.server import Server
-from mcp.server.models import InitializationOptions
-from mcp.server.stdio import stdio_server
-from mcp.types import ServerCapabilities, ToolsCapability
-
-from . import __version__
-from .client import VerbumiaApiError, VerbumiaClient
-from .config import Config, load_config
-from .tools import register
-
-
-def _info(msg: str) -> None:
-    """Stderr-only logging — stdout is reserved for the MCP framing."""
-    print(msg, file=sys.stderr, flush=True)
-
-
-@asynccontextmanager
-async def _client_for(config: Config) -> AsyncIterator[VerbumiaClient]:
-    client = VerbumiaClient(config)
-    try:
-        yield client
-    finally:
-        await client.aclose()
-
-
-async def _preflight(client: VerbumiaClient) -> None:
-    """Verify reachability + auth before starting the JSON-RPC loop.
-
-    Hits `/v1/mcp/projects?limit=1` so we exercise both the API key (auth)
-    and the mcp:* scope. Failures are turned into stderr-friendly messages
-    so the MCP host (Claude Desktop / etc.) surfaces a real cause.
-    """
-    try:
-        await client.get("/v1/mcp/projects", params={"limit": 1})
-        _info(f"sonenta-mcp: connected to {client.config.api_base}")
-    except VerbumiaApiError as exc:
-        if exc.status == 401:
-            raise RuntimeError(
-                "SONENTA_API_KEY was rejected (401). Verify the key in Sonenta → "
-                "Org Settings → API Keys; new keys are shown once on creation."
-            ) from exc
-        if exc.status == 403:
-            raise RuntimeError(
-                "API key lacks the `mcp:*` scope (403). Issue a key with mcp:* in "
-                "Sonenta → Org Settings → API Keys."
-            ) from exc
-        raise RuntimeError(
-            f"Sonenta API rejected the connectivity probe ({exc.status}): {exc.body}"
-        ) from exc
-    except Exception as exc:
-        raise RuntimeError(
-            f"Could not reach {client.config.api_base}: {exc}. "
-            f"Set SONENTA_BASE_URL (or legacy VERBUMIA_*) for self-host or staging."
-        ) from exc
-
-
-async def run() -> None:
-    config = load_config()
-    _info(f"sonenta-mcp {__version__} starting (api={config.api_base})")
-    server: Server = Server("sonenta")
-
-    async with _client_for(config) as client:
-        await _preflight(client)
-        register(server, client)
-        async with stdio_server() as (read_stream, write_stream):
-            await server.run(
-                read_stream,
-                write_stream,
-                InitializationOptions(
-                    server_name="sonenta",
-                    server_version=__version__,
-                    capabilities=ServerCapabilities(tools=ToolsCapability(listChanged=False)),
-                ),
-            )