@smilintux/skmemory 0.5.0 → 0.7.2

package/skmemory/register.py

@@ -0,0 +1,454 @@
+"""SK* skill, MCP server, and OpenClaw plugin auto-registration.
+
+Detects the user's development environments (OpenClaw, Claude Code, Cursor,
+VS Code, OpenCode CLI, mcporter) and registers SKILL.md symlinks, MCP
+server entries, and OpenClaw plugin manifests so everything works out-of-the-box.
+
+This module is the shared engine — individual packages call it, and
+skcapstone orchestrates registration for the whole suite.
+
+Usage (from any SK* package):
+    from skmemory.register import register_package, detect_environments
+
+    register_package(
+        name="skmemory",
+        skill_md_path=Path(__file__).parent / "SKILL.md",
+        mcp_command="skmemory-mcp",
+        mcp_args=[],
+        openclaw_plugin_path=Path(__file__).parent.parent / "openclaw-plugin" / "src" / "index.ts",
+    )
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+
+# ── Environment detection ────────────────────────────────────────────────────
+
+
+def detect_environments() -> list[str]:
+    """Return list of detected development environments.
+
+    Checks for:
+      - openclaw: OpenClaw CLI installed
+      - claude-code: ~/.claude/ directory
+      - cursor: ~/.cursor/ directory
+      - vscode: ~/.vscode/ or ~/.config/Code/ directory
+      - opencode: ~/.opencode/ or opencode binary
+      - mcporter: mcporter.json in known locations
+
+    Returns:
+        List of environment identifiers (e.g. ["claude-code", "mcporter"]).
+    """
+    home = Path.home()
+    envs: list[str] = []
+
+    # OpenClaw
+    openclaw_lib = home / ".npm-global" / "lib" / "node_modules" / "openclaw"
+    if openclaw_lib.is_dir() or shutil.which("openclaw"):
+        envs.append("openclaw")
+
+    # Claude Code
+    if (home / ".claude").is_dir():
+        envs.append("claude-code")
+
+    # Cursor
+    if (home / ".cursor").is_dir():
+        envs.append("cursor")
+
+    # VS Code
+    if (home / ".vscode").is_dir() or (home / ".config" / "Code").is_dir():
+        envs.append("vscode")
+
+    # OpenCode CLI
+    if (home / ".opencode").is_dir() or shutil.which("opencode"):
+        envs.append("opencode")
+
+    # mcporter
+    mcporter_paths = [
+        home / "clawd" / "config" / "mcporter.json",
+        home / ".config" / "mcporter" / "mcporter.json",
+    ]
+    for p in mcporter_paths:
+        if p.is_file():
+            envs.append("mcporter")
+            break
+
+    return envs
+
+
+# ── Skill registration ───────────────────────────────────────────────────────
+
+
+def register_skill(
+    name: str,
+    skill_md_path: Path,
+    workspace: Optional[Path] = None,
+) -> dict:
+    """Register a skill by symlinking its SKILL.md into the workspace skills dir.
+
+    Args:
+        name: Package/skill name (e.g. "skmemory").
+        skill_md_path: Absolute path to the source SKILL.md file.
+        workspace: Workspace root (defaults to ~/clawd/).
+
+    Returns:
+        Dict with 'skill' key describing what was done.
+    """
+    if workspace is None:
+        workspace = Path.home() / "clawd"
+
+    skill_dir = workspace / "skills" / name
+    target = skill_dir / "SKILL.md"
+
+    result: dict = {"name": name, "action": "skip", "path": str(target)}
+
+    if not skill_md_path.exists():
+        result["action"] = "error"
+        result["error"] = f"Source SKILL.md not found: {skill_md_path}"
+        return result
+
+    skill_dir.mkdir(parents=True, exist_ok=True)
+
+    # If target already exists and is correct, skip
+    if target.is_symlink():
+        try:
+            if target.resolve() == skill_md_path.resolve():
+                result["action"] = "exists"
+                return result
+        except OSError:
+            pass
+        # Remove broken or wrong symlink
+        target.unlink()
+
+    if target.exists():
+        result["action"] = "exists"
+        return result
+
+    # Create symlink — prefer relative path
+    try:
+        rel = os.path.relpath(skill_md_path, skill_dir)
+        target.symlink_to(rel)
+    except (ValueError, OSError):
+        target.symlink_to(skill_md_path)
+
+    result["action"] = "created"
+    return result
+
+
+# ── MCP registration ─────────────────────────────────────────────────────────
+
+
+def _read_json(path: Path) -> dict:
+    """Read a JSON file, returning empty dict on error."""
+    try:
+        return json.loads(path.read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+
+
+def _write_json(path: Path, data: dict) -> None:
+    """Write dict as pretty-printed JSON."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n")
+
+
+def _upsert_mcp_entry(
+    path: Path,
+    name: str,
+    command: str,
+    args: list,
+    env: Optional[dict] = None,
+) -> str:
+    """Add or update an MCP server entry in a JSON config file.
+
+    Expects the file to have a top-level "mcpServers" key.
+
+    Args:
+        path: Path to the JSON config file.
+        name: Server name.
+        command: Command to run.
+        args: Command arguments.
+        env: Optional environment variables.
+
+    Returns:
+        "created", "updated", or "exists".
+    """
+    data = _read_json(path)
+    servers = data.setdefault("mcpServers", {})
+
+    entry: dict = {"command": command, "args": args}
+    if env:
+        entry["env"] = env
+
+    if name in servers:
+        if servers[name] == entry:
+            return "exists"
+        servers[name] = entry
+        _write_json(path, data)
+        return "updated"
+
+    servers[name] = entry
+    _write_json(path, data)
+    return "created"
+
+
+def register_mcp(
+    name: str,
+    command: str,
+    args: list,
+    env: Optional[dict] = None,
+    environments: Optional[list[str]] = None,
+) -> dict:
+    """Register an MCP server in detected (or specified) environments.
+
+    Writes to:
+      - claude-code: ~/.claude/mcp.json
+      - cursor: ~/.cursor/mcp.json
+      - vscode: (skipped — requires workspace .vscode/)
+      - opencode: ~/.opencode/mcp.json
+      - mcporter: ~/clawd/config/mcporter.json or ~/.config/mcporter/mcporter.json
+
+    Args:
+        name: Server name (e.g. "skmemory").
+        command: Command to run (e.g. "skmemory-mcp").
+        args: Command arguments.
+        env: Optional environment variables.
+        environments: Target environments. If None, auto-detect.
+
+    Returns:
+        Dict mapping environment -> action taken.
+    """
+    if environments is None:
+        environments = detect_environments()
+
+    home = Path.home()
+    results: dict = {}
+
+    env_to_path: dict[str, Path] = {
+        "claude-code": home / ".claude" / "mcp.json",
+        "cursor": home / ".cursor" / "mcp.json",
+        "opencode": home / ".opencode" / "mcp.json",
+    }
+
+    # OpenClaw: uses mcporter for MCP — no native mcpServers key in
+    # openclaw.json. MCP registration for OpenClaw happens via mcporter.
+
+    # mcporter: find first existing file
+    mcporter_candidates = [
+        home / "clawd" / "config" / "mcporter.json",
+        home / ".config" / "mcporter" / "mcporter.json",
+    ]
+    for p in mcporter_candidates:
+        if p.is_file():
+            env_to_path["mcporter"] = p
+            break
+
+    for env_name in environments:
+        path = env_to_path.get(env_name)
+        if path is None:
+            continue
+        try:
+            action = _upsert_mcp_entry(path, name, command, args, env)
+            results[env_name] = action
+        except Exception as exc:
+            results[env_name] = f"error: {exc}"
+
+    return results
+
+
+# ── OpenClaw plugin registration ─────────────────────────────────────────────
+
+
+def _get_openclaw_json_path() -> Path:
+    """Return path to ~/.openclaw/openclaw.json."""
+    return Path.home() / ".openclaw" / "openclaw.json"
+
+
+def _is_openclaw_plugin_registered(plugin_path: Path) -> bool:
+    """Check if plugin_path is already in openclaw.json plugins.load.paths."""
+    oc_json = _get_openclaw_json_path()
+    if not oc_json.is_file():
+        return False
+    data = _read_json(oc_json)
+    paths = data.get("plugins", {}).get("load", {}).get("paths", [])
+    resolved = str(plugin_path.resolve())
+    return any(str(Path(p).resolve()) == resolved for p in paths)
+
+
+def _upsert_openclaw_plugin_path(plugin_id: str, plugin_path: Path) -> None:
+    """Add plugin to plugins.load.paths and plugins.installs in openclaw.json."""
+    oc_json = _get_openclaw_json_path()
+    data = _read_json(oc_json)
+
+    plugins = data.setdefault("plugins", {})
+    load = plugins.setdefault("load", {})
+    paths = load.setdefault("paths", [])
+
+    resolved = str(plugin_path.resolve())
+    if resolved not in paths:
+        paths.append(resolved)
+
+    installs = plugins.setdefault("installs", {})
+    # Point to the plugin directory (parent of src/index.ts)
+    plugin_dir = str(plugin_path.resolve().parent.parent)
+    installs[plugin_id] = {"path": plugin_dir, "linked": True}
+
+    _write_json(oc_json, data)
+
+
+def _ensure_openclaw_plugin_enabled(plugin_id: str) -> None:
+    """Set plugins.entries.<plugin_id>.enabled = true (idempotent)."""
+    oc_json = _get_openclaw_json_path()
+    data = _read_json(oc_json)
+
+    entries = data.setdefault("plugins", {}).setdefault("entries", {})
+    entry = entries.setdefault(plugin_id, {})
+
+    if entry.get("enabled") is True:
+        return
+
+    entry["enabled"] = True
+    _write_json(oc_json, data)
+
+
+def _detect_plugin_id(plugin_path: Path, fallback: str) -> str:
+    """Read plugin id from openclaw.plugin.json manifest."""
+    manifest = plugin_path.parent / "openclaw.plugin.json"
+    if manifest.is_file():
+        try:
+            data = json.loads(manifest.read_text())
+            return data.get("id", fallback)
+        except (json.JSONDecodeError, KeyError):
+            pass
+    return fallback
+
+
+def register_openclaw_plugin(
+    plugin_id: str,
+    plugin_path: Path,
+    dry_run: bool = False,
+) -> str:
+    """Register an OpenClaw plugin. Returns 'exists', 'created', or 'error:...'.
+
+    1. Check _is_openclaw_plugin_registered() -> skip if already registered
+    2. Try `openclaw plugins install --link <path>` via subprocess
+    3. Fallback: write openclaw.json directly if CLI fails
+    4. _ensure_openclaw_plugin_enabled()
+
+    Args:
+        plugin_id: Plugin identifier (e.g. "skmemory").
+        plugin_path: Path to the plugin entry point (e.g. src/index.ts).
+        dry_run: If True, only report what would be done.
+
+    Returns:
+        Action taken: "exists", "created", "dry-run", or "error:...".
+    """
+    if dry_run:
+        return "dry-run"
+
+    if not plugin_path.exists():
+        return f"error: plugin not found: {plugin_path}"
+
+    # Detect actual plugin ID from manifest
+    actual_id = _detect_plugin_id(plugin_path, plugin_id)
+
+    if _is_openclaw_plugin_registered(plugin_path):
+        _ensure_openclaw_plugin_enabled(actual_id)
+        return "exists"
+
+    # Try CLI first
+    plugin_dir = str(plugin_path.resolve().parent.parent)
+    try:
+        subprocess.run(
+            ["openclaw", "plugins", "install", "--link", plugin_dir],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+        if _is_openclaw_plugin_registered(plugin_path):
+            _ensure_openclaw_plugin_enabled(actual_id)
+            return "created"
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        pass
+
+    # Fallback: write directly
+    try:
+        _upsert_openclaw_plugin_path(actual_id, plugin_path)
+        _ensure_openclaw_plugin_enabled(actual_id)
+        return "created"
+    except Exception as exc:
+        return f"error: {exc}"
+
+
+# ── High-level package registration ──────────────────────────────────────────
+
+
+def register_package(
+    name: str,
+    skill_md_path: Path,
+    mcp_command: Optional[str] = None,
+    mcp_args: Optional[list] = None,
+    mcp_env: Optional[dict] = None,
+    openclaw_plugin_path: Optional[Path] = None,
+    workspace: Optional[Path] = None,
+    environments: Optional[list[str]] = None,
+    dry_run: bool = False,
+) -> dict:
+    """Register a skill, MCP server, and OpenClaw plugin in all detected environments.
+
+    Args:
+        name: Package/skill name.
+        skill_md_path: Path to the SKILL.md file.
+        mcp_command: MCP server command (None to skip MCP registration).
+        mcp_args: MCP server arguments.
+        mcp_env: MCP server environment variables.
+        openclaw_plugin_path: Path to OpenClaw plugin entry (e.g. src/index.ts).
+        workspace: Workspace root for skill symlinks.
+        environments: Target environments (auto-detect if None).
+        dry_run: If True, only report what would be done.
+
+    Returns:
+        Dict with 'skill', 'mcp', and 'openclaw_plugin' results.
+    """
+    if environments is None:
+        environments = detect_environments()
+
+    result: dict = {"name": name, "environments": environments}
+
+    if dry_run:
+        result["skill"] = {"action": "dry-run", "path": str(
+            (workspace or Path.home() / "clawd") / "skills" / name / "SKILL.md"
+        )}
+        if mcp_command:
+            result["mcp"] = {env: "dry-run" for env in environments}
+        if openclaw_plugin_path and "openclaw" in environments:
+            result["openclaw_plugin"] = "dry-run"
+        return result
+
+    # Register skill
+    result["skill"] = register_skill(name, skill_md_path, workspace)
+
+    # Register MCP server
+    if mcp_command is not None:
+        result["mcp"] = register_mcp(
+            name,
+            mcp_command,
+            mcp_args or [],
+            env=mcp_env,
+            environments=environments,
+        )
+
+    # Register OpenClaw plugin
+    if openclaw_plugin_path is not None and "openclaw" in environments:
+        result["openclaw_plugin"] = register_openclaw_plugin(
+            name, openclaw_plugin_path, dry_run=dry_run,
+        )
+
+    return result

package/skmemory/register_mcp.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""
+MCP Server Registration for SKMemory/SKCapstone
+
+Auto-registers MCP servers with OpenCode, Claude Code, and OpenClaw.
+Usage:
+    python -m skmemory.register_mcp
+    python -m skmemory.register_mcp --env opencode
+    python -m skmemory.register_mcp --env claude
+    python -m skmemory.register_mcp --env openclaw
+    python -m skmemory.register_mcp --agent lumina
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+def get_agent_name() -> str:
+    """Get agent name from environment or default."""
+    return os.environ.get("SKMEMORY_AGENT") or os.environ.get("SKCAPSTONE_AGENT") or "lumina"
+
+
+def register_opencode(agent: str, dry_run: bool = False) -> bool:
+    """Register SKMemory with OpenCode."""
+    config_dir = Path.home() / ".opencode"
+    config_file = config_dir / "mcp.json"
+
+    if dry_run:
+        print(f"[DRY-RUN] Would create: {config_file}")
+        return True
+
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    # Build MCP config
+    config = {
+        "mcpServers": {
+            "skmemory": {
+                "command": "python",
+                "args": ["-m", "skmemory.mcp_server"],
+                "env": {
+                    "SKMEMORY_AGENT": agent,
+                    "SKMEMORY_HOME": str(Path.home() / ".skcapstone" / "agents" / agent),
+                },
+            },
+            "skcapstone": {
+                "command": "python",
+                "args": ["-m", "skcapstone.mcp_server"],
+                "env": {"SKCAPSTONE_AGENT": agent},
+            },
+        },
+        "skills": [
+            {
+                "name": "skmemory",
+                "path": str(Path.home() / "clawd" / "skcapstone-repos" / "skmemory" / "SKILL.md"),
+            },
+            {"name": "skcapstone", "path": str(Path.home() / "clawd" / "skcapstone" / "SKILL.md")},
+        ],
+    }
+
+    with open(config_file, "w") as f:
+        json.dump(config, f, indent=2)
+
+    print(f"✓ Registered with OpenCode: {config_file}")
+    return True
+
+
+def register_claude(agent: str, dry_run: bool = False) -> bool:
+    """Register SKMemory with Claude Code."""
+    config_file = Path.home() / ".config" / "claude" / "claude_desktop_config.json"
+
+    if dry_run:
+        print(f"[DRY-RUN] Would create: {config_file}")
+        return True
+
+    config_file.parent.mkdir(parents=True, exist_ok=True)
+
+    config = {
+        "mcpServers": {
+            "skmemory": {
+                "command": "python",
+                "args": ["-m", "skmemory.mcp_server"],
+                "env": {
+                    "SKMEMORY_AGENT": agent,
+                    "SKMEMORY_HOME": str(Path.home() / ".skcapstone" / "agents" / agent),
+                },
+            },
+            "skcapstone": {
+                "command": "python",
+                "args": ["-m", "skcapstone.mcp_server"],
+                "env": {"SKCAPSTONE_AGENT": agent},
+            },
+        }
+    }
+
+    with open(config_file, "w") as f:
+        json.dump(config, f, indent=2)
+
+    print(f"✓ Registered with Claude Code: {config_file}")
+    return True
+
+
+def register_openclaw(agent: str, dry_run: bool = False) -> bool:
+    """Register SKMemory with OpenClaw (via plugin)."""
+    config_file = Path.home() / ".openclaw" / "openclaw.json"
+
+    if dry_run:
+        print(f"[DRY-RUN] Would update: {config_file}")
+        return True
+
+    # Read existing config
+    if config_file.exists():
+        with open(config_file, "r") as f:
+            config = json.load(f)
+    else:
+        config = {}
+
+    # Add plugins
+    config.setdefault("plugins", {})
+    config["plugins"]["skmemory"] = {
+        "enabled": True,
+        "path": str(Path.home() / "clawd" / "skcapstone-repos" / "skmemory" / "openclaw-plugin"),
+    }
+    config["plugins"]["skcapstone"] = {
+        "enabled": True,
+        "path": str(Path.home() / "clawd" / "skcapstone" / "openclaw-plugin"),
+    }
+
+    with open(config_file, "w") as f:
+        json.dump(config, f, indent=2)
+
+    print(f"✓ Registered with OpenClaw: {config_file}")
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Register SKMemory MCP servers with AI clients")
+    parser.add_argument(
+        "--env",
+        choices=["opencode", "claude", "openclaw", "all"],
+        default="all",
+        help="Target environment (default: all)",
+    )
+    parser.add_argument(
+        "--agent", default=None, help="Agent name (default: SKMEMORY_AGENT env var or 'lumina')"
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Show what would be done without making changes"
+    )
+
+    args = parser.parse_args()
+
+    agent = args.agent or get_agent_name()
+
+    print(f"Registering MCP servers for agent: {agent}")
+    if args.dry_run:
+        print("[DRY-RUN MODE - No changes will be made]")
+    print()
+
+    results = []
+
+    if args.env in ("opencode", "all"):
+        results.append(("OpenCode", register_opencode(agent, args.dry_run)))
+
+    if args.env in ("claude", "all"):
+        results.append(("Claude Code", register_claude(agent, args.dry_run)))
+
+    if args.env in ("openclaw", "all"):
+        results.append(("OpenClaw", register_openclaw(agent, args.dry_run)))
+
+    print()
+    print("=" * 50)
+    print("Registration Summary")
+    print("=" * 50)
+
+    for name, success in results:
+        status = "✓" if success else "✗"
+        print(f"{status} {name}")
+
+    if all(success for _, success in results):
+        print("\n✓ All MCP servers registered successfully!")
+        print("\nNext steps:")
+        print("  1. Restart your AI client")
+        print("  2. Verify with: skmemory show-context")
+        return 0
+    else:
+        print("\n✗ Some registrations failed")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())