karma-connect 1.0.0__tar.gz

karma_connect-1.0.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: karma-connect
+Version: 1.0.0
+Summary: One command that wires the Karma MCP server into every agent host on this machine
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# karma-connect
+
+One command that wires the **Karma MCP server** into every agent host on this machine.
+
+```bash
+pip install ./packages/karma-connect
+# or, without cloning the repo:
+pip install "karma-connect @ git+https://github.com/AtoB101/Karma@main#subdirectory=packages/karma-connect"
+karma-connect detect
+karma-connect install
+```
+
+Not on PyPI yet (`pip install karma-connect` returns 404); see
+[`docs/mcp/karma-mcp-integration.md`](../../docs/mcp/karma-mcp-integration.md).
+
+No JSON editing, no config file archaeology. It finds the hosts you already have
+and writes one named server entry into each.
+
+## Which server it wires
+
+`karma-mcp-server` (`packages/karma-mcp-server`) - the thin access layer that only
+ever holds `KARMA_RUNTIME_KEY`. The older `karma-mcp` package is **not** used: it
+wanted `KARMA_PRIVATE_KEY` injected into the MCP process, which the security audit
+retired, and `karma-mcp-server` refuses to start when private key material is in its
+environment. So `install` refuses `--env KARMA_PRIVATE_KEY=...` (or any mnemonic key)
+instead of writing a server that can never boot.
+
+`KARMA_RUNTIME_URL` defaults to the public node (`https://karma-network.ai`), so a
+fresh install needs no `--env` at all. Everything else the agent needs arrives when
+the owner approves the pairing.
+
+## What it touches
+
+| host | config | key |
+|---|---|---|
+| Codex CLI | `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) | `[mcp_servers.karma]` |
+| Claude Code | `~/.claude.json` | `mcpServers.karma` |
+| Cursor | `~/.cursor/mcp.json` | `mcpServers.karma` |
+| Muse Code (Meta) | `${XDG_CONFIG_HOME:-~/.config}/muse/settings.json` | `mcpServers.karma` |
+| OpenClaw | `$OPENCLAW_STATE_DIR/openclaw.json` (default `~/.openclaw/openclaw.json`) | `mcp.servers.karma` |
+| VS Code | `<workspace>/.vscode/mcp.json` (only with `--workspace`) | `servers.karma` |
+
+Only that one entry is touched; every other line is preserved. Running install
+twice changes nothing the second time.
+
+## Gotchas it handles for you
+
+- **Muse Code** wants `"type": "stdio"` (its docs page says `transport`, the binary
+  does not) plus `schema_version: 1`, and it drops the whole MCP block if
+  `mcp_servers` and `mcpServers` ever appear together. This tool only writes
+  `mcpServers`.
+- **Codex** keeps MCP servers in TOML tables, not JSON, so the writer replaces just
+  the `[mcp_servers.karma]` block and leaves your `model`, plugins and marketplaces
+  alone.
+- **OpenClaw** nests under `mcp.servers`, not `mcpServers`.
+
+## Commands
+
+- `karma-connect detect` - which hosts exist here, and where their config lives
+- `karma-connect install [--host codex,muse] [--dry-run]` - write the entry
+- `karma-connect doctor` - is `karma-mcp-server` reachable, is every config readable, is this machine paired yet
+- `karma-connect sign-check` - print the per-request signature this machine would send
+
+## After installing
+
+1. Restart the agent host so it reloads MCP servers.
+2. Have the agent call `karma_connect` (`agent_name` = whatever it calls itself). It
+   prints a `user_code` and a `verification_uri` - open that link in Karma Console,
+   check the `agent_fingerprint` on the card matches the one the agent showed you,
+   set the limits, and approve.
+3. Have the agent call `karma_connect_claim`. Approval **is** activation, so the
+   credentials come back directly - there is no 8-character code to relay.
+4. Credentials land in `~/.karma/agent.env` (0600). Nothing secret travels through chat.
+
+The 8-character handoff code still exists as a fallback for machines that cannot
+generate a local agent key, and the console can add an email-receipt gate as a third
+lock when the approval carries `notify_email`.

karma_connect-1.0.0/README.md

@@ -0,0 +1,77 @@
+# karma-connect
+
+One command that wires the **Karma MCP server** into every agent host on this machine.
+
+```bash
+pip install ./packages/karma-connect
+# or, without cloning the repo:
+pip install "karma-connect @ git+https://github.com/AtoB101/Karma@main#subdirectory=packages/karma-connect"
+karma-connect detect
+karma-connect install
+```
+
+Not on PyPI yet (`pip install karma-connect` returns 404); see
+[`docs/mcp/karma-mcp-integration.md`](../../docs/mcp/karma-mcp-integration.md).
+
+No JSON editing, no config file archaeology. It finds the hosts you already have
+and writes one named server entry into each.
+
+## Which server it wires
+
+`karma-mcp-server` (`packages/karma-mcp-server`) - the thin access layer that only
+ever holds `KARMA_RUNTIME_KEY`. The older `karma-mcp` package is **not** used: it
+wanted `KARMA_PRIVATE_KEY` injected into the MCP process, which the security audit
+retired, and `karma-mcp-server` refuses to start when private key material is in its
+environment. So `install` refuses `--env KARMA_PRIVATE_KEY=...` (or any mnemonic key)
+instead of writing a server that can never boot.
+
+`KARMA_RUNTIME_URL` defaults to the public node (`https://karma-network.ai`), so a
+fresh install needs no `--env` at all. Everything else the agent needs arrives when
+the owner approves the pairing.
+
+## What it touches
+
+| host | config | key |
+|---|---|---|
+| Codex CLI | `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) | `[mcp_servers.karma]` |
+| Claude Code | `~/.claude.json` | `mcpServers.karma` |
+| Cursor | `~/.cursor/mcp.json` | `mcpServers.karma` |
+| Muse Code (Meta) | `${XDG_CONFIG_HOME:-~/.config}/muse/settings.json` | `mcpServers.karma` |
+| OpenClaw | `$OPENCLAW_STATE_DIR/openclaw.json` (default `~/.openclaw/openclaw.json`) | `mcp.servers.karma` |
+| VS Code | `<workspace>/.vscode/mcp.json` (only with `--workspace`) | `servers.karma` |
+
+Only that one entry is touched; every other line is preserved. Running install
+twice changes nothing the second time.
+
+## Gotchas it handles for you
+
+- **Muse Code** wants `"type": "stdio"` (its docs page says `transport`, the binary
+  does not) plus `schema_version: 1`, and it drops the whole MCP block if
+  `mcp_servers` and `mcpServers` ever appear together. This tool only writes
+  `mcpServers`.
+- **Codex** keeps MCP servers in TOML tables, not JSON, so the writer replaces just
+  the `[mcp_servers.karma]` block and leaves your `model`, plugins and marketplaces
+  alone.
+- **OpenClaw** nests under `mcp.servers`, not `mcpServers`.
+
+## Commands
+
+- `karma-connect detect` - which hosts exist here, and where their config lives
+- `karma-connect install [--host codex,muse] [--dry-run]` - write the entry
+- `karma-connect doctor` - is `karma-mcp-server` reachable, is every config readable, is this machine paired yet
+- `karma-connect sign-check` - print the per-request signature this machine would send
+
+## After installing
+
+1. Restart the agent host so it reloads MCP servers.
+2. Have the agent call `karma_connect` (`agent_name` = whatever it calls itself). It
+   prints a `user_code` and a `verification_uri` - open that link in Karma Console,
+   check the `agent_fingerprint` on the card matches the one the agent showed you,
+   set the limits, and approve.
+3. Have the agent call `karma_connect_claim`. Approval **is** activation, so the
+   credentials come back directly - there is no 8-character code to relay.
+4. Credentials land in `~/.karma/agent.env` (0600). Nothing secret travels through chat.
+
+The 8-character handoff code still exists as a fallback for machines that cannot
+generate a local agent key, and the console can add an email-receipt gate as a third
+lock when the approval carries `notify_email`.

karma_connect-1.0.0/karma_connect/__init__.py

@@ -0,0 +1,3 @@
+"""karma-connect - wire the Karma MCP server into every agent host on this machine."""
+
+__version__ = "1.0.0"

karma_connect-1.0.0/karma_connect/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m karma_connect`."""
+
+from karma_connect.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

karma_connect-1.0.0/karma_connect/cli.py

@@ -0,0 +1,279 @@
+"""karma-connect CLI: detect agent hosts, install the Karma MCP server, verify it."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from karma_connect.hosts import (DEFAULT_COMMAND, DEFAULT_NAME, FORBIDDEN_ENV_KEYS,
+                                 KNOWN_ENV_KEYS, default_hosts, install, parse_env)
+
+DEFAULT_MODULE = "karma_mcp_server"
+#: Without KARMA_RUNTIME_URL the MCP server falls back to http://localhost:8000 and every
+#: call dies with "All connection attempts failed" -- no user_code, no matching code.
+#: Bake the public node in so an out-of-the-box install actually talks to Karma.
+DEFAULT_ENV = {"KARMA_RUNTIME_URL": "https://karma-network.ai"}
+#: GUI 之外的兜底：直接 ``python -m karma_mcp_server``（同一个包，不必装 console script）。
+#: 老 ``karma_mcp``（私钥进进程）刻意不列 —— 装了也不能用。
+FALLBACK_MODULES = ("karma_mcp_server",)
+
+
+def _module_command(module: str, extra, env: dict):
+    """Run the MCP server as `<this python> -m <module>` and make it importable."""
+    top = module.split(".")[0]
+    spec = importlib.util.find_spec(top)
+    if spec is None or not spec.origin:
+        raise ValueError("module %r is not importable by %s" % (module, sys.executable))
+    root = str(Path(spec.origin).resolve().parents[1])
+    existing = [p for p in env.get("PYTHONPATH", "").split(os.pathsep) if p]
+    if root not in existing:
+        env["PYTHONPATH"] = os.pathsep.join([root, *existing])
+    return sys.executable, ["-m", module, *extra]
+
+
+def _resolve(args):
+    env = parse_env(getattr(args, "env", None))
+    applied_defaults = []
+    for key, value in DEFAULT_ENV.items():
+        if not env.get(key):
+            env[key] = value
+            applied_defaults.append("%s=%s" % (key, value))
+    name = args.name or DEFAULT_NAME
+    command = args.command
+    extra = list(args.arg or [])
+
+    if args.module:
+        command, extra = _module_command(args.module, extra, env)
+    elif command is None:
+        if shutil.which(DEFAULT_COMMAND):
+            command = DEFAULT_COMMAND
+        else:
+            for module in FALLBACK_MODULES:
+                if importlib.util.find_spec(module.split(".")[0]) is not None:
+                    command, extra = _module_command(module, extra, env)
+                    break
+            else:
+                command = DEFAULT_COMMAND
+    return name, command, extra, env, applied_defaults
+
+
+def result_path(host):
+    return str(host.config_path)
+
+
+def hint_for(exc, host):
+    if isinstance(exc, PermissionError):
+        return "permission denied - this shell cannot write %s" % host.config_path
+    return "%s: %s" % (type(exc).__name__, exc)
+
+
+def cmd_detect(args) -> int:
+    rows = []
+    for host in default_hosts(workspace=args.workspace):
+        rows.append({"host": host.key, "label": host.label,
+                     "detected": host.detected(), "config": str(host.config_path)})
+    if args.json:
+        print(json.dumps(rows, indent=2, ensure_ascii=False))
+        return 0
+    print("agent hosts found on this machine:")
+    for row in rows:
+        print("  [%s] %-9s %-20s %s" % ("yes" if row["detected"] else "no ", row["host"],
+                                        row["label"], row["config"]))
+    return 0
+
+
+def cmd_install(args) -> int:
+    name, command, extra, env, defaults = _resolve(args)
+    hosts = default_hosts(workspace=args.workspace)
+    if args.host and args.host != "all":
+        wanted = {h.strip() for h in args.host.split(",") if h.strip()}
+        unknown = wanted - {host.key for host in hosts}
+        if unknown:
+            print("unknown host(s): %s" % ", ".join(sorted(unknown)), file=sys.stderr)
+            return 2
+        hosts = [host for host in hosts if host.key in wanted]
+    else:
+        hosts = [host for host in hosts if host.detected()]
+
+    forbidden_env = sorted(key for key in env if key in FORBIDDEN_ENV_KEYS)
+    if forbidden_env:
+        print("refusing to install: %s must never be written into an MCP host config."
+              % ", ".join(forbidden_env), file=sys.stderr)
+        print("  karma-mcp-server refuses to start when private key material is in its "
+              "environment, so this entry would be dead on arrival.", file=sys.stderr)
+        print("  Karma wallet signatures always come from the owner's own wallet; the "
+              "agent side only ever holds a Runtime Key.", file=sys.stderr)
+        return 2
+    unknown_env = [key for key in env if key not in KNOWN_ENV_KEYS]
+    if unknown_env:
+        print("warning: unrecognized env key(s): %s" % ", ".join(unknown_env), file=sys.stderr)
+        print("  karma-mcp-server ignores these; pairing writes KARMA_RUNTIME_KEY on its own.",
+              file=sys.stderr)
+    if not hosts:
+        print("no agent host detected on this machine.", file=sys.stderr)
+        return 3
+    if not os.path.isabs(command) and shutil.which(command) is None:
+        print("warning: %r is not on PATH yet - the host will fail to start the server."
+              % command, file=sys.stderr)
+        print("  install it first: pip install ./packages/karma-mcp-server", file=sys.stderr)
+
+    print("server: %s %s" % (command, " ".join(extra)))
+    for key in defaults:
+        print("  default env: %s" % key)
+    changed = 0
+    failed = []
+    for host in hosts:
+        try:
+            result = install(host, name, command, extra, env, dry_run=args.dry_run)
+        except Exception as exc:
+            failed.append((host, exc))
+            print("  %-9s %-12s %s" % (host.key, "FAILED", result_path(host)))
+            print("  %-9s   %s" % ("", hint_for(exc, host)))
+            continue
+        if args.dry_run:
+            state = "would write"
+        else:
+            state = "updated" if result["changed"] else "already set"
+        print("  %-9s %-12s %s" % (host.key, state, result["path"]))
+        changed += 1 if result["changed"] else 0
+
+    print()
+    if failed:
+        print("%d host(s) could not be written (the rest are done)." % len(failed))
+        print("Re-run the same command in a normal terminal (not the sandbox) to finish those.")
+    if args.dry_run:
+        print("dry run: %d file(s) would change. Re-run without --dry-run to apply." % changed)
+        return 0
+    print("done. %d file(s) changed." % changed)
+    print("next: restart the agent host so it reloads MCP servers, then have the agent call")
+    print("      karma_connect; check the agent_fingerprint against the Console card, approve")
+    print("      it there - that approval IS the activation - then have it call")
+    print("      karma_connect_claim.")
+    print("      credentials land in ~/.karma/agent.env (0600) - nothing secret in chat.")
+    return 0
+
+
+def _local_runtime_key() -> str:
+    """本机凭据文件里的 Runtime Key（配对批准后由 karma_connect_claim 落盘）。"""
+    override = os.environ.get("KARMA_AGENT_ENV_PATH")
+    path = Path(override) if override else Path.home() / ".karma" / "agent.env"
+    try:
+        text = path.expanduser().read_text(encoding="utf-8")
+    except OSError:
+        return ""
+    for line in text.splitlines():
+        line = line.strip()
+        if line.startswith("KARMA_RUNTIME_KEY="):
+            return line.partition("=")[2].strip()
+    return ""
+
+
+def cmd_doctor(args) -> int:
+    name, command, extra, env, _defaults = _resolve(args)
+    problems = []
+    notes = []
+    if not os.path.isabs(command) and shutil.which(command) is None:
+        problems.append("%r is not on PATH - pip install ./packages/karma-mcp-server first"
+                        % command)
+    if not env.get("KARMA_RUNTIME_URL"):
+        problems.append("no KARMA_RUNTIME_URL: pairing would hit http://localhost:8000")
+    forbidden_env = sorted(key for key in env if key in FORBIDDEN_ENV_KEYS)
+    if forbidden_env:
+        problems.append("private key material in env (%s): karma-mcp-server refuses to start "
+                        "with those" % ", ".join(forbidden_env))
+    if not env.get("KARMA_RUNTIME_KEY") and not _local_runtime_key():
+        notes.append("not paired yet - the agent can still call karma_connect, and the Runtime "
+                     "Key lands in ~/.karma/agent.env once the owner approves")
+    for host in default_hosts(workspace=args.workspace):
+        if not host.detected():
+            continue
+        try:
+            path, _ = host.render(name, command, extra, env)
+        except Exception as exc:
+            problems.append("%s: %s" % (host.key, exc))
+            continue
+        print("  ok   %-9s %s" % (host.key, path))
+    if problems or notes:
+        print()
+        for problem in problems:
+            print("  warn %s" % problem)
+        for note in notes:
+            print("  note %s" % note)
+    if problems:
+        return 1
+    print()
+    print("configs look good." if notes else "no problems found.")
+    return 0
+
+
+def _add_common(parser):
+    parser.add_argument("--host", default="all",
+                        help="all (default) or a comma list: codex,claude,cursor,muse,openclaw,vscode")
+    parser.add_argument("--name", default=DEFAULT_NAME, help="MCP server name (default %s)" % DEFAULT_NAME)
+    parser.add_argument("--command", default=None,
+                        help="server command; default is %s if on PATH, else this python"
+                             % DEFAULT_COMMAND)
+    parser.add_argument("--module", default=None,
+                        help="run the server as `python -m <module>` (default: %s)"
+                             % DEFAULT_MODULE)
+    parser.add_argument("--arg", action="append", default=[],
+                        help="argument for the server command (repeatable)")
+    parser.add_argument("--env", action="append", default=[],
+                        help="KEY=VALUE passed to the server (repeatable)")
+    parser.add_argument("--workspace", default=None, help="workspace path, enables the vscode host")
+
+
+def cmd_sign_check(args) -> int:
+    """逐请求签名的自检 —— 实现在 karma_connect.signcheck，这里只转发参数。"""
+    from karma_connect import signcheck
+
+    argv = ["--path", args.path]
+    if args.runtime_url:
+        argv += ["--runtime-url", args.runtime_url]
+    if args.json:
+        argv.append("--json")
+    return signcheck.main(argv)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="karma-connect",
+        description="Wire the Karma MCP server into every agent host on this machine.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    detect = sub.add_parser("detect", help="list agent hosts found on this machine")
+    detect.add_argument("--json", action="store_true")
+    detect.add_argument("--workspace", default=None)
+    detect.set_defaults(func=cmd_detect)
+
+    inst = sub.add_parser("install", help="write the Karma MCP server into each detected host")
+    _add_common(inst)
+    inst.add_argument("--dry-run", action="store_true")
+    inst.set_defaults(func=cmd_install)
+
+    doctor = sub.add_parser("doctor", help="check that the install can work")
+    _add_common(doctor)
+    doctor.set_defaults(func=cmd_doctor)
+
+    sign = sub.add_parser(
+        "sign-check",
+        help="check the per-request Ed25519 signing path against a live node")
+    sign.add_argument("--runtime-url", default=None)
+    sign.add_argument("--path", default="/runtime/permissions")
+    sign.add_argument("--json", action="store_true")
+    sign.set_defaults(func=cmd_sign_check)
+    return parser
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

