MCP Tooling

python -m musehub.mcp.stdio_server

# HTTP Streamable — listens on http://127.0.0.1:1337/mcp by default
muse hub mcp

# Custom port
muse hub mcp --port 8080

# Target a specific hub instead of localhost
muse hub mcp --hub http://staging.musehub.ai

# Stdio mode (newline-delimited JSON-RPC on stdin/stdout — no HTTP layer)
muse hub mcp --stdio

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "musehub": {
      "command": "muse",
      "args": ["hub", "mcp", "--stdio"]
    }
  }
}

// .cursor/mcp.json
{
  "mcpServers": {
    "musehub": {
      "command": "muse",
      "args": ["hub", "mcp", "--stdio"]
    }
  }
}

# 1. Initialize — get session ID
POST http://staging.musehub.ai/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": { "elicitation": { "form": {}, "url": {} } },
    "clientInfo": { "name": "my-agent", "version": "1.0" }
  }
}
# Response header: Mcp-Session-Id: <session-id>

# 2. Open SSE push channel
GET http://staging.musehub.ai/mcp
Mcp-Session-Id: <session-id>
Accept: text/event-stream

# 3. Call tools (include session ID on every request)
POST http://staging.musehub.ai/mcp
Content-Type: application/json
Mcp-Session-Id: <session-id>
Authorization: MSign handle="gabriel" ts=1745280000 sig="<base64url>"

{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "musehub_set_context", "arguments": { "owner": "gabriel", "slug": "muse" } }
}

# 4. Terminate session
DELETE http://staging.musehub.ai/mcp
Mcp-Session-Id: <session-id>

{
  "capabilities": {
    "tools":     { "listChanged": false },
    "resources": { "subscribe": false, "listChanged": false },
    "prompts":   { "listChanged": false },
    "elicitation": { "form": {}, "url": {} },
    "logging":   {}
  }
}

{
  "name": "musehub_list_commits",
  "description": "List commits on a MuseHub repository (newest first).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "repo_id":  { "type": "string", "description": "sha256 genesis hash (alt: owner+slug)" },
      "owner":   { "type": "string" },
      "slug":    { "type": "string" },
      "branch":  { "type": "string", "description": "Branch name filter" },
      "limit":   { "type": "integer", "default": 20, "minimum": 1 }
    },
    "required": []  // context from musehub_set_context satisfies repo args
  }
}

// SSE event pushed by server
{
  "jsonrpc": "2.0", "id": "<request_id>", "method": "elicitation/create",
  "params": {
    "mode": "form",
    "message": "Configure your review",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "dimension_focus": { "type": "string", "enum": ["security", "performance", "all"] },
        "review_depth":    { "type": "string", "enum": ["quick", "thorough"] }
      },
      "required": ["dimension_focus"]
    }
  }
}

// Client response (POST /mcp)
{
  "jsonrpc": "2.0", "id": "<request_id>",
  "result": { "action": "accept", "content": { "dimension_focus": "security", "review_depth": "thorough" } }
}
// or: { "result": { "action": "decline" } }

POST /mcp
Authorization: MSign handle="gabriel" alg="ed25519" ts=1746576000 sig="Zj8…"
Mcp-Session-Id: ses_4f2a9b3d
Content-Type: application/json

{
  "jsonrpc": "2.0", "id": "call-77", "method": "tools/call",
  "params": {
    "name": "musehub_review_proposal_interactive",
    "arguments": { "owner": "gabriel", "slug": "muse", "proposal_id": "af54753d" }
  }
}

# Server responds: 200 OK with Content-Type: text/event-stream
# (the response body is an SSE stream because the tool needs to elicit)

POST /mcp
Mcp-Session-Id: ses_4f2a9b3d
Content-Type: application/json

{
  "jsonrpc": "2.0", "id": "call-77",
  "result": {
    "action": "accept",
    "content": {
      "dimension_focus": "security",
      "review_depth": "thorough",
      "reviewer_note": "Pay attention to the new auth middleware"
    }
  }
}

class ToolCallContext:
    user_id: str | None
    is_agent: bool
    agent_name: str | None
    has_session: bool
    has_elicitation: bool   # true if client advertised elicitation capability

    async def elicit_form(schema, message) -> JSONObject | None
    async def elicit_url(url, message, elicitation_id=None) -> bool
    async def progress(token, value, total=None, label=None) -> None

id: 42
event: notifications/progress
data: {"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"t1","progress":3,"total":10,"message":"Analyzing symbols"}}

# 1. Initialize and capture the session ID
SESSION=$(curl -s -X POST http://staging.musehub.ai/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{"elicitation":{"form":{},"url":{}}},"clientInfo":{"name":"curl-test","version":"1.0"}}}' \
  -D - | grep -i mcp-session-id | awk '{print $2}' | tr -d '\r')

# 2. Open persistent SSE channel (blocks; -N disables buffering)
curl -N \
  -H "Accept: text/event-stream" \
  -H "Mcp-Session-Id: $SESSION" \
  http://staging.musehub.ai/mcp

# reconnect with event replay from event 37 onward
curl -N \
  -H "Accept: text/event-stream" \
  -H "Mcp-Session-Id: $SESSION" \
  -H "Last-Event-ID: 37" \
  http://staging.musehub.ai/mcp

# Authorization header — required on write tool calls
Authorization: MSign handle="gabriel" alg="ed25519" ts=1745280000 sig="<base64url>"

# Generate with muse sign header
muse sign header \
  --method POST \
  --path /mcp \
  --hub http://staging.musehub.ai --json

{
  "result": {
    "ok": false,
    "isError": true,
    "error_code": "proposal_not_found",
    "error_message": "Proposal 123 not found.",
    "hint": "Call musehub_list_proposals() to see open proposals."
  }
}