@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/mcp_tools/__init__.py

@@ -0,0 +1,94 @@
+"""MCP tool group modules — split from mcp_server.py for maintainability.
+
+Each module exposes:
+    TOOLS:    list[Tool]   — MCP tool definitions
+    HANDLERS: dict         — {tool_name: async_handler_fn}
+
+The ``collect_all_tools`` and ``collect_all_handlers`` functions aggregate
+across every module so mcp_server.py can register them in one shot.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Coroutine
+
+from mcp.types import TextContent, Tool
+
+from . import (
+    agent_tools,
+    ansible_tools,
+    chat_tools,
+    comm_tools,
+    consciousness_tools,
+    coord_tools,
+    deploy_tools,
+    did_tools,
+    emotion_tools,
+    file_tools,
+    fortress_tools,
+    gtd_tools,
+    health_tools,
+    heartbeat_tools,
+    kms_tools,
+    memory_tools,
+    model_tools,
+    notification_tools,
+    promoter_tools,
+    pubsub_tools,
+    skills_tools,
+    skseed_tools,
+    skstacks_tools,
+    soul_tools,
+    sync_tools,
+    telegram_tools,
+    trust_tools,
+    trustee_tools,
+)
+
+# Ordered list of all tool-group modules.
+_MODULES = [
+    agent_tools,
+    memory_tools,
+    comm_tools,
+    sync_tools,
+    coord_tools,
+    ansible_tools,
+    soul_tools,
+    did_tools,
+    trust_tools,
+    skills_tools,
+    chat_tools,
+    trustee_tools,
+    health_tools,
+    heartbeat_tools,
+    file_tools,
+    gtd_tools,
+    pubsub_tools,
+    fortress_tools,
+    promoter_tools,
+    kms_tools,
+    skseed_tools,
+    skstacks_tools,
+    deploy_tools,
+    model_tools,
+    consciousness_tools,
+    emotion_tools,
+    notification_tools,
+    telegram_tools,
+]
+
+
+def collect_all_tools() -> list[Tool]:
+    """Return every Tool definition from all group modules."""
+    tools: list[Tool] = []
+    for mod in _MODULES:
+        tools.extend(mod.TOOLS)
+    return tools
+
+
+def collect_all_handlers() -> dict[str, Callable[..., Coroutine[Any, Any, list[TextContent]]]]:
+    """Return a merged {name: handler} dict from all group modules."""
+    handlers: dict[str, Callable[..., Coroutine[Any, Any, list[TextContent]]]] = {}
+    for mod in _MODULES:
+        handlers.update(mod.HANDLERS)
+    return handlers

package/src/skcapstone/mcp_tools/_helpers.py

@@ -0,0 +1,51 @@
+"""Shared helpers for MCP tool modules."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from mcp.types import TextContent
+
+from .. import AGENT_HOME, SHARED_ROOT
+
+logger = logging.getLogger("skcapstone.mcp")
+
+
+def _home() -> Path:
+    """Resolve the per-agent home directory."""
+    return Path(AGENT_HOME).expanduser()
+
+
+def _shared_root() -> Path:
+    """Resolve the shared agent root (coordination, heartbeats, peers)."""
+    return Path(SHARED_ROOT).expanduser()
+
+
+def _json_response(data: Any) -> list[TextContent]:
+    """Wrap data as a JSON text content response."""
+    return [TextContent(type="text", text=json.dumps(data, indent=2, default=str))]
+
+
+def _text_response(text: str) -> list[TextContent]:
+    """Wrap a plain string as a text content response."""
+    return [TextContent(type="text", text=text)]
+
+
+def _error_response(message: str) -> list[TextContent]:
+    """Return an error message as text content."""
+    return [TextContent(type="text", text=json.dumps({"error": message}))]
+
+
+def _get_agent_name(home: Path) -> str:
+    """Read the agent name from identity file."""
+    identity_path = home / "identity" / "identity.json"
+    if identity_path.exists():
+        try:
+            data = json.loads(identity_path.read_text(encoding="utf-8"))
+            return data.get("name", "anonymous")
+        except Exception:
+            pass
+    return "anonymous"

package/src/skcapstone/mcp_tools/agent_tools.py

