@smilintux/skcapstone 0.9.0 → 0.12.5

package/src/skcapstone/mcp_server.py

@@ -9,8 +9,8 @@ Tools:
     memory_store    — Save content to SKMemory
     memory_search   — Search memories by query
     memory_recall   — Recall a specific memory by ID
-    send_message    — Send a message via SKComm
-    check_inbox     — Check for new SKComm messages
+    send_message    — Send a message via SKComms
+    check_inbox     — Check for new SKComms messages
     sync_push       — Push agent state to sync mesh
     sync_pull       — Pull seeds from peers
     coord_status    — Show coordination board
@@ -55,6 +55,16 @@ Tools:
     kms_list_keys   — List all KMS keys
     kms_rotate      — Rotate a KMS key
     model_route     — Route task to optimal model tier/name
+    itil_incident_create — Create ITIL incident
+    itil_incident_update — Update incident status/severity
+    itil_incident_list   — List/filter incidents
+    itil_problem_create  — Create problem record
+    itil_problem_update  — Update problem/root cause
+    itil_change_propose  — Propose change (RFC)
+    itil_change_update   — Update change status
+    itil_cab_vote        — Submit CAB vote
+    itil_status          — ITIL dashboard
+    itil_kedb_search     — Search Known Error Database
 
 Invocation (all equivalent):
     skcapstone mcp serve                     # CLI entry point
@@ -98,33 +108,18 @@ from mcp.server import Server
 from mcp.server.stdio import stdio_server
 from mcp.types import TextContent, Tool
 
-from . import AGENT_HOME
+from .mcp_tools._helpers import (
+    _error_response,
+    _home,
+    _json_response,
+    _text_response,
+)
 
 logger = logging.getLogger("skcapstone.mcp")
 
 server = Server("skcapstone")
 
 
-def _home() -> Path:
-    """Resolve the agent home directory."""
-    return Path(AGENT_HOME).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"
@@ -132,8 +127,8 @@ def _get_agent_name(home: Path) -> str:
         try:
             data = json.loads(identity_path.read_text(encoding="utf-8"))
             return data.get("name", "anonymous")
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to read agent name from identity.json: %s", exc)
     return "anonymous"
 
 