karma_connect-1.0.0/karma_connect/hosts.py

@@ -0,0 +1,231 @@
+"""Detect agent hosts on this machine and write Karma's MCP server into them.
+
+Every host gets the same treatment: read its config, upsert one named MCP server
+entry, leave everything else alone. Writes are idempotent, so running the
+command twice changes nothing the second time.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_NAME = "karma"
+#: 默认指向通用薄接入层 ``packages/karma-mcp-server``。**不要**改回老包 ``karma-mcp``：
+#: 那个包把 ``KARMA_PRIVATE_KEY`` 注进 MCP 进程（安全审计判定作废），而
+#: ``karma-mcp-server`` 启动时发现私钥类键就直接拒绝启动（红线 R1）。
+DEFAULT_COMMAND = "karma-mcp-server"
+
+#: ``karma-mcp-server`` 真正会读的键（契约见 packages/karma-mcp-server/README.md）。
+#: 只用于提示「这个环境变量它根本不认」，不参与任何校验。
+KNOWN_ENV_KEYS = (
+    "KARMA_RUNTIME_URL",
+    "KARMA_RUNTIME_KEY",
+    "KARMA_API_KEY",
+    "KARMA_AGENT_ID",
+    "KARMA_AGENT_PRIVATE_KEY",
+    "KARMA_AGENT_ENV_PATH",
+    "KARMA_MCP_STATE_DIR",
+    "KARMA_MCP_ENABLE_TIER2",
+    "KARMA_MCP_ENABLE_TIER3",
+    "KARMA_MCP_ENABLE_HTTP",
+    "KARMA_MCP_HTTP_TOKEN",
+    "KARMA_MCP_ISSUER_URL",
+    "KARMA_MCP_RESOURCE_URL",
+    "PYTHONPATH",
+    "PYTHONIOENCODING",
+)
+
+#: 绝不能写进宿主配置的键：``karma-mcp-server`` 启动时会检查它们并**拒绝启动**，
+#: 写进去等于给宿主配一个起不来的 server。所以安装时直接拒绝（fail-closed）。
+#: 老 ``karma-mcp`` 那套链上私钥模型（KARMA_PRIVATE_KEY / KARMA_MNEMONIC）一并列入。
+FORBIDDEN_ENV_KEYS = (
+    "KARMA_PRIVATE_KEY",
+    "KARMA_MNEMONIC",
+    "MNEMONIC",
+    "USER_PRIVATE_KEY",
+    "DEPLOYER_PRIVATE_KEY",
+)
+
+
+def _home() -> Path:
+    return Path(os.path.expanduser("~"))
+
+
+def xdg_config_home() -> Path:
+    value = os.environ.get("XDG_CONFIG_HOME")
+    return Path(value) if value else _home() / ".config"
+
+
+def codex_home() -> Path:
+    return Path(os.environ.get("CODEX_HOME") or (_home() / ".codex"))
+
+
+def parse_env(pairs):
+    """["KEY=VALUE", ...] -> dict, insertion order kept."""
+    out = {}
+    for pair in pairs or []:
+        if "=" not in pair:
+            raise ValueError("--env expects KEY=VALUE, got %r" % (pair,))
+        key, _, value = pair.partition("=")
+        key = key.strip()
+        if not key:
+            raise ValueError("--env expects KEY=VALUE, got %r" % (pair,))
+        out[key] = value
+    return out
+
+
+# ---------------------------------------------------------------- TOML helpers
+
+def _toml_string(value: str) -> str:
+    return json.dumps(value)
+
+
+def _toml_array(values) -> str:
+    return "[" + ", ".join(_toml_string(v) for v in values) + "]"
+
+
+def upsert_toml_table(text: str, table: str, body) -> str:
+    """Insert or replace [table], preserving every other line."""
+    header = "[%s]" % table
+    lines = text.splitlines()
+    start = next((i for i, line in enumerate(lines) if line.strip() == header), None)
+    if start is None:
+        out = text.rstrip("\n")
+        prefix = out + "\n\n" if out else ""
+        return prefix + "\n".join([header, *body]) + "\n"
+    end = len(lines)
+    for j in range(start + 1, len(lines)):
+        stripped = lines[j].strip()
+        if stripped.startswith("[") and stripped.endswith("]"):
+            if stripped.startswith(header[:-1] + "."):
+                continue
+            end = j
+            break
+    merged = [*lines[:start], header, *body]
+    tail = lines[end:]
+    if tail:
+        merged.append("")
+        merged.extend(tail)
+    return "\n".join(merged).rstrip("\n") + "\n"
+
+
+# ---------------------------------------------------------------- JSON helpers
+
+def read_json_object(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    raw = path.read_text(encoding="utf-8").strip()
+    if not raw:
+        return {}
+    data = json.loads(raw)
+    if not isinstance(data, dict):
+        raise ValueError("%s does not hold a JSON object" % path)
+    return data
+
+
+def write_json_object(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def json_upsert(data: dict, dotted: str, name: str, entry: dict) -> None:
+    node = data
+    parts = dotted.split(".")
+    for part in parts[:-1]:
+        child = node.get(part)
+        if not isinstance(child, dict):
+            child = {}
+            node[part] = child
+        node = child
+    bucket = node.get(parts[-1])
+    if not isinstance(bucket, dict):
+        bucket = {}
+        node[parts[-1]] = bucket
+    bucket[name] = entry
+
+
+# ------------------------------------------------------------------- host spec
+
+def build_entry(command: str, args, env: dict, style: str) -> dict:
+    if style == "muse":
+        return {"type": "stdio", "command": command, "args": list(args),
+                "env": dict(env), "mode": "optional"}
+    if style == "vscode":
+        return {"type": "stdio", "command": command, "args": list(args), "env": dict(env)}
+    if style == "openclaw":
+        return {"transport": "stdio", "command": command, "args": list(args), "env": dict(env)}
+    return {"command": command, "args": list(args), "env": dict(env)}
+
+
+@dataclass
+class Host:
+    key: str
+    label: str
+    style: str
+    config_path: Path
+    json_bucket: str = "mcpServers"
+    toml_table: str = "mcp_servers"
+    format: str = "json"
+    detect_paths: tuple = field(default_factory=tuple)
+
+    def detected(self) -> bool:
+        if not self.detect_paths:
+            return True
+        return any(path.exists() for path in self.detect_paths)
+
+    def render(self, name: str, command: str, args, env: dict):
+        """-> (path, new_text). Pure: no disk writes."""
+        if self.format == "toml":
+            current = (self.config_path.read_text(encoding="utf-8")
+                       if self.config_path.exists() else "")
+            body = ["command = %s" % _toml_string(command),
+                    "args = %s" % _toml_array(args)]
+            if env:
+                body.append("[%s.%s.env]" % (self.toml_table, name))
+                body.extend("%s = %s" % (k, _toml_string(v)) for k, v in env.items())
+            text = upsert_toml_table(current, "%s.%s" % (self.toml_table, name), body)
+            return self.config_path, text
+        data = read_json_object(self.config_path)
+        json_upsert(data, self.json_bucket, name, build_entry(command, args, env, self.style))
+        if self.style == "muse" and "schema_version" not in data:
+            data = {"schema_version": 1, **data}
+        return self.config_path, json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+
+
+def default_hosts(workspace=None):
+    home = _home()
+    cfg = xdg_config_home()
+    openclaw_state = Path(os.environ.get("OPENCLAW_STATE_DIR") or (home / ".openclaw"))
+    hosts = [
+        Host("codex", "Codex CLI", "plain", codex_home() / "config.toml",
+             toml_table="mcp_servers", format="toml", detect_paths=(codex_home(),)),
+        Host("claude", "Claude Code", "plain", home / ".claude.json",
+             detect_paths=(home / ".claude.json",)),
+        Host("cursor", "Cursor", "plain", home / ".cursor" / "mcp.json",
+             detect_paths=(home / ".cursor",)),
+        Host("muse", "Muse Code (Meta)", "muse", cfg / "muse" / "settings.json",
+             detect_paths=(cfg / "muse",)),
+        Host("openclaw", "OpenClaw", "openclaw", openclaw_state / "openclaw.json",
+             json_bucket="mcp.servers", detect_paths=(openclaw_state,)),
+    ]
+    if workspace is not None:
+        hosts.append(Host("vscode", "VS Code (this workspace)", "vscode",
+                          Path(workspace) / ".vscode" / "mcp.json",
+                          json_bucket="servers", detect_paths=(Path(workspace),)))
+    return hosts
+
+
+def install(host: Host, name: str, command: str, args, env: dict, dry_run: bool = False):
+    """-> dict describing what happened."""
+    path, new_text = host.render(name, command, args, env)
+    if dry_run:
+        return {"host": host.key, "path": str(path), "changed": True, "dry_run": True}
+    before = path.read_text(encoding="utf-8") if path.exists() else None
+    if before == new_text:
+        return {"host": host.key, "path": str(path), "changed": False}
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(new_text, encoding="utf-8")
+    return {"host": host.key, "path": str(path), "changed": True}