ermes-cli 1.0.0__py3-none-any.whl

ermes_cli/mcp_server.py

@@ -0,0 +1,167 @@
+"""FastMCP server for Ermes — exposes read-only API tools.
+
+Tools are loaded from ``routes.yaml`` at import time, so adding a new
+read-only MCP tool is a YAML edit, not a Python change. The CLI surface
+(``ermes_cli/commands/*.py``) is hand-coded and richer (CRUD + prompts);
+the manifest drives only the MCP tool list.
+
+Profile-based auth via the existing ``ermes_cli`` config. Write tools
+(create/update/delete) are deliberately omitted from the default surface;
+enable them later when there's a clear use case and a per-tool review.
+
+Set ``ERMES_MCP_DEBUG=1`` to print the loaded tool count to stderr at
+startup.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any, Callable
+
+from fastmcp import FastMCP
+
+from ermes_cli.client import ErmesClient
+from ermes_cli.config import resolve_profile
+from ermes_cli.manifest import (
+    QueryArg,
+    Route,
+    exposed_routes,
+    load_manifest,
+)
+
+mcp = FastMCP("ermes")
+
+
+# ---------------------------------------------------------------------------
+# Auth helpers
+# ---------------------------------------------------------------------------
+
+
+def _client() -> ErmesClient:
+    profile = resolve_profile()
+    return ErmesClient(profile["base_url"], profile["api_key"])
+
+
+# ---------------------------------------------------------------------------
+# Route execution
+# ---------------------------------------------------------------------------
+
+
+def _execute_route(route: Route, args: dict[str, Any]) -> Any:
+    """Run one manifest-defined route against the Ermes API."""
+    path_values: dict[str, str] = {}
+    for arg in route.path_args:
+        if arg.name not in args or args[arg.name] in (None, ""):
+            raise ValueError(f"missing required argument '{arg.name}'")
+        path_values[arg.name] = str(args[arg.name])
+
+    query_params: dict[str, Any] = {}
+    limit: int | None = None
+    for q in route.query_args:
+        value = args.get(q.name)
+        if value is None:
+            continue
+        if q.name == "limit" and route.paginated:
+            limit = int(value)
+            continue
+        query_params[q.name] = value
+
+    path = route.render_path(path_values)
+    client = _client()
+    try:
+        if route.paginated:
+            return client.get_paginated(
+                path,
+                params=query_params or None,
+                limit=limit if limit is not None else 100,
+            )
+        return client.get(path, params=query_params or None)
+    finally:
+        client.close()
+
+
+# ---------------------------------------------------------------------------
+# Dynamic tool handler factory
+# ---------------------------------------------------------------------------
+
+
+_QUERY_TYPE_MAP = {"str": "str", "int": "int", "bool": "bool"}
+
+
+def _query_annotation(q: QueryArg) -> str:
+    base = _QUERY_TYPE_MAP[q.type]
+    return f"{base} | None" if q.optional else base
+
+
+def _build_handler(route: Route) -> Callable[..., Any]:
+    """Generate a typed handler function for one route.
+
+    Builds the function via ``exec`` so the generated signature carries
+    real annotations and defaults — fastmcp introspects these to produce
+    the tool's JSON Schema.
+    """
+    sig_parts: list[str] = []
+    for arg in route.path_args:
+        sig_parts.append(f"{arg.name}: str")
+    for q in route.query_args:
+        ann = _query_annotation(q)
+        if q.default is not None:
+            sig_parts.append(f"{q.name}: {ann} = {q.default!r}")
+        elif q.optional:
+            sig_parts.append(f"{q.name}: {ann} = None")
+        else:
+            sig_parts.append(f"{q.name}: {ann}")
+
+    sig = ", ".join(sig_parts)
+    src = (
+        f"def handler({sig}) -> object:\n"
+        f"    return _execute_route(_ROUTE, locals())\n"
+    )
+    ns: dict[str, Any] = {"_execute_route": _execute_route, "_ROUTE": route}
+    exec(src, ns)
+    fn = ns["handler"]
+    fn.__name__ = route.mcp.tool_name or route.id
+    fn.__doc__ = route.mcp.description
+    return fn
+
+
+# ---------------------------------------------------------------------------
+# Hand-coded tools (no HTTP call)
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool
+def whoami() -> dict[str, Any]:
+    """Return the current Ermes profile + base URL (no API call — local only)."""
+    profile = resolve_profile()
+    return {
+        "base_url": profile["base_url"],
+        "api_key_masked": profile["api_key"][:3] + "***" + profile["api_key"][-3:],
+    }
+
+
+# ---------------------------------------------------------------------------
+# Manifest-driven tool registration (at import time)
+# ---------------------------------------------------------------------------
+
+
+_ROUTES = load_manifest()
+for _route in exposed_routes(_ROUTES):
+    mcp.tool(
+        _build_handler(_route),
+        name=_route.mcp.tool_name,
+        description=_route.mcp.description,
+    )
+
+
+def main() -> None:
+    if os.environ.get("ERMES_MCP_DEBUG"):
+        # +1 for the hand-coded whoami tool.
+        count = len(exposed_routes(_ROUTES)) + 1
+        print(f"ermes-mcp starting ({count} tools)", file=sys.stderr)
+    mcp.run(transport="stdio", show_banner=False)
+
+
+if __name__ == "__main__":
+    main()

ermes_cli/output.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+import json
+from typing import Any
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def render(
+    data: list[dict],
+    columns: list[str],
+    use_json: bool,
+    title: str | None = None,
+    column_labels: dict[str, str] | None = None,
+) -> None:
+    if use_json:
+        print(json.dumps(data, indent=2, default=str))
+        return
+    if not data:
+        console.print("[dim]No results[/dim]")
+        return
+    labels = column_labels or {}
+    table = Table(title=title, show_lines=False)
+    for col in columns:
+        table.add_column(labels.get(col, col))
+    for row in data:
+        table.add_row(*[_format_value(row.get(col)) for col in columns])
+    console.print(table)
+
+
+def render_detail(data: dict, use_json: bool) -> None:
+    if use_json:
+        print(json.dumps(data, indent=2, default=str))
+        return
+    table = Table(show_header=False, show_lines=False)
+    table.add_column("Key", style="bold")
+    table.add_column("Value")
+    for key, value in data.items():
+        table.add_row(key, _format_value(value))
+    console.print(table)
+
+
+def render_message(message: str, use_json: bool) -> None:
+    if use_json:
+        print(json.dumps({"message": message}))
+        return
+    console.print(message)
+
+
+def _format_value(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    if isinstance(value, (list, dict)):
+        return json.dumps(value, default=str)
+    return str(value)

ermes_cli/routes.yaml

@@ -0,0 +1,163 @@
+# ermes-cli MCP route manifest (v0.3 — read-only surface).
+#
+# Each entry describes one Ermes API route exposed through the MCP server.
+# The MCP dispatch builds its tool list from entries where `mcp.expose` is
+# true, using `mcp.tool_name` as the tool id and `mcp.description` as the
+# tool description shown to the model.
+#
+# Conventions:
+#   - `risk: read` — safe GETs only. Mutating tiers ("write", "delete") are
+#     reserved for v0.4+ when the confirmation UX lands.
+#   - `mcp.tool_name` — concept-style snake_case (e.g., `get_campaign`).
+#   - `paginated: true` — dispatch through `ErmesClient.get_paginated` so
+#     `limit` is honored across cursor pages.
+#
+# Adding a route:
+#   1. Add an entry here.
+#   2. Make sure `id` and `mcp.tool_name` are globally unique.
+#   3. Run `pytest cli/tests/test_manifest.py` to validate.
+#
+# The hand-coded CLI (`ermes_cli/commands/*.py`) is NOT generated from this
+# file. The CLI surface is richer (CRUD + prompts + validation) and lives
+# separately. The manifest exists to drive the MCP tool set so adding a
+# new MCP tool is a YAML edit, not a Python change.
+
+- id: list_campaigns
+  path: /campaigns
+  method: GET
+  risk: read
+  paginated: true
+  mcp:
+    expose: true
+    tool_name: list_campaigns
+    description: List campaigns. Optional `status` filter (e.g. 'sent', 'draft', 'running').
+  query_args:
+    - name: limit
+      type: int
+      default: 50
+      help: Max number of campaigns to return.
+    - name: status
+      type: str
+      optional: true
+      help: Optional status filter.
+
+- id: get_campaign
+  path: /campaigns/{campaign_id}
+  method: GET
+  risk: read
+  paginated: false
+  mcp:
+    expose: true
+    tool_name: get_campaign
+    description: Fetch one campaign by id.
+  args:
+    - name: campaign_id
+      help: The campaign id.
+
+- id: list_templates
+  path: /templates
+  method: GET
+  risk: read
+  paginated: true
+  mcp:
+    expose: true
+    tool_name: list_templates
+    description: List email templates.
+  query_args:
+    - name: limit
+      type: int
+      default: 50
+      help: Max number of templates to return.
+
+- id: get_template
+  path: /templates/{template_id}
+  method: GET
+  risk: read
+  paginated: false
+  mcp:
+    expose: true
+    tool_name: get_template
+    description: Fetch one template by id.
+  args:
+    - name: template_id
+      help: The template id.
+
+- id: list_lists
+  path: /lists
+  method: GET
+  risk: read
+  paginated: true
+  mcp:
+    expose: true
+    tool_name: list_lists
+    description: List contact lists.
+  query_args:
+    - name: limit
+      type: int
+      default: 50
+      help: Max number of lists to return.
+
+- id: list_journeys
+  path: /journeys
+  method: GET
+  risk: read
+  paginated: true
+  mcp:
+    expose: true
+    tool_name: list_journeys
+    description: List automation journeys.
+  query_args:
+    - name: limit
+      type: int
+      default: 50
+      help: Max number of journeys to return.
+
+- id: list_users
+  path: /users
+  method: GET
+  risk: read
+  paginated: true
+  mcp:
+    expose: true
+    tool_name: list_users
+    description: List users (contacts). Optional exact-email filter.
+  query_args:
+    - name: limit
+      type: int
+      default: 100
+      help: Max number of users to return.
+    - name: email
+      type: str
+      optional: true
+      help: Optional exact-email filter.
+
+- id: get_user
+  path: /users/{user_id}
+  method: GET
+  risk: read
+  paginated: false
+  mcp:
+    expose: true
+    tool_name: get_user
+    description: Fetch one user by id.
+  args:
+    - name: user_id
+      help: The user id.
+
+- id: get_user_events
+  path: /users/{user_id}/events
+  method: GET
+  risk: read
+  paginated: true
+  mcp:
+    expose: true
+    tool_name: get_user_events
+    description: Recent events for one user (sends, opens, clicks).
+  args:
+    - name: user_id
+      help: The user id.
+  query_args:
+    - name: limit
+      type: int
+      default: 100
+      help: Max number of events to return.

ermes_cli/rules.py

@@ -0,0 +1,54 @@
+"""Normalization for rule trees sent to the API.
+
+The platform accepts arbitrary JSON scalars as rule ``value``s and the rule
+engine coerces them at evaluation time (``NumberRule`` does ``Number(value)``,
+``BooleanRule`` never reads ``rule.value``), but the admin UI builder always
+stores strings. Hand-authored payloads naturally write ``"value": 156004``,
+which crashed the journey editor's rule renderer (DEV-1374). Canonicalize
+CLI-authored payloads to the string form the UI produces so stored rules stay
+uniform regardless of who wrote them.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+RULE_TYPES = {"wrapper", "string", "number", "boolean", "date", "array"}
+
+
+def _is_rule_node(node: dict) -> bool:
+    return node.get("type") in RULE_TYPES and "path" in node and "operator" in node
+
+
+def _to_string(value: Any) -> Any:
+    # json.dumps matches JS literal semantics: True -> "true", 156004 -> "156004",
+    # 1.5 -> "1.5". Strings and null pass through untouched.
+    if isinstance(value, (bool, int, float)):
+        return json.dumps(value)
+    return value
+
+
+def normalize_rule_values(payload: Any) -> Any:
+    """Recursively stringify scalar ``value``s on every rule node in ``payload``.
+
+    Works on any JSON shape (a bare rule, a journey step map, a list body) by
+    detecting rule nodes structurally (``type``/``path``/``operator``). Mutates
+    dicts and lists in place and returns ``payload`` for convenience.
+    """
+    if isinstance(payload, dict):
+        # Date rules are exempt: DateRule casts with `new Date(value)`, and a
+        # numeric epoch is a valid Date while its string form is not
+        # ("Invalid Date" -> rule evaluates false). The UI tolerates
+        # non-string values since DEV-1374, so numeric dates stay numeric.
+        if _is_rule_node(payload) and payload.get("type") != "date":
+            value = payload.get("value")
+            if isinstance(value, list):
+                payload["value"] = [_to_string(item) for item in value]
+            elif value is not None:
+                payload["value"] = _to_string(value)
+        for child in payload.values():
+            normalize_rule_values(child)
+    elif isinstance(payload, list):
+        for item in payload:
+            normalize_rule_values(item)
+    return payload