@@ -232,7 +227,7 @@ async def list_tools() -> list[Tool]:
         Tool(
             name="send_message",
             description=(
-                "Send a message to another agent via SKComm. "
+                "Send a message to another agent via SKComms. "
                 "Routes through available transports (Syncthing, file)."
             ),
             inputSchema={
@@ -258,7 +253,7 @@ async def list_tools() -> list[Tool]:
         Tool(
             name="check_inbox",
             description=(
-                "Check for new incoming messages across all SKComm transports. "
+                "Check for new incoming messages across all SKComms transports. "
                 "Returns any unread message envelopes."
             ),
             inputSchema={"type": "object", "properties": {}, "required": []},
@@ -1633,7 +1628,7 @@ async def list_tools() -> list[Tool]:
             description=(
                 "Check ecosystem package versions against PyPI. "
                 "Shows installed vs latest for skmemory, skcapstone, capauth, "
-                "sksecurity, skcomm, skchat, cloud9-protocol."
+                "sksecurity, skcomms, skchat, cloud9."
             ),
             inputSchema={
                 "type": "object",
@@ -2358,11 +2353,11 @@ async def list_tools() -> list[Tool]:
                 "required": [],
             },
         ),
-        # ── SKComm tools ──────────────────────────────────────
+        # ── SKComms tools ──────────────────────────────────────
         Tool(
             name="comm_notify",
             description=(
-                "Send a notification message via SKComm. Routes through "
+                "Send a notification message via SKComms. Routes through "
                 "available transports (Syncthing, file, Tailscale). "
                 "Supports urgency levels for priority routing."
             ),
@@ -2393,7 +2388,7 @@ async def list_tools() -> list[Tool]:
         Tool(
             name="comm_status",
             description=(
-                "Show SKComm subsystem status: installed version, "
+                "Show SKComms subsystem status: installed version, "
                 "available transports, connection state, and recent "
                 "delivery statistics."
             ),
@@ -2470,6 +2465,213 @@ async def list_tools() -> list[Tool]:
                 "required": ["name"],
             },
         ),
+        # ── ITIL Service Management ─────────────────────────────
+        Tool(
+            name="itil_incident_create",
+            description=(
+                "Create a new ITIL incident for a service disruption. "
+                "Auto-creates a linked GTD item (next-action for sev1/sev2, inbox for sev3/sev4)."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "title": {"type": "string", "description": "Brief description of the incident"},
+                    "severity": {"type": "string", "enum": ["sev1", "sev2", "sev3", "sev4"], "description": "Severity level (default: sev3)"},
+                    "source": {"type": "string", "enum": ["service_health", "dreaming", "manual", "daemon_error", "heartbeat"], "description": "Detection source (default: manual)"},
+                    "affected_services": {"type": "array", "items": {"type": "string"}, "description": "List of affected service names"},
+                    "impact": {"type": "string", "description": "Business impact description"},
+                    "managed_by": {"type": "string", "description": "Agent responsible for managing this incident"},
+                    "tags": {"type": "array", "items": {"type": "string"}, "description": "Tags for categorization"},
+                },
+                "required": ["title"],
+            },
+        ),
+        Tool(
+            name="itil_incident_update",
+            description=(
+                "Update an incident: transition status, escalate severity, "
+                "add timeline notes, or resolve. Valid status transitions: "
+                "detected->acknowledged->investigating->resolved->closed."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "incident_id": {"type": "string", "description": "Incident ID (e.g. inc-a1b2c3d4)"},
+                    "agent": {"type": "string", "description": "Agent making the update"},
+                    "new_status": {"type": "string", "enum": ["acknowledged", "investigating", "escalated", "resolved", "closed"], "description": "New status"},
+                    "severity": {"type": "string", "enum": ["sev1", "sev2", "sev3", "sev4"], "description": "New severity"},
+                    "note": {"type": "string", "description": "Timeline note"},
+                    "resolution_summary": {"type": "string", "description": "Resolution summary (when resolving)"},
+                    "related_problem_id": {"type": "string", "description": "Link to a related problem record"},
+                },
+                "required": ["incident_id", "agent"],
+            },
+        ),
+        Tool(
+            name="itil_incident_list",
+            description="List ITIL incidents filtered by status, severity, or affected service.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "status": {"type": "string", "enum": ["detected", "acknowledged", "investigating", "escalated", "resolved", "closed"], "description": "Filter by status"},
+                    "severity": {"type": "string", "enum": ["sev1", "sev2", "sev3", "sev4"], "description": "Filter by severity"},
+                    "service": {"type": "string", "description": "Filter by affected service name"},
+                },
+                "required": [],
+            },
+        ),
+        Tool(
+            name="itil_problem_create",
+            description=(
+                "Create a new ITIL problem record to investigate root cause. "
+                "Links to related incidents and auto-creates a GTD project."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "title": {"type": "string", "description": "Problem title"},
+                    "managed_by": {"type": "string", "description": "Agent responsible for investigation"},
+                    "related_incident_ids": {"type": "array", "items": {"type": "string"}, "description": "Related incident IDs"},
+                    "workaround": {"type": "string", "description": "Known workaround if any"},
+                    "tags": {"type": "array", "items": {"type": "string"}, "description": "Tags for categorization"},
+                },
+                "required": ["title"],
+            },
+        ),
+        Tool(
+            name="itil_problem_update",
+            description=(
+                "Update a problem record: transition status, set root cause, "
+                "add workaround, optionally create a KEDB entry. "
+                "Valid transitions: identified->analyzing->known_error->resolved."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "problem_id": {"type": "string", "description": "Problem ID (e.g. prb-e5f6g7h8)"},
+                    "agent": {"type": "string", "description": "Agent making the update"},
+                    "new_status": {"type": "string", "enum": ["analyzing", "known_error", "resolved"], "description": "New status"},
+                    "root_cause": {"type": "string", "description": "Root cause description"},
+                    "workaround": {"type": "string", "description": "Workaround description"},
+                    "note": {"type": "string", "description": "Timeline note"},
+                    "create_kedb": {"type": "boolean", "description": "Create a KEDB entry from this problem"},
+                },
+                "required": ["problem_id", "agent"],
+            },
+        ),
+        Tool(
+            name="itil_change_propose",
+            description=(
+                "Propose a change (RFC). Standard changes auto-approve. "
+                "Normal changes require CAB approval. Emergency changes have a "
+                "15-min timeout before auto-approval."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "title": {"type": "string", "description": "Change title"},
+                    "change_type": {"type": "string", "enum": ["standard", "normal", "emergency"], "description": "Type of change (default: normal)"},
+                    "risk": {"type": "string", "enum": ["low", "medium", "high"], "description": "Risk level (default: medium)"},
+                    "rollback_plan": {"type": "string", "description": "How to roll back if the change fails"},
+                    "test_plan": {"type": "string", "description": "How to verify the change works"},
+                    "managed_by": {"type": "string", "description": "Agent managing the change"},
+                    "implementer": {"type": "string", "description": "Agent who will implement the change"},
+                    "related_problem_id": {"type": "string", "description": "Related problem ID if applicable"},
+                    "tags": {"type": "array", "items": {"type": "string"}, "description": "Tags for categorization"},
+                },
+                "required": ["title"],
+            },
+        ),
+        Tool(
+            name="itil_change_update",
+            description=(
+                "Update a change: transition status (implementing, deployed, "
+                "verified, failed, closed) or add timeline notes."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "change_id": {"type": "string", "description": "Change ID (e.g. chg-i1j2k3l4)"},
+                    "agent": {"type": "string", "description": "Agent making the update"},
+                    "new_status": {"type": "string", "enum": ["reviewing", "approved", "rejected", "implementing", "deployed", "verified", "failed", "closed"], "description": "New status"},
+                    "note": {"type": "string", "description": "Timeline note"},
+                },
+                "required": ["change_id", "agent"],
+            },
+        ),
+        Tool(
+            name="itil_cab_vote",
+            description=(
+                "Submit a CAB (Change Advisory Board) vote for a proposed change. "
+                "Each agent writes its own vote file (conflict-free). "
+                "A human rejection blocks the change; a human approval unblocks it."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "change_id": {"type": "string", "description": "Change ID to vote on"},
+                    "agent": {"type": "string", "description": "Voting agent name"},
+                    "decision": {"type": "string", "enum": ["approved", "rejected", "abstain"], "description": "Vote decision (default: abstain)"},
+                    "conditions": {"type": "string", "description": "Conditions for approval"},
+                },
+                "required": ["change_id", "agent"],
+            },
+        ),
+        Tool(
+            name="itil_status",
+            description=(
+                "ITIL dashboard: open incidents by severity, active problems, "
+                "pending changes, and KEDB count."
+            ),
+            inputSchema={"type": "object", "properties": {}, "required": []},
+        ),
+        Tool(
+            name="itil_kedb_search",
+            description=(
+                "Search the Known Error Database by symptoms, service name, "
+                "or keywords. Returns matching entries with workarounds."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Search query (matches title, symptoms, root cause, tags)"},
+                },
+                "required": ["query"],
+            },
+        ),
+        # Brain-First Protocol
+        Tool(
+            name="brain_first_check",
+            description=(
+                "Brain-First Protocol: consult the agent's memory before "
+                "acting on a task. Extracts keywords from the given context, "
+                "searches memory for relevant prior knowledge, and returns "
+                "any matching memories. Use this before starting new work to "
+                "avoid duplicating effort or missing prior decisions."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "context": {
+                        "type": "string",
+                        "description": (
+                            "The task description, prompt, or action context "
+                            "to search memory for"
+                        ),
+                    },
+                    "tags": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Optional tag filter for the memory search",
+                    },
+                    "max_results": {
+                        "type": "integer",
+                        "description": "Max memories to return (default: from config, usually 5)",
+                    },
+                },
+                "required": ["context"],
+            },
+        ),
     ]
 
 
