@sonenta/mcp 0.16.0

package/python/verbumia_mcp/config.py

@@ -0,0 +1,105 @@
+"""Runtime configuration loaded from environment variables.
+
+The MCP server is invoked by clients like Claude Desktop, which pass `env`
+entries through to the spawned process. We never read a config file — env
+vars are the only contract.
+
+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.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+
+DEFAULT_API_BASE = "https://api.sonenta.com"
+
+
+@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:
+    # Auth key. Canonical: SONENTA_API_KEY. Accepted fallbacks (in order):
+    # SONENTA_TOKEN, then the legacy VERBUMIA_API_KEY / VERBUMIA_TOKEN.
+    token = _env("SONENTA_API_KEY", "SONENTA_TOKEN", "VERBUMIA_API_KEY", "VERBUMIA_TOKEN")
+    if not token:
+        raise RuntimeError(
+            "SONENTA_API_KEY is required. Generate one in Sonenta → Org Settings → "
+            "API Keys and add it to your MCP client config (e.g. Claude Desktop's "
+            "mcp.json `env`). SONENTA_TOKEN — and the legacy VERBUMIA_API_KEY / "
+            "VERBUMIA_TOKEN — are also accepted for back-compat."
+        )
+
+    # API base. Canonical: SONENTA_BASE_URL. Fallbacks: SONENTA_API_BASE, then
+    # legacy VERBUMIA_BASE_URL / VERBUMIA_API_BASE, then the default host.
+    api_base = (
+        _env("SONENTA_BASE_URL", "SONENTA_API_BASE", "VERBUMIA_BASE_URL", "VERBUMIA_API_BASE")
+        or DEFAULT_API_BASE
+    ).rstrip("/")
+
+    # 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

@@ -0,0 +1,88 @@
+"""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"verbumia-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 Verbumia → "
+                "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 "
+                "Verbumia → Org Settings → API Keys."
+            ) from exc
+        raise RuntimeError(
+            f"Verbumia 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"verbumia-mcp {__version__} starting (api={config.api_base})")
+    server: Server = Server("verbumia")
+
+    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="verbumia",
+                    server_version=__version__,
+                    capabilities=ServerCapabilities(tools=ToolsCapability(listChanged=False)),
+                ),
+            )