@@ -0,0 +1,243 @@
+"""Agent status, context, state diff, and session capture tools."""
+
+from __future__ import annotations
+
+import json
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _error_response, _home, _json_response, _text_response
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="agent_status",
+        description=(
+            "Get the sovereign agent's current state: pillar statuses "
+            "(identity, memory, trust, security, sync), consciousness "
+            "level, connected platforms, and overall health."
+        ),
+        inputSchema={"type": "object", "properties": {}, "required": []},
+    ),
+    Tool(
+        name="session_capture",
+        description=(
+            "Capture AI conversation content as sovereign memories. "
+            "Extracts key moments, auto-scores importance by topic "
+            "novelty and information density, deduplicates against "
+            "existing memories, and stores as tagged, searchable "
+            "memories. The agent never forgets a conversation."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "content": {
+                    "type": "string",
+                    "description": "Conversation text to capture (any length)",
+                },
+                "tags": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Extra tags to apply to all captured memories",
+                },
+                "source": {
+                    "type": "string",
+                    "description": "Source identifier (default: 'mcp-session')",
+                },
+                "min_importance": {
+                    "type": "number",
+                    "description": "Minimum importance threshold (default: 0.3)",
+                },
+            },
+            "required": ["content"],
+        },
+    ),
+    Tool(
+        name="state_diff",
+        description=(
+            "Show what changed since the last sync/snapshot. "
+            "Compares current agent state to the baseline: new "
+            "memories, trust changes, completed tasks, pillar "
+            "status changes. Use action='save' to set a new baseline."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": ["diff", "save"],
+                    "description": "Action: diff (compare) or save (new baseline). Default: diff.",
+                },
+            },
+            "required": [],
+        },
+    ),
+    Tool(
+        name="agent_context",
+        description=(
+            "Get the full agent context: identity, pillar status, "
+            "coordination board, recent memories, soul overlay, and "
+            "MCP status. Returns everything an AI needs to understand "
+            "the sovereign agent's current state. Supports text, JSON, "
+            "and claude-md output formats."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "format": {
+                    "type": "string",
+                    "enum": ["text", "json", "claude-md", "cursor-rules"],
+                    "description": "Output format (default: json)",
+                },
+                "memories": {
+                    "type": "integer",
+                    "description": "Max recent memories to include (default: 10)",
+                },
+            },
+            "required": [],
+        },
+    ),
+]
+
+
+def _get_memory_backend_health() -> dict:
+    """Get health status of all memory backends (sqlite, skvector, skgraph)."""
+    try:
+        from ..memory_adapter import get_unified
+
+        store = get_unified()
+        if store is None:
+            return {"json": "ok"}
+
+        health = store.health()
+        backends = {}
+        if "primary" in health:
+            backends["sqlite"] = "ok" if health["primary"].get("ok") else "error"
+        if "vector" in health:
+            backends["skvector"] = "ok" if health["vector"].get("ok") else "error"
+        if "graph" in health:
+            backends["skgraph"] = "ok" if health["graph"].get("ok") else "error"
+        return backends or {"json": "ok"}
+    except Exception:
+        return {"json": "ok"}
+
+
+async def _handle_agent_status(_args: dict) -> list[TextContent]:
+    """Return agent pillar states and consciousness level."""
+    from ..runtime import get_runtime
+
+    home = _home()
+    if not home.exists():
+        return _error_response("Agent not initialized. Run: skcapstone init")
+
+    runtime = get_runtime(home)
+    m = runtime.manifest
+    return _json_response({
+        "name": m.name,
+        "version": m.version,
+        "is_conscious": m.is_conscious,
+        "is_singular": m.is_singular,
+        "pillars": {
+            "identity": {
+                "status": m.identity.status.value,
+                "fingerprint": m.identity.fingerprint,
+            },
+            "memory": {
+                "status": m.memory.status.value,
+                "total": m.memory.total_memories,
+                "long_term": m.memory.long_term,
+                "mid_term": m.memory.mid_term,
+                "short_term": m.memory.short_term,
+                "backends": _get_memory_backend_health(),
+            },
+            "trust": {
+                "status": m.trust.status.value,
+                "depth": m.trust.depth,
+                "trust_level": m.trust.trust_level,
+                "love_intensity": m.trust.love_intensity,
+                "entangled": m.trust.entangled,
+            },
+            "security": {
+                "status": m.security.status.value,
+                "audit_entries": m.security.audit_entries,
+                "threats_detected": m.security.threats_detected,
+            },
+            "sync": {
+                "status": m.sync.status.value,
+                "seed_count": m.sync.seed_count,
+                "transport": m.sync.transport.value if m.sync.transport else None,
+            },
+        },
+        "connectors": [c.platform for c in m.connectors if c.active],
+        "last_awakened": m.last_awakened.isoformat() if m.last_awakened else None,
+    })
+
+
+async def _handle_session_capture(args: dict) -> list[TextContent]:
+    """Capture conversation content as sovereign memories."""
+    from ..session_capture import SessionCapture
+
+    content = args.get("content", "")
+    if not content:
+        return _error_response("content is required")
+
+    home = _home()
+    cap = SessionCapture(home)
+    entries = cap.capture(
+        content=content,
+        tags=args.get("tags", []),
+        source=args.get("source", "mcp-session"),
+        min_importance=args.get("min_importance", 0.3),
+    )
+
+    return _json_response({
+        "captured": len(entries),
+        "moments": [
+            {
+                "memory_id": e.memory_id,
+                "content": e.content[:200],
+                "layer": e.layer.value,
+                "importance": e.importance,
+                "tags": e.tags,
+            }
+            for e in entries
+        ],
+    })
+
+
+async def _handle_state_diff(args: dict) -> list[TextContent]:
+    """Show agent state diff or save a baseline snapshot."""
+    from ..state_diff import compute_diff, format_json, save_snapshot
+
+    home = _home()
+    action = args.get("action", "diff")
+
+    if action == "save":
+        path = save_snapshot(home)
+        return _json_response({"saved": True, "path": str(path)})
+
+    diff = compute_diff(home)
+    return _json_response(json.loads(format_json(diff)))
+
+
+async def _handle_agent_context(args: dict) -> list[TextContent]:
+    """Return the full agent context in the requested format."""
+    from ..context_loader import FORMATTERS, gather_context
+
+    home = _home()
+    fmt = args.get("format", "json")
+    limit = args.get("memories", 10)
+
+    ctx = gather_context(home, memory_limit=limit)
+    formatter = FORMATTERS.get(fmt, FORMATTERS["json"])
+
+    if fmt == "json":
+        return _json_response(ctx)
+    return _text_response(formatter(ctx))
+
+
+HANDLERS: dict = {
+    "agent_status": _handle_agent_status,
+    "session_capture": _handle_session_capture,
+    "state_diff": _handle_state_diff,
+    "agent_context": _handle_agent_context,
+}