@@ -2609,7 +2811,7 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
         # SKChat
         "chat_send": _handle_chat_send,
         "chat_history": _handle_chat_history,
-        # SKComm
+        # SKComms
         "comm_notify": _handle_comm_notify,
         "comm_status": _handle_comm_status,
         # CapAuth
@@ -2618,6 +2820,19 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
         # Soul Blueprint Registry
         "soul_registry_search": _handle_soul_registry_search,
         "soul_registry_publish": _handle_soul_registry_publish,
+        # ITIL Service Management
+        "itil_incident_create": _handle_itil_incident_create,
+        "itil_incident_update": _handle_itil_incident_update,
+        "itil_incident_list": _handle_itil_incident_list,
+        "itil_problem_create": _handle_itil_problem_create,
+        "itil_problem_update": _handle_itil_problem_update,
+        "itil_change_propose": _handle_itil_change_propose,
+        "itil_change_update": _handle_itil_change_update,
+        "itil_cab_vote": _handle_itil_cab_vote,
+        "itil_status": _handle_itil_status,
+        "itil_kedb_search": _handle_itil_kedb_search,
+        # Brain-First Protocol
+        "brain_first_check": _handle_brain_first_check,
     }
     handler = handlers.get(name)
     if handler is None:
@@ -2647,7 +2862,8 @@ def _get_memory_backend_health() -> dict:
         if "graph" in health:
             backends["skgraph"] = "ok" if health["graph"].get("ok") else "error"
         return backends or {"json": "ok"}
