maverick-mcp-server 0.1.2__tar.gz

maverick_mcp_server-0.1.2/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: maverick-mcp-server
+Version: 0.1.2
+Summary: Model Context Protocol server for Maverick (exposes the swarm to MCP clients)
+Author: cdayAI
+License: MIT
+Project-URL: Homepage, https://github.com/cdayAI/maverick
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: maverick-agent>=0.1
+
+# maverick-mcp-server
+
+A Model Context Protocol (MCP) server that exposes Maverick's agent
+loop as a set of MCP tools. Any MCP-compatible client (Claude Code,
+Claude Desktop, Cursor, etc.) can drive Maverick over stdio JSON-RPC.
+
+## Why
+
+Maverick is a swarm of agents with persistent memory, budget caps,
+and verifier loops. Most MCP clients are single-turn. By plugging
+Maverick in via MCP, you get:
+
+- A "think hard for an hour" tool from inside Claude Code
+- Persistent goals that survive editor restarts
+- Per-role model routing controlled by your `~/.maverick/config.toml`
+- Auto-distilled skills that compound across sessions
+
+## Install
+
+```bash
+pip install -e ./packages/maverick-mcp
+```
+
+## Wire into Claude Code
+
+Add to your Claude Code MCP config (typically
+`~/.config/claude-code/mcp.json` or similar):
+
+```json
+{
+  "mcpServers": {
+    "maverick": {
+      "command": "maverick-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Then restart Claude Code. The Maverick tools should appear under the
+MCP servers menu.
+
+## Tools exposed
+
+| Tool | What it does |
+|---|---|
+| `maverick_start` | Start a new goal, run the swarm, return the final answer |
+| `maverick_status` | List recent goals + open questions |
+| `maverick_resume` | Resume a paused goal |
+| `maverick_answer` | Answer a queued question |
+| `maverick_skill_install` | Install a SKILL.md from URL / gh:org/repo / local path |
+| `maverick_skills_list` | List installed / distilled skills |
+| `maverick_fact_set` | Set a fact in the world model |
+| `maverick_facts_get` | Get all known facts |
+
+All calls go through `maverick.orchestrator.run_goal` -- same Shield
+chokepoints, same budget caps, same per-role model routing.
+
+## Protocol
+
+Minimal JSON-RPC 2.0 over stdio, matching the MCP 2024-11-05 spec
+(`initialize`, `tools/list`, `tools/call`). No external dependencies.
+The full `mcp` Python SDK is an option for a future hardening pass;
+this hand-rolled version keeps the dependency footprint tiny.

maverick_mcp_server-0.1.2/README.md

@@ -0,0 +1,64 @@
+# maverick-mcp-server
+
+A Model Context Protocol (MCP) server that exposes Maverick's agent
+loop as a set of MCP tools. Any MCP-compatible client (Claude Code,
+Claude Desktop, Cursor, etc.) can drive Maverick over stdio JSON-RPC.
+
+## Why
+
+Maverick is a swarm of agents with persistent memory, budget caps,
+and verifier loops. Most MCP clients are single-turn. By plugging
+Maverick in via MCP, you get:
+
+- A "think hard for an hour" tool from inside Claude Code
+- Persistent goals that survive editor restarts
+- Per-role model routing controlled by your `~/.maverick/config.toml`
+- Auto-distilled skills that compound across sessions
+
+## Install
+
+```bash
+pip install -e ./packages/maverick-mcp
+```
+
+## Wire into Claude Code
+
+Add to your Claude Code MCP config (typically
+`~/.config/claude-code/mcp.json` or similar):
+
+```json
+{
+  "mcpServers": {
+    "maverick": {
+      "command": "maverick-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Then restart Claude Code. The Maverick tools should appear under the
+MCP servers menu.
+
+## Tools exposed
+
+| Tool | What it does |
+|---|---|
+| `maverick_start` | Start a new goal, run the swarm, return the final answer |
+| `maverick_status` | List recent goals + open questions |
+| `maverick_resume` | Resume a paused goal |
+| `maverick_answer` | Answer a queued question |
+| `maverick_skill_install` | Install a SKILL.md from URL / gh:org/repo / local path |
+| `maverick_skills_list` | List installed / distilled skills |
+| `maverick_fact_set` | Set a fact in the world model |
+| `maverick_facts_get` | Get all known facts |
+
+All calls go through `maverick.orchestrator.run_goal` -- same Shield
+chokepoints, same budget caps, same per-role model routing.
+
+## Protocol
+
+Minimal JSON-RPC 2.0 over stdio, matching the MCP 2024-11-05 spec
+(`initialize`, `tools/list`, `tools/call`). No external dependencies.
+The full `mcp` Python SDK is an option for a future hardening pass;
+this hand-rolled version keeps the dependency footprint tiny.

maverick_mcp_server-0.1.2/maverick_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for Maverick."""
+
+__version__ = "0.1.2"

maverick_mcp_server-0.1.2/maverick_mcp/http_transport.py

@@ -0,0 +1,164 @@
+"""Streamable HTTP transport for Maverick's MCP server (spec 2025-11-25).
+
+The stdio JSON-RPC transport in `server.py` works great for desktop
+clients (Claude Desktop, Cursor) that spawn Maverick as a subprocess.
+For hosted Maverick — VPS deployments, multi-tenant setups, MCP
+gateways like Composio / MintMCP / Cloudflare — clients need an HTTP
+endpoint.
+
+This module ships the Streamable HTTP transport per MCP 2025-11-25:
+single POST endpoint that accepts JSON-RPC requests and returns
+JSON-RPC responses, with optional Server-Sent Events for streaming
+results (long-running tools, sampling).
+
+Usage::
+
+    maverick mcp --http --port 8771 --token $MAVERICK_MCP_TOKEN
+
+Security:
+  - Bearer-token auth required when MAVERICK_MCP_TOKEN is set.
+  - Per the 2025-11-25 spec, server runs as an OAuth resource server;
+    full OAuth flow is a v0.3 follow-up. Bearer is the simpler path
+    that works today.
+  - All requests are routed through the same MCPServer.handle_*
+    dispatch as stdio, so the security audit you do on the stdio
+    side covers HTTP too.
+
+Spec deprecation note: the older SSE-only transport is EOL mid-2026
+across major clients; we ship Streamable HTTP as the GA transport.
+"""
+from __future__ import annotations
+
+import hmac
+import logging
+import os
+from typing import Optional
+
+
+log = logging.getLogger(__name__)
+
+
+try:
+    from fastapi import FastAPI, Header, HTTPException, Request
+    from fastapi.responses import JSONResponse, StreamingResponse
+    _HAVE_FASTAPI = True
+except ImportError:
+    _HAVE_FASTAPI = False
+    FastAPI = Header = HTTPException = Request = None  # type: ignore
+    JSONResponse = StreamingResponse = None  # type: ignore
+
+
+def _check_bearer(authorization: Optional[str]) -> bool:
+    """Bearer-token gate for network HTTP transport.
+
+    Unlike stdio, HTTP requests are network-reachable; token auth is
+    therefore mandatory and a missing MAVERICK_MCP_TOKEN rejects all
+    requests.
+    """
+    expected = os.environ.get("MAVERICK_MCP_TOKEN")
+    if not expected:
+        return False
+    if not authorization or not authorization.startswith("Bearer "):
+        return False
+    given = authorization[len("Bearer "):].strip()
+    return hmac.compare_digest(expected, given)
+
+
+def build_app(server) -> "FastAPI":
+    """Wrap an MCPServer instance in a Streamable HTTP transport.
+
+    `server` is an instance of `maverick_mcp.server.MCPServer`. We
+    reuse its handle_* methods 1:1; this module is just the transport.
+    """
+    if not _HAVE_FASTAPI:
+        raise ImportError(
+            "fastapi not installed; install maverick-mcp-server[http] to enable "
+            "the streamable HTTP transport"
+        )
+
+    app = FastAPI(
+        title="Maverick MCP HTTP",
+        description=(
+            "MCP 2025-11-25 streamable HTTP transport. POST a JSON-RPC "
+            "request; receive a JSON-RPC response or an SSE stream."
+        ),
+        version="0.2.0",
+    )
+
+    @app.post("/mcp")
+    async def mcp_endpoint(
+        request: "Request",
+        authorization: Optional[str] = Header(None),
+    ):
+        if not _check_bearer(authorization):
+            raise HTTPException(status_code=401, detail="invalid bearer")
+        body = await request.json()
+        is_notification = "id" not in body
+        request_id = body.get("id")
+        method = body.get("method", "")
+        params = body.get("params", {}) or {}
+
+        # Route via the existing MCPServer dispatcher. We piggyback on
+        # its method table by calling the appropriate handle_* directly.
+        try:
+            result = _dispatch(server, method, params)
+        except Exception as e:
+            from .server import _ProtocolError
+            if isinstance(e, _ProtocolError):
+                code, message = e.code, e.message
+            else:
+                code, message = -32603, f"internal error: {e}"
+            if is_notification:
+                return JSONResponse({}, status_code=204)
+            return JSONResponse({
+                "jsonrpc": "2.0", "id": request_id,
+                "error": {"code": code, "message": message},
+            })
+
+        if is_notification:
+            return JSONResponse({}, status_code=204)
+        return JSONResponse({
+            "jsonrpc": "2.0", "id": request_id, "result": result,
+        })
+
+    @app.get("/healthz")
+    async def healthz():
+        return {"status": "ok", "transport": "http"}
+
+    return app
+
+
+_METHOD_MAP = {
+    "initialize":      "handle_initialize",
+    "tools/list":      "handle_tools_list",
+    "tools/call":      "handle_tools_call",
+    "resources/list":  "handle_resources_list",
+    "resources/read":  "handle_resources_read",
+    "prompts/list":    "handle_prompts_list",
+    "prompts/get":     "handle_prompts_get",
+}
+
+
+def _dispatch(server, method: str, params: dict) -> dict:
+    """Route a JSON-RPC method to the corresponding handle_* method."""
+    if method == "notifications/initialized":
+        return {}
+    if method == "ping":
+        return {}
+    handler_name = _METHOD_MAP.get(method)
+    if not handler_name:
+        from .server import _ProtocolError
+        raise _ProtocolError(-32601, f"method not found: {method}")
+    handler = getattr(server, handler_name)
+    return handler(params)
+
+
+def serve(host: str = "127.0.0.1", port: int = 8771) -> None:
+    """Run the HTTP transport on host:port. Blocking."""
+    import uvicorn
+    from .server import MCPServer
+
+    server = MCPServer()
+    app = build_app(server)
+    log.info("MCP Streamable HTTP transport on http://%s:%d/mcp", host, port)
+    uvicorn.run(app, host=host, port=port, log_level="info")

maverick_mcp_server-0.1.2/maverick_mcp/server.py

@@ -0,0 +1,506 @@
+"""MCP server for Maverick."""
+from __future__ import annotations
+
+import json
+import logging
+import sys
+import traceback
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+logging.basicConfig(
+    level=logging.INFO,
+    stream=sys.stderr,
+    format="%(asctime)s [%(levelname)s] mcp: %(message)s",
+)
+
+# Protocol version. MCP 2025-11-25 ships Tasks / Resources / Elicitation /
+# Sampling / MCP Apps; we negotiate down to the older spec when a client
+# advertises that, but our initialize response is on the current one.
+PROTOCOL_VERSION = "2025-11-25"
+PROTOCOL_VERSION_FALLBACK = "2024-11-05"
+SERVER_NAME = "maverick"
+SERVER_VERSION = "0.2.0"
+
+
+class _ProtocolError(Exception):
+    """Raised for JSON-RPC protocol-level errors (unknown method/tool, bad params).
+
+    The `run()` loop catches this and emits a structured JSON-RPC error
+    response (per MCP 2024-11-05 spec). Surface in tests via
+    pytest.raises -- it deliberately does NOT collapse into an isError
+    envelope because Claude Desktop / Cursor treat those differently.
+    """
+    def __init__(self, code: int, message: str):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+TOOLS: list[dict[str, Any]] = [
+    {
+        "name": "maverick_start",
+        "description": (
+            "Start a new goal in Maverick's recursive multi-agent swarm. "
+            "Returns the final answer after the swarm completes. Long-running."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "title": {"type": "string"},
+                "description": {"type": "string"},
+                "max_dollars": {"type": "number", "default": 5.0},
+                "max_wall_seconds": {"type": "number", "default": 3600},
+                "max_depth": {"type": "integer", "default": 3},
+            },
+            "required": ["title"],
+        },
+    },
+    {
+        "name": "maverick_status",
+        "description": "List recent goals and any open questions.",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "maverick_resume",
+        "description": "Resume a paused goal by id.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"goal_id": {"type": "integer"}},
+        },
+    },
+    {
+        "name": "maverick_answer",
+        "description": "Answer a queued question.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "question_id": {"type": "integer"},
+                "answer": {"type": "string"},
+            },
+            "required": ["question_id", "answer"],
+        },
+    },
+    {
+        "name": "maverick_skill_install",
+        "description": "Install a SKILL.md from a URL or gh:org/repo[:path].",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"source": {"type": "string"}},
+            "required": ["source"],
+        },
+    },
+    {
+        "name": "maverick_skills_list",
+        "description": "List installed / distilled skills.",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "maverick_fact_set",
+        "description": "Store a fact in the persistent world model.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "key": {"type": "string"},
+                "value": {"type": "string"},
+            },
+            "required": ["key", "value"],
+        },
+    },
+    {
+        "name": "maverick_facts_get",
+        "description": "Get all known facts.",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+]
+
+_TOOL_NAMES = {t["name"] for t in TOOLS}
+
+
+class MCPServer:
+    def __init__(self):
+        self._initialized = False
+        self._shield = self._build_shield()
+
+    @staticmethod
+    def _build_shield():
+        try:
+            from maverick_shield import Shield
+            return Shield.from_config()
+        except Exception:
+            return None
+
+    def handle_initialize(self, params: dict) -> dict:
+        self._initialized = True
+        # Negotiate down if the client only speaks the older spec.
+        client_ver = params.get("protocolVersion", "")
+        version = PROTOCOL_VERSION
+        if client_ver and client_ver < "2025-11-25":
+            version = PROTOCOL_VERSION_FALLBACK
+        return {
+            "protocolVersion": version,
+            "capabilities": {
+                "tools": {"listChanged": False},
+                # Resources: goals/skills/facts exposed as URI-addressable
+                # objects for clients (Claude Desktop, Cursor) that support
+                # the 2025-11-25 spec.
+                "resources": {"subscribe": False, "listChanged": False},
+                # Prompts: ship templated goal patterns so clients can
+                # surface "start a research run" / "plan a trip" without
+                # the user typing the prompt themselves.
+                "prompts": {"listChanged": False},
+                # Elicitation: server can ask the user a follow-up question
+                # (replaces our ask_user tool in 2025-11-25-aware clients).
+                # We declare it; the actual call falls back to tool-result
+                # when the client doesn't support it.
+                "elicitation": {},
+            },
+            "serverInfo": {"name": SERVER_NAME, "version": SERVER_VERSION},
+        }
+
+    def handle_tools_list(self, params: dict) -> dict:
+        return {"tools": TOOLS}
+
+    # ---- 2025-11-25 Resources -----------------------------------------
+
+    def handle_resources_list(self, params: dict) -> dict:
+        """Expose Maverick state as MCP Resources.
+
+        - maverick://goals          — list of active/recent goals
+        - maverick://skills         — installed skills
+        """
+        resources = [
+            {
+                "uri": "maverick://goals",
+                "name": "All recent goals",
+                "mimeType": "application/json",
+            },
+            {
+                "uri": "maverick://skills",
+                "name": "Installed skills",
+                "mimeType": "application/json",
+            },
+        ]
+        return {"resources": resources}
+
+    def handle_resources_read(self, params: dict) -> dict:
+        uri = params.get("uri", "")
+        if not uri.startswith("maverick://"):
+            raise _ProtocolError(-32602, f"unsupported uri scheme: {uri}")
+        path = uri[len("maverick://"):]
+        from maverick.world_model import DEFAULT_DB, WorldModel
+        wm = WorldModel(DEFAULT_DB)
+
+        if path == "goals":
+            data = [
+                {"id": g.id, "status": g.status, "title": g.title}
+                for g in wm.list_goals()[-20:]
+            ]
+        elif path == "skills":
+            try:
+                from maverick.skills import load_skills
+                data = [
+                    {"name": s.name, "triggers": s.triggers,
+                     "tools_needed": s.tools_needed}
+                    for s in load_skills()
+                ]
+            except Exception:
+                data = []
+        else:
+            raise _ProtocolError(-32602, f"unknown resource path: {uri}")
+
+        return {
+            "contents": [{
+                "uri": uri,
+                "mimeType": "application/json",
+                "text": json.dumps(data, indent=2, default=str),
+            }],
+        }
+
+    # ---- 2025-11-25 Prompts -------------------------------------------
+
+    def handle_prompts_list(self, params: dict) -> dict:
+        return {"prompts": [
+            {
+                "name": "research_topic",
+                "description": "Spawn a research swarm to investigate a topic.",
+                "arguments": [
+                    {"name": "topic", "description": "What to research",
+                     "required": True},
+                    {"name": "depth", "description": "shallow / medium / deep",
+                     "required": False},
+                ],
+            },
+            {
+                "name": "draft_message",
+                "description": "Draft an email / message in a given tone.",
+                "arguments": [
+                    {"name": "recipient", "required": True},
+                    {"name": "intent", "required": True},
+                    {"name": "tone", "required": False},
+                ],
+            },
+            {
+                "name": "compare_options",
+                "description": "Compare 2-N options against a criterion list.",
+                "arguments": [
+                    {"name": "options", "required": True},
+                    {"name": "criteria", "required": True},
+                ],
+            },
+        ]}
+
+    def handle_prompts_get(self, params: dict) -> dict:
+        name = params.get("name", "")
+        args = params.get("arguments", {}) or {}
+        templates = {
+            "research_topic": (
+                "Spawn a research swarm to investigate: {topic}. "
+                "Depth: {depth}. Verify findings before FINAL."
+            ),
+            "draft_message": (
+                "Draft a message to {recipient} with intent: {intent}. "
+                "Tone: {tone}. Keep it concise."
+            ),
+            "compare_options": (
+                "Compare these options: {options}. Use criteria: {criteria}. "
+                "Build a table; recommend one."
+            ),
+        }
+        if name not in templates:
+            raise _ProtocolError(-32602, f"unknown prompt: {name}")
+        try:
+            text = templates[name].format(**{
+                "topic": args.get("topic", ""),
+                "depth": args.get("depth", "medium"),
+                "recipient": args.get("recipient", ""),
+                "intent": args.get("intent", ""),
+                "tone": args.get("tone", "professional"),
+                "options": args.get("options", ""),
+                "criteria": args.get("criteria", ""),
+            })
+        except KeyError as e:
+            raise _ProtocolError(-32602, f"missing argument: {e}") from e
+        return {
+            "description": f"Maverick prompt: {name}",
+            "messages": [{
+                "role": "user",
+                "content": {"type": "text", "text": text},
+            }],
+        }
+
+    def handle_tools_call(self, params: dict) -> dict:
+        name = params.get("name")
+        if name not in _TOOL_NAMES:
+            raise _ProtocolError(-32602, f"unknown tool: {name!r}")
+        arguments = params.get("arguments", {}) or {}
+        tool_spec = next(t for t in TOOLS if t["name"] == name)
+        required = tool_spec.get("inputSchema", {}).get("required", []) or []
+        missing = [r for r in required if r not in arguments]
+        if missing:
+            raise _ProtocolError(-32602, f"missing required argument(s) for {name}: {missing}")
+        try:
+            result = self._dispatch_tool(name, arguments)
+        except Exception as e:
+            return {
+                "isError": True,
+                "content": [{"type": "text", "text": f"{type(e).__name__}: {e}"}],
+            }
+        if self._shield is not None:
+            verdict = self._shield.scan_output(result)
+            if not verdict.allowed:
+                return {
+                    "isError": True,
+                    "content": [{"type": "text", "text": f"⚠ Output blocked: {'; '.join(verdict.reasons)}"}],
+                }
+        return {
+            "isError": False,
+            "content": [{"type": "text", "text": result}],
+        }
+
+    def _dispatch_tool(self, name: str, args: dict) -> str:
+        if name == "maverick_start":
+            return self._tool_start(args)
+        if name == "maverick_status":
+            return self._tool_status()
+        if name == "maverick_resume":
+            return self._tool_resume(args)
+        if name == "maverick_answer":
+            return self._tool_answer(args)
+        if name == "maverick_skill_install":
+            return self._tool_skill_install(args)
+        if name == "maverick_skills_list":
+            return self._tool_skills_list()
+        if name == "maverick_fact_set":
+            return self._tool_fact_set(args)
+        if name == "maverick_facts_get":
+            return self._tool_facts_get()
+        raise _ProtocolError(-32602, f"unknown tool {name!r}")
+
+    def _tool_start(self, args: dict) -> str:
+        from maverick.budget import Budget
+        from maverick.llm import LLM
+        from maverick.orchestrator import run_goal_sync
+        from maverick.sandbox import build_sandbox
+        from maverick.world_model import WorldModel
+        title = args["title"]
+        description = args.get("description", "")
+        if self._shield is not None:
+            verdict = self._shield.scan_input(f"{title}\n{description}")
+            if not verdict.allowed:
+                return f"⚠ Blocked: {'; '.join(verdict.reasons)}"
+        budget = Budget(
+            max_dollars=float(args.get("max_dollars", 5.0)),
+            max_wall_seconds=float(args.get("max_wall_seconds", 3600)),
+        )
+        world = WorldModel()
+        goal_id = world.create_goal(title, description)
+        llm = LLM()
+        sandbox = build_sandbox()
+        return run_goal_sync(
+            llm, world, budget, goal_id, sandbox=sandbox,
+            max_depth=int(args.get("max_depth", 3)),
+        )
+
+    def _tool_status(self) -> str:
+        from maverick.world_model import WorldModel
+        w = WorldModel()
+        goals = w.list_goals()
+        if not goals:
+            return "no goals yet"
+        lines = [f"#{g.id} [{g.status}] {g.title}" for g in goals[-10:]]
+        for q in w.open_questions():
+            lines.append(f"  open question #{q.id} (goal {q.goal_id}): {q.question}")
+        return "\n".join(lines)
+
+    def _tool_resume(self, args: dict) -> str:
+        from maverick.budget import Budget
+        from maverick.llm import LLM
+        from maverick.orchestrator import run_goal_sync
+        from maverick.world_model import WorldModel
+        w = WorldModel()
+        goal_id = args.get("goal_id")
+        if goal_id is None:
+            g = w.active_goal()
+            if not g:
+                return "no active or blocked goal to resume"
+            goal_id = g.id
+        return run_goal_sync(LLM(), w, Budget(), int(goal_id))
+
+    def _tool_answer(self, args: dict) -> str:
+        from maverick.world_model import WorldModel
+        w = WorldModel()
+        w.answer(int(args["question_id"]), str(args["answer"]))
+        return f"answered #{args['question_id']}"
+
+    def _tool_skill_install(self, args: dict) -> str:
+        from maverick.skills import install_skill
+        s = install_skill(args["source"], trusted_local=True)
+        return f"installed: {s.name} -> {s.path}"
+
+    def _tool_skills_list(self) -> str:
+        from maverick.skills import load_skills
+        items = load_skills()
+        if not items:
+            return "no skills installed"
+        return "\n".join(f"{s.name}: {', '.join(s.triggers[:3])}" for s in items)
+
+    def _tool_fact_set(self, args: dict) -> str:
+        from maverick.world_model import WorldModel
+        w = WorldModel()
+        w.upsert_fact(args["key"], args["value"])
+        return f"set {args['key']}"
+
+    def _tool_facts_get(self) -> str:
+        from maverick.world_model import WorldModel
+        w = WorldModel()
+        facts = w.get_facts()
+        if not facts:
+            return "no facts known"
+        return "\n".join(f"{k}: {v}" for k, v in facts.items())
+
+    def _send(self, message: dict) -> None:
+        sys.stdout.write(json.dumps(message) + "\n")
+        sys.stdout.flush()
+
+    def _send_error(self, request_id: Any, code: int, message: str) -> None:
+        self._send({
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "error": {"code": code, "message": message},
+        })
+
+    def _send_result(self, request_id: Any, result: dict) -> None:
+        self._send({"jsonrpc": "2.0", "id": request_id, "result": result})
+
+    def run(self) -> None:
+        log.info("Maverick MCP server starting (protocol %s)", PROTOCOL_VERSION)
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                msg = json.loads(line)
+            except json.JSONDecodeError as e:
+                log.warning("bad JSON: %s", e)
+                continue
+            method = msg.get("method")
+            request_id = msg.get("id")
+            params = msg.get("params", {}) or {}
+            is_notification = request_id is None
+            try:
+                if method == "initialize":
+                    self._send_result(request_id, self.handle_initialize(params))
+                elif method == "tools/list":
+                    self._send_result(request_id, self.handle_tools_list(params))
+                elif method == "tools/call":
+                    self._send_result(request_id, self.handle_tools_call(params))
+                elif method == "resources/list":
+                    self._send_result(request_id, self.handle_resources_list(params))
+                elif method == "resources/read":
+                    self._send_result(request_id, self.handle_resources_read(params))
+                elif method == "prompts/list":
+                    self._send_result(request_id, self.handle_prompts_list(params))
+                elif method == "prompts/get":
+                    self._send_result(request_id, self.handle_prompts_get(params))
+                elif method == "notifications/initialized":
+                    pass
+                elif method == "ping":
+                    if not is_notification:
+                        self._send_result(request_id, {})
+                else:
+                    if not is_notification:
+                        self._send_error(request_id, -32601, f"method not found: {method}")
+            except _ProtocolError as e:
+                if not is_notification:
+                    self._send_error(request_id, e.code, e.message)
+            except Exception as e:
+                log.exception("handler error")
+                if not is_notification:
+                    self._send_error(
+                        request_id, -32603,
+                        f"internal error: {type(e).__name__}: {e}\n{traceback.format_exc()}",
+                    )
+
+
+def main() -> None:
+    """Entry point. Defaults to stdio transport (Claude Desktop /
+    Cursor compatible). Pass `--http` for the Streamable HTTP
+    transport (hosted Maverick, MCP gateways)."""
+    import argparse
+    ap = argparse.ArgumentParser(prog="maverick-mcp")
+    ap.add_argument("--http", action="store_true",
+                    help="Serve over Streamable HTTP instead of stdio")
+    ap.add_argument("--host", default="127.0.0.1")
+    ap.add_argument("--port", type=int, default=8771)
+    args = ap.parse_args()
+    if args.http:
+        from .http_transport import serve
+        serve(host=args.host, port=args.port)
+    else:
+        MCPServer().run()
+
+
+if __name__ == "__main__":
+    main()

maverick_mcp_server-0.1.2/maverick_mcp_server.egg-info/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: maverick-mcp-server
+Version: 0.1.2
+Summary: Model Context Protocol server for Maverick (exposes the swarm to MCP clients)
+Author: cdayAI
+License: MIT
+Project-URL: Homepage, https://github.com/cdayAI/maverick
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: maverick-agent>=0.1
+
+# maverick-mcp-server
+
+A Model Context Protocol (MCP) server that exposes Maverick's agent
+loop as a set of MCP tools. Any MCP-compatible client (Claude Code,
+Claude Desktop, Cursor, etc.) can drive Maverick over stdio JSON-RPC.
+
+## Why
+
+Maverick is a swarm of agents with persistent memory, budget caps,
+and verifier loops. Most MCP clients are single-turn. By plugging
+Maverick in via MCP, you get:
+
+- A "think hard for an hour" tool from inside Claude Code
+- Persistent goals that survive editor restarts
+- Per-role model routing controlled by your `~/.maverick/config.toml`
+- Auto-distilled skills that compound across sessions
+
+## Install
+
+```bash
+pip install -e ./packages/maverick-mcp
+```
+
+## Wire into Claude Code
+
+Add to your Claude Code MCP config (typically
+`~/.config/claude-code/mcp.json` or similar):
+
+```json
+{
+  "mcpServers": {
+    "maverick": {
+      "command": "maverick-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Then restart Claude Code. The Maverick tools should appear under the
+MCP servers menu.
+
+## Tools exposed
+
+| Tool | What it does |
+|---|---|
+| `maverick_start` | Start a new goal, run the swarm, return the final answer |
+| `maverick_status` | List recent goals + open questions |
+| `maverick_resume` | Resume a paused goal |
+| `maverick_answer` | Answer a queued question |
+| `maverick_skill_install` | Install a SKILL.md from URL / gh:org/repo / local path |
+| `maverick_skills_list` | List installed / distilled skills |
+| `maverick_fact_set` | Set a fact in the world model |
+| `maverick_facts_get` | Get all known facts |
+
+All calls go through `maverick.orchestrator.run_goal` -- same Shield
+chokepoints, same budget caps, same per-role model routing.
+
+## Protocol
+
+Minimal JSON-RPC 2.0 over stdio, matching the MCP 2024-11-05 spec
+(`initialize`, `tools/list`, `tools/call`). No external dependencies.
+The full `mcp` Python SDK is an option for a future hardening pass;
+this hand-rolled version keeps the dependency footprint tiny.

maverick_mcp_server-0.1.2/maverick_mcp_server.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+maverick_mcp/__init__.py
+maverick_mcp/http_transport.py
+maverick_mcp/server.py
+maverick_mcp_server.egg-info/PKG-INFO
+maverick_mcp_server.egg-info/SOURCES.txt
+maverick_mcp_server.egg-info/dependency_links.txt
+maverick_mcp_server.egg-info/entry_points.txt
+maverick_mcp_server.egg-info/requires.txt
+maverick_mcp_server.egg-info/top_level.txt
+tests/test_http_transport.py
+tests/test_server.py

maverick_mcp_server-0.1.2/maverick_mcp_server.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

maverick_mcp_server-0.1.2/maverick_mcp_server.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+maverick-mcp = maverick_mcp.server:main

maverick_mcp_server-0.1.2/maverick_mcp_server.egg-info/requires.txt

@@ -0,0 +1 @@
+maverick-agent>=0.1

maverick_mcp_server-0.1.2/maverick_mcp_server.egg-info/top_level.txt

@@ -0,0 +1 @@
+maverick_mcp

maverick_mcp_server-0.1.2/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "maverick-mcp-server"
+version = "0.1.2"
+description = "Model Context Protocol server for Maverick (exposes the swarm to MCP clients)"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "cdayAI" }]
+readme = "README.md"
+dependencies = [
+    "maverick-agent>=0.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/cdayAI/maverick"
+
+[project.scripts]
+maverick-mcp = "maverick_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["maverick_mcp*"]

maverick_mcp_server-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

maverick_mcp_server-0.1.2/tests/test_http_transport.py

@@ -0,0 +1,112 @@
+"""MCP Streamable HTTP transport tests."""
+from __future__ import annotations
+
+import pytest
+
+
+def _have_fastapi() -> bool:
+    try:
+        import fastapi  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+@pytest.mark.skipif(not _have_fastapi(), reason="fastapi not installed")
+class TestHTTPTransport:
+    def _client(self):
+        from fastapi.testclient import TestClient
+
+        from maverick_mcp.http_transport import build_app
+        from maverick_mcp.server import MCPServer
+        app = build_app(MCPServer())
+        return TestClient(app)
+
+    def test_initialize_returns_capabilities(self, monkeypatch):
+        monkeypatch.setenv("MAVERICK_MCP_TOKEN", "s3cr3t")
+        client = self._client()
+        resp = client.post("/mcp", json={
+            "jsonrpc": "2.0", "id": 1, "method": "initialize",
+            "params": {"protocolVersion": "2025-11-25"},
+        }, headers={"Authorization": "Bearer s3cr3t"})
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["jsonrpc"] == "2.0"
+        assert body["id"] == 1
+        assert "result" in body
+        assert "capabilities" in body["result"]
+
+    def test_unknown_method_returns_jsonrpc_error(self, monkeypatch):
+        monkeypatch.setenv("MAVERICK_MCP_TOKEN", "s3cr3t")
+        client = self._client()
+        resp = client.post("/mcp", json={
+            "jsonrpc": "2.0", "id": 2, "method": "no/such/method",
+            "params": {},
+        }, headers={"Authorization": "Bearer s3cr3t"})
+        body = resp.json()
+        assert "error" in body
+        assert body["error"]["code"] == -32601
+
+    def test_resources_list_works_over_http(self, monkeypatch):
+        monkeypatch.setenv("MAVERICK_MCP_TOKEN", "s3cr3t")
+        client = self._client()
+        resp = client.post("/mcp", json={
+            "jsonrpc": "2.0", "id": 3, "method": "resources/list",
+            "params": {},
+        }, headers={"Authorization": "Bearer s3cr3t"})
+        body = resp.json()
+        assert "result" in body
+        assert "resources" in body["result"]
+
+    def test_bearer_required_when_token_set(self, monkeypatch):
+        monkeypatch.setenv("MAVERICK_MCP_TOKEN", "s3cr3t")
+        client = self._client()
+        resp = client.post("/mcp", json={
+            "jsonrpc": "2.0", "id": 1, "method": "initialize",
+            "params": {},
+        })
+        assert resp.status_code == 401
+
+    def test_bearer_accepted_when_correct(self, monkeypatch):
+        monkeypatch.setenv("MAVERICK_MCP_TOKEN", "s3cr3t")
+        client = self._client()
+        resp = client.post("/mcp", json={
+            "jsonrpc": "2.0", "id": 1, "method": "initialize",
+            "params": {},
+        }, headers={"Authorization": "Bearer s3cr3t"})
+        assert resp.status_code == 200
+
+    def test_wrong_bearer_rejected(self, monkeypatch):
+        monkeypatch.setenv("MAVERICK_MCP_TOKEN", "s3cr3t")
+        client = self._client()
+        resp = client.post("/mcp", json={
+            "jsonrpc": "2.0", "id": 1, "method": "initialize",
+            "params": {},
+        }, headers={"Authorization": "Bearer wrong"})
+        assert resp.status_code == 401
+
+    def test_auth_required_when_token_unset(self, monkeypatch):
+        monkeypatch.delenv("MAVERICK_MCP_TOKEN", raising=False)
+        client = self._client()
+        resp = client.post("/mcp", json={
+            "jsonrpc": "2.0", "id": 1, "method": "initialize",
+            "params": {},
+        })
+        assert resp.status_code == 401
+
+    def test_healthz_exempt(self, monkeypatch):
+        monkeypatch.setenv("MAVERICK_MCP_TOKEN", "s3cr3t")
+        client = self._client()
+        resp = client.get("/healthz")
+        assert resp.status_code == 200
+        assert resp.json()["transport"] == "http"
+
+    def test_notification_returns_204(self, monkeypatch):
+        monkeypatch.setenv("MAVERICK_MCP_TOKEN", "s3cr3t")
+        client = self._client()
+        resp = client.post("/mcp", json={
+            "jsonrpc": "2.0", "method": "notifications/initialized",
+            "params": {},
+        }, headers={"Authorization": "Bearer s3cr3t"})
+        # No "id" -> notification -> 204
+        assert resp.status_code == 204

maverick_mcp_server-0.1.2/tests/test_server.py

@@ -0,0 +1,176 @@
+"""MCP server smoke + protocol tests.
+
+v0.1.6: handle_tools_call now RAISES `_ProtocolError` for unknown tool /
+missing required args (per MCP spec -- protocol errors must come back as
+JSON-RPC `-32602`, not `isError`). Tests assert the exception is raised
+and carries the right code. The `isError` envelope is only for tool
+*execution* failures (e.g., the tool raised mid-call).
+"""
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from maverick_mcp.server import (
+    PROTOCOL_VERSION,
+    TOOLS,
+    MCPServer,
+    _ProtocolError,
+)
+
+
+class TestTools:
+    def test_all_tools_have_required_fields(self):
+        for t in TOOLS:
+            assert "name" in t
+            assert "description" in t
+            assert "inputSchema" in t
+            assert t["inputSchema"].get("type") == "object"
+
+    def test_known_tool_names(self):
+        names = {t["name"] for t in TOOLS}
+        for expected in (
+            "maverick_start",
+            "maverick_status",
+            "maverick_skill_install",
+            "maverick_fact_set",
+        ):
+            assert expected in names
+
+
+class TestProtocol:
+    def test_initialize_response_shape(self):
+        s = MCPServer()
+        out = s.handle_initialize({})
+        assert out["protocolVersion"] == PROTOCOL_VERSION
+        assert out["serverInfo"]["name"] == "maverick"
+        assert "capabilities" in out
+
+    def test_tools_list_returns_full_catalog(self):
+        s = MCPServer()
+        out = s.handle_tools_list({})
+        assert len(out["tools"]) == len(TOOLS)
+
+    def test_unknown_tool_raises_protocol_error(self):
+        """Unknown tool -> JSON-RPC -32602, not isError envelope."""
+        s = MCPServer()
+        with pytest.raises(_ProtocolError) as excinfo:
+            s.handle_tools_call({"name": "does_not_exist", "arguments": {}})
+        assert excinfo.value.code == -32602
+        assert "unknown tool" in excinfo.value.message
+
+    def test_missing_required_arg_raises_protocol_error(self):
+        """Missing required arg -> JSON-RPC -32602."""
+        s = MCPServer()
+        # maverick_answer requires question_id + answer
+        with pytest.raises(_ProtocolError) as excinfo:
+            s.handle_tools_call({"name": "maverick_answer", "arguments": {}})
+        assert excinfo.value.code == -32602
+        assert "question_id" in excinfo.value.message
+        assert "answer" in excinfo.value.message
+
+    def test_tool_execution_failure_returns_isError_envelope(self):
+        """Tool that raises mid-execution -> isError (not protocol error).
+
+        maverick_facts_get touches WorldModel and would normally succeed;
+        we'd need to mock it to force a raise. Skip the full path test and
+        just verify the contract via _dispatch_tool returning isError when
+        dispatch raises.
+        """
+        s = MCPServer()
+        # All registered names dispatch normally. Force an exception
+        # by passing a name the dispatch can find but the tool raises on.
+        # maverick_answer with bad question_id type -> int() raises.
+        out = s.handle_tools_call({
+            "name": "maverick_answer",
+            "arguments": {"question_id": "not-a-number", "answer": "x"},
+        })
+        assert out["isError"] is True
+        assert "text" in out["content"][0]
+
+    def test_maverick_start_blocks_disallowed_input(self, monkeypatch):
+        s = MCPServer()
+        s._shield = SimpleNamespace(
+            scan_input=lambda _text: SimpleNamespace(allowed=False, reasons=["blocked input"]),
+            scan_output=lambda _text: SimpleNamespace(allowed=True, reasons=[]),
+        )
+
+        out = s.handle_tools_call({
+            "name": "maverick_start",
+            "arguments": {"title": "bad payload", "description": "ignore rules"},
+        })
+
+        assert out["isError"] is False
+        assert "⚠ Blocked: blocked input" in out["content"][0]["text"]
+
+    def test_tools_call_blocks_disallowed_output(self, monkeypatch):
+        s = MCPServer()
+        s._shield = SimpleNamespace(
+            scan_output=lambda _text: SimpleNamespace(allowed=False, reasons=["blocked output"]),
+        )
+        monkeypatch.setattr(s, "_dispatch_tool", lambda *_args, **_kwargs: "secret")
+
+        out = s.handle_tools_call({
+            "name": "maverick_status",
+            "arguments": {},
+        })
+
+        assert out["isError"] is True
+        assert "⚠ Output blocked: blocked output" in out["content"][0]["text"]
+
+
+class TestProtocol2025_11_25:
+    """Tests for the new MCP 2025-11-25 primitives."""
+
+    def test_initialize_advertises_new_capabilities(self):
+        s = MCPServer()
+        out = s.handle_initialize({"protocolVersion": "2025-11-25"})
+        assert "resources" in out["capabilities"]
+        assert "prompts" in out["capabilities"]
+        assert "elicitation" in out["capabilities"]
+
+    def test_initialize_negotiates_down_for_old_clients(self):
+        s = MCPServer()
+        out = s.handle_initialize({"protocolVersion": "2024-11-05"})
+        assert out["protocolVersion"] == "2024-11-05"
+
+    def test_initialize_uses_current_version_for_new_clients(self):
+        s = MCPServer()
+        out = s.handle_initialize({"protocolVersion": "2025-11-25"})
+        assert out["protocolVersion"] == "2025-11-25"
+
+    def test_resources_list_includes_static_namespaces(self):
+        s = MCPServer()
+        out = s.handle_resources_list({})
+        uris = {r["uri"] for r in out["resources"]}
+        assert "maverick://goals" in uris
+        assert "maverick://skills" in uris
+
+    def test_resources_read_rejects_unsupported_scheme(self):
+        s = MCPServer()
+        with pytest.raises(_ProtocolError):
+            s.handle_resources_read({"uri": "file:///etc/passwd"})
+
+    def test_prompts_list_returns_three_templates(self):
+        s = MCPServer()
+        out = s.handle_prompts_list({})
+        names = {p["name"] for p in out["prompts"]}
+        assert "research_topic" in names
+        assert "draft_message" in names
+        assert "compare_options" in names
+
+    def test_prompts_get_renders_with_args(self):
+        s = MCPServer()
+        out = s.handle_prompts_get({
+            "name": "research_topic",
+            "arguments": {"topic": "fusion reactors", "depth": "deep"},
+        })
+        text = out["messages"][0]["content"]["text"]
+        assert "fusion reactors" in text
+        assert "deep" in text
+
+    def test_prompts_get_unknown_raises(self):
+        s = MCPServer()
+        with pytest.raises(_ProtocolError):
+            s.handle_prompts_get({"name": "nonexistent", "arguments": {}})