cinna-cli 0.1.0__py3-none-any.whl

cinna/mcp_proxy.py

@@ -0,0 +1,151 @@
+"""MCP stdio server that proxies knowledge queries to the platform backend.
+
+Launched by Claude Code (or other MCP clients) via .mcp.json config.
+Runs as a subprocess — reads from stdin, writes to stdout (MCP stdio transport).
+"""
+
+import logging
+import os
+import asyncio
+from pathlib import Path
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from cinna.config import load_config, CinnaConfig
+from cinna.client import PlatformClient
+
+logger = logging.getLogger("cinna.mcp_proxy")
+
+
+def create_mcp_server(config: CinnaConfig) -> Server:
+    """Create the MCP server with knowledge query tool."""
+
+    server = Server("agent-knowledge")
+    client = PlatformClient(config)
+    logger.info("MCP server created for agent %s (%s)", config.agent_name, config.agent_id)
+
+    @server.list_tools()
+    async def list_tools():
+        return [
+            Tool(
+                name="knowledge_query",
+                description="Search the agent's knowledge base for relevant documentation and articles",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "Natural language search query",
+                        },
+                        "topic": {
+                            "type": "string",
+                            "description": f"Knowledge topic to search in. Available: {_topic_list(config)}",
+                        },
+                    },
+                    "required": ["query"],
+                },
+            )
+        ]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict):
+        if name != "knowledge_query":
+            logger.warning("Unknown tool called: %s", name)
+            return [TextContent(type="text", text=f"Unknown tool: {name}")]
+
+        query = arguments.get("query", "")
+        topic = arguments.get("topic")
+        logger.info("knowledge_query: query=%r topic=%r", query, topic)
+
+        try:
+            response = client.search_knowledge(config.agent_id, query, topic)
+        except Exception:
+            logger.exception("knowledge_query failed for query=%r topic=%r", query, topic)
+            raise
+        results = response.get("results", [])
+        logger.info("knowledge_query returned %d results", len(results))
+
+        if not results:
+            return [TextContent(type="text", text="No results found.")]
+
+        formatted = _format_results(results)
+        return [TextContent(type="text", text=formatted)]
+
+    return server
+
+
+def _topic_list(config: CinnaConfig) -> str:
+    topics = [t for ks in config.knowledge_sources for t in ks.topics]
+    return ", ".join(topics) if topics else "all topics"
+
+
+def _format_results(results: list[dict]) -> str:
+    parts = []
+    for r in results:
+        source = r.get("source", "unknown")
+        similarity = r.get("similarity", 0)
+        content = r.get("content", "")
+        parts.append(f"## [{source}] (relevance: {similarity:.0%})\n\n{content}")
+    return "\n\n---\n\n".join(parts)
+
+
+def _setup_mcp_logging(workspace_root: Path) -> None:
+    """Set up file logging for the MCP proxy subprocess.
+
+    The proxy is launched directly by the MCP client (not via the Click CLI
+    group), so the normal setup_logging() path is never hit.  We configure
+    logging to the same cinna.log used by the rest of the CLI.
+    """
+    from cinna.logging import LOG_FILE
+    import logging.handlers
+
+    log_path = workspace_root / LOG_FILE
+    handler = logging.handlers.RotatingFileHandler(
+        log_path, maxBytes=5 * 1024 * 1024, backupCount=3,
+    )
+    handler.setFormatter(
+        logging.Formatter("%(asctime)s %(levelname)s [%(name)s] %(message)s")
+    )
+    root = logging.getLogger("cinna")
+    root.setLevel(logging.DEBUG)
+    root.addHandler(handler)
+
+
+def run_mcp_proxy():
+    """Entry point for `cinna mcp-proxy` — run as MCP stdio server."""
+    config_path = os.environ.get("CINNA_CONFIG")
+    if not config_path:
+        raise SystemExit("CINNA_CONFIG environment variable not set")
+
+    workspace_root = Path(config_path).parent.parent
+    _setup_mcp_logging(workspace_root)
+
+    logger.info("MCP proxy starting (config=%s)", config_path)
+
+    try:
+        config = load_config(workspace_root)
+    except Exception:
+        logger.exception("Failed to load config from %s", workspace_root)
+        raise
+
+    try:
+        server = create_mcp_server(config)
+    except Exception:
+        logger.exception("Failed to create MCP server")
+        raise
+
+    async def main():
+        async with stdio_server() as (read_stream, write_stream):
+            logger.info("MCP stdio transport connected, serving requests")
+            init_options = server.create_initialization_options()
+            await server.run(read_stream, write_stream, init_options)
+
+    try:
+        asyncio.run(main())
+    except Exception:
+        logger.exception("MCP proxy crashed")
+        raise
+    finally:
+        logger.info("MCP proxy shut down")

cinna/mutagen_runtime.py

@@ -0,0 +1,168 @@
+"""Mutagen install/verification helpers.
+
+The platform pins a specific Mutagen version and exposes it via GET /sync-runtime.
+This module checks what the local machine has, prompts to install if missing,
+and gates `cinna setup` / `cinna sync start` on a version match.
+"""
+
+import logging
+import platform
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+import click
+
+from cinna.client import PlatformClient
+from cinna.config import CinnaConfig, save_config
+from cinna.errors import MutagenNotFoundError, MutagenVersionMismatchError
+from cinna import console
+
+logger = logging.getLogger("cinna.mutagen_runtime")
+
+
+@dataclass
+class InstalledMutagen:
+    path: str
+    version: str
+
+
+@dataclass
+class RequiredMutagen:
+    version: str
+    agent_sha256: str
+    platform_api_version: str
+
+
+def detect_local_mutagen() -> InstalledMutagen | None:
+    """Locate `mutagen` on PATH and parse its version."""
+    path = shutil.which("mutagen")
+    if not path:
+        return None
+
+    try:
+        result = subprocess.run(
+            [path, "version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+
+    version = _parse_mutagen_version(result.stdout)
+    if not version:
+        logger.warning("Could not parse Mutagen version from: %r", result.stdout)
+        return None
+    return InstalledMutagen(path=path, version=version)
+
+
+def _parse_mutagen_version(text: str) -> str | None:
+    """Extract a semver-ish version string from `mutagen version` output."""
+    match = re.search(r"(\d+\.\d+\.\d+(?:[-.][A-Za-z0-9]+)*)", text)
+    return match.group(1) if match else None
+
+
+def _minor_version(v: str) -> tuple[int, int] | None:
+    """Return (major, minor) from a version string, ignoring patch/suffix."""
+    match = re.match(r"(\d+)\.(\d+)", v or "")
+    if not match:
+        return None
+    return int(match.group(1)), int(match.group(2))
+
+
+def fetch_required_mutagen(
+    client: PlatformClient, agent_id: str
+) -> RequiredMutagen:
+    """Ask the platform which Mutagen version to pin to."""
+    data = client.get_sync_runtime(agent_id)
+    return RequiredMutagen(
+        version=data.get("mutagen_version", ""),
+        agent_sha256=data.get("mutagen_agent_sha256", ""),
+        platform_api_version=data.get("platform_api_version", ""),
+    )
+
+
+def install_mutagen(required: RequiredMutagen) -> None:
+    """Platform-aware install. Prints the one-liner; the user runs it.
+
+    We deliberately do not shell out to a package manager automatically — that
+    is a privileged operation the user should authorize. We print the install
+    command, wait for confirmation that they've run it, and re-detect.
+    """
+    system = platform.system()
+    if system == "Darwin":
+        cmd = "brew install mutagen-io/mutagen/mutagen"
+    elif system == "Linux":
+        cmd = (
+            "See https://mutagen.io/documentation/introduction/installation for "
+            "Linux install instructions (prebuilt tarballs on GitHub releases)."
+        )
+    else:
+        cmd = "Mutagen supports Windows via WSL. See https://mutagen.io/ for details."
+
+    console.console.print()
+    console.console.print(
+        f"Mutagen {required.version} is required for continuous sync."
+    )
+    console.console.print(f"  {cmd}")
+    console.console.print()
+
+
+def ensure_mutagen_ready(
+    client: PlatformClient,
+    config: CinnaConfig,
+    workspace_root,
+    *,
+    interactive: bool = True,
+) -> InstalledMutagen:
+    """Verify a matching Mutagen install; prompt to install if missing.
+
+    Updates `config.mutagen_version` and `last_sync_runtime_check_at` on success.
+    Raises MutagenNotFoundError / MutagenVersionMismatchError on hard failures.
+    """
+    required = fetch_required_mutagen(client, config.agent_id)
+    installed = detect_local_mutagen()
+
+    if installed is None:
+        install_mutagen(required)
+        if interactive and click.confirm(
+            "Run the command above, then press Enter to continue.", default=True
+        ):
+            installed = detect_local_mutagen()
+        if installed is None:
+            raise MutagenNotFoundError(required.version)
+
+    if required.version and installed.version != required.version:
+        req_minor = _minor_version(required.version)
+        inst_minor = _minor_version(installed.version)
+        same_minor = req_minor is not None and req_minor == inst_minor
+
+        if same_minor:
+            # Patch-level differences within the same minor version — Mutagen's
+            # wire protocol is stable across these, so warn and continue.
+            console.warn(
+                f"Mutagen {installed.version} differs from platform pin "
+                f"{required.version} (patch-level only — proceeding)."
+            )
+        else:
+            if interactive:
+                console.warn(
+                    f"Installed Mutagen {installed.version} does not match required "
+                    f"{required.version}."
+                )
+                if not click.confirm("Continue anyway?", default=False):
+                    raise MutagenVersionMismatchError(
+                        installed.version, required.version
+                    )
+            else:
+                raise MutagenVersionMismatchError(installed.version, required.version)
+
+    config.mutagen_version = installed.version
+    config.last_sync_runtime_check_at = datetime.now(timezone.utc).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+    save_config(config, workspace_root)
+    return installed

cinna/sync.py

@@ -0,0 +1,120 @@
+"""Workspace archive helpers for the initial clone.
+
+Continuous sync is handled by Mutagen (see sync_session.py). What remains here
+is just the tarball/zip extraction used once, when `cinna setup` seeds the
+workspace from `GET /workspace`.
+"""
+
+import io
+import logging
+import tarfile
+import zipfile
+from pathlib import Path
+
+from cinna import console
+
+logger = logging.getLogger("cinna.sync")
+
+MAX_FILE_SIZE = 100 * 1024 * 1024  # 100MB
+
+
+def ensure_workspace_dirs(workspace: Path) -> None:
+    """Ensure required workspace subdirectories exist.
+
+    Mirrors the layout the remote agent environment guarantees so the local
+    workspace matches production even when the downloaded tarball is sparse:
+
+    - ``files/``, ``knowledge/`` — bundle-owned folders that always exist on the
+      env but may be empty.
+    - ``app-data/storage/``, ``app-data/uploads/``, ``app-data/cache/`` — the
+      per-user persistent volume mounted at ``/app/workspace/app-data`` in the
+      env. Created locally so script paths resolve immediately and Mutagen has
+      a target to sync into.
+    """
+    for rel in (
+        "files",
+        "knowledge",
+        "app-data/storage",
+        "app-data/uploads",
+        "app-data/cache",
+    ):
+        (workspace / rel).mkdir(parents=True, exist_ok=True)
+
+
+def extract_workspace_tarball(
+    archive_bytes: bytes,
+    workspace: Path,
+    only_files: set[str] | None = None,
+) -> list[str]:
+    """Extract workspace archive to the workspace directory.
+
+    Supports tar (gz/bz2/xz/plain) and zip formats — auto-detected from content.
+    Returns list of extracted file paths.
+    Validates: no path traversal, no symlinks, max file size.
+
+    If only_files is provided, only extracts files whose relative path is in the set.
+    """
+    workspace.mkdir(parents=True, exist_ok=True)
+
+    if zipfile.is_zipfile(io.BytesIO(archive_bytes)):
+        logger.debug("Detected zip archive (%d bytes)", len(archive_bytes))
+        return _extract_zip(archive_bytes, workspace, only_files)
+    else:
+        logger.debug("Detected tar archive (%d bytes)", len(archive_bytes))
+        return _extract_tar(archive_bytes, workspace, only_files)
+
+
+def _extract_tar(
+    archive_bytes: bytes,
+    workspace: Path,
+    only_files: set[str] | None = None,
+) -> list[str]:
+    """Extract a tar archive (any compression) to workspace."""
+    extracted = []
+    with tarfile.open(fileobj=io.BytesIO(archive_bytes), mode="r:*") as tar:
+        for member in tar.getmembers():
+            member_path = Path(member.name)
+            if member_path.is_absolute() or ".." in member_path.parts:
+                console.warn(f"Skipping unsafe path: {member.name}")
+                continue
+            if member.issym() or member.islnk():
+                console.warn(f"Skipping symlink: {member.name}")
+                continue
+            if member.size > MAX_FILE_SIZE:
+                console.warn(f"Skipping large file: {member.name}")
+                continue
+            if only_files is not None and member.name not in only_files:
+                continue
+
+            tar.extract(member, path=workspace, filter="data")
+            extracted.append(member.name)
+    return extracted
+
+
+def _extract_zip(
+    archive_bytes: bytes,
+    workspace: Path,
+    only_files: set[str] | None = None,
+) -> list[str]:
+    """Extract a zip archive to workspace."""
+    extracted = []
+    with zipfile.ZipFile(io.BytesIO(archive_bytes)) as zf:
+        for info in zf.infolist():
+            member_path = Path(info.filename)
+            if member_path.is_absolute() or ".." in member_path.parts:
+                console.warn(f"Skipping unsafe path: {info.filename}")
+                continue
+            if info.file_size > MAX_FILE_SIZE:
+                console.warn(f"Skipping large file: {info.filename}")
+                continue
+            if info.is_dir():
+                continue
+            if only_files is not None and info.filename not in only_files:
+                continue
+
+            target = workspace / info.filename
+            target.parent.mkdir(parents=True, exist_ok=True)
+            with zf.open(info) as src, open(target, "wb") as dst:
+                dst.write(src.read())
+            extracted.append(info.filename)
+    return extracted