@sakanano-moe/agenthelm 0.0.0-stage → 6.5.1

package/runtime/mcp_env_launcher.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Launch one stdio MCP after loading a project-local dotenv file.
+
+The launcher never prints dotenv values. Configuration contains only variable
+references and is generated into a client-local project capability package.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+REFERENCE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+def load_dotenv(path: Path) -> dict[str, str]:
+    if path.is_symlink() or not path.is_file():
+        raise RuntimeError(f"credential env file missing or unsafe: {path}")
+    values: dict[str, str] = {}
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:].lstrip()
+        key, separator, value = line.partition("=")
+        key = key.strip()
+        if not separator or not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", key):
+            continue
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}:
+            value = value[1:-1]
+        values[key] = value
+    return values
+
+
+def expand(value: Any, environment: dict[str, str]) -> Any:
+    if isinstance(value, str):
+        def replace(match: re.Match[str]) -> str:
+            name = match.group(1)
+            if name not in environment:
+                raise RuntimeError(f"credential env file missing key: {name}")
+            return environment[name]
+
+        return REFERENCE.sub(replace, value)
+    if isinstance(value, list):
+        return [expand(item, environment) for item in value]
+    if isinstance(value, dict):
+        return {key: expand(item, environment) for key, item in value.items()}
+    return value
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--env-file", type=Path, required=True)
+    parser.add_argument("--config", type=Path, required=True)
+    args = parser.parse_args(argv)
+    try:
+        config = json.loads(args.config.read_text(encoding="utf-8"))
+        if not isinstance(config, dict) or config.get("type") != "stdio":
+            raise RuntimeError("launcher config must be a stdio MCP object")
+        environment = dict(os.environ)
+        environment.update(load_dotenv(args.env_file))
+        config = expand(config, environment)
+        command = config.get("command")
+        command_args = config.get("args", [])
+        if not isinstance(command, str) or not command:
+            raise RuntimeError("stdio command is required")
+        if not isinstance(command_args, list) or not all(isinstance(item, str) for item in command_args):
+            raise RuntimeError("stdio args must be a string array")
+        child_env = dict(environment)
+        raw_env = config.get("env", {})
+        if not isinstance(raw_env, dict) or not all(isinstance(key, str) and isinstance(value, str) for key, value in raw_env.items()):
+            raise RuntimeError("stdio env must be a string object")
+        child_env.update(raw_env)
+        cwd = config.get("cwd")
+        if cwd is not None:
+            if not isinstance(cwd, str):
+                raise RuntimeError("stdio cwd must be a string")
+            os.chdir(cwd)
+        os.execvpe(command, [command, *command_args], child_env)
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError, RuntimeError) as exc:
+        print(f"agent-pack MCP launch failed: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/mcp_server.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python3
+"""MCP stdio adapter for agent-pack capability-management operations.
+
+Primary protocol: MCP 2026-07-28 (stateless, per-request metadata).
+Compatibility: legacy initialize/notifications/initialized clients.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from agent_pack_config import (
+    AgentPackError,
+    doctor,
+    install_plugin,
+    inventory_source,
+    reconcile_project,
+    sync_project,
+    transfer_to_project,
+)
+
+
+PROTOCOL_VERSION = "2026-07-28"
+LEGACY_VERSION = "2025-06-18"
+def _plugin_version() -> str:
+    """Single source of truth: the sibling plugin.json version."""
+    try:
+        manifest = json.loads((Path(__file__).resolve().parents[1] / "plugin.json").read_text(encoding="utf-8"))
+        version = manifest.get("version")
+        return version if isinstance(version, str) else "0.0.0"
+    except (OSError, json.JSONDecodeError):
+        return "0.0.0"
+
+
+SERVER_INFO = {"name": "agent-pack", "version": _plugin_version()}
+SERVER_META = {"io.modelcontextprotocol/serverInfo": SERVER_INFO}
+
+
+TOOLS = [
+    {
+        "name": "agent_pack_bootstrap",
+        "title": "Install Agent Plugin",
+        "description": "Dry-run or install a portable plugin, including agent-pack itself, into Codex, Cursor, or Claude Code without overwriting an existing package.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "plugin": {"type": "string"},
+                "client": {"type": "string", "enum": ["codex", "cursor", "claude"]},
+                "home": {"type": "string"},
+                "apply": {"type": "boolean", "default": False},
+                "replace": {"type": "boolean", "default": False},
+                "recoveryRoot": {"type": "string"},
+            },
+            "required": ["plugin", "client"],
+            "additionalProperties": False,
+        },
+        "annotations": {"destructiveHint": False, "idempotentHint": False},
+    },
+    {
+        "name": "agent_pack_reconcile",
+        "title": "Reconcile Project and Client Capabilities",
+        "description": "Classify capability drift, safely replace the managed project package, and archive explicitly selected legacy Skills or plugins with rollback. apply defaults to false.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project": {"type": "string"},
+                "client": {"type": "string", "enum": ["codex", "cursor"]},
+                "home": {"type": "string"},
+                "retireSkills": {"type": "array", "items": {"type": "string"}, "default": []},
+                "retirePlugins": {"type": "array", "items": {"type": "string"}, "default": []},
+                "recoveryRoot": {"type": "string"},
+                "retireOnly": {"type": "boolean", "default": False},
+                "apply": {"type": "boolean", "default": False},
+            },
+            "required": ["project", "client"],
+            "additionalProperties": False,
+        },
+        "annotations": {"destructiveHint": True, "idempotentHint": False},
+    },
+    {
+        "name": "agent_pack_inventory",
+        "title": "Inventory Agent Capabilities",
+        "description": "Discover portable Agent Plugins, Skills, and MCP servers from a project, plugin directory, or supported client.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "source": {"type": "string", "description": "project:/path, plugin:/path, client:codex, client:cursor, or client:claude"},
+                "home": {"type": "string"},
+            },
+            "required": ["source"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "agent_pack_doctor",
+        "title": "Validate Project Capabilities",
+        "description": "Validate an initialized project's Agent Plugin, Skill, MCP, duplicate-name, portability, and secret boundaries.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"project": {"type": "string"}},
+            "required": ["project"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "agent_pack_transfer",
+        "title": "Transfer Skills and MCP Servers",
+        "description": "Dry-run or copy explicitly selected portable Skills and MCP definitions into another initialized project. apply defaults to false.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "source": {"type": "string"},
+                "toProject": {"type": "string"},
+                "skills": {"type": "array", "items": {"type": "string"}, "default": []},
+                "mcps": {"type": "array", "items": {"type": "string"}, "default": []},
+                "home": {"type": "string"},
+                "apply": {"type": "boolean", "default": False},
+            },
+            "required": ["source", "toProject"],
+            "additionalProperties": False,
+        },
+        "annotations": {"destructiveHint": False, "idempotentHint": False},
+    },
+    {
+        "name": "agent_pack_sync",
+        "title": "Sync Project Capabilities to an Agent Client",
+        "description": "Dry-run or install a project's portable capability package into Codex or Cursor. apply defaults to false and existing targets are never overwritten.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "project": {"type": "string"},
+                "client": {"type": "string", "enum": ["codex", "cursor"]},
+                "home": {"type": "string"},
+                "apply": {"type": "boolean", "default": False},
+            },
+            "required": ["project", "client"],
+            "additionalProperties": False,
+        },
+        "annotations": {"destructiveHint": False, "idempotentHint": False},
+    },
+]
+
+
+def _modern(params: dict[str, Any]) -> bool:
+    meta = params.get("_meta", {})
+    return isinstance(meta, dict) and meta.get("io.modelcontextprotocol/protocolVersion") == PROTOCOL_VERSION
+
+
+def _result(payload: dict[str, Any], modern: bool) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "content": [{"type": "text", "text": json.dumps(payload, ensure_ascii=False, indent=2)}],
+        "structuredContent": payload,
+        "isError": not payload.get("ok", True),
+    }
+    if modern:
+        result["resultType"] = "complete"
+        result["_meta"] = SERVER_META
+    return result
+
+
+def _call(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    home_value = arguments.get("home")
+    home = Path(home_value) if isinstance(home_value, str) else None
+    if name == "agent_pack_bootstrap":
+        recovery_value = arguments.get("recoveryRoot")
+        recovery = Path(recovery_value) if isinstance(recovery_value, str) else None
+        return install_plugin(
+            Path(arguments["plugin"]),
+            arguments["client"],
+            home=home,
+            apply=bool(arguments.get("apply", False)),
+            replace=bool(arguments.get("replace", False)),
+            recovery_root=recovery,
+        )
+    if name == "agent_pack_reconcile":
+        recovery_value = arguments.get("recoveryRoot")
+        recovery = Path(recovery_value) if isinstance(recovery_value, str) else None
+        return reconcile_project(
+            Path(arguments["project"]),
+            arguments["client"],
+            home=home,
+            retire_skills=arguments.get("retireSkills", []),
+            retire_plugins=arguments.get("retirePlugins", []),
+            recovery_root=recovery,
+            apply=bool(arguments.get("apply", False)),
+            retire_only=bool(arguments.get("retireOnly", False)),
+        )
+    if name == "agent_pack_inventory":
+        inventory = inventory_source(arguments["source"], home)
+        payload = inventory.to_dict()
+        payload["ok"] = not payload["issues"]
+        return payload
+    if name == "agent_pack_doctor":
+        return doctor(Path(arguments["project"]))
+    if name == "agent_pack_transfer":
+        source = inventory_source(arguments["source"], home)
+        return transfer_to_project(
+            source,
+            Path(arguments["toProject"]),
+            arguments.get("skills", []),
+            arguments.get("mcps", []),
+            apply=bool(arguments.get("apply", False)),
+        )
+    if name == "agent_pack_sync":
+        return sync_project(
+            Path(arguments["project"]),
+            arguments["client"],
+            home=home,
+            apply=bool(arguments.get("apply", False)),
+        )
+    raise AgentPackError(f"unknown tool: {name}")
+
+
+def handle_message(message: dict[str, Any]) -> dict[str, Any] | None:
+    if message.get("jsonrpc") != "2.0":
+        return {"jsonrpc": "2.0", "id": message.get("id"), "error": {"code": -32600, "message": "Invalid Request"}}
+    if "id" not in message:
+        return None
+    request_id = message["id"]
+    method = message.get("method")
+    params = message.get("params") if isinstance(message.get("params"), dict) else {}
+    modern = _modern(params)
+    try:
+        if method == "server/discover":
+            result = {
+                "resultType": "complete",
+                "supportedVersions": [PROTOCOL_VERSION],
+                "capabilities": {"tools": {}},
+                "_meta": SERVER_META,
+                "instructions": "Inventory first. Transfer and sync default to dry-run; set apply=true only after user approval.",
+                "ttlMs": 3600000,
+                "cacheScope": "public",
+            }
+        elif method == "initialize":
+            result = {
+                "protocolVersion": LEGACY_VERSION,
+                "capabilities": {"tools": {}},
+                "serverInfo": SERVER_INFO,
+                "instructions": "Inventory first; write operations require apply=true.",
+            }
+        elif method == "tools/list":
+            result = {"tools": TOOLS}
+            if modern:
+                result.update({
+                    "resultType": "complete",
+                    "ttlMs": 300000,
+                    "cacheScope": "public",
+                    "_meta": SERVER_META,
+                })
+        elif method == "tools/call":
+            name = params.get("name")
+            arguments = params.get("arguments", {})
+            if not isinstance(name, str) or not isinstance(arguments, dict):
+                raise AgentPackError("tools/call requires string name and object arguments")
+            result = _result(_call(name, arguments), modern)
+        else:
+            return {"jsonrpc": "2.0", "id": request_id, "error": {"code": -32601, "message": "Method not found"}}
+        return {"jsonrpc": "2.0", "id": request_id, "result": result}
+    except (AgentPackError, KeyError, TypeError, ValueError) as exc:
+        payload = {"ok": False, "error": str(exc)}
+        if method == "tools/call":
+            return {"jsonrpc": "2.0", "id": request_id, "result": _result(payload, modern)}
+        return {"jsonrpc": "2.0", "id": request_id, "error": {"code": -32602, "message": str(exc)}}
+
+
+def main() -> int:
+    for line in sys.stdin:
+        try:
+            message = json.loads(line)
+            if not isinstance(message, dict):
+                raise ValueError("message must be an object")
+            response = handle_message(message)
+        except (json.JSONDecodeError, ValueError) as exc:
+            response = {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": str(exc)}}
+        if response is not None:
+            sys.stdout.write(json.dumps(response, ensure_ascii=False, separators=(",", ":")) + "\n")
+            sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.