package/src/skcapstone/mcp_tools/ansible_tools.py

@@ -0,0 +1,232 @@
+"""Ansible playbook runner tool — run_ansible_playbook.
+
+Streams stdout/stderr lines to the activity feed SSE queue as
+``ansible.playbook.line`` / ``ansible.playbook.stderr`` events.
+Stores the exit code and play-recap summary in agent memory with
+``tag=ansible-run``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import shutil
+import uuid
+from pathlib import Path
+
+from mcp.types import TextContent, Tool
+
+from ._helpers import _error_response, _home, _json_response
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="run_ansible_playbook",
+        description=(
+            "Run an Ansible playbook via ansible-playbook subprocess. "
+            "Streams stdout lines to the activity feed SSE queue as "
+            "ansible.playbook.line events (stderr lines as "
+            "ansible.playbook.stderr). Stores exit code and play-recap "
+            "summary in agent memory with tag=ansible-run. "
+            "dry_run=true adds --check (no changes applied). "
+            "Requires ansible-playbook binary in PATH."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "playbook_path": {
+                    "type": "string",
+                    "description": (
+                        "Absolute or relative path to the Ansible playbook YAML file"
+                    ),
+                },
+                "inventory": {
+                    "type": "string",
+                    "description": (
+                        "Inventory file path, directory, or comma-separated host pattern"
+                    ),
+                },
+                "extra_vars": {
+                    "type": "object",
+                    "description": (
+                        "Extra variables passed to ansible-playbook via --extra-vars "
+                        "(serialised as a JSON string)"
+                    ),
+                    "additionalProperties": True,
+                },
+                "dry_run": {
+                    "type": "boolean",
+                    "description": (
+                        "If true, pass --check so ansible-playbook simulates changes "
+                        "without applying them (default: false)"
+                    ),
+                },
+            },
+            "required": ["playbook_path", "inventory"],
+        },
+    ),
+]
+
+
+# ── handler ───────────────────────────────────────────────────────────────────
+
+
+async def _handle_run_ansible_playbook(args: dict) -> list[TextContent]:
+    """Run an Ansible playbook and stream output to the activity bus."""
+    playbook_path = args.get("playbook_path", "").strip()
+    inventory = args.get("inventory", "").strip()
+    extra_vars: dict = args.get("extra_vars") or {}
+    dry_run: bool = bool(args.get("dry_run", False))
+
+    # --- input validation ---
+    if not playbook_path:
+        return _error_response("playbook_path is required")
+    if not inventory:
+        return _error_response("inventory is required")
+
+    # Require ansible-playbook binary in PATH
+    if not shutil.which("ansible-playbook"):
+        return _error_response(
+            "ansible-playbook binary not found in PATH; "
+            "install Ansible first (e.g. pip install ansible or dnf install ansible)"
+        )
+
+    playbook = Path(playbook_path).expanduser().resolve()
+    if not playbook.exists():
+        return _error_response(f"playbook not found: {playbook_path!r}")
+
+    # --- build command ---
+    cmd: list[str] = [
+        "ansible-playbook",
+        str(playbook),
+        "-i", inventory,
+    ]
+    if dry_run:
+        cmd.append("--check")
+    if extra_vars:
+        cmd.extend(["--extra-vars", json.dumps(extra_vars)])
+
+    # --- emit start event ---
+    run_id = uuid.uuid4().hex[:8]
+
+    try:
+        from .. import activity as _activity
+
+        _activity.push("ansible.playbook.start", {
+            "run_id": run_id,
+            "playbook": str(playbook),
+            "inventory": inventory,
+            "dry_run": dry_run,
+            "cmd": cmd,
+        })
+    except Exception:
+        _activity = None  # type: ignore[assignment]
+
+    # --- stream subprocess output ---
+    stdout_lines: list[str] = []
+    stderr_lines: list[str] = []
+
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        async def _drain(
+            stream: asyncio.StreamReader,
+            store: list[str],
+            event_type: str,
+        ) -> None:
+            while True:
+                raw = await stream.readline()
+                if not raw:
+                    break
+                line = raw.decode(errors="replace").rstrip("\n")
+                store.append(line)
+                try:
+                    if _activity is not None:
+                        _activity.push(event_type, {"run_id": run_id, "line": line})
+                except Exception:
+                    pass
+
+        await asyncio.gather(
+            _drain(proc.stdout, stdout_lines, "ansible.playbook.line"),
+            _drain(proc.stderr, stderr_lines, "ansible.playbook.stderr"),
+        )
+        await proc.wait()
+        exit_code: int = proc.returncode  # type: ignore[assignment]
+
+    except Exception as exc:
+        return _error_response(f"Failed to launch ansible-playbook: {exc}")
+
+    # --- build summary ---
+    success = exit_code == 0
+
+    # Extract PLAY RECAP block lines (host rows contain "ok=" or "failed=")
+    recap_lines = [
+        line for line in stdout_lines
+        if "PLAY RECAP" in line or ("ok=" in line and "changed=" in line)
+    ]
+
+    summary = {
+        "run_id": run_id,
+        "playbook": str(playbook),
+        "inventory": inventory,
+        "dry_run": dry_run,
+        "exit_code": exit_code,
+        "success": success,
+        "stdout_lines": len(stdout_lines),
+        "stderr_lines": len(stderr_lines),
+        "recap": recap_lines,
+    }
+
+    # --- emit completion event ---
+    try:
+        if _activity is not None:
+            _activity.push("ansible.playbook.done", summary)
+    except Exception:
+        pass
+
+    # --- store in memory with tag=ansible-run ---
+    try:
+        from ..memory_engine import store as _mem_store
+
+        recap_str = " | ".join(recap_lines) if recap_lines else "none"
+        _mem_store(
+            home=_home(),
+            content=(
+                f"Ansible run {'(dry-run) ' if dry_run else ''}— "
+                f"playbook: {str(playbook)!r}, inventory: {inventory!r}, "
+                f"exit_code: {exit_code}, success: {success}. "
+                f"Recap: {recap_str}"
+            ),
+            tags=["ansible-run"],
+            source="mcp:run_ansible_playbook",
+            importance=0.6 if success else 0.8,
+            metadata={
+                "run_id": run_id,
+                "playbook": str(playbook),
+                "inventory": inventory,
+                "dry_run": dry_run,
+                "exit_code": exit_code,
+                "recap": recap_lines,
+            },
+        )
+    except Exception:
+        pass  # memory failure must not block the tool response
+
+    if not success:
+        # Surface last 20 stderr lines for quick diagnosis
+        stderr_tail = stderr_lines[-20:] if len(stderr_lines) > 20 else stderr_lines
+        return _json_response({
+            **summary,
+            "stderr_tail": stderr_tail,
+            "error": f"ansible-playbook exited with code {exit_code}",
+        })
+
+    return _json_response(summary)
+
+
+HANDLERS: dict = {
+    "run_ansible_playbook": _handle_run_ansible_playbook,
+}