ermes_cli/write_mode.py

@@ -0,0 +1,178 @@
+"""Write-mode guard: block mutating CLI/MCP calls by default.
+
+Why: most CLI sessions are read-only investigation ("what campaigns ran
+last week?"). The mutating commands (`campaigns create`, `lists delete`,
+`templates update`) only exist for the maintenance use case, and a
+typo'd flag or copy-pasted-from-docs command shouldn't be one Enter-press
+away from deleting production data.
+
+Behavior:
+  - Default: writes BLOCKED. POST/PATCH/PUT/DELETE through `client.py` raise
+    WriteBlockedError before hitting the network.
+  - `ermes write allow` → unblocks for 30 min (default).
+    `ermes write allow --minutes 5` for shorter windows.
+    `ermes write allow --persistent` for permanent (until `write deny`).
+  - `ermes write deny` → revoke immediately.
+  - `ermes write status` → show current state.
+  - `ERMES_ALLOW_WRITES=1` env override (for CI/scripts that consciously
+    want unguarded behavior).
+
+State lives in `~/.ermes/state.yml` (chmod 600). It's deliberately
+separate from projects.yml so refreshing projects doesn't accidentally
+clobber the write window.
+
+The MCP server's tool set is read-only by design (see PR #395 TODO), so
+this guard primarily protects the `ermes` CLI surface. When MCP gains
+mutating tools (v0.4), they'll be gated through the same helper.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from ermes_cli.config import _config_dir
+from ermes_cli.errors import WriteBlockedError
+
+
+def _state_path() -> Path:
+    return _config_dir() / "state.yml"
+
+
+def _load_state() -> dict[str, Any]:
+    p = _state_path()
+    if not p.exists():
+        return {}
+    try:
+        with open(p) as f:
+            data = yaml.safe_load(f)
+        return data if isinstance(data, dict) else {}
+    except (OSError, yaml.YAMLError):
+        return {}
+
+
+def _save_state(state: dict[str, Any]) -> None:
+    p = _state_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with open(p, "w") as f:
+        yaml.dump(state, f, default_flow_style=False, sort_keys=False)
+    p.chmod(0o600)
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _parse_iso(value: Any) -> datetime | None:
+    if not isinstance(value, str):
+        return None
+    try:
+        # Tolerate the trailing "Z" form.
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+# WriteBlockedError is defined in ermes_cli.errors so both client.py and
+# this module can import it without a circular dependency. Re-exporting
+# here keeps the old import path (`from ermes_cli.write_mode import
+# WriteBlockedError`) working for any caller that already used it.
+__all__ = [
+    "WriteBlockedError",
+    "env_override_active",
+    "status",
+    "is_writes_allowed",
+    "allow",
+    "deny",
+    "assert_writes_allowed",
+]
+
+
+def env_override_active() -> bool:
+    """True if the operator opted in via env var (CI / automation path)."""
+    return os.environ.get("ERMES_ALLOW_WRITES", "").lower() in {"1", "true", "yes"}
+
+
+def status() -> dict[str, Any]:
+    """Structured status: {allowed, mode, until, source}."""
+    if env_override_active():
+        return {
+            "allowed": True,
+            "mode": "env",
+            "until": None,
+            "source": "ERMES_ALLOW_WRITES env",
+        }
+    state = _load_state()
+    if state.get("write_mode_persistent"):
+        return {
+            "allowed": True,
+            "mode": "persistent",
+            "until": None,
+            "source": "state.yml",
+        }
+    until = _parse_iso(state.get("write_mode_until"))
+    if until and until > _now():
+        return {
+            "allowed": True,
+            "mode": "timed",
+            "until": until.isoformat(),
+            "source": "state.yml",
+        }
+    return {
+        "allowed": False,
+        "mode": "denied",
+        "until": until.isoformat() if until else None,
+        "source": "default" if not state else "state.yml",
+    }
+
+
+def is_writes_allowed() -> bool:
+    return bool(status()["allowed"])
+
+
+def allow(minutes: int = 30, persistent: bool = False) -> dict[str, Any]:
+    """Open the write window.
+
+    `persistent=True` ignores `minutes` and unblocks indefinitely. Otherwise
+    the window opens for `minutes` and closes automatically when it expires.
+    """
+    state = _load_state()
+    if persistent:
+        state["write_mode_persistent"] = True
+        state.pop("write_mode_until", None)
+    else:
+        until = _now() + _delta(minutes)
+        state["write_mode_persistent"] = False
+        state["write_mode_until"] = until.isoformat()
+    _save_state(state)
+    return status()
+
+
+def deny() -> dict[str, Any]:
+    """Close the write window immediately."""
+    state = _load_state()
+    state["write_mode_persistent"] = False
+    state.pop("write_mode_until", None)
+    _save_state(state)
+    return status()
+
+
+def _delta(minutes: int):
+    from datetime import timedelta
+
+    return timedelta(minutes=int(minutes))
+
+
+def assert_writes_allowed(method: str, path: str) -> None:
+    """Guard called from `client.py` before sending mutating requests."""
+    if is_writes_allowed():
+        return
+    raise WriteBlockedError(
+        f"Write blocked: {method} {path}. Writes are disabled by default. "
+        "Run `ermes write allow` (30 min) or `ermes write allow --persistent`, "
+        "or set ERMES_ALLOW_WRITES=1 in your environment."
+    )