kmcp 0.1.5.dev0__py3-none-any.whl

kali_mcp/monitor/sessions.py

@@ -0,0 +1,70 @@
+"""MCP client session registry for the interactive monitor.
+
+Tracks active MCP client sessions: when they connect, their last activity,
+and client information from the MCP ``initialize`` handshake. State lives
+in-memory and resets on server restart (by design).
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from kali_mcp.models import utc_now_iso
+
+
+class SessionRegistry:
+    """Thread-safe registry of active MCP client sessions."""
+
+    def __init__(self) -> None:
+        self._sessions: dict[str, dict[str, Any]] = {}
+        self._lock = threading.RLock()
+
+    def on_connect(self, session_id: str, client_info: dict[str, Any] | None = None) -> None:
+        """Record that a new MCP client session has connected."""
+        now = utc_now_iso()
+        with self._lock:
+            self._sessions[session_id] = {
+                "session_id": session_id,
+                "connected_at": now,
+                "last_activity": now,
+                "client_info": client_info or {},
+            }
+
+    def on_activity(self, session_id: str) -> None:
+        """Update the last-activity timestamp for an existing session."""
+        now = utc_now_iso()
+        with self._lock:
+            if session_id in self._sessions:
+                self._sessions[session_id]["last_activity"] = now
+
+    def on_disconnect(self, session_id: str) -> None:
+        """Remove a session from the registry (client disconnected)."""
+        with self._lock:
+            self._sessions.pop(session_id, None)
+
+    def list_sessions(self) -> list[dict[str, Any]]:
+        """Return a copy of all known sessions, newest-created first."""
+        with self._lock:
+            sessions = list(self._sessions.values())
+        sessions.sort(key=lambda s: s["connected_at"], reverse=True)
+        return sessions
+
+    def get_session(self, session_id: str) -> dict[str, Any] | None:
+        """Return a single session by ID, or None if unknown."""
+        with self._lock:
+            return self._sessions.get(session_id)
+
+    def count(self) -> int:
+        """Return the number of currently tracked sessions."""
+        with self._lock:
+            return len(self._sessions)
+
+    def clear(self) -> None:
+        """Remove all sessions (used in tests / forced reset)."""
+        with self._lock:
+            self._sessions.clear()
+
+
+# Global session registry shared by the server and the monitor module.
+session_registry = SessionRegistry()

kali_mcp/monitor/sse_client.py

@@ -0,0 +1,87 @@
+"""SSE client for the monitor TUI.
+
+Connects to ``GET /monitor/stream`` on the Kali MCP Server and yields live
+snapshots as they arrive. Slow consumers have their snapshots dropped
+(queue full) so the reader never blocks.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+import httpx
+
+
+class SseClient:
+    """Reads SSE snapshots from the monitor stream endpoint.
+
+    Usage::
+
+        client = SseClient("http://localhost:8399/monitor/stream")
+        await client.connect()
+        snapshot = await client.next_snapshot()  # blocks until next event
+    """
+
+    def __init__(self, url: str, max_queue: int = 10) -> None:
+        self.url = url
+        self._max_queue = max_queue
+        self._snapshot: dict[str, Any] | None = None
+        self._queue: asyncio.Queue[dict[str, Any] | None] = asyncio.Queue(maxsize=max_queue)
+        self._task: asyncio.Task | None = None
+        self._closed = False
+
+    async def connect(self) -> None:
+        """Connect to the SSE stream and start reading in the background."""
+        self._task = asyncio.create_task(self._read_loop())
+
+    async def _read_loop(self) -> None:
+        while not self._closed:
+            try:
+                async with httpx.AsyncClient(timeout=None) as http, http.stream(
+                    "GET", self.url
+                ) as response:
+                        response.raise_for_status()
+                        async for line in response.aiter_lines():
+                            if self._closed:
+                                return
+                            if line.startswith("data: "):
+                                try:
+                                    payload = json.loads(line[len("data: ") :])
+                                except json.JSONDecodeError:
+                                    continue
+                                self._snapshot = payload
+                                try:
+                                    self._queue.put_nowait(payload)
+                                except asyncio.QueueFull:
+                                    # Slow consumer — drop this snapshot
+                                    try:
+                                        self._queue.get_nowait()
+                                    except asyncio.QueueEmpty:
+                                        pass
+                                    self._queue.put_nowait(payload)
+            except (httpx.ConnectError, httpx.ReadError, OSError):
+                # Server went down — retry after a short pause
+                await asyncio.sleep(2.0)
+            except asyncio.CancelledError:
+                return
+
+    async def next_snapshot(self) -> dict[str, Any] | None:
+        """Wait for and return the next snapshot from the stream."""
+        item = await self._queue.get()
+        return item
+
+    def get_latest_snapshot(self) -> dict[str, Any] | None:
+        """Return the most recent snapshot without waiting."""
+        return self._snapshot
+
+    async def close(self) -> None:
+        """Close the SSE connection."""
+        self._closed = True
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass

kali_mcp/monitor/tui.py

@@ -0,0 +1,364 @@
+"""Interactive CLI/TUI for the Kali MCP monitor.
+
+Female cyberspace aesthetic — gummy amber (#FFBF00), magenta-pink (#FF69B4),
+and cyberspace cyan (#18FFFF) on a deep dark background. Built with Rich for
+rendering and a background thread for non-blocking stdin.
+
+Connects to the server's ``GET /monitor/stream`` SSE endpoint and renders a
+live dashboard with three panels:
+
+  * Connected Users — active MCP client sessions
+  * Running Jobs — active tool executions (nmap, sqlmap, etc.)
+  * Server Health — uptime, memory, request counts, tool inventory
+
+Keybindings:
+
+  * ``q`` — quit
+  * ``r`` — force a refresh of the display
+  * ``f`` — force cleanup all tracked executions (with confirmation)
+  * ``k`` — kill a specific job (prompts for request id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+import termios
+import threading
+import tty
+from typing import Any
+
+import httpx
+from rich.layout import Layout
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from kali_mcp.monitor.sse_client import SseClient
+
+# ════════════════════════════════════════════════════════════════════════════
+# Cyberspace color palette (dark-background friendly)
+# ════════════════════════════════════════════════════════════════════════════
+
+CYBERSPACE_CYAN = "#18FFFF"  # bright electric cyan — headers / primary text
+GUMMY_AMBER = "#FFBF00"  # gummy amber — highlights / values / jobs
+GUMMY_PINK = "#FF69B4"  # hot pink / magenta — alerts / actions / borders
+GUMMY_LIGHT_PINK = "#FFB6C1"  # soft pink — secondary text
+DARK_PANEL_BG = "#0a0a0f"  # near-black panel background — deep cyberspace
+
+
+def _styled_text(content: str, style: str) -> Text:
+    return Text(content, style=style)
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# Panel builders
+# ════════════════════════════════════════════════════════════════════════════
+
+
+def _sessions_panel(sessions: list[dict[str, Any]]) -> Panel:
+    table = Table(show_header=True, header_style=f"bold {GUMMY_AMBER}", expand=True)
+    table.add_column("Session ID", style=CYBERSPACE_CYAN, width=14)
+    table.add_column("Connected At", style=GUMMY_LIGHT_PINK, width=20)
+    table.add_column("Last Activity", style=GUMMY_LIGHT_PINK, width=20)
+    table.add_column("Client", style=CYBERSPACE_CYAN, width=26)
+
+    for s in sessions:
+        ci = s.get("client_info", {}) or {}
+        client_str = f"{ci.get('name', '-')}/{ci.get('version', '-')}"
+        table.add_row(
+            str(s.get("session_id", "-")),
+            str(s.get("connected_at", "-")),
+            str(s.get("last_activity", "-")),
+            client_str,
+        )
+
+    return Panel(
+        table,
+        title=_styled_text("Connected Users", f"bold {GUMMY_PINK}"),
+        border_style=GUMMY_PINK,
+        title_align="left",
+    )
+
+
+def _jobs_panel(jobs: list[dict[str, Any]]) -> Panel:
+    table = Table(show_header=True, header_style=f"bold {GUMMY_AMBER}", expand=True)
+    table.add_column("Request ID", style=CYBERSPACE_CYAN, width=14)
+    table.add_column("Tool", style=CYBERSPACE_CYAN, width=16)
+    table.add_column("Elapsed (s)", style=GUMMY_AMBER, width=12, justify="right")
+
+    for j in jobs:
+        table.add_row(
+            str(j.get("request_id", "-")),
+            str(j.get("tool", "-")),
+            f"{j.get('elapsed_seconds', 0):.1f}",
+        )
+
+    return Panel(
+        table,
+        title=_styled_text("Running Jobs", f"bold {GUMMY_PINK}"),
+        border_style=GUMMY_PINK,
+        title_align="left",
+    )
+
+
+def _health_panel(health: dict[str, Any]) -> Panel:
+    grid = Table.grid(padding=(0, 1), expand=True)
+    grid.add_column(style=CYBERSPACE_CYAN, width=24)
+    grid.add_column(style=GUMMY_LIGHT_PINK)
+
+    grid.add_row("Status:", str(health.get("status", "-")))
+    grid.add_row("Uptime:", f"{health.get('uptime_seconds', 0):.1f}s")
+    grid.add_row("Active Executions:", str(health.get("active_executions", 0)))
+    grid.add_row("Total Requests:", str(health.get("total_requests", 0)))
+    grid.add_row("Total Errors:", str(health.get("total_errors", 0)))
+    grid.add_row("Tools Registered:", str(health.get("tools_registered", 0)))
+    grid.add_row("Memory:", f"{health.get('memory_mb', 0):.1f} MB")
+
+    return Panel(
+        grid,
+        title=_styled_text("Server Health", f"bold {GUMMY_PINK}"),
+        border_style=GUMMY_PINK,
+        title_align="left",
+    )
+
+
+def build_layout(
+    snapshot: dict[str, Any] | None,
+    status_msg: str = "",
+) -> Layout:
+    """Build the full dashboard layout from a monitor snapshot."""
+    layout = Layout()
+
+    ts = snapshot.get("timestamp", "-") if snapshot else "-"
+    header_text = Text(
+        f"Kali MCP Monitor — {ts}",
+        style=f"bold {CYBERSPACE_CYAN} on {DARK_PANEL_BG}",
+    )
+    if status_msg:
+        header_text.append("  |  ", style=GUMMY_LIGHT_PINK)
+        header_text.append(status_msg, style=GUMMY_AMBER)
+    header = Panel(header_text, border_style=GUMMY_PINK, style=DARK_PANEL_BG)
+
+    layout.split(
+        Layout(header, name="top", size=3),
+        Layout(name="middle", ratio=1),
+        Layout(name="bottom", ratio=1),
+    )
+
+    layout["middle"].split_row(
+        Layout(
+            _sessions_panel(snapshot.get("sessions", []) if snapshot else []),
+            name="sessions",
+        ),
+        Layout(_jobs_panel(snapshot.get("jobs", []) if snapshot else []), name="jobs"),
+    )
+    layout["bottom"].update(_health_panel(snapshot.get("health", {}) if snapshot else {}))
+
+    return layout
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# HTTP action helpers
+# ════════════════════════════════════════════════════════════════════════════
+
+
+async def _http_post(base_url: str, payload: dict[str, Any]) -> dict[str, Any]:
+    async with httpx.AsyncClient(timeout=10.0) as http:
+        resp = await http.post(f"{base_url}/monitor/action", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# TUI
+# ════════════════════════════════════════════════════════════════════════════
+
+
+async def run(url: str) -> None:
+    """Run the interactive monitor TUI.
+
+    Parameters
+    ----------
+    url:
+        Base URL of the Kali MCP Server, e.g. ``http://127.0.0.1:8399``.
+    """
+    client = SseClient(f"{url}/monitor/stream")
+    await client.connect()
+
+    loop = asyncio.get_event_loop()
+    input_queue: asyncio.Queue[str] = asyncio.Queue()
+    fd = sys.stdin.fileno()
+
+    # Put stdin in cbreak mode: single keypresses available immediately,
+    # no Enter required, but signals (Ctrl+C) still work.
+    old_settings = None
+    try:
+        old_settings = termios.tcgetattr(fd)
+    except Exception:  # noqa: BLE001
+        old_settings = None
+    if old_settings is not None:
+        try:
+            tty.setcbreak(fd)
+        except Exception:  # noqa: BLE001
+            old_settings = None
+
+    def _read_stdin() -> None:
+        """Blocking stdin reader in a background thread."""
+        try:
+            while True:
+                ch = os.read(fd, 1)
+                if not ch:
+                    break
+                try:
+                    loop.call_soon_threadsafe(input_queue.put_nowait, ch.decode(errors="replace"))
+                except Exception:  # noqa: BLE001
+                    break
+        except OSError:
+            pass
+
+    stdin_thread = threading.Thread(target=_read_stdin, daemon=True)
+    stdin_thread.start()
+
+    snapshot = client.get_latest_snapshot() or {}
+    layout = build_layout(
+        snapshot,
+        "Press q to quit · f: force cleanup · k: kill job",
+    )
+
+    waiting_for_kill_id = False
+    kill_id_buffer = ""
+
+    try:
+        with Live(layout, refresh_per_second=4, screen=False) as live:
+            while True:
+                snapshot_task = asyncio.create_task(client.next_snapshot())
+                input_task = asyncio.create_task(input_queue.get())
+
+                done, pending = await asyncio.wait(
+                    [snapshot_task, input_task],
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+                for task in pending:
+                    task.cancel()
+
+                result = done.pop().result()
+
+                # ── New snapshot from SSE ──────────────────────────────
+                if isinstance(result, dict):
+                    snapshot = result
+                    layout = build_layout(
+                        snapshot,
+                        "Press q to quit · f: force cleanup · k: kill job",
+                    )
+                    live.update(layout, refresh=True)
+                    continue
+
+                # ── User input (single keypress in cbreak mode) ────────
+                key = result
+
+                # Ctrl+C → quit
+                if key == "\x03":
+                    break
+
+                if waiting_for_kill_id:
+                    # Enter → submit the request id
+                    if key in ("\r", "\n"):
+                        req_id = kill_id_buffer.strip()
+                        if req_id:
+                            try:
+                                res = await _http_post(
+                                    f"{url}/monitor/action",
+                                    {"action": "kill_job", "request_id": req_id},
+                                )
+                                status_msg = (
+                                    f"kill_job {req_id}: "
+                                    f"{'killed' if res.get('killed') else 'not found'}"
+                                )
+                            except Exception as exc:  # noqa: BLE001
+                                status_msg = f"kill_job {req_id}: error — {exc}"
+                        else:
+                            status_msg = "kill_job cancelled (no id)"
+                        waiting_for_kill_id = False
+                        kill_id_buffer = ""
+                        layout = build_layout(snapshot, status_msg)
+                        live.update(layout, refresh=True)
+                    # Backspace / delete → remove last char
+                    elif key in ("\x7f", "\x08"):
+                        kill_id_buffer = kill_id_buffer[:-1]
+                        layout = build_layout(
+                            snapshot,
+                            f"Enter request id to kill: {kill_id_buffer}_",
+                        )
+                        live.update(layout, refresh=True)
+                    # Printable char → accumulate (digits only, it's a PID)
+                    elif len(key) == 1 and key.isdigit():
+                        kill_id_buffer += key
+                        layout = build_layout(
+                            snapshot,
+                            f"Enter request id to kill: {kill_id_buffer}_",
+                        )
+                        live.update(layout, refresh=True)
+                    # Escape → cancel back to normal mode
+                    elif key == "\x1b":
+                        waiting_for_kill_id = False
+                        kill_id_buffer = ""
+                        layout = build_layout(
+                            snapshot,
+                            "Press q to quit · f: force cleanup · k: kill job",
+                        )
+                        live.update(layout, refresh=True)
+                    # 'q' while waiting → quit anyway
+                    elif key == "q":
+                        break
+                    continue
+
+                # Normal mode keybindings
+                if key == "q":
+                    break
+
+                elif key == "r":
+                    latest = client.get_latest_snapshot() or {}
+                    layout = build_layout(
+                        latest, "Press q to quit · f: force cleanup · k: kill job"
+                    )
+                    live.update(layout, refresh=True)
+
+                elif key == "f":
+                    try:
+                        res = await _http_post(f"{url}/monitor/action", {"action": "force_cleanup"})
+                        status_msg = f"force_cleanup: {res.get('cleaned', 0)} cleaned"
+                    except Exception as exc:  # noqa: BLE001
+                        status_msg = f"force_cleanup: error — {exc}"
+                    layout = build_layout(snapshot, status_msg)
+                    live.update(layout, refresh=True)
+
+                elif key == "k":
+                    waiting_for_kill_id = True
+                    kill_id_buffer = ""
+                    layout = build_layout(
+                        snapshot,
+                        "Enter request id to kill: ",
+                    )
+                    live.update(layout, refresh=True)
+
+    except (KeyboardInterrupt, EOFError):
+        # Ctrl+C or Ctrl+D — exit gracefully without traceback noise
+        pass
+    finally:
+        if old_settings is not None:
+            try:
+                termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+            except Exception:  # noqa: BLE001, S110
+                pass
+        # Clear the screen on exit so the TUI doesn't leave artifacts
+        sys.stdout.write("\x1b[2J\x1b[H")
+        sys.stdout.flush()
+        await client.close()
+
+
+def main(url: str = "http://127.0.0.1:8399") -> None:
+    """Entry point for ``python -m kali_mcp monitor``."""
+    asyncio.run(run(url))

kali_mcp/notifications.py

@@ -0,0 +1,130 @@
+"""MCP server→client notification helpers.
+All helpers are best-effort: if the Context (or its active session) is not
+available the call is a safe no-op. For a local single-user server this is
+enough — notifications are emitted on the request's active session.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mcp.server.fastmcp.server import Context
+
+logger = logging.getLogger("kali_mcp.notifications")
+
+
+def _session(ctx: Any) -> Any:
+    """Return the active MCP ServerSession from a Context, or None."""
+    try:
+        if ctx is None:
+            return None
+        session = getattr(ctx, "session", None)
+        if session is None:
+            request_context = getattr(ctx, "request_context", None)
+            session = getattr(request_context, "session", None) if request_context else None
+        if session is None:
+            return None
+        if not hasattr(session, "send_notification"):
+            return None
+        return session
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _emit(session: Any, coro: Any) -> None:
+    """Schedule a notification coroutine fire-and-forget on the loop."""
+    try:
+        task = asyncio.create_task(coro)
+        task.add_done_callback(_swallow_task_error)
+    except RuntimeError:
+        # No running loop (e.g. context teardown) — run it synchronously.
+        try:
+            asyncio.run(coro)
+        except Exception:
+            logger.debug("notification failed (session closing?)", exc_info=True)
+
+
+def _swallow_task_error(task: asyncio.Task) -> None:
+    if task.cancelled():
+        return
+    exc = task.exception()
+    if exc is not None:
+        logger.debug("notification failed (session closing?)", exc_info=exc)
+
+
+def notify_resource_updated(ctx: Context | None, uri: str) -> None:
+    """Notify the client that a resource changed."""
+    session = _session(ctx)
+    if session is None:
+        return
+    try:
+        send = getattr(session, "send_resource_updated", None)
+        if send is not None:
+            from pydantic.networks import AnyUrl
+
+            _emit(session, send(AnyUrl(uri)))
+            return
+        from mcp.types import (
+            ResourceUpdatedNotification,
+            ResourceUpdatedNotificationParams,
+        )
+        from pydantic.networks import AnyUrl
+
+        notification = ResourceUpdatedNotification(
+            params=ResourceUpdatedNotificationParams(uri=AnyUrl(uri))
+        )
+        _emit(session, session.send_notification(notification))
+    except Exception:
+        logger.debug("resource-updated notification failed", exc_info=True)
+
+
+def notify_resources_changed(ctx: Context | None) -> None:
+    """Notify the client that the resource list changed."""
+    session = _session(ctx)
+    if session is None:
+        return
+    try:
+        from mcp.types import ResourceListChangedNotification, ServerNotification
+
+        _emit(
+            session,
+            session.send_notification(ServerNotification(ResourceListChangedNotification())),
+        )
+    except Exception:
+        logger.debug("resources-changed notification failed", exc_info=True)
+
+
+def notify_tools_changed(ctx: Context | None) -> None:
+    """Notify the client that the tool list changed."""
+    session = _session(ctx)
+    if session is None:
+        return
+    try:
+        _emit(session, session.send_tool_list_changed())
+    except Exception:
+        logger.debug("tool-list-changed notification failed", exc_info=True)
+
+
+def notify_prompts_changed(ctx: Context | None) -> None:
+    """Notify the client that the prompt list changed."""
+    session = _session(ctx)
+    if session is None:
+        return
+    try:
+        _emit(session, session.send_prompt_list_changed())
+    except Exception:
+        logger.debug("prompt-list-changed notification failed", exc_info=True)
+
+
+def emit_log(ctx: Context | None, level: str, message: str) -> None:
+    """Emit an MCP protocol-level log message on the session."""
+    session = _session(ctx)
+    if session is None:
+        return
+    try:
+        _emit(session, session.send_log_message(level, message, logger="kali_mcp"))
+    except Exception:
+        logger.debug("log-message notification failed", exc_info=True)