-    except Exception:
+    except Exception as e:
+        logger.warning("Failed to get memory backend health: %s", e)
         return {"json": "ok"}
 
 
@@ -2778,15 +2994,15 @@ async def _handle_memory_recall(args: dict) -> list[TextContent]:
 
 
 async def _handle_send_message(args: dict) -> list[TextContent]:
-    """Send a message via SKComm."""
+    """Send a message via SKComms."""
     recipient = args.get("recipient", "")
     message = args.get("message", "")
     if not recipient or not message:
         return _error_response("recipient and message are required")
 
     try:
-        from skcomm.core import SKComm
-        comm = SKComm.from_config()
+        from skcomms.core import SKComms
+        comm = SKComms.from_config()
         report = comm.send(recipient, message)
         return _json_response({
             "sent": report.success,
@@ -2801,7 +3017,7 @@ async def _handle_send_message(args: dict) -> list[TextContent]:
             ],
         })
     except ImportError:
-        return _error_response("SKComm not installed. Run: pip install skcomm")
+        return _error_response("SKComms not installed. Run: pip install skcomms")
     except Exception as exc:
         return _error_response(f"Send failed: {exc}")
 
@@ -2809,8 +3025,8 @@ async def _handle_send_message(args: dict) -> list[TextContent]:
 async def _handle_check_inbox(_args: dict) -> list[TextContent]:
     """Check for incoming messages."""
     try:
-        from skcomm.core import SKComm
-        comm = SKComm.from_config()
+        from skcomms.core import SKComms
+        comm = SKComms.from_config()
         envelopes = comm.receive()
         return _json_response([
             {
@@ -2826,7 +3042,7 @@ async def _handle_check_inbox(_args: dict) -> list[TextContent]:
             for e in envelopes
         ])
     except ImportError:
-        return _error_response("SKComm not installed. Run: pip install skcomm")
+        return _error_response("SKComms not installed. Run: pip install skcomms")
     except Exception as exc:
         return _error_response(f"Inbox check failed: {exc}")
 
@@ -2959,8 +3175,8 @@ async def _handle_coord_complete(args: dict) -> list[TextContent]:
                     t.priority.value, ("community", "support_ticket", 50)
                 )
                 break
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to calculate joules for completed task %s: %s", task_id, exc)
 
     return _json_response({
         "completed": True,
@@ -3015,6 +3231,8 @@ async def _handle_ritual(_args: dict) -> list[TextContent]:
             "journal_entries": result.journal_entries,
             "germination_prompts": result.germination_prompts,
             "strongest_memories": result.strongest_memories,
+            "song_anchors_loaded": result.song_anchors_loaded,
+            "song_anchor_ids": result.song_anchor_ids,
             "context_prompt": result.context_prompt,
         })
     except ImportError:
@@ -3394,7 +3612,8 @@ def _get_skchat_identity() -> str:
         home = _home()
         runtime = get_runtime(home)
         return f"capauth:{runtime.manifest.name}@local"
-    except Exception:
+    except Exception as e:
+        logger.warning("Failed to resolve sovereign identity: %s", e)
         return "capauth:agent@local"
 
 
@@ -3411,7 +3630,8 @@ def _resolve_recipient(name: str) -> str:
     try:
         from skchat.identity_bridge import resolve_peer_name
         return resolve_peer_name(name)
-    except Exception:
+    except Exception as e:
+        logger.warning("Failed to resolve peer name %r: %s", name, e)
         return f"capauth:{name}@local"
 
 
@@ -4598,18 +4818,18 @@ async def _handle_chat_history(args: dict) -> list[TextContent]:
     return await _impl(args)
 
 
-# ── SKComm tools ──────────────────────────────────────────
+# ── SKComms tools ──────────────────────────────────────────
 
 
 async def _handle_comm_notify(args: dict) -> list[TextContent]:
-    """Send a notification via SKComm."""
-    from .mcp_tools.skcomm_tools import _handle_comm_notify as _impl
+    """Send a notification via SKComms."""
+    from .mcp_tools.skcomms_tools import _handle_comm_notify as _impl
     return await _impl(args)
 
 
 async def _handle_comm_status(args: dict) -> list[TextContent]:
-    """Show SKComm subsystem status."""
-    from .mcp_tools.skcomm_tools import _handle_comm_status as _impl
+    """Show SKComms subsystem status."""
+    from .mcp_tools.skcomms_tools import _handle_comm_status as _impl
     return await _impl(args)
 
 
@@ -4679,6 +4899,78 @@ async def _handle_soul_registry_publish(args: dict) -> list[TextContent]:
         return _error_response(f"Registry publish failed: {exc}")
 
 
+# ── ITIL handlers ─────────────────────────────────────────
+
+
+async def _handle_itil_incident_create(args: dict) -> list[TextContent]:
+    """Create a new ITIL incident."""
+    from .mcp_tools.itil_tools import _handle_itil_incident_create as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_incident_update(args: dict) -> list[TextContent]:
+    """Update an ITIL incident."""
+    from .mcp_tools.itil_tools import _handle_itil_incident_update as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_incident_list(args: dict) -> list[TextContent]:
+    """List ITIL incidents."""
+    from .mcp_tools.itil_tools import _handle_itil_incident_list as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_problem_create(args: dict) -> list[TextContent]:
+    """Create a new ITIL problem."""
+    from .mcp_tools.itil_tools import _handle_itil_problem_create as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_problem_update(args: dict) -> list[TextContent]:
+    """Update an ITIL problem."""
+    from .mcp_tools.itil_tools import _handle_itil_problem_update as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_change_propose(args: dict) -> list[TextContent]:
+    """Propose a change (RFC)."""
+    from .mcp_tools.itil_tools import _handle_itil_change_propose as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_change_update(args: dict) -> list[TextContent]:
+    """Update a change status."""
+    from .mcp_tools.itil_tools import _handle_itil_change_update as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_cab_vote(args: dict) -> list[TextContent]:
+    """Submit a CAB vote."""
+    from .mcp_tools.itil_tools import _handle_itil_cab_vote as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_status(args: dict) -> list[TextContent]:
+    """ITIL dashboard status."""
+    from .mcp_tools.itil_tools import _handle_itil_status as _impl
+    return await _impl(args)
+
+
+async def _handle_itil_kedb_search(args: dict) -> list[TextContent]:
+    """Search the Known Error Database."""
+    from .mcp_tools.itil_tools import _handle_itil_kedb_search as _impl
+    return await _impl(args)
+
+
+# ── Brain-First Protocol ──────────────────────────────────
+
+
+async def _handle_brain_first_check(args: dict) -> list[TextContent]:
+    """Consult memory before acting on a task."""
+    from .mcp_tools.brain_first_tools import _handle_brain_first_check as _impl
+    return await _impl(args)
+
+
 # ═══════════════════════════════════════════════════════════
 # Entry Point
 # ═══════════════════════════════════════════════════════════

package/src/skcapstone/mcp_tools/__init__.py

@@ -17,6 +17,7 @@ from mcp.types import TextContent, Tool
 from . import (
     agent_tools,
     ansible_tools,
+    brain_first_tools,
     chat_tools,
     comm_tools,
     consciousness_tools,
@@ -49,6 +50,7 @@ from . import (
 # Ordered list of all tool-group modules.
 _MODULES = [
     agent_tools,
+    brain_first_tools,
     memory_tools,
     comm_tools,
     sync_tools,

package/src/skcapstone/mcp_tools/_helpers.py

@@ -46,6 +46,6 @@ def _get_agent_name(home: Path) -> str:
         try:
             data = json.loads(identity_path.read_text(encoding="utf-8"))
             return data.get("name", "anonymous")
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to read agent name from identity.json: %s", exc)
     return "anonymous"

package/src/skcapstone/mcp_tools/ansible_tools.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import logging
 import shutil
 import uuid
 from pathlib import Path
@@ -18,6 +19,8 @@ from mcp.types import TextContent, Tool
 
 from ._helpers import _error_response, _home, _json_response
 
+logger = logging.getLogger(__name__)
+
 TOOLS: list[Tool] = [
     Tool(
         name="run_ansible_playbook",
@@ -146,8 +149,8 @@ async def _handle_run_ansible_playbook(args: dict) -> list[TextContent]:
                 try:
                     if _activity is not None:
                         _activity.push(event_type, {"run_id": run_id, "line": line})
-                except Exception:
-                    pass
+                except Exception as exc:
+                    logger.warning("Failed to push ansible line event for run %s: %s", run_id, exc)
 
         await asyncio.gather(
             _drain(proc.stdout, stdout_lines, "ansible.playbook.line"),
@@ -184,8 +187,8 @@ async def _handle_run_ansible_playbook(args: dict) -> list[TextContent]:
     try:
         if _activity is not None:
             _activity.push("ansible.playbook.done", summary)
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to push ansible.playbook.done event for run %s: %s", run_id, exc)
 
     # --- store in memory with tag=ansible-run ---
     try: