@andespindola/crow-skills 0.24.0 → 0.26.0

package/crow_skills/mcp.py

@@ -0,0 +1,632 @@
+"""Opt-in, reversible native-host adapters for crow-uny-mcp.
+
+Discovery never starts an MCP or prints commands, environment or credentials.
+Host configuration writes require explicit approval and a private recovery record.
+"""
+from __future__ import annotations
+
+import argparse
+from contextlib import contextmanager
+import hashlib
+import importlib.util
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import sys
+import tempfile
+import time
+import uuid
+
+try:
+    import tomllib
+except ImportError:  # Codex TOML is observational-only on Python 3.10.
+    tomllib = None
+
+SCHEMA = "crow-mcp-adapters/1"
+HOSTS = (
+    ("codex", ".codex/config.toml", "toml"),
+    ("claude", ".claude.json", "claude"),
+    ("devin", ".config/devin/mcp_config.json", "json"),
+    ("claude-desktop", "Library/Application Support/Claude/claude_desktop_config.json", "json"),
+    ("agents", ".config/agents/mcp-servers.json", "flat"),
+)
+MAX_CONFIG = 16 * 1024 * 1024
+
+
+class MCPError(ValueError):
+    """Safe-to-display adapter error: never include configuration values."""
+
+
+def _digest(data):
+    return hashlib.sha256(data).hexdigest()
+
+
+def _home(value):
+    return Path(os.path.abspath(os.path.expanduser(str(value))))
+
+
+def _safe(path, home):
+    path, home = Path(os.path.abspath(path)), _home(home)
+    try:
+        rel = path.relative_to(home)
+    except ValueError:
+        raise MCPError("path outside selected home") from None
+    current = home
+    if current.is_symlink():
+        raise MCPError("symlink home refused")
+    for part in rel.parts:
+        current = current / part
+        if current.is_symlink():
+            raise MCPError("symlink configuration/state path refused")
+    return path
+
+
+def _read(path, home):
+    path = _safe(path, home)
+    fd = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+    try:
+        st = os.fstat(fd)
+        if not stat.S_ISREG(st.st_mode) or st.st_nlink != 1 or st.st_size > MAX_CONFIG:
+            raise MCPError("configuration is not a bounded regular file")
+        with os.fdopen(fd, "rb", closefd=False) as f:
+            data = f.read(MAX_CONFIG + 1)
+        if len(data) > MAX_CONFIG:
+            raise MCPError("configuration exceeds size limit")
+        return data
+    finally:
+        os.close(fd)
+
+
+def _mkdir(path, home):
+    path = _safe(path, home)
+    path.mkdir(parents=True, exist_ok=True, mode=0o700)
+    os.chmod(path, 0o700)
+    return path
+
+
+def _atomic(path, data, home, expected=None, private=False):
+    path = _safe(path, home)
+    _mkdir(path.parent, home) if private else path.parent.mkdir(parents=True, exist_ok=True)
+    mode = 0o600 if private else stat.S_IMODE(path.stat().st_mode) if path.exists() else 0o600
+    fd, temp = tempfile.mkstemp(prefix="." + path.name + ".", dir=path.parent)
+    try:
+        os.fchmod(fd, mode)
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        # Optimistic compare immediately before replace. External applications
+        # do not share our lock: a filesystem-wide atomic CAS is not claimed.
+        if expected is not None and (not path.exists() or _digest(_read(path, home)) != expected):
+            raise MCPError("configuration changed during operation; refused overwrite")
+        _safe(path, home)
+        os.replace(temp, path)
+    finally:
+        if os.path.lexists(temp):
+            os.unlink(temp)
+
+
+def _encode(value):
+    return (json.dumps(value, ensure_ascii=False, indent=2) + "\n").encode()
+
+
+def _state(home):
+    return _home(home) / ".local/state/crow-skills/mcp"
+
+
+@contextmanager
+def _mutation_lock(home):
+    """Serialize this manager's mutations; external hosts still need digest checks."""
+    directory = _mkdir(_state(home), home)
+    path = _safe(directory / "adapter.lock", home)
+    fd = os.open(path, os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    locked = False
+    try:
+        os.fchmod(fd, 0o600)
+        if os.name == "nt":
+            import msvcrt
+            if os.fstat(fd).st_size == 0:
+                os.write(fd, b"0")
+            os.lseek(fd, 0, os.SEEK_SET)
+            try:
+                msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+            except OSError:
+                raise MCPError("another MCP configuration operation is active") from None
+        else:
+            import fcntl
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except OSError:
+                raise MCPError("another MCP configuration operation is active") from None
+        locked = True
+        yield
+    finally:
+        if locked:
+            if os.name == "nt":
+                import msvcrt
+                os.lseek(fd, 0, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+            else:
+                import fcntl
+                fcntl.flock(fd, fcntl.LOCK_UN)
+        os.close(fd)
+
+
+def _platform_supported():
+    return sys.platform == "darwin" or sys.platform.startswith("linux")
+
+
+def _require_platform():
+    if not _platform_supported():
+        raise MCPError("unsupported-platform: lifecycle wrapping requires macOS or Linux kernel process identity")
+
+
+def _runtime(runtime=None):
+    candidate = Path(runtime) if runtime is not None else Path(__file__).resolve().parents[1] / "skills/crow-uny-mcp/scripts/crow_mcp.py"
+    if not candidate.is_absolute() or candidate.name != "crow_mcp.py" or not candidate.is_file():
+        raise MCPError("absolute crow_mcp.py runtime file required")
+    return str(candidate.resolve())
+
+
+def _is_managed(config):
+    args = config.get("args", [])
+    return (isinstance(args, list) and len(args) >= 2 and isinstance(args[0], str)
+            and Path(args[0]).name == "crow_mcp.py" and args[1] == "serve")
+
+
+def _tables(text):
+    """Return root [mcp_servers.NAME] spans; nested env tables are untouched."""
+    if tomllib is None:
+        return {}
+    headers = list(re.finditer(r"(?m)^[ \t]*\[[^\n]+\][ \t]*(?:\#[^\n]*)?(?:\n|$)", text))
+    result = {}
+    for i, match in enumerate(headers):
+        header = match.group().strip()
+        if header.startswith("[["):
+            continue
+        try:
+            parsed = tomllib.loads(header + "\n__crow_probe = true\n")
+            servers = parsed.get("mcp_servers")
+            if not isinstance(servers, dict) or len(servers) != 1:
+                continue
+            name, value = next(iter(servers.items()))
+            if not isinstance(value, dict) or value != {"__crow_probe": True}:
+                continue
+        except (ValueError, TypeError):
+            continue
+        end = headers[i + 1].start() if i + 1 < len(headers) else len(text)
+        result[name] = (match.end(), end)
+    return result
+
+
+def _toml_replace(text, name, command, args):
+    spans = _tables(text)
+    if name not in spans:
+        raise MCPError("unsupported Codex TOML layout; no changes applied")
+    start, end = spans[name]
+    body = text[start:end]
+    edits = []
+    found = set()
+    lines = body.splitlines(keepends=True)
+    offsets, pos = [], 0
+    for line in lines:
+        offsets.append(pos)
+        pos += len(line)
+    for i, line in enumerate(lines):
+        match = re.match(r"^[ \t]*(command|args)[ \t]*=", line)
+        if not match:
+            continue
+        key = match.group(1)
+        for j in range(i + 1, len(lines) + 1):
+            try:
+                parsed = tomllib.loads("".join(lines[i:j]))
+            except ValueError:
+                continue
+            if set(parsed) == {key}:
+                oldend = offsets[j] if j < len(lines) else len(body)
+                value = command if key == "command" else args
+                edits.append((offsets[i], oldend, key + " = " + json.dumps(value, ensure_ascii=False) + "\n"))
+                found.add(key)
+                break
+        else:
+            raise MCPError("unsupported Codex assignment; no changes applied")
+    for left, right, replacement in reversed(edits):
+        body = body[:left] + replacement + body[right:]
+    for key, value in (("command", command), ("args", args)):
+        if key not in found:
+            body += ("" if not body or body.endswith("\n") else "\n") + key + " = " + json.dumps(value, ensure_ascii=False) + "\n"
+    changed = text[:start] + body + text[end:]
+    try:
+        tomllib.loads(changed)
+    except ValueError:
+        raise MCPError("generated Codex TOML rejected") from None
+    return changed
+
+
+def _maps(document, kind):
+    if kind == "flat":
+        yield "", document
+    else:
+        servers = document.get("mcpServers", {})
+        if isinstance(servers, dict):
+            yield "", servers
+        if kind == "claude":
+            projects = document.get("projects", {})
+            if isinstance(projects, dict):
+                for index, (_path, project) in enumerate(projects.items()):
+                    if isinstance(project, dict) and isinstance(project.get("mcpServers"), dict):
+                        # Do not disclose project paths in observations.
+                        yield "project-" + str(index), project["mcpServers"]
+
+
+def _inventory(home):
+    home = _home(home)
+    files = []
+    rows = []
+    for host, rel, kind in HOSTS:
+        path = home / rel
+        try:
+            _safe(path, home)
+            if not path.exists():
+                continue
+            raw = _read(path, home)
+            if kind == "toml":
+                if tomllib is None:
+                    rows.append({"host": host, "name": "*", "status": "unsupported-python-toml", "managed": False})
+                    continue
+                doc = tomllib.loads(raw.decode())
+                maps = [("", doc.get("mcp_servers", {}))]
+                spans = _tables(raw.decode())
+            else:
+                doc = json.loads(raw)
+                if not isinstance(doc, dict):
+                    raise MCPError("invalid configuration shape")
+                maps = list(_maps(doc, kind))
+                spans = None
+            item = {"path": path, "rel": rel, "kind": kind, "raw": raw, "doc": doc, "entries": []}
+            for scope, servers in maps:
+                if not isinstance(servers, dict):
+                    continue
+                for name, config in servers.items():
+                    if not isinstance(config, dict):
+                        continue
+                    public_name = str(name) if not scope else scope + ":" + str(name)
+                    managed = _is_managed(config)
+                    native_http = "url" in config or config.get("type") in ("http", "sse", "streamable-http", "streamableHttp") or config.get("transport") in ("http", "sse", "streamable-http", "streamableHttp")
+                    eligible = (not native_http and isinstance(config.get("command"), str) and bool(config["command"]) and isinstance(config.get("args", []), list) and all(isinstance(v, str) for v in config.get("args", [])))
+                    state = "managed" if managed else "native-http-observed" if native_http else "eligible-stdio" if eligible else "unsupported-config"
+                    if config.get("enabled") is False:
+                        state, eligible = "disabled-observed", False
+                    if kind == "toml" and eligible and name not in spans:
+                        state, eligible = "unsupported-toml-layout", False
+                    row = {"host": host, "name": public_name, "status": state, "managed": managed}
+                    if managed:
+                        argv = config.get("args", [])
+                        try:
+                            row["profile"] = argv[argv.index("--profile") + 1]
+                        except (ValueError, IndexError):
+                            row["profile"] = "unknown"
+                    rows.append(row)
+                    if state == "eligible-stdio":
+                        item["entries"].append((scope, name, config, row))
+            files.append(item)
+        except (OSError, ValueError, UnicodeError) as error:
+            # No exception text: parsers can include secret input fragments.
+            rows.append({"host": host, "name": "*", "status": "unsafe-or-invalid-config", "managed": False})
+    return files, rows
+
+
+def plan(home, runtime=None, restartable=(), hosts=None):
+    _files, rows = _inventory(home)
+    if hosts is not None:
+        rows = [row for row in rows if row["host"] in hosts]
+    try:
+        resolved = _runtime(runtime)
+        runtime_ready = _platform_supported()
+        runtime_status = "ready" if runtime_ready else "unsupported-platform"
+    except MCPError:
+        resolved, runtime_ready = None, False
+        runtime_status = "missing-runtime" if _platform_supported() else "unsupported-platform"
+    names = set(restartable)
+    for row in rows:
+        if not row["managed"]:
+            row["profile"] = "restartable" if row["name"] in names or row["host"] + ":" + row["name"] in names else "session"
+    return {"schema": SCHEMA, "action": "plan", "runtimeReady": runtime_ready, "runtimeStatus": runtime_status, "servers": rows,
+            "eligible": sum(r["status"] == "eligible-stdio" for r in rows), "mutation": False}
+
+
+def _manifest_path(home):
+    return _state(home) / "adapter-manifest.json"
+
+
+def _manifest(home):
+    path = _manifest_path(home)
+    if not path.exists():
+        return {"schema": SCHEMA, "files": []}
+    try:
+        data = json.loads(_read(path, home))
+        if data.get("schema") != SCHEMA or not isinstance(data.get("files"), list):
+            raise MCPError("invalid adapter recovery record")
+        known = {rel for _host, rel, _kind in HOSTS}
+        for record in data["files"]:
+            if (not isinstance(record, dict) or record.get("path") not in known
+                    or not re.fullmatch(r"\.local/state/crow-skills/mcp/backups/[0-9a-f]{32}\.original", str(record.get("backup", "")))
+                    or any(not re.fullmatch(r"[0-9a-f]{64}", str(record.get(key, ""))) for key in ("originalSha256", "appliedSha256"))
+                    or record.get("state") not in ("prepared", "applied", "restored")):
+                raise MCPError("invalid adapter recovery record")
+        return data
+    except (OSError, ValueError, TypeError):
+        raise MCPError("invalid or unsafe adapter recovery record") from None
+
+
+def _save_manifest(home, data):
+    _atomic(_manifest_path(home), _encode(data), home, private=True)
+
+
+def apply(home, runtime=None, restartable=(), yes=False, hosts=None):
+    if not yes:
+        raise MCPError("explicit --yes approval required for host configuration changes")
+    _require_platform()
+    _runtime(runtime)
+    with _mutation_lock(home):
+        return _apply(home, runtime=runtime, restartable=restartable, yes=yes, hosts=hosts)
+
+
+def _apply(home, runtime=None, restartable=(), yes=False, hosts=None):
+    if not yes:
+        raise MCPError("explicit --yes approval required for host configuration changes")
+    home = _home(home)
+    runtime = _runtime(runtime)
+    files, rows = _inventory(home)
+    if hosts is not None:
+        selected = set(hosts)
+        supported = {host for host, _rel, _kind in HOSTS}
+        if not selected or not selected <= supported:
+            raise MCPError("explicit supported host scope required")
+        rows = [row for row in rows if row["host"] in selected]
+        files = [item for item in files if any(row["host"] in selected for _scope, _name, _config, row in item["entries"])]
+    if any(row["status"] == "unsafe-or-invalid-config" for row in rows):
+        raise MCPError("unsafe or invalid host configuration; no changes applied")
+    manifest = _manifest(home)
+    existing = {r["path"] for r in manifest["files"]}
+    names = set(restartable)
+    for row in rows:
+        if row["managed"] and (row["name"] in names or row["host"] + ":" + row["name"] in names) and row.get("profile") != "restartable":
+            raise MCPError("managed profile change requires conditional restore before reapply")
+    changed = []
+    prepared = []
+    for item in files:
+        entries = item["entries"]
+        if entries and not (item["path"].stat().st_mode & 0o222):
+            raise MCPError("read-only host configuration; no changes applied")
+        if not entries:
+            continue
+        if item["rel"] in existing:
+            raise MCPError("managed configuration has additional changes; restore before reapplying")
+        text = item["raw"].decode()
+        for _scope, name, config, row in entries:
+            profile = "restartable" if row["name"] in names or row["host"] + ":" + row["name"] in names else "session"
+            argv = [runtime, "serve", "--name", row["host"] + ":" + row["name"], "--profile", profile, "--state-dir", str(_state(home) / "instances"), "--", config["command"], *config.get("args", [])]
+            python = str(Path(sys.executable).resolve())
+            if item["kind"] == "toml":
+                text = _toml_replace(text, name, python, argv)
+            else:
+                config["command"], config["args"] = python, argv
+        data = text.encode() if item["kind"] == "toml" else _encode(item["doc"])
+        prepared.append((item, data))
+    # Check every baseline again before creating recovery records or modifying hosts.
+    for item, _ in prepared:
+        if _read(item["path"], home) != item["raw"]:
+            raise MCPError("configuration changed during planning; no changes applied")
+    for item, data in prepared:
+        backup_rel = ".local/state/crow-skills/mcp/backups/" + uuid.uuid4().hex + ".original"
+        _atomic(home / backup_rel, item["raw"], home, private=True)
+        record = {"path": item["rel"], "backup": backup_rel, "originalSha256": _digest(item["raw"]),
+                  "appliedSha256": _digest(data), "state": "prepared", "host": item["entries"][0][3]["host"]}
+        manifest["files"].append(record)
+        _save_manifest(home, manifest)
+        _atomic(item["path"], data, home, expected=_digest(item["raw"]))
+        record["state"] = "applied"
+        _save_manifest(home, manifest)
+        changed.append(item["rel"])
+    return {"schema": SCHEMA, "action": "apply", "changed": changed,
+            "servers": plan(home, runtime, restartable, hosts=hosts)["servers"], "mutation": bool(changed),
+            "runtimeReloadRequired": bool(changed)}
+
+
+def restore(home, yes=False, hosts=None, dry_run=False):
+    if dry_run:
+        return _restore(home, yes=yes, hosts=hosts, dry_run=True)
+    if not yes:
+        raise MCPError("explicit --yes approval required for restore")
+    with _mutation_lock(home):
+        return _restore(home, yes=yes, hosts=hosts)
+
+
+def _restore(home, yes=False, hosts=None, dry_run=False):
+    if not yes and not dry_run:
+        raise MCPError("explicit --yes approval required for restore")
+    home = _home(home)
+    manifest = _manifest(home)
+    ready, conflicts = [], []
+    if hosts is not None and (not hosts or not set(hosts) <= {host for host, _rel, _kind in HOSTS}):
+        raise MCPError("explicit supported host scope required")
+    for record in manifest["files"]:
+        owner = record.get("host") or next((host for host, rel, _kind in HOSTS if rel == record.get("path")), None)
+        if hosts is not None and owner not in hosts:
+            continue
+        if record.get("state") == "restored":
+            continue
+        path = _safe(home / record["path"], home)
+        try:
+            current = _read(path, home)
+        except OSError:
+            # External deletion or loss of read access is a restore conflict,
+            # never authority to recreate, chmod or overwrite the host file.
+            conflicts.append(record["path"])
+            continue
+        if _digest(current) == record["originalSha256"]:
+            record["state"] = "restored"
+            continue
+        if _digest(current) != record["appliedSha256"]:
+            conflicts.append(record["path"])
+            continue
+        try:
+            original = _read(home / record["backup"], home)
+        except (OSError, MCPError):
+            raise MCPError("backup integrity check failed; no restore applied") from None
+        if _digest(original) != record["originalSha256"]:
+            raise MCPError("backup integrity check failed; no restore applied")
+        ready.append((record, path, original))
+    if conflicts:
+        raise MCPError("configuration changed externally; restore refused without overwriting edits")
+    if dry_run:
+        return {"schema": SCHEMA, "action": "restore", "changed": [], "wouldRestore": [r["path"] for r, _p, _o in ready],
+                "mutation": False, "dry_run": True}
+    changed = []
+    for record, path, original in ready:
+        _atomic(path, original, home, expected=record["appliedSha256"])
+        record["state"] = "restored"
+        _save_manifest(home, manifest)
+        changed.append(record["path"])
+    manifest["files"] = [r for r in manifest["files"] if r.get("state") != "restored"]
+    if _manifest_path(home).exists():
+        _save_manifest(home, manifest)
+    return {"schema": SCHEMA, "action": "restore", "changed": changed, "mutation": bool(changed),
+            "runtimeReloadRequired": bool(changed)}
+
+
+def runtime_dependencies(home, runtime):
+    """Observe native wrappers referencing a runtime, never signal or mutate them."""
+    target = Path(runtime).resolve()
+    files, rows = _inventory(home)
+    result = [{"host": row["host"], "name": "*", "unverifiable": True}
+              for row in rows if row["status"] == "unsafe-or-invalid-config"]
+    for item in files:
+        maps = [("", item["doc"].get("mcp_servers", {}))] if item["kind"] == "toml" else _maps(item["doc"], item["kind"])
+        host = next(host for host, rel, _kind in HOSTS if rel == item["rel"])
+        for scope, servers in maps:
+            if not isinstance(servers, dict):
+                continue
+            for name, config in servers.items():
+                if isinstance(config, dict) and _is_managed(config) and Path(config["args"][0]).resolve() == target:
+                    result.append({"host": host, "name": (scope + ":" if scope else "") + str(name)})
+    return result
+
+
+_IDENTITY_READER = None
+
+
+def _identity(pid):
+    global _IDENTITY_READER
+    if not isinstance(pid, int) or isinstance(pid, bool) or pid <= 0:
+        return None
+    try:
+        if _IDENTITY_READER is None:
+            spec = importlib.util.spec_from_file_location("crow_mcp_status_identity", _runtime())
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+            _IDENTITY_READER = module.process_identity
+        return _IDENTITY_READER(pid)
+    except (OSError, ValueError, ImportError, AttributeError):
+        return None
+
+
+def status(home):
+    home = _home(home)
+    result = plan(home)
+    result.update(action="status", configuredManaged=sum(r["managed"] for r in result["servers"]))
+    snapshots = []
+    directory = _state(home) / "instances"
+    if directory.exists():
+        _safe(directory, home)
+        for path in sorted(directory.glob("runtime-*.json"))[:200]:
+            try:
+                data = json.loads(_read(path, home))
+                # Registry entries are observations, never authority to signal PIDs.
+                row = {k: data[k] for k in ("pid", "child_pid", "pending_client", "pending_server", "subscriptions", "startup_ms", "resume_ms")
+                       if k in data and isinstance(data[k], (int, float, type(None))) and not isinstance(data[k], bool)}
+                if data.get("state") in ("cold", "starting", "ready", "busy", "idle", "standby", "stopped", "pinned", "failed", "active", "hibernated", "session_lost"):
+                    row["state"] = data["state"]
+                if data.get("profile") in ("session", "restartable"):
+                    row["profile"] = data["profile"]
+                if isinstance(data.get("retainedMemory"), bool):
+                    row["retainedMemory"] = data["retainedMemory"]
+                for pid_key, identity_key, live_key, verified_key in (("pid", "pid_identity", "pidAlive", "identityVerified"),
+                                                                   ("child_pid", "child_identity", "childAlive", "childIdentityVerified")):
+                    current = _identity(data.get(pid_key))
+                    recorded = data.get(identity_key)
+                    row[live_key] = current is not None
+                    row[verified_key] = current is not None and isinstance(recorded, (tuple, list)) and tuple(recorded) == tuple(current)
+                row["source"] = "runtime-reported"
+                snapshots.append(row)
+            except (OSError, ValueError):
+                continue
+    result["runtimeObservations"] = snapshots
+    result["liveSessionsReloaded"] = False
+    return result
+
+
+def activate(home, runtime, approved=False, hosts=None):
+    """Installer hook: approved, scoped installation wraps hosts without starting servers.
+
+    Without installation approval this is observation only. An approved call must
+    name a supported host scope; it never expands to unrelated configured apps.
+    """
+    if not approved:
+        return {"schema": SCHEMA, "active": False, "mode": "observe", "wrapped": False,
+                "plan": plan(home, runtime=runtime, hosts=hosts)}
+    _require_platform()
+    if not hosts:
+        raise MCPError("explicit supported host scope required for installation activation")
+    resolved = _runtime(runtime)
+    result = apply(home, runtime=resolved, yes=True, hosts=hosts)
+    _atomic(_state(home) / "activation.json", _encode({"schema": SCHEMA, "enabled": True,
+            "mode": "managed", "runtime": resolved, "hosts": sorted(set(hosts)),
+            "activatedAt": int(time.time())}), home, private=True)
+    return {"schema": SCHEMA, "active": True, "mode": "managed", "wrapped": True,
+            "result": result, "runtimeReloadRequired": result["runtimeReloadRequired"]}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="crow-skills mcp")
+    parser.add_argument("action", choices=("status", "plan", "apply", "restore"))
+    parser.add_argument("--home", default=str(Path.home()))
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--yes", action="store_true")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--runtime")
+    parser.add_argument("--hosts", help="comma-separated explicit host scope")
+    parser.add_argument("--restartable", default="", help="comma-separated server names or host:name, explicit restartable profile")
+    args = parser.parse_args(argv)
+    try:
+        if args.action == "status":
+            result = status(args.home)
+        elif args.action == "restore":
+            result = restore(args.home, yes=args.yes, dry_run=args.dry_run, hosts=[s.strip() for s in args.hosts.split(",") if s.strip()] if args.hosts is not None else None)
+        else:
+            opts = {"runtime": args.runtime, "restartable": [s.strip() for s in args.restartable.split(",") if s.strip()],
+                    "hosts": [s.strip() for s in args.hosts.split(",") if s.strip()] if args.hosts is not None else None}
+            result = apply(args.home, yes=args.yes, **opts) if args.action == "apply" and not args.dry_run else plan(args.home, **opts)
+        if args.json:
+            print(json.dumps({"schema_version": 1, "ok": True, "command": "mcp", "data": result}, ensure_ascii=False))
+        else:
+            print("MCP " + args.action + ": " + str(len(result.get("changed", []))) + " file(s) changed" if args.action in ("apply", "restore") else
+                  "MCP " + args.action + ": " + str(len(result.get("servers", []))) + " configured entry/entries")
+            for row in result.get("servers", []):
+                print((row["host"] + " / " + row["name"] + ": " + row["status"]).encode("unicode_escape").decode())
+        return 0
+    except (MCPError, OSError) as error:
+        # OSError can include paths but not config bodies; keep it generic too.
+        message = str(error) if isinstance(error, MCPError) else "filesystem operation failed; no unsafe retry performed"
+        if args.json:
+            print(json.dumps({"schema_version": 1, "ok": False, "command": "mcp", "error": {"code": "mcp_adapter", "message": message}}))
+        else:
+            print("MCP: " + message, file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/docs/cli.md

@@ -69,6 +69,8 @@ Nome: `@andespindola/crow-skills`; `publishConfig.access` é `public` desde a 0.
 
 A publicação é feita pelo workflow `.github/workflows/publish.yml` ao empurrar uma tag `vX.Y.Z` igual à `version` do `package.json` (ou por `workflow_dispatch` em `main`). Ele autentica por Trusted Publishing (OIDC), sem token npm em secret, e roda check, testes e o teste de instalação isolada antes de `npm publish`. O trusted publisher do pacote no npmjs.com deve apontar para `andersonflima/crow-skills` e `publish.yml`.
 
+Depois do `npm publish`, o pipeline confirma a versão no próprio registry: consulta `https://registry.npmjs.org/@andespindola%2Fcrow-skills` sem npm e sem credencial e espera a versão do `package.json` aparecer em `.versions` e virar o `dist-tags.latest`, tentando a cada 20 s por até 15 minutos e registrando cada tentativa no log. Isso existe porque o log do `npm publish` sozinho não distingue uma publicação real de um `--dry-run` (que imprime um `+ pacote@versao` praticamente igual) nem de um passo pulado por gate, que deixa o job verde sem ter publicado nada. Propagação de alguns minutos até dezenas de minutos é normal e **não** é falha: passado o teto, o job termina com sucesso e emite um aviso com o comando `curl -s https://registry.npmjs.org/@andespindola%2Fcrow-skills | jq -r '.["dist-tags"].latest'` para conferir depois.
+
 Depois de a versão estar publicada e a conta estar autenticada com acesso:
 
 ```sh
@@ -620,3 +622,25 @@ Cada execução:
 3. Para cada agente com skills gerenciadas (claude, codex/`$CODEX_HOME/skills`, gemini, devin, uniflow), roda o equivalente a `update <skills> --agents <agente> --global --yes`: regenera guia, integrações e hooks; a [identidade do pacote](#origem-e-versões) evita `source_mismatch` depois do upgrade. Skills editadas localmente (`modified`), ausentes ou instaladas de outra origem (`other_origin`, por exemplo de um clone Git) ficam como estão e aparecem em `kept`; nada é sobrescrito. Uma reaplicação dos hooks troca as entradas do crow-skills no lugar, sem mudar a posição das suas. Uma recusa num agente (por exemplo, guia editado) aparece em `error` e não interrompe os outros.
 
 O resultado fica em `~/.local/state/crow-skills/autoupdate/state.json` (`lastRun` e as últimas 20 execuções), aparece em `autoupdate status`, em `status`/`doctor` (doctor `healthy:false` se a última execução falhou ou o agendador foi alterado/removido) e em `events snapshot`. Duas execuções simultâneas são recusadas (`busy`).
+
+## MCP passivo: crow-uny-mcp
+
+`crow-uny-mcp` é uma skill com runtime stdio autocontido, não uma substituição das ferramentas por comandos de uma CLI externa. Uma instalação global explicitamente aprovada configura os adaptadores suportados do agente selecionado e o guia nativo; instalação de projeto não modifica configurações globais. Não instala dependências de terceiros nem acorda servidores para descobrir ferramentas. Recarregue o host: configuração em disco não substitui conexões já abertas.
+
+```sh
+crow-skills install crow-uny-mcp --agents claude --global --yes
+crow-skills mcp status --json
+crow-skills mcp plan --hosts claude --json
+crow-skills mcp apply --hosts claude --yes
+crow-skills mcp restore --hosts claude --yes
+```
+
+Os adaptadores cobrem entradas stdio nos formatos conhecidos de Codex, Claude Code, Devin, Claude Desktop no macOS e catálogo JSON compartilhado de agentes. Entradas HTTP nativas, plugins internos de apps e outros formatos ficam somente observados. O runtime usa sinais e identidade de processos POSIX; isso não é validação em todos os sistemas operacionais ou versões desses hosts.
+
+- Padrão `session`: preserva o estado suspendendo a árvore própria ociosa e retomando antes da chamada. A RAM permanece alocada; sockets remotos ainda podem expirar durante a pausa.
+- Perfil `restartable`: encerra a árvore ociosa para liberar RAM e refaz somente o handshake na próxima chamada. Autorize os nomes verificados com `--restartable nome1,nome2`; mudar perfil já gerenciado requer restore/novo apply, não troca silenciosa.
+- Pedidos em andamento, chamadas servidor→cliente e assinaturas impedem standby/reap. O cache privado atende descoberta quente sem iniciar o servidor; descoberta fria ainda precisa de uma inicialização. Não há repetição automática de operação de negócio após falha.
+- O proxy tem overhead próprio. Tempos sintéticos de warm-up não garantem latência de um servidor autenticado real. Processos externos já existentes ou que se desprendem antes da captura de propriedade não são adotados pelo manager.
+- Backup e restauração são privados e condicionais: edição externa bloqueia restore, preservando o arquivo. O plano distingue configurado, observado e não suportado; `status` sem processo observado não prova que a conexão de um app foi recarregada.
+
+O guia torna o contrato passivo vigente quando instalado, independentemente do interruptor de coordenação `crow-behaviour`; não confunda isso com poder obrigar um app sem adaptador a obedecer. O usuário continua dono da configuração e das permissões.