deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/mcp_server.py

@@ -0,0 +1,906 @@
+"""MCP server exposing the DeepCell CLI as a single tool.
+
+Supports two transports:
+- **stdio** (default): local Claude Code / Desktop — no authentication.
+- **streamable-http**: remote access for Claude.ai, ChatGPT, Manus —
+  OAuth 2.1 + PKCE when ``MCP_OAUTH_URL`` is set.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shlex
+import traceback
+from urllib.parse import quote, urlparse
+
+# Suppress httpx INFO-level request logs so they don't leak into MCP output.
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logging.getLogger("httpcore").setLevel(logging.WARNING)
+
+logger = logging.getLogger(__name__)
+
+from click.testing import CliRunner
+from mcp.server.fastmcp import FastMCP
+
+from deepcell_cli.capabilities import (
+    MCP_ALLOWED_COMMANDS,
+    MCP_BLOCKED_COMMANDS as MCP_BLOCK_POLICY,
+    blocked_mcp_commands,
+    mcp_blocked_summary,
+)
+
+# ── Configuration ──────────────────────────────────────────
+
+# Commands that require interactive input, produce binary output, need local
+# sync state, or would mutate process-global credentials on a shared host.
+BLOCKED_COMMANDS = blocked_mcp_commands()
+
+# Commands that need confirmation flags auto-appended for non-interactive use.
+# Keys are matched against the leading tokens, so a key may name a top-level
+# command ("rm") or a "<group> <subcommand>" pair.
+AUTO_CONFIRM: dict[str, list[str]] = {
+    "rm": ["-y"],
+    "restore": ["--yes"],
+    "changes revert": ["--yes"],
+}
+
+# Top-level commands documented in TOOL_DESCRIPTION. Must stay equal to the
+# registered Click commands minus BLOCKED_COMMANDS — tests/test_mcp_server.py
+# cross-checks both directions so the catalog can't silently drift.
+DOCUMENTED_COMMANDS = frozenset(MCP_ALLOWED_COMMANDS)
+
+TOOL_DESCRIPTION = """\
+Run a DeepCell CLI command. Structured results are JSON; `cat` prints raw XML
+and sheet queries print markdown. `guide <topic>` returns a JSON envelope whose
+`content` is the topic's markdown, alongside the routing metadata (stage, order,
+reads, commands, see_also) — read `content`. An "[exit code N]" line means the
+command reported a problem — but NOT always that nothing happened: `write`,
+`push`, `commit`, `replace` and the reasoning writers save
+first and validate after, so exit 1 there means "saved AND invalid" (fix and
+write again; do not retry blindly), while `defs` is whole-batch atomic and
+exit 1 means nothing changed. Run `ref exit` for the full contract.
+
+A .deepcell file connects selectable Reasoning, Spreadsheet, Document and Deck
+surfaces; qualitative work need not invent a Spreadsheet. Use `help` for exact
+invocation and exits, `rules` for invariants, `guide` for procedures, `ref` for
+legal names and values, and `example` for complete valid artifacts.
+
+Available commands:
+
+  ORIENT — look at what exists before adding to it
+    ls                          List files in active project
+    cat <file> [--revision R]   Print file content (XML)
+    describe <file>             Inspect model schema (items, contexts, sheets)
+    query <file> <item> [ctx] [status]
+                                Query a value or all values for an item
+    query <file> --sheet <id>   Render a sheet as markdown
+    cell-meta <file> <item> <ctx> [--status REF] [--scenario REF] [--custom-dimensions dim:member;...]
+                                Show cell metadata (formula, deps, data source)
+    grep <pattern> [--file F]   Search items/values by regex
+
+  INGEST — external data in (skip for from-scratch work)
+    import <file.xlsx|csv> ...  Import xlsx/csv into a .deepcell document
+    ingest cn ...               Ingest cninfo A-share filings
+
+  GENERATE — create one file, then build only the surfaces the work needs
+    write <file> --content <xml>  Upload/create a file (inline content)
+    write <file> --content-base64 <b64>  Upload/create (base64-encoded content)
+    write <file> --file <path>    Upload/create from a LOCAL file (see caveat)
+    edit <file> <item> <ctx> <value> [--force]
+                                Edit a single value
+    edit <file> --batch '<json>'
+                                Batch edit: inline JSON array (starts with
+                                '[' or '{'), or a JSON file path
+    defs add-item / update-item / delete-item / rename-item / reorder-item
+    defs add-calc / update-calc / delete-calc      Formulas (CalcDefs)
+    defs add-context / update-context / delete-context / rename-context
+    defs add-period / add-scenario / add-status / add-rule / delete-rule
+    defs add-sheet / rename-sheet / reorder-sheets / delete-sheet
+    defs add-block / set-block-attrs / add-axis-member / delete-axis-member
+    defs add-format / update-format / delete-format / set-format / header
+    defs add-source / update-source / set-source-cites / delete-source
+    defs add-doc / update-doc / delete-doc
+    defs reorder-contexts / rename-dimension / rename-member
+    defs add-sensitivity / update-sensitivity
+    defs apply <file> --ops '<json>'
+                                Apply a JSON ops batch atomically (inline JSON;
+                                --ops-file reads a LOCAL path — see caveat)
+    (defs ops are validated; prefer them over replace.
+     Run `defs --help` for every convenience command.)
+    reasoning add-claim / add-assumption / add-evidence / add-argument
+    reasoning update-claim / update-assumption   Patch attributes in place
+    reasoning graph / impact / lint       Inspect the reasoning graph
+    doc list <file>             Every <Document> in the file
+    doc show <file> [--doc ID] [--as text|markdown]
+                                The memo, with every deepcell: link RESOLVED
+    doc outline <file>          Headings and the anchor each is addressable by
+    doc links <file> [--unresolved]      Every reference and whether it resolved
+    doc backlinks <file> --target 'claim/t_hold'
+                                What cites a reference -- THIS FILE ONLY
+    deck add <file> --name "Q3 review"      Add a deck
+    deck add-slide <file> --deck d1 --name "Outlook"
+                                Add an empty slide
+    deck rename / reorder / delete          Deck structure
+    deck rename-slide / reorder-slide / delete-slide
+                                Slide structure (all need --deck)
+    deck bind <file> --deck d1 --binding-id b1 --binding-kind value --ref ...
+                                Point a slide at a live value, or update it
+    deck unbind <file> <binding_id> --deck d1
+    Deck structure is flags, above.
+    Only two ops still need `defs apply` — "set_presentation_slide_html" and
+    "set_presentation_deck_style", which carry document-sized arguments.
+    Exact op names and fields come from `ref op`. See "guide present/decks".
+
+  REVISE — change a premise and reassess what depends on it
+    replace <file> <old> <new>
+                                String-replace in XML (last resort — prefer defs;
+                                `edit --replace` is a deprecated alias)
+    variant list                List variants
+    variant create <name>       Create a variant
+                                (Note: variant checkout/diff/merge need a LOCAL clone — blocked here)
+    rm <file>                   Delete a file (auto-confirmed)
+    log [--file F] [-n N]       Show version history
+    diff <rev_a> [rev_b]        Diff between revisions
+    restore <rev> [--file F]    Restore to a revision (auto-confirmed)
+    changes list [FILE] [-n N]  Grouped changes by writer (agent/CLI/browser)
+    changes diff <base> [head]  What one change did, semantically
+    changes revert <base> <head>
+                                Undo one change as a new commit (auto-confirmed)
+
+  VERIFY — change one thing, see everything it affects
+    relationships <file>        Show relationship graph
+    reasoning-diff <file>       Warn if a Claim's anchor changed vs git HEAD
+    impact show <file> --since <rev>   Every place a change may have made stale
+                                (spreadsheet -> reasoning -> document -> deck)
+    impact review <file> <key> --surface S --locator L
+                                Mark one place reviewed (the marker disappears)
+    impact apply <file> <key> --op O --target-id T --surface S --locator L
+                                Apply one reviewed reasoning fix, recorded as revised
+    impact reopen <file> <key>  Undo one review decision
+    claim falsified / history / variant   Claim lifecycle in a project file
+    assumption impact <file> <id>   Direct dependent Claims (project file)
+
+  PRESENT — deliver the work to someone else
+    viewer <file>               Print the signed-in workbench URL (auth: edit, chat)
+    share create <file> [--permission view|edit] [--expires-days N]
+                                Create a browser share link (prints viewer URL)
+    share list [--file F]       List active share links
+    share revoke <id>           Revoke a share link
+    After writing or editing a .deepcell file, offer the user a browser link.
+    "viewer <file>" prints the owner's signed-in workbench URL, while
+    "share create <file>" prints a public view URL that opens for anyone
+    (including readers who cannot use the workbench). See "guide present/deliver".
+
+  SESSION — who you are and where your work lands
+    whoami                      Show the authenticated user
+    project list                List projects
+    project use <slug>          Set active project
+    project create <name>       Create a new project
+    project info [slug]         Show project details
+    doctor                      Check setup and report what to run next
+
+  SYNC — local <-> cloud
+    download <file> -o <path>   Download file to local path
+                                (the rest of sync is blocked here — see below)
+
+  LEARN — the five reference surfaces
+    help [command]              Every command, flag, exit code and example.
+                                "help -f json" is the whole tree in one call.
+    guide [topic]               Show built-in topic guides
+    guide --capabilities        Jingwei/CLI/reference/transport contract
+    rules [id] [--surfaces LIST | --all]
+                                Invariants, scoped to the work shape.
+                                "rules" alone is the universal set only.
+                                "--surfaces reasoning,document" adds a shape's.
+                                "--all" is every rule, whatever the shape.
+                                Lint findings cite the rule they enforce, so
+                                "rules R2" reads the rule a failure just named.
+    ref [ns|ns/name|id]         Legal values, generated from the code.
+                                Run bare `ref` for the generated namespaces.
+                                Resolves any typed id: "ref rule:R2".
+    example [--pack NAME]       Complete, valid documents, indexed by the
+                                Mechanic each one demonstrates.
+    example show <name> <layer> One layer: skeleton, full, or transcript.
+                                Transcript is the build order — the thing
+                                Agents most often get wrong.
+    example get <name> --into F Write a guaranteed-parsing document to F.
+    ref search <text>           Search every surface at once.
+                                Each result says its type: op, topic, rule.
+
+Local-disk caveat: these read or write paths on the machine running this server,
+not project files, so over a remote connection they cannot see your model:
+import, download, reasoning-diff, write --file, and defs apply --ops-file.
+Workspace-backed claim, assumption, and reasoning reads are not local-disk
+commands and work normally over MCP. Prefer inline forms where offered:
+write --content and defs apply --ops.
+
+"--stdin" is unavailable here (this server runs the CLI with no stdin, so it
+would write empty content). Use write --content or --content-base64.
+
+"restore <rev>" without --file rolls back the WHOLE project and is
+auto-confirmed — pass --file to limit it, and check `log` first.
+
+Blocked commands: {blocked_commands}.
+
+Examples:
+  ls
+  query model.deepcell Revenue FY2025E projected
+  query model.deepcell --sheet income_statement
+  edit model.deepcell Revenue_Growth FY2025E 0.12 --force
+  edit model.deepcell --batch '[{"itemRef":"Revenue","contextRef":"FY2025E","newValue":"120"}]'
+  grep Revenue --file model.deepcell
+  describe model.deepcell
+  project list
+""".replace("{blocked_commands}", mcp_blocked_summary())
+
+
+# ── Command parsing ────────────────────────────────────────
+
+
+# Root-level options that take a value. Their *values* must not be mistaken
+# for the subcommand name when locating it (mirrors `FlexibleGroup`).
+_GLOBAL_VALUE_OPTS = frozenset({"-f", "--format", "--project", "--workspace"})
+
+
+def _command_index(tokens: list[str]) -> int | None:
+    """Index of the subcommand name, skipping leading global options.
+
+    ``FlexibleGroup`` accepts global options before the subcommand, so
+    ``-v push`` really does run ``push``. Keying the safety checks off
+    ``tokens[0]`` would leave every blocked command one option away from
+    executing, and every auto-confirm flag one option away from being
+    dropped.
+    """
+    i = 0
+    while i < len(tokens):
+        tok = tokens[i]
+        if tok in _GLOBAL_VALUE_OPTS:
+            i += 2  # skip the option and its value
+            continue
+        if tok.startswith("-"):
+            i += 1
+            continue
+        return i
+    return None
+
+
+def _command_path(tokens: list[str]) -> list[str]:
+    """The non-option tokens, in order, with option values skipped.
+
+    ``_command_index`` finds only the *first* command word. Matching a
+    ``"<group> <subcommand>"`` key needs the same option-skipping applied all
+    the way down.
+    """
+    path: list[str] = []
+    i = 0
+    while i < len(tokens):
+        tok = tokens[i]
+        if tok in _GLOBAL_VALUE_OPTS:
+            i += 2  # skip the option and its value
+            continue
+        if tok.startswith("-"):
+            i += 1
+            continue
+        path.append(tok)
+        i += 1
+    return path
+
+
+def _parse_command(command: str) -> list[str]:
+    """Parse a CLI command string into args for Click, with safety checks."""
+    tokens = shlex.split(command)
+
+    # Strip optional leading "deepcell" prefix
+    if tokens and tokens[0] == "deepcell":
+        tokens = tokens[1:]
+
+    if not tokens:
+        # Plain, and not by omission: `--help` is an eager Click flag. It fires
+        # during parsing and exits before `--format` is ever applied, so
+        # `--help --format json` returns text — the `--format json` that used
+        # to sit here did nothing at all. Every other path below prepends it
+        # for real (`test_format_json_always_prepended`), which is exactly what
+        # made the dead one read as if this path were JSON too.
+        #
+        # Root `--help` is also not the thing the next comment is about: it is
+        # Click's ~90-line root help, which names `help` and `guide` as the two
+        # entry points. That is a good first MCP response.
+        return ["--help"]
+
+    # Root JSON help is the complete generated command/capability tree (about
+    # 480 KB at the time this guard was added). That is useful as a local,
+    # cacheable artifact, but it is an unusable first MCP response and can
+    # exhaust a client's tool-result budget before the agent reads one command.
+    # Keep command-specific help structured; only the bare index is the compact
+    # plain listing. An explicit ``help -f json`` remains available.
+    if tokens == ["help"]:
+        return ["--format", "plain", "help"]
+
+    cmd_idx = _command_index(tokens)
+    cmd_name = tokens[cmd_idx] if cmd_idx is not None else tokens[0]
+
+    if cmd_name in BLOCKED_COMMANDS:
+        policy = MCP_BLOCK_POLICY[cmd_name]
+        raise ValueError(
+            f"Command '{cmd_name}' is blocked in MCP mode "
+            f"({policy['reason']}: {policy['detail']}). "
+            f"Blocked: {', '.join(sorted(BLOCKED_COMMANDS))}"
+        )
+
+    # This server runs the CLI through CliRunner, whose stdin is empty, so
+    # `--stdin` reads "" and overwrites the file with empty content — a
+    # destructive write the caller reads back as a malformed-XML error.
+    if "--stdin" in tokens:
+        raise ValueError(
+            "'--stdin' cannot be used over MCP (this server runs the CLI with "
+            "no stdin, so it would write empty content). Pass the content "
+            "inline with --content '<xml/>' or --content-base64 instead."
+        )
+
+    # Auto-append confirmation flags for destructive commands. Keys may be a
+    # top-level command ("rm") or a "<group> <subcommand>" pair — matched
+    # against the resolved command path after options have been skipped.
+    path = _command_path(tokens)
+    for key, flags in AUTO_CONFIRM.items():
+        key_tokens = key.split()
+        if path[: len(key_tokens)] == key_tokens:
+            for flag in flags:
+                if flag not in tokens:
+                    tokens.append(flag)
+
+    # Always force JSON output for structured agent consumption
+    return ["--format", "json"] + tokens
+
+
+def _token_identity(token: str) -> str:
+    """Stable per-caller key: the JWT's subject, else the token itself.
+
+    Keying on the raw access token meant the path changed every time the token
+    refreshed, silently resetting the caller's ``project use`` mid-session.
+    The payload is decoded WITHOUT verification on purpose — this only picks a
+    filename, never authorizes anything, and the server validates the token.
+    """
+    import base64
+    import json as _json
+
+    parts = token.split(".")
+    if len(parts) == 3:
+        try:
+            payload = parts[1]
+            payload += "=" * (-len(payload) % 4)  # restore base64url padding
+            claims = _json.loads(base64.urlsafe_b64decode(payload))
+            sub = claims.get("sub")
+            if sub:
+                return str(sub)
+        except Exception:
+            pass  # not a JWT we can read — fall back to the opaque token
+    return token
+
+
+def _config_path_for_token(token: str) -> str:
+    """Per-caller config path, keyed by a hash of the caller's identity.
+
+    Hashed so no credential lands in a filename. The file is seeded from the
+    base config's ``api_url`` on creation: ``get_api_url()`` falls back to
+    DEFAULT_API_URL (the public beta) when the config it reads has no
+    ``api_url``, so handing a caller an empty config silently repointed a
+    self-hosted deployment at beta.deepcell.net. ``active_workspace`` is
+    deliberately NOT inherited — isolating it is the whole point of this file.
+    """
+    import hashlib
+    import json as _json
+    from pathlib import Path
+
+    digest = hashlib.sha256(
+        _token_identity(token).encode("utf-8")
+    ).hexdigest()[:16]
+    path = Path.home() / ".deepcell" / "mcp-sessions" / f"{digest}.json"
+
+    if not path.exists():
+        seed: dict = {}
+        base = Path.home() / ".deepcell" / "config.json"
+        try:
+            if base.exists():
+                base_cfg = _json.loads(base.read_text())
+                if isinstance(base_cfg, dict) and base_cfg.get("api_url"):
+                    seed["api_url"] = base_cfg["api_url"]
+        except Exception:
+            pass  # unreadable base config — the env vars still apply
+        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        path.write_text(_json.dumps(seed, indent=2) + "\n")
+        try:
+            path.chmod(0o600)
+        except OSError:
+            pass
+
+    return str(path)
+
+
+def _stream(result, name: str) -> str:
+    """Read ``result.stdout`` / ``result.stderr``, tolerating old Click.
+
+    On Click 8.1 with a mixed runner, ``.stderr`` raises ``ValueError``; fall
+    back to the combined stream for stdout and to empty for stderr.
+    """
+    try:
+        return getattr(result, name) or ""
+    except ValueError:
+        return (result.output or "") if name == "stdout" else ""
+
+
+def _run_cli(
+    args: list[str],
+    env_override: dict[str, str] | None = None,
+) -> tuple[str, str, int]:
+    """Invoke the Click CLI and capture output."""
+    from deepcell_cli.config import ENV_CLIENT as _ENV_CLIENT
+    from deepcell_cli.main import cli
+    from deepcell_cli.upgrade_check import ENV_DISABLE as _NO_UPGRADE_CHECK
+
+    # Every stderr byte a command writes is appended to the MCP response as
+    # "[stderr] ...", so an upgrade-available notice would ride along on every
+    # single tool result. It is also advice the caller cannot act on — the
+    # install being checked is this server's. Silence it for all MCP paths,
+    # not just the OAuth one, since env_override is None without a token.
+    #
+    # `DEEPCELL_CLIENT` rides along for the same reason: this function runs the
+    # CLI *in-process*, so without it every MCP tool call reaches the API as an
+    # ordinary CLI request and the two are indistinguishable in the funnel —
+    # yet an agent calling a tool and a human typing a command are different
+    # products with different questions to ask of them. Set after the spread so
+    # a caller cannot claim to be anything else.
+    env_override = {
+        **(env_override or {}),
+        _NO_UPGRADE_CHECK: "1",
+        _ENV_CLIENT: "mcp",
+    }
+
+    try:
+        runner = CliRunner(mix_stderr=False)
+    except TypeError:
+        # Click 8.2+ removed mix_stderr
+        runner = CliRunner()
+
+    result = runner.invoke(cli, args, catch_exceptions=True, env=env_override)
+
+    # `Result.output` is the INTERLEAVED stdout+stderr stream on Click 8.2+
+    # ("what the user would see in a terminal"). Using it as stdout splices
+    # warnings into the JSON payload and repeats them under `[stderr]`.
+    # `Result.stdout` is the clean stream on both 8.1 (mix_stderr=False) and
+    # 8.2+.
+    stdout = _stream(result, "stdout")
+    stderr = _stream(result, "stderr")
+    exit_code = result.exit_code
+
+    # Surface unexpected exceptions
+    if result.exception and not isinstance(result.exception, SystemExit):
+        tb = "".join(traceback.format_exception(type(result.exception), result.exception, result.exception.__traceback__))
+        stderr = f"{stderr}\n{tb}".strip()
+        if exit_code == 0:
+            exit_code = 1
+
+    return stdout, stderr, exit_code
+
+
+# ── MCP Server ─────────────────────────────────────────────
+
+def _build_server(
+    host: str = "127.0.0.1",
+    port: int = 8080,
+    oauth_url: str | None = None,
+) -> FastMCP:
+    """Build the FastMCP server instance.
+
+    When *oauth_url* is provided, OAuth 2.1 + PKCE authentication is enabled
+    for the streamable-http transport (required for Claude.ai / ChatGPT / Manus).
+    """
+    kwargs: dict = dict(
+        host=host,
+        port=port,
+        instructions=(
+            "DeepCell CLI server. Use the 'deepcell' tool to run CLI commands "
+            "against .deepcell financial models. Output is JSON, except the "
+            "help index — an empty command and a bare `help` return plain "
+            "text, because the JSON command tree is ~550 KB and would exhaust "
+            "a client's result budget before it read one command. Ask for "
+            "`help -f json` explicitly if you want that tree."
+        ),
+    )
+
+    if oauth_url:
+        from urllib.parse import urlparse
+
+        from mcp.server.auth.settings import (
+            AuthSettings,
+            ClientRegistrationOptions,
+            RevocationOptions,
+        )
+        from deepcell_cli.oauth_provider import DeepCellOAuthProvider
+
+        jwt_secret = os.environ.get("JWT_SECRET", "")
+        if not jwt_secret:
+            raise RuntimeError(
+                "JWT_SECRET env var is required when MCP_OAUTH_URL is set. "
+                "It must match the Jingwei API's JWT_SECRET."
+            )
+
+        # MCP_OAUTH_URL may include the MCP path (e.g. https://example.com/mcp).
+        # Split into base URL (for OAuth issuer / login redirects) and resource
+        # URL (the actual MCP transport endpoint).
+        parsed = urlparse(oauth_url)
+        base_url = f"{parsed.scheme}://{parsed.netloc}"
+        resource_url = oauth_url  # full URL including /mcp path
+
+        provider = DeepCellOAuthProvider(
+            api_url=os.environ.get("DEEPCELL_API_URL", "http://localhost:8001"),
+            server_url=base_url,
+            # The consent page is a frontend route. In the standard deployment
+            # nginx serves it from this same origin, so base_url is the right
+            # default; MCP_FRONTEND_URL overrides for split-origin setups.
+            frontend_url=os.environ.get("MCP_FRONTEND_URL") or base_url,
+            jwt_secret=jwt_secret,
+            jwt_algorithm=os.environ.get("JWT_ALGORITHM", "HS256"),
+            jwt_issuer=os.environ.get("JWT_ISSUER", "deepcell-api"),
+            jwt_audience=os.environ.get("JWT_AUDIENCE", "deepcell-user"),
+        )
+
+        kwargs["auth_server_provider"] = provider
+        kwargs["auth"] = AuthSettings(
+            issuer_url=base_url,
+            resource_server_url=resource_url,
+            client_registration_options=ClientRegistrationOptions(
+                enabled=True,
+                valid_scopes=["deepcell"],
+                default_scopes=["deepcell"],
+            ),
+            revocation_options=RevocationOptions(enabled=True),
+            required_scopes=["deepcell"],
+        )
+
+    return FastMCP("deepcell", **kwargs)
+
+
+server = _build_server()
+
+
+def _get_access_token_for_request() -> str | None:
+    """Extract the Bearer token from the MCP auth context (if available)."""
+    try:
+        from mcp.server.auth.middleware.auth_context import get_access_token
+
+        at = get_access_token()
+        return at.token if at else None
+    except Exception:
+        return None
+
+
+@server.tool(description=TOOL_DESCRIPTION)
+def deepcell(command: str) -> str:
+    """Run a DeepCell CLI command."""
+    try:
+        args = _parse_command(command)
+    except ValueError as exc:
+        # Carry the same "[exit code N]" marker a failing command would.
+        # `ref exit` tells agents to match on that prefix rather than
+        # on the wording, so a refusal that returned bare prose read as a
+        # command that ran and succeeded.
+        return (
+            f"[exit code 1] Command refused before it ran — nothing changed. "
+            f"{exc}"
+        )
+
+    # If running behind OAuth, propagate the authenticated user's token and
+    # give them a private config file. `project use` (and the single-
+    # workspace auto-select) persist the active workspace to disk, and on a
+    # shared remote host that file is process-global — one caller's active
+    # workspace would silently become every other caller's default.
+    env_override: dict[str, str] | None = None
+    token = _get_access_token_for_request()
+    if token:
+        env_override = {
+            "DEEPCELL_ACCESS_TOKEN": token,
+            "DEEPCELL_CONFIG": _config_path_for_token(token),
+        }
+
+    stdout, stderr, exit_code = _run_cli(args, env_override=env_override)
+
+    # Build response
+    parts: list[str] = []
+    if stdout.strip():
+        parts.append(stdout.strip())
+    if stderr.strip():
+        parts.append(f"[stderr] {stderr.strip()}")
+    if exit_code != 0:
+        # Always spell out failure — several commands exit 1 WITH output
+        # (e.g. "saved but invalid" validation errors), and the caller only
+        # sees this text, never the exit code itself.
+        parts.append(
+            f"[exit code {exit_code}] Command reported a problem. This does "
+            "NOT always mean nothing changed — writes save before they "
+            "validate, so check for a commit_sha/revision in the output "
+            "above before retrying. See `ref exit/1`."
+        )
+
+    return "\n".join(parts) if parts else "(no output)"
+
+
+# ── OAuth consent routes ─────────────────────────────────────
+
+
+def _add_oauth_routes(srv: FastMCP, provider: "DeepCellOAuthProvider") -> None:
+    """Mount the consent-flow JSON routes on the FastMCP Starlette app.
+
+    The sign-in UI itself is the frontend's ``/mcp-auth`` page, which renders
+    the same shared ``AuthPanel`` as every other DeepCell sign-in surface. Only
+    the OAuth state machine lives here, because ``_pending_auth`` is in-process.
+
+    These routes are NOT behind the MCP bearer auth middleware: the caller is a
+    browser mid-authorization that has no MCP token yet. ``/oauth/complete``
+    does its own check instead — it requires the consenting user's Jingwei
+    access token and refuses to issue a code unless the device code was approved
+    by *that same* user. Holding a `session_id` is therefore not enough to bind
+    an identity to someone else's pending authorization.
+    """
+    from starlette.requests import Request
+    from starlette.responses import JSONResponse, RedirectResponse, Response
+    from starlette.routing import Route
+
+    from mcp.server.auth.provider import construct_redirect_uri
+
+    _NO_STORE = {"Cache-Control": "no-store"}
+
+    # When the consent page is served from a different origin than this server
+    # (MCP_FRONTEND_URL), its fetches are cross-origin. Allow exactly that one
+    # origin, on exactly these routes — not app-wide, which would also loosen
+    # /mcp itself. Credentials are never allowed: the page authenticates with an
+    # explicit Authorization header, so no cookie ever needs to ride along.
+    _parsed_frontend = urlparse(provider.frontend_url)
+    _ALLOWED_ORIGIN = (
+        f"{_parsed_frontend.scheme}://{_parsed_frontend.netloc}"
+        if _parsed_frontend.scheme and _parsed_frontend.netloc
+        else ""
+    )
+
+    def _headers(request: Request) -> dict[str, str]:
+        headers = dict(_NO_STORE)
+        origin = request.headers.get("origin")
+        if origin and _ALLOWED_ORIGIN and origin == _ALLOWED_ORIGIN:
+            headers["Access-Control-Allow-Origin"] = origin
+            headers["Vary"] = "Origin"
+        return headers
+
+    def _json(request: Request, payload: dict, status_code: int = 200) -> JSONResponse:
+        return JSONResponse(payload, status_code=status_code, headers=_headers(request))
+
+    def _expired(request: Request) -> JSONResponse:
+        return _json(
+            request,
+            {
+                "error": "invalid_session",
+                "error_description": (
+                    "Invalid or expired session. Restart the authorization "
+                    "flow from your AI assistant."
+                ),
+            },
+            status_code=404,
+        )
+
+    def _bearer(request: Request) -> str:
+        auth = request.headers.get("authorization", "")
+        scheme, _, token = auth.partition(" ")
+        return token.strip() if scheme.lower() == "bearer" else ""
+
+    async def preflight(request: Request) -> Response:
+        """CORS preflight for the split-origin consent page.
+
+        Only fires when MCP_FRONTEND_URL puts the page on another origin; the
+        same-origin deployment never sends one.
+        """
+        headers = _headers(request)
+        if "Access-Control-Allow-Origin" in headers:
+            headers["Access-Control-Allow-Methods"] = "GET, POST, OPTIONS"
+            headers["Access-Control-Allow-Headers"] = "authorization, content-type"
+            headers["Access-Control-Max-Age"] = "600"
+        return Response(status_code=204, headers=headers)
+
+    async def session_get(request: Request) -> Response:
+        """Consent-screen metadata: who is asking, and where the grant goes."""
+        session_id = request.query_params.get("session_id", "")
+        info = provider.describe_pending(session_id) if session_id else None
+        if info is None:
+            return _expired(request)
+        return _json(request, info)
+
+    async def complete_post(request: Request) -> Response:
+        """Finish the authorization once the user has consented.
+
+        Body: ``{session_id, device_code}``, plus the consenting user's Jingwei
+        access token as a Bearer header.
+
+        Both are required, and they must agree. The device code proves a signed-in
+        user approved *something*; the bearer proves who is sitting in front of
+        this browser. Without the cross-check, anyone holding a leaked
+        ``session_id`` could complete it with a device code approved on their own
+        account and silently bind the victim's connector to the attacker's
+        workspace — the redirect still carries the victim's ``state``, so the AI
+        platform would accept it.
+        """
+        try:
+            body = await request.json()
+        except ValueError:
+            return _json(
+                request,
+                {"error": "invalid_request", "error_description": "Malformed JSON body."},
+                status_code=400,
+            )
+        if not isinstance(body, dict):
+            return _json(
+                request,
+                {"error": "invalid_request", "error_description": "Expected a JSON object."},
+                status_code=400,
+            )
+
+        session_id = str(body.get("session_id") or "")
+        device_code = str(body.get("device_code") or "")
+        if not session_id or not device_code:
+            return _json(
+                request,
+                {
+                    "error": "invalid_request",
+                    "error_description": "session_id and device_code are required.",
+                },
+                status_code=400,
+            )
+
+        # Who is consenting? Verified locally against the shared JWT secret.
+        bearer = _bearer(request)
+        consenting = await provider.load_access_token(bearer) if bearer else None
+        if consenting is None:
+            return _json(
+                request,
+                {
+                    "error": "invalid_token",
+                    "error_description": "A valid DeepCell access token is required.",
+                },
+                status_code=401,
+            )
+
+        # Check the session BEFORE burning the single-use device code, so a
+        # stale tab doesn't consume a code it can't complete with.
+        if provider.describe_pending(session_id) is None:
+            return _expired(request)
+
+        redeemed = await provider.redeem_device_code(device_code)
+        if redeemed is None:
+            return _json(
+                request,
+                {
+                    "error": "authorization_pending",
+                    "error_description": (
+                        "That authorization could not be confirmed. Please try again."
+                    ),
+                },
+                status_code=400,
+            )
+        user_id, jingwei_refresh_token = redeemed
+
+        if user_id != consenting.user_id:
+            logger.warning(
+                "Rejected /oauth/complete: device code approved by a different user"
+            )
+            return _json(
+                request,
+                {
+                    "error": "access_denied",
+                    "error_description": (
+                        "That approval belongs to a different account."
+                    ),
+                },
+                status_code=403,
+            )
+
+        try:
+            code, redirect_uri, state = provider.create_authorization_code(
+                session_id, user_id, jingwei_refresh_token
+            )
+        except ValueError:
+            return _expired(request)
+
+        # Returned as JSON rather than a 302 so the page can navigate itself —
+        # fetch() would otherwise follow the redirect to the AI platform's
+        # callback and swallow it.
+        return _json(
+            request,
+            {"redirect_url": construct_redirect_uri(redirect_uri, code=code, state=state)},
+        )
+
+    async def login_redirect(request: Request) -> Response:
+        """Back-compat for the retired server-rendered password page.
+
+        This only buys a readable error, not a surviving authorization:
+        ``_pending_auth`` is in-process, so a deploy drops every pending session
+        and the consent page will report it expired. That still beats a bare 404
+        for anyone holding an old ``/oauth/login`` URL.
+        """
+        session_id = request.query_params.get("session_id", "")
+        target = f"{provider.frontend_url}/mcp-auth"
+        if session_id:
+            target = f"{target}?session_id={quote(session_id, safe='')}"
+        return RedirectResponse(url=target, status_code=302, headers=_NO_STORE)
+
+    # We need to inject these routes BEFORE the app is fully constructed.
+    # FastMCP uses _custom_starlette_routes for this purpose.
+    srv._custom_starlette_routes = getattr(srv, "_custom_starlette_routes", []) + [
+        Route("/oauth/session", endpoint=session_get, methods=["GET"]),
+        Route("/oauth/complete", endpoint=complete_post, methods=["POST"]),
+        Route("/oauth/login", endpoint=login_redirect, methods=["GET"]),
+        Route("/oauth/session", endpoint=preflight, methods=["OPTIONS"]),
+        Route("/oauth/complete", endpoint=preflight, methods=["OPTIONS"]),
+    ]
+
+
+# ── Entry point ────────────────────────────────────────────
+
+
+def main() -> None:
+    """Run the MCP server.
+
+    Usage:
+      deepcell-mcp                        # stdio (local, for Claude Code / Desktop)
+      deepcell-mcp --http                 # streamable-http on 127.0.0.1:8080
+      deepcell-mcp --http --port 9000     # custom port
+      deepcell-mcp --http --host 0.0.0.0  # all interfaces (for Claude connector)
+
+    Environment variables:
+      MCP_OAUTH_URL     Public URL of this server (enables OAuth 2.1 for remote access)
+      JWT_SECRET        Required when MCP_OAUTH_URL is set (must match Jingwei API)
+      MCP_FRONTEND_URL  Origin serving the /mcp-auth consent page
+                        (default: the MCP_OAUTH_URL origin)
+      MCP_HOST          Default host for --http (default: 127.0.0.1)
+      MCP_PORT          Default port for --http (default: 8080)
+      LOG_LEVEL         Root log level (default: INFO)
+      LOG_FORMAT        text (default) or json, for GCP Cloud Logging ingest
+      LOG_SERVICE       Value of the `service` label in json output
+    """
+    import sys
+
+    from deepcell_cli.logging_setup import setup_logging
+
+    # Until now this process installed no handler at all, so its records fell
+    # through to logging's lastResort — stderr, WARNING and above, unformatted.
+    # Everything below WARNING was simply discarded.
+    setup_logging()
+
+    if "--http" in sys.argv:
+        host = os.environ.get("MCP_HOST", "127.0.0.1")
+        port = int(os.environ.get("MCP_PORT", "8080"))
+        oauth_url = os.environ.get("MCP_OAUTH_URL")
+
+        # Parse --host / --port from argv
+        args = sys.argv[1:]
+        for i, arg in enumerate(args):
+            if arg == "--host" and i + 1 < len(args):
+                host = args[i + 1]
+            elif arg == "--port" and i + 1 < len(args):
+                port = int(args[i + 1])
+
+        srv = _build_server(host=host, port=port, oauth_url=oauth_url)
+        # Re-register the tool on this new instance
+        srv.tool(description=TOOL_DESCRIPTION)(deepcell)
+
+        # Add OAuth login routes when auth is enabled
+        if oauth_url:
+            from deepcell_cli.oauth_provider import DeepCellOAuthProvider
+
+            provider = srv._auth_server_provider
+            if isinstance(provider, DeepCellOAuthProvider):
+                _add_oauth_routes(srv, provider)
+
+        srv.run(transport="streamable-http")
+    else:
+        server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()