# MuseHub MCP Reference > Protocol version: **2025-11-25** | Implementation: pure-Python async, no external MCP SDK MuseHub treats AI agents as first-class citizens. The MCP integration gives agents complete capability parity with the web UI: they can browse, search, compose, review, and publish — over a standard protocol that every major agent runtime supports. MCP 2025-11-25 adds the full **Streamable HTTP transport** (`GET /mcp` SSE push channel, session management, Origin security) and **Elicitation** (server-initiated user input via form and URL modes), enabling real-time interactive tool calls that interview users mid-execution. --- ## Table of Contents 1. [Architecture](#architecture) 2. [Transports](#transports) 3. [Authentication](#authentication) 4. [Session Management](#session-management) 5. [Elicitation](#elicitation) 6. [Tools — 127 total](#tools) - [Read Tools (52)](#read-tools-52) - [Write Tools (73)](#write-tools-73) - [Elicitation-Powered Tools (2)](#elicitation-powered-tools-2) 7. [Resources — 28 total](#resources) - [Static Resources (9)](#static-resources-9) - [Templated Resources (19)](#templated-resources-19) 8. [Prompts — 11 total](#prompts) 9. [Error Handling](#error-handling) 10. [Usage Patterns](#usage-patterns) 11. [Architecture Diagrams](#architecture-diagrams) --- ## Architecture ``` MCP Client (Cursor, Claude Desktop, any SDK) │ ├─ HTTP POST /mcp (all client→server) ├─ HTTP GET /mcp (SSE push, server→client) ├─ HTTP DELETE /mcp (session termination) └─ stdio python -m musehub.mcp.stdio_server (local dev) │ musehub/api/routes/mcp.py ← Streamable HTTP transport (2025-11-25) │ musehub/mcp/dispatcher.py ← async JSON-RPC 2.0 engine │ ┌───────┼───────────────┬────────────────┐ │ │ │ │ tools/call resources/read prompts/get notifications/* │ │ │ │ Read executors Resource handlers Prompt Session/Elicitation (musehub_mcp_executor.py) (resources.py) assembler (session.py) Write executors (context.py) Elicitation tools (mcp/write_tools/elicitation_tools.py) │ AsyncSession → Postgres ``` The dispatcher speaks JSON-RPC 2.0 directly. The HTTP envelope is always `200 OK` — tool errors are signalled via `isError: true` on the content block, not via HTTP status codes. Notifications (no `id` field) return `202 Accepted` with an empty body. Elicitation-powered tools return `text/event-stream` so the server can push `elicitation/create` events mid-call. --- ## Transports ### HTTP Streamable — Full 2025-11-25 Transport #### `POST /mcp` The production transport. Accepts `application/json`. Returns `application/json` for most requests, or `text/event-stream` for elicitation-powered tool calls. ```http POST /mcp HTTP/1.1 Content-Type: application/json Authorization: MSign handle="..." ts=... sig="..." Mcp-Session-Id: ← required after initialize MCP-Protocol-Version: 2025-11-25 ← optional; validated if present {"jsonrpc":"2.0","id":1,"method":"tools/list"} ``` **Batch requests** — send a JSON array; responses are returned as an array in the same order (notifications are filtered out): ```http POST /mcp [ {"jsonrpc":"2.0","id":1,"method":"tools/list"}, {"jsonrpc":"2.0","id":2,"method":"resources/list"} ] ``` **Notifications** (no `id`) return `202 Accepted` with an empty body. #### `GET /mcp` — SSE Push Channel Persistent server-to-client event stream. Required for receiving elicitation requests and progress notifications outside of an active tool call. ```http GET /mcp HTTP/1.1 Accept: text/event-stream Mcp-Session-Id: Last-Event-ID: ← optional; triggers replay ``` Returns `text/event-stream`. Server pushes: - `notifications/progress` — tool progress updates - `elicitation/create` — server-initiated user input requests - `notifications/elicitation/complete` — URL-mode OAuth completion signals - `: heartbeat` — comment every 15 s to keep proxies alive #### `DELETE /mcp` — Session Termination ```http DELETE /mcp HTTP/1.1 Mcp-Session-Id: ``` Returns `200 OK`. Closes all open SSE streams and cancels pending elicitation Futures for the session. ### stdio — `python -m musehub.mcp.stdio_server` The local dev and Cursor IDE transport. Reads newline-delimited JSON from `stdin`, writes JSON-RPC responses to `stdout`, logs to `stderr`. **Cursor IDE integration** — create or update `.cursor/mcp.json` in your workspace: ```json { "mcpServers": { "musehub": { "command": "python", "args": ["-m", "musehub.mcp.stdio_server"], "cwd": "/path/to/musehub" } } } ``` The stdio server runs without auth (trusted local process). Write tools are available unconditionally. --- ## Authentication | Context | How | |---------|-----| | HTTP transport — read tools + public resources | No auth required | | HTTP transport — write / elicitation tools | `Authorization: MSign handle="..." ts=... sig="..."` | | HTTP transport — private repo resources | `Authorization: MSign handle="..." ts=... sig="..."` | | stdio transport | No auth (trusted process) | MuseHub uses Ed25519 / MSign request signing. Register your Ed25519 public key via `POST /api/auth/challenge` → `POST /api/auth/verify`. The `muse` CLI manages key registration and signs all requests automatically. The verified `handle` claim is used as the acting `user_id` for all write operations. Attempting a write tool without a valid MSign request returns a JSON-RPC error (`code: -32001`, `message: "Authentication required for write tools"`). --- ## Session Management Session management is required for elicitation and the GET /mcp SSE push channel. **Creating a session:** ```http POST /mcp {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{"elicitation":{"form":{},"url":{}}}}} ``` Response includes: ```http Mcp-Session-Id: ``` **Using the session:** include `Mcp-Session-Id` in all subsequent requests. Sessions expire after 1 hour of inactivity. **Ending a session:** `DELETE /mcp` with the `Mcp-Session-Id` header. **Security:** All requests are validated against an Origin allowlist (`localhost` always permitted; production: `musehub.ai`). Requests from unlisted Origins are rejected with `403 Forbidden`. --- ## Elicitation Elicitation is a MCP 2025-11-25 feature that allows the server to request structured input from the user *mid-tool-call*. MuseHub supports both modes: ### Form Mode The server sends an `elicitation/create` request with a restricted JSON Schema object describing the fields to collect. The client shows a form to the user, then sends the response back via `POST /mcp`. ``` Agent MuseHub MCP │ │ │ POST tools/call │ │ (musehub_review_proposal_interactive) │──────────────────────────►│ │ │ opens SSE stream │◄──────────────────────────│ │ SSE: elicitation/create │ │ {mode:"form", schema:{ │ │ dimension_focus, depth,│ │ reviewer_note, ...}} │ │◄──────────────────────────│ │ [user fills form] │ │ POST elicitation result │ │ {action:"accept", │ │ content:{dimension_focus│ │ :"harmonic",...}} │ │──────────────────────────►│ │ │ tool continues │ SSE: tools/call response │ │◄──────────────────────────│ ``` ### Elicitation Schemas MuseHub exposes two form schemas used by the interactive tools: | Schema key | Used by | Fields | |------------|---------|--------| | `proposal_review_focus` | `musehub_review_proposal_interactive` | `dimension_focus` (all/melodic/harmonic/rhythmic/structural/dynamic), `review_depth` (quick/standard/thorough), `check_harmonic_tension`, `check_rhythmic_consistency`, `reviewer_note` | | `release_metadata` | `musehub_create_release_interactive` | `tag`, `title`, `release_notes`, `is_prerelease`, `highlight` | --- ## Tools All 127 tools use `server_side: true`. The JSON-RPC envelope is always a success response — errors are represented inside the content block via `isError: true`. ### Repo identification: `repo_id` or `owner` + `slug` All repo-scoped tools accept either form. The dispatcher resolves `owner` + `slug` to a `repo_id` transparently — agents can use human-readable names without a prior lookup step: ```json { "repo_id": "abc-123-uuid" } // or equivalently: { "owner": "gabriel", "slug": "jazz-standards" } ``` ### Calling a tool ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "musehub_get_context", "arguments": { "owner": "gabriel", "slug": "jazz-standards" } } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "content": [{ "type": "text", "text": "{\"name\":\"my-song\", ...}" }], "isError": false } } ``` --- ### Read Tools (52) #### `muse_mist_embed` Get embeddable codes (iframe, JavaScript snippet, markdown badge) for a public Mist. Use these to share a Mist in documentation, READMEs, or web pages. The embed counter is incremented so the owner can track distribution. Only available for public mists. Example: muse_mist_embed(mist_id='aB3xKq9dPwNm', owner='gabriel') | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mist_id` | string | yes | 12-character mist ID. | | `owner` | string | yes | Handle of the mist owner (used to build canonical URLs). | --- #### `muse_mist_list` List Mists — either for a specific owner or the global public discovery feed. When owner is omitted, returns the newest public mists from all users (explore mode). When owner is provided, returns that handle's mists; pass include_secret=true as the authenticated owner to include your own secret mists. Supports cursor-based pagination via next_cursor. Filter by artifact_type (e.g. 'code', 'midi', 'schema', 'dataset'). Examples: muse_mist_list() — global explore; muse_mist_list(owner='gabriel') — gabriel's public mists; muse_mist_list(owner='gabriel', include_secret=True) — all gabriel's mists (owner only). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `artifact_type` | string | no | Filter by artifact type (e.g. 'code', 'midi', 'schema'). | | `cursor` | string | no | Pagination cursor from a previous next_cursor field. | | `include_secret` | boolean | no | Include secret mists (only works when authenticated as the owner). | | `limit` | integer | no | Results per page (default 20, max 200). | | `owner` | string | no | Handle to filter by. Omit for global explore. | --- #### `muse_mist_list_forks` List the direct (one-level) forks of a mist, newest first. Returns each fork's mist_id, owner, filename, artifact_type, fork_depth, and created_at. The parent mist must exist and be readable by the caller — secret parents require authentication. Example: muse_mist_list_forks(mist_id='aB3xKq9dPwNm') | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | no | Maximum number of forks to return (1–100, default 20). | | `mist_id` | string | yes | 12-character mist ID whose direct forks to list. | --- #### `muse_mist_raw` Fetch the raw artifact content of a mist as a plain string — faster than muse_mist_read when you only need the content without full metadata. Secret mists require authentication as the owner. Increments the view counter. Example: muse_mist_raw(mist_id='aB3xKq9dPwNm') | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mist_id` | string | yes | 12-character mist ID whose content to fetch. | --- #### `muse_mist_read` Fetch the full content and metadata of a single Mist by its content-addressed ID. Public mists are readable by any caller. Secret mists require authentication as the owner. The view counter is incremented on each call. Example: muse_mist_read(mist_id='aB3xKq9dPwNm') | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mist_id` | string | yes | 12-character content-addressed mist ID. | --- #### `muse_pull` Fetch missing commits and blobs from a MuseHub repository. Equivalent to 'muse pull' — returns new commits and blob metadata since the given commit ID. Use since_commit_id to fetch incrementally. Pass blob_ids to download specific blobs — their content is returned as base64-encoded strings in the 'content_b64' field of each blob entry; decode with base64.b64decode() before writing to disk. Example: muse_pull(repo_id='a3f2-...', branch='main', since_commit_id='abc123') or muse_pull(owner='gabriel', slug='jazz-standards', branch='main'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `blob_ids` | array | no | Specific blob IDs to fetch (content-addressed sha256: prefixed IDs). | | `branch` | string | no | Branch to pull from. Defaults to the default branch. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `since_commit_id` | string | no | Only return commits newer than this commit ID. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `muse_remote` Return the remote URL, push/pull API endpoints, and clone command for a MuseHub repository. Covers both 'muse remote -v' and 'muse clone' use cases in a single call. Returns: origin URL, push endpoint, pull endpoint, clone command (with optional ref), and the 'muse remote add origin' command. Use this when setting up a local repo to push to MuseHub, or to get the clone URL. Example: muse_remote(owner='gabriel', slug='neo-soul-experiment') or muse_remote(owner='gabriel', slug='neo-soul-experiment', ref='feat/jazz-bridge'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | yes | Repository owner username. | | `ref` | string | no | Optional branch or tag to target (used in the clone command). | | `slug` | string | yes | Repository slug (URL-safe name). | --- #### `musehub_compare` Compare two refs (branches or commit IDs) in a MuseHub repository. Returns a multidimensional state diff: which artifacts were added, removed, or modified, and per-dimension change scores sourced from the repo's domain plugin capabilities. Example: musehub_compare(repo_id='a3f2-...', base_ref='main', head_ref='feature/new-section') or musehub_compare(owner='gabriel', slug='jazz-standards', base_ref='main', head_ref='feature/bridge'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `base_ref` | string | yes | Base branch name or commit ID. | | `head_ref` | string | yes | Head branch name or commit ID to compare against base. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_get_fork_network` Return the complete recursive fork network tree rooted at a MuseHub repository. The response has a 'root' node (the source repo) with 'children' (direct forks), each child carrying its own 'children' for second-level forks, etc. 'totalForks' is the flat count of all fork nodes (excluding root). Use this to find the most-diverged fork, visualise the fork graph, or decide which fork to merge back into the upstream before a breaking change. Example: musehub_get_fork_network(repo_id='a3f2-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `repo_id` | string | yes | sha256 genesis ID of the root repository. | --- #### `musehub_get_repo` Fetch metadata for a single MuseHub repository by repo_id or owner+slug. Returns name, owner, slug, visibility, description, tags, default_branch, clone_url, created_at, updated_at, and pushed_at. Use this to inspect a specific repo without searching. Example: musehub_get_repo(owner='gabriel', slug='jazz-standards') or musehub_get_repo(repo_id='a3f2-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner handle (used together with slug). | | `repo_id` | string | no | Repository sha256 genesis ID. Takes precedence over owner+slug when both provided. | | `slug` | string | no | URL-safe repository slug (used together with owner). | --- #### `musehub_get_user_forks` List all repositories that a MuseHub user has forked, with source attribution. Returns each fork entry with the fork repo's full metadata plus 'sourceOwner' and 'sourceSlug' so you can render 'forked from {sourceOwner}/{sourceSlug}'. Ordered newest-first. Example: musehub_get_user_forks(username='gabriel'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `username` | string | yes | MSign handle of the user whose forks to retrieve. | --- #### `musehub_list_branches` List all branches in a MuseHub repository with their head commit IDs. Call before musehub_list_commits to identify the target branch ref. Example: musehub_list_branches(repo_id='a3f2-...') or musehub_list_branches(owner='gabriel', slug='jazz-standards'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_list_commits` List commits on a MuseHub repository (newest first). Optionally filter by branch name and cap the result count. Example: musehub_list_commits(repo_id='a3f2-...', branch='main', limit=10) or musehub_list_commits(owner='gabriel', slug='jazz-standards', branch='main'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `branch` | string | no | Branch name filter (e.g. 'main'). Omit to list across all branches. | | `limit` | integer | no | Maximum commits to return (default: 20, max: 100). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_list_coord_reservations` List active symbol reservations (locked symbols) in the repository. A reservation means another agent is actively editing that symbol — do not edit it. Use agent_id filter to see what a specific agent has locked. For a quick conflict check before reserving, prefer musehub_read_coord_conflicts(addresses=[...]) — it returns only the subset that conflicts rather than the full list. Part of the SYMBOL EDITING PROTOCOL: read_coord_conflicts → create_coord_reservation → [edit] → delete_coord_reservation | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | no | Filter reservations by this agent ID. | | `include_expired` | boolean | no | Include expired (but not released) reservations. Default false. | | `limit` | integer | no | Max reservations to return (default 200, max 1000). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_list_coord_tasks` TASK QUEUE PROTOCOL — Worker step 1: Find pending tasks to claim. Tasks flow: pending → claimed → completed | failed Typical worker loop: 1. musehub_list_coord_tasks(status='pending', queue='my-queue') — find work 2. musehub_claim_coord_task(task_id='...', agent_id='me') — atomically claim one 3. [do the work described in task.payload] 4. musehub_complete_coord_task(...) or musehub_fail_coord_task(...) Filter by queue to specialise (e.g. queue='analysis' for symbol-analysis agents). Sort order: highest priority first, then created_at ascending. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | no | Max tasks to return (default 100, max 500). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `queue` | string | no | Filter by queue name (e.g. 'tasks', 'analysis'). Omit for all queues. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `status` | string | no | Filter by task status. Omit to return all statuses. | --- #### `musehub_list_domains` List and search all registered Muse domain plugins. Domains are the extensibility layer that give Muse its domain-agnostic power — each domain defines its own dimensions, viewer, merge semantics, CLI commands, and artifact types. Filter by query string, viewer_type, or verified status. Returns scoped_id (@author/slug), display_name, description, capabilities, repo_count, and install_count for each domain. Example: musehub_list_domains(query='genomics', verified=true). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `cursor` | string | no | Opaque cursor from a previous call's next_cursor field to fetch the next page. | | `limit` | integer | no | Maximum results (default 20, max 100). | | `query` | string | no | Full-text search across name and description. | | `verified` | boolean | no | When true, return only officially-verified domains. | | `viewer_type` | string | no | Filter by viewer type: 'generic', 'symbol_graph', or 'piano_roll'. | --- #### `musehub_list_issues` List issues for a MuseHub repository. Filter by state (open/closed/all) or label string. Returns issue summaries (title, state, labels) — call musehub_read_issue with the number to get the full body and comment thread. Example: musehub_list_issues(repo_id='a3f2-...', state='open', label='bug') or musehub_list_issues(owner='gabriel', slug='jazz-standards'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `label` | string | no | Filter to issues with this label string. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `state` | string | no | Filter by state: 'open', 'closed', or 'all'. | --- #### `musehub_list_labels` List all labels defined in a MuseHub repository. Returns label_id, name, color, and description for each label. Use label_id values with musehub_update_label and musehub_delete_label. Example: musehub_list_labels(repo_id='a3f2-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_list_proposals` List merge proposals for a MuseHub repository. Filter by state (open/merged/closed/all). Returns merge proposal summaries — call musehub_read_proposal with the proposal_id to get reviews and inline comments. Example: musehub_list_proposals(repo_id='a3f2-...', state='open') or musehub_list_proposals(owner='gabriel', slug='jazz-standards'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `state` | string | no | Filter by state: 'open', 'merged', 'closed', or 'all'. | --- #### `musehub_list_proposals_context` List merge proposals with full enrichment: risk band, approval status, active domains, blocking dependencies, and author type — all in a single call. Use this instead of musehub_list_proposals when you need to triage the merge queue without calling musehub_read_proposal for each entry. Returns up to 50 proposals sorted by the state filter. Example: musehub_list_proposals_context(repo_id='a3f2-...', state='open') or musehub_list_proposals_context(owner='gabriel', slug='jazz-standards'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `state` | string | no | Filter by state: 'open', 'merged', 'settling', or 'all'. | --- #### `musehub_list_releases` List all releases for a MuseHub repository, ordered newest first. Each release includes tag, title, release notes summary, and asset counts. Example: musehub_list_releases(repo_id='a3f2-...') or musehub_list_releases(owner='gabriel', slug='jazz-standards'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_list_repo_forks` List all direct forks of a MuseHub repository. Returns each fork's full repo metadata (owner, slug, repo_id, description, tags, created_at) plus source attribution so you can render 'forked from {owner}/{slug}'. Use musehub_get_fork_network to traverse the full recursive tree including forks-of-forks. Example: musehub_list_repo_forks(repo_id='a3f2-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `repo_id` | string | yes | sha256 genesis ID of the source repository whose forks you want to list. | --- #### `musehub_list_repos` List repositories owned by or collaborated on by the authenticated user. Results are ordered newest-first. Use next_cursor from the response to page. This is the only way to enumerate your own private repos — musehub_search_repos only surfaces public repositories. Example: musehub_list_repos() or musehub_list_repos(limit=50, cursor='...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `cursor` | string | no | Opaque pagination cursor from a previous next_cursor field. | | `limit` | integer | no | Maximum repos per page (default 20, max 100). | --- #### `musehub_list_symbols` List or search all symbols known to MuseHub for a repo. Uses the materialized symbol index built from commit structured_delta on each push. Supports substring search with ?q= and op-kind filter (add|modify|delete). Returns address, last op, content_id, last_modified, history_count per symbol. Repo identifier required: provide repo_id OR both owner+slug. Example: musehub_list_symbols(repo_id='a3f2-...', q='MyClass') or musehub_list_symbols(owner='gabriel', slug='muse', q='CommitRecord'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `cursor` | string | no | Opaque cursor from a previous call's next_cursor field to fetch the next page. | | `kind` | string | no | Filter by last op kind | | `limit` | integer | no | Max symbols to return | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `q` | string | no | Substring to match against symbol address | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_commit` Get detailed information about a single commit, including its message, author, timestamp, parent IDs, and the full list of artifact paths at that snapshot. Use to inspect what changed at a specific point in history. Example: musehub_read_commit(repo_id='a3f2-...', commit_id='sha256:abc...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `commit_id` | string | yes | Commit ID (SHA or short ID). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_context` Start here. Get the full AI context document for a MuseHub repository: domain plugin (scoped_id, dimensions, capabilities), branches, recent commits, and artifact inventory — in a single call. This is the primary oracle for any agent: always call it before creating or modifying state to ensure coherence with the existing multidimensional content. For computed analytics (per-dimension scores), follow up with musehub_read_domain_insights. For the full viewer payload (dimension slices, navigation strip), follow up with musehub_read_view. Repo identifier required: provide repo_id OR both owner+slug. Example: musehub_read_context(repo_id='a3f2-...') or musehub_read_context(owner='gabriel', slug='jazz-standards'). If no repo identifier is provided and session context is set via musehub_set_context, the focused repo is used automatically. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_coord_conflicts` SYMBOL EDITING PROTOCOL — Step 1 of 3: Check if target symbols are free before reserving. Returns has_conflicts=false when all addresses are free (safe to proceed to reserve). Returns has_conflicts=true with a conflicts list when symbols are locked by other agents. If conflicts exist: - Check conflicts[].expires_at — wait until expiry if close - Contact the owning agent via the task queue or choose different symbols - Do NOT proceed to edit without a reservation Step 1: musehub_read_coord_conflicts(addresses=[...]) Step 2: musehub_create_coord_reservation(addresses=[...], agent_id='...') if no conflicts Step 3: musehub_delete_coord_reservation(reservation_id='...') after committing your changes | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `addresses` | array | yes | Symbol addresses to check (e.g. 'file.py::ClassName'). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_coord_swarm` MULTI-AGENT ENTRY POINT: Call this first when joining or starting a multi-agent session. Returns: active agents, symbols each agent has reserved, and task queue depths per queue. Use this to: - Understand who is working and what is already claimed - Decide which task queue to join - Detect if the swarm is idle (no active agents, no pending tasks) Follow-up tools: - musehub_read_coord_conflicts(addresses=[...]) before reserving symbols - musehub_list_coord_tasks(status='pending') to find claimable work - musehub_create_coord_reservation(...) to lock symbols before editing | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_cross_repo_impact` Compute the blast radius of a symbol across all repos in the owner's workspace. Returns local co-changed symbols (within the source repo) AND symbols from other repos that were modified during overlapping time windows — surfacing cross-repo coupling heuristically from shared commit timestamps. Example: musehub_read_cross_repo_impact(repo_id='a3f2-...', address='musehub.services.musehub_wire.wire_push'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `address` | string | yes | Fully-qualified symbol address to analyse. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_domain` Fetch the full manifest for a specific Muse domain plugin by its scoped ID. Returns all capabilities: dimensions list, viewer_type, merge_semantics, cli_commands, artifact_types, manifest_hash (content-addressed, immutable), version, repo_count, and install_count. Call this after musehub_read_context to understand the domain a repo uses, or before creating a repo to verify domain capabilities. Example: musehub_read_domain(scoped_id='@gabriel/midi'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scoped_id` | string | yes | Domain scoped identifier in '@author/slug' format. | --- #### `musehub_read_domain_insights` Get computed analytics for a MuseHub repository across any of its domain's dimensions. Returns numeric scores and structured metrics — e.g. harmonic tension score, rhythmic complexity, melodic contour for MIDI; symbol hotspots, coupling metrics for Code. The available dimensions are defined by the repo's domain plugin — call musehub_read_domain first to learn the dimension names. dimension='overview' always returns cross-domain stats (commits, objects, collaborators). Prefer musehub_read_context for structural understanding; use this tool when you need quantitative analysis of a specific dimension. For the viewer-ready state payload, use musehub_read_view instead. Example: musehub_read_domain_insights(repo_id='a3f2-...', dimension='harmonic'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `dimension` | string | no | Insight dimension to fetch. 'overview' is always available; other values depend on the repo's domain plugin. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `ref` | string | no | Branch name, tag, or commit SHA to scope the insights to. Defaults to HEAD. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_file` Read the metadata for a stored artifact (MIDI, MP3, WebP piano roll) in a MuseHub repo. Returns path, size_bytes, mime_type, and object_id. Binary content is not returned — discover object IDs via musehub_read_context first. Example: musehub_read_file(repo_id='a3f2-...', object_id='sha256:abc...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `object_id` | string | yes | Content-addressed object ID (e.g. 'sha256:abc...'). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_intel_blast_risk` Return symbols with the highest historical co-change blast radius. Each entry contains: address, co_change_count, top_co_symbols (up to 5). Sorted by co_change_count descending. Use to identify 'leverage points' — symbols where a change ripples farthest. Example: musehub_read_intel_blast_risk(repo_id='a3f2-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_intel_dead` Return dead code candidates — symbols added but rarely or never modified, cold for 90+ days. Each entry contains: address, days_cold, blast_radius, added_at. Sorted by days_cold descending (stalest first). Example: musehub_read_intel_dead(repo_id='a3f2-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_intel_health_score` Return the repository health score (0–100) and label ('Excellent'/'Good'/'Fair'/'Poor'/'Critical'). Also returns the four penalty components: dead_penalty, hotspot_penalty, coupling_penalty, breakage_penalty. Use before a release or after a large merge to gauge repo hygiene. Example: musehub_read_intel_health_score(repo_id='a3f2-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_intel_hotspots` Return symbols ranked by change frequency — the highest-churn code paths. Each entry contains: address, change_count, last_changed (ISO-8601). Results are sorted descending by change_count. Example: musehub_read_intel_hotspots(repo_id='a3f2-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_intel_index_status` Check whether the symbol index has been built for a repo, when it was last built, and how many symbols it contains. Returns status: 'ready' or 'not_built'. Example: musehub_read_intel_index_status(repo_id='a3f2-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_issue` Read a single issue by its per-repo number, including the full body and comment thread. Use musehub_list_issues to discover issue numbers, then this tool to read the detail. Example: musehub_read_issue(repo_id='a3f2-...', issue_number=42) or musehub_read_issue(owner='gabriel', slug='jazz-standards', issue_number=42). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `issue_number` | integer | yes | Per-repo issue number. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_prompt` Return the fully assembled content of a named MuseHub MCP prompt. This is a tool-layer shim over the MCP prompts/get primitive, enabling agents whose client only supports tools/call to access prompt content programmatically — identical output to prompts/get, callable as a tool. Use musehub_list_prompts() (prompts/list) to discover available prompt names. The eleven available prompts are: musehub/orientation, musehub/contribute, musehub/create, musehub/review_proposal, musehub/issue_triage, musehub/release_prep, musehub/onboard, musehub/safe-to-merge, musehub/pre-release-audit, musehub/agent-onboarding, musehub/symbol-investigation. Pass caller_type='agent' to musehub/orientation for agent-specific guidance. Example: musehub_read_prompt(name='musehub/orientation', arguments={'caller_type': 'agent'}). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `arguments` | object | no | Optional prompt arguments as string key-value pairs. E.g. {'caller_type': 'agent'} for musehub/orientation, {'repo_id': ''} for musehub/contribute, {'repo_id': '', 'proposal_id': ''} for musehub/review_proposal. | | `name` | string | yes | Prompt name to fetch, e.g. 'musehub/orientation' or 'musehub/review_proposal'. Must be one of the eleven musehub/* prompts. | --- #### `musehub_read_proposal` Read a single merge proposal by ID, including all reviews and inline dimension-anchored comments. Use musehub_list_proposals to discover proposal_ids, then this tool to read the full detail. Example: musehub_read_proposal(repo_id='a3f2-...', proposal_id='b5e8-...') or musehub_read_proposal(owner='gabriel', slug='jazz-standards', proposal_id='b5e8-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_proposal_breakage` Get the list of breaking changes for a merge proposal — symbols deleted or structurally modified in a way that breaks callers. An empty list means no breaking changes were detected across all commits. Example: musehub_read_proposal_breakage(repo_id='a3f2-...', proposal_id='b5e8-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_proposal_diff` Get the full symbol-level diff for a merge proposal — added, modified, and deleted named symbols across all commits on the from-branch. Returns sym_added, sym_modified, sym_deleted counts and all symbol addresses by category. Use this to understand the semantic scope of a proposal before reviewing or merging. Example: musehub_read_proposal_diff(repo_id='a3f2-...', proposal_id='b5e8-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_proposal_risk` Get the computed risk score for a merge proposal. Returns risk score (0-100), band (low/medium/high/critical), blast delta, breakage count, symbol totals, agent commit ratio, and signing status. Use this before merging to decide whether to require additional review. Example: musehub_read_proposal_risk(repo_id='a3f2-...', proposal_id='b5e8-...'). Pair with musehub/safe-to-merge prompt for a full pre-merge audit. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_symbol` Get the full history timeline for a single symbol address. Returns every commit that touched the symbol, with op type (add/modify/delete), content_id (body hash), and timestamp. Use this to understand how a symbol evolved, who changed it, and when. Repo identifier and address both required. Example: musehub_read_symbol(repo_id='a3f2-...', address='muse/core/store.py::CommitRecord') or musehub_read_symbol(owner='gabriel', slug='muse', address='muse/core/store.py::CommitRecord'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `address` | string | yes | Symbol address (e.g. 'file.py::ClassName::method') | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_view` Fetch the universal viewer payload for a repo at a given ref. Returns the structured representation of multidimensional state as rendered by the domain's viewer — dimension slices, navigation strip entries, and domain-specific viewer metadata. This is the MCP equivalent of the /{owner}/{repo}/insights/{ref} page. Use when you need the full state payload for reasoning or rendering. For quantitative analytics (scores, metrics), use musehub_read_domain_insights instead. For repo identity and inventory, use musehub_read_context instead. Example: musehub_read_view(repo_id='a3f2-...', ref='main') or musehub_read_view(owner='gabriel', slug='jazz-standards', ref='main'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `dimension` | string | no | Optional: restrict the view payload to a single dimension slice. Omit to get the full multi-dimensional view. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `ref` | string | no | Branch name, tag, or commit SHA. Defaults to HEAD of default branch. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_read_workspace_intel` Return a health overview for all repos in an owner's workspace. Includes per-repo symbol counts, health scores, and the top 10 cross-repo blast-risk symbols. Example: musehub_read_workspace_intel(owner='gabriel'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | yes | Owner username whose workspace to inspect. | --- #### `musehub_search` Search within a MuseHub repository by substring query. Mode 'path' matches artifact file paths (e.g. 'tracks/jazz'); mode 'commit' searches commit messages (e.g. 'add bass'). Returns matching items with their metadata. Example: musehub_search(repo_id='a3f2-...', query='bass', mode='path') or musehub_search(owner='gabriel', slug='jazz-standards', query='bass'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mode` | string | no | Search mode: 'path' searches object paths; 'commit' searches commit messages. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `query` | string | yes | Substring query string (case-insensitive). | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_search_repos` Discover public MuseHub repositories across all domains by text query, domain plugin, or free-text tags. Filter by domain scoped ID (e.g. '@gabriel/midi') to browse repos of a specific type. Returns repos sorted by relevance including repo_id, owner, and slug for each result. Example: musehub_search_repos(query='jazz', domain='@gabriel/midi'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `domain` | string | no | Filter by domain scoped ID, e.g. '@gabriel/midi' or '@gabriel/code'. | | `limit` | integer | no | Maximum results to return (default: 20, max: 100). | | `query` | string | no | Free-text query matched against repo names and descriptions. | | `tags` | array | no | Filter repos that have all of these tags. | --- #### `musehub_set_context` Set the session's focused repository. After calling this, all subsequent tool calls that accept owner/slug will use this repo automatically — you no longer need to pass owner+slug on every call. Calling again with different owner/slug switches focus. Example: musehub_set_context(owner='gabriel', slug='jazz-standards') then musehub_list_branches() with no other args. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | yes | Repository owner username. | | `slug` | string | yes | Repository slug (URL-safe name). | --- #### `musehub_symbol_clones` Find symbols that share the exact same body hash as the given symbol (clones / duplicates). Uses hash_occurrence index for O(1) lookup. Example: musehub_symbol_clones(repo_id='a3f2-...', address='muse/core/store.py::_utc_now'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `address` | string | yes | Symbol address to find clones of | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_symbol_impact` Get the blast radius for a symbol: which other symbols are co-changed with it most frequently. Uses commit co-occurrence analysis — if symbols A and B are modified in the same commits often, they are likely coupled. Essential before refactoring: reveals hidden dependencies. Returns co_changed list sorted by shared_commit_count descending. Example: musehub_symbol_impact(repo_id='a3f2-...', address='muse/core/store.py::CommitRecord'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `address` | string | yes | Symbol address | | `depth` | integer | no | | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_whoami` Return identity information for the currently authenticated caller. Call this first to confirm authentication before any write operations. Works for both human users and AI agent tokens. Authenticated response includes: user_id (handle), username (handle), display_name, repo_count, is_admin, and token_type ('human' or 'agent'). Returns {authenticated: false} when called without a valid MSign header — never errors. Example: musehub_whoami(). _No parameters._ --- ### Write Tools (73) #### `muse_config` Read info about Muse configuration keys or generate a 'muse config set' command. Equivalent to 'muse config get ' or 'muse config set '. Call without arguments to list all known config keys. Pass key and value to get the exact CLI command to run. Repo-level keys (stored in .muse/config.toml): hub.url, user.type. Auth tokens are stored per-hub in ~/.muse/identity.toml — use 'muse auth login' or write the token directly under the hub hostname section. Example: muse_config(key='hub.url', value='https://musehub.ai'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `key` | string | no | Configuration key to query or set (e.g. 'hub.url', 'user.type'). Note: auth tokens live in ~/.muse/identity.toml, not config.toml. Omit to list all known keys. | | `value` | string | no | When provided together with key, returns the CLI command 'muse config set '. | --- #### `muse_mist_create` Publish a new content-addressed, cryptographically signed Mist. The mist_id is derived automatically from the artifact content (SHA-256 → base-58, 12 chars) — identical content from any owner produces the same mist_id. Artifact type and language are detected from filename and content. Symbol anchors are extracted automatically for Python/JS/TS code. Rate-limited to 20 creates per minute per handle. Example: muse_mist_create(filename='validate.py', content='def validate(x): ...', title='Handle validation primitive', tags=['security', 'utils']) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | no | Agent identifier for AI-authored mists. | | `content` | string | yes | Artifact content (UTF-8 text, or base64 for binary). Must not be empty. | | `description` | string | no | Optional Markdown description. | | `filename` | string | yes | Original filename (used for type detection). Must not be empty. | | `gpg_signature` | string | no | ASCII-armoured Ed25519 signature (optional). | | `model_id` | string | no | Model identifier for AI provenance. | | `tags` | array | no | Freeform tags (max 10). | | `title` | string | no | Optional human-readable title. | | `visibility` | string | no | Visibility: 'public' (default) or 'secret'. | --- #### `muse_mist_delete` Permanently delete a Mist and its underlying Muse repository. Only the mist owner may delete. The backing repo (commits, snapshots) is removed via cascade. This action is irreversible. Example: muse_mist_delete(mist_id='aB3xKq9dPwNm') | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mist_id` | string | yes | 12-character mist ID to delete. | --- #### `muse_mist_fork` Fork an existing Mist into the authenticated caller's namespace. The fork inherits the source content and metadata but gets a new mist_id and owner. The source's fork_count is incremented. Fork depth is enforced (max 5 levels). Rate-limited to 30 forks per minute per handle. Example: muse_mist_fork(mist_id='aB3xKq9dPwNm') | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mist_id` | string | yes | mist_id of the Mist to fork. | --- #### `muse_mist_update` Update a mist's metadata or replace its content. Only the mist owner may update. Fields that are omitted are left unchanged (partial update). Replacing content increments the version counter. Example: muse_mist_update(mist_id='aB3xKq9dPwNm', title='Better title', visibility='secret') | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | string | no | New artifact content (omit to leave unchanged). Increments version. | | `description` | string | no | New Markdown description (omit to leave unchanged). | | `mist_id` | string | yes | 12-character mist ID to update. | | `tags` | array | no | New tag list (omit to leave unchanged). | | `title` | string | no | New title (omit to leave unchanged). | | `visibility` | string | no | New visibility (omit to leave unchanged). | --- #### `muse_push` Push commits, snapshots, and binary objects to a MuseHub repository. Equivalent to 'muse push' — uploads new commits, their snapshot manifests, and base64-encoded binary objects in a single atomic batch. Enforces fast-forward semantics unless force=true. All three arrays are optional — a push with only commits and no new file content is valid (e.g. a merge commit that modifies no files). Authentication required: use `muse auth keygen` + `muse auth register --agent`. Example: muse_push(repo_id='a3f2-...', branch='main', head_commit_id='abc123', commits=[{commit_id, parent_ids, message, snapshot_id, ...}], snapshots=[{snapshot_id, manifest:{path: object_id}}], objects=[{object_id, path, content_b64}]). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `blobs` | array | no | List of blob objects to upload. Each has: object_id (str, e.g. 'sha256:abc...'), path (str, e.g. 'tracks/bass.mid'), content_b64 (str, base64-encoded bytes). | | `branch` | string | yes | Target branch name (e.g. 'main'). | | `commits` | array | no | List of CommitInput objects to push. Each has: commit_id (str), parent_ids (list[str]), message (str), author (str), timestamp (ISO-8601 str), snapshot_id (str). | | `force` | boolean | no | Allow non-fast-forward push (overwrites remote head). Use with caution. | | `head_commit_id` | string | yes | SHA of the new HEAD commit after this push. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `snapshots` | array | no | Snapshot manifests for the pushed commits. Each has: snapshot_id (str, SHA-256 of sorted path:oid pairs), manifest (dict[str, str] mapping path → object_id), created_at (ISO-8601 str, optional). Snapshots are idempotent — already-stored snapshots are skipped. Include one snapshot per commit that introduces file changes. | --- #### `musehub_accept_collaborator_invite` Accept the caller's own pending collaborator invitation on a repository. Self-service — there is no target handle; the caller accepts the invitation addressed to their own authenticated identity. Idempotent. Example: musehub_accept_collaborator_invite(repo_id='a3f2-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_agent_broadcast` Broadcast a real-time signal to ALL agents focused on the same repo via SSE. Delivers notifications/agent_message to every active MCP session whose repo focus matches your current session focus (set via musehub_set_context). Your own session is excluded. Use cases: - Swarm coordination: 'Starting merge, pause your pushes' - Progress updates: 'Analysis complete, results in task queue' - Phase transitions: 'Phase 1 done, all workers proceed to phase 2' Requires musehub_set_context(owner, slug) to be called first. Returns sessions_reached=0 (not an error) when no other agents are focused on the repo. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `event` | string | yes | Short signal name (e.g. 'phase_complete', 'merge_starting', 'results_ready'). | | `payload` | object | yes | Arbitrary JSON payload for receiving agents. | --- #### `musehub_agent_notify` Send a real-time signal to another agent's active MCP session(s) via SSE. The target agent receives a notifications/agent_message event on their GET /mcp SSE stream immediately — no polling needed. Use cases: - Handoff: 'I finished processing the repo, your turn' - Unblock: 'I released the reservation on AudioEngine, you can proceed' - Coordinate: 'I found a conflict in track 3, assigning to you' target_handle is the MSign handle (username) of the receiving agent. event is a short string naming the signal (e.g. 'task_complete', 'handoff', 'conflict_found'). payload is arbitrary JSON for the receiver to act on. Returns sessions_reached=0 with not_ready error if the target has no active sessions. Check musehub_read_coord_swarm() to see which agents are currently connected. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `event` | string | yes | Short signal name (e.g. 'task_complete', 'handoff', 'unblocked'). | | `payload` | object | yes | Arbitrary JSON payload for the receiving agent. | | `target_handle` | string | yes | MSign handle (username) of the target agent to notify. | --- #### `musehub_assign_issue` Assign or unassign a collaborator on an issue. Pass assignee='' to unassign. Example: musehub_assign_issue(repo_id='a3f2-...', issue_number=42, assignee='gabriel'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `assignee` | string | yes | Username to assign, or empty string to unassign. | | `issue_number` | integer | yes | Per-repo issue number. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_attach_release_asset` Attach a downloadable asset file to an existing release. Assets represent build artifacts, MIDI bundles, model checkpoints, or any file associated with a release. Requires write/admin access or repo ownership. The release must already exist (create it with musehub_create_release first). Example: musehub_attach_release_asset(repo_id='a3f2-...', tag='v1.2.3', name='myapp-v1.2.3-linux.tar.gz', download_url='https://cdn.example.com/myapp-v1.2.3-linux.tar.gz'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content_type` | string | no | MIME type of the artifact (e.g. 'application/gzip'). | | `download_url` | string | yes | Direct download URL for the artifact. | | `label` | string | no | Optional human-readable label (e.g. 'Linux bundle'). | | `name` | string | yes | Filename shown in the UI (e.g. 'myapp-v1.2.3-linux.tar.gz'). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `size` | integer | no | File size in bytes (0 if unknown). | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `tag` | string | yes | Release tag the asset belongs to (e.g. 'v1.2.3'). | --- #### `musehub_claim_coord_task` TASK QUEUE PROTOCOL — Worker step 2: Atomically claim a pending task. Atomic: only one agent can claim a given task even under concurrent calls. Returns the task record with status='claimed' on success. Returns task_not_found if the task is already claimed, completed, or doesn't exist — call musehub_list_coord_tasks(status='pending') to find currently claimable tasks. After claiming: - Execute the work described in the task payload - Call musehub_complete_coord_task when done - Call musehub_fail_coord_task if an unrecoverable error occurs - Do not abandon a claimed task — it blocks the queue until TTL expiry | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | yes | Identifier of the claiming agent (e.g. 'agentception-worker-42'). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `task_id` | string | yes | ID of the task to claim. | --- #### `musehub_close_issue` Close an open issue. Idempotent — closing an already-closed issue returns the issue unchanged. Use musehub_reopen_issue to reverse. Example: musehub_close_issue(repo_id='a3f2-...', issue_number=42). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `issue_number` | integer | yes | Per-repo issue number. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_complete_coord_task` TASK QUEUE PROTOCOL — Worker step 3a: Mark your claimed task as completed. The agent_id must match the agent that claimed the task. Attach a result payload with any output the orchestrator needs (e.g. commit_id, analysis summary, generated file paths). Returns task_not_found if the task is not claimed by this agent. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | yes | Agent ID that claimed this task. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `result` | object | no | Optional JSON result payload to attach to the completed task. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `task_id` | string | yes | ID of the claimed task to complete. | --- #### `musehub_create_coord_reservation` SYMBOL EDITING PROTOCOL — Step 2 of 3: Reserve symbol addresses before editing them. Step 1: musehub_read_coord_conflicts(addresses=[...]) — verify symbols are free. Step 2: musehub_create_coord_reservation(addresses=[...], agent_id='...', ttl_s=300) — lock them. Step 3: Do your work, then musehub_delete_coord_reservation(reservation_id='...') when done. If another agent has the symbols reserved, read_coord_conflicts will tell you — wait and retry rather than proceeding without a reservation. One reservation_id covers all addresses in the batch. Default TTL is 300s (5 min). Extend with musehub_extend_coord_reservation if work takes longer. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `addresses` | array | yes | Symbol addresses to reserve (e.g. 'src/engine.py::AudioEngine'). | | `agent_id` | string | yes | Identifier of the reserving agent (e.g. 'agentception-worker-42'). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `ttl_s` | integer | no | Reservation TTL in seconds (30–3600, default 300). | --- #### `musehub_create_issue` Open a new issue in a MuseHub repository. Use issues to track bugs, feature requests, or work items — anchored directly to Muse symbols and commits so agents can trace issues back to the exact code that needs changing. Always supply symbol_anchors (e.g. 'musehub/services/foo.py::create_foo') and commit_anchors when the issue originates from specific code or a specific commit. When filing on behalf of an AI agent, set agent_id and model_id for full provenance. Example: musehub_create_issue(repo_id='a3f2-...', title='fix: crash in create_issue', symbol_anchors=['musehub/services/musehub_issues.py::create_issue'], agent_id='agentception-worker-42', model_id='claude-sonnet-4-6') or musehub_create_issue(owner='gabriel', slug='musehub', title='perf: slow list_issues'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | no | Agent identifier when filing on behalf of an AI agent (e.g. 'agentception-worker-42'). Leave empty for human-filed issues. | | `body` | string | no | Optional markdown description of the issue. | | `commit_anchors` | array | no | Muse commit IDs this issue is anchored to. Use when the issue was introduced by or relates to a specific commit. Obtain commit IDs via muse log --json. | | `labels` | array | no | Label strings to apply on creation. | | `model_id` | string | no | Model identifier when filing on behalf of an AI agent (e.g. 'claude-sonnet-4-6', 'claude-opus-4-6'). Leave empty for human-filed issues. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `symbol_anchors` | array | no | Muse symbol addresses this issue is anchored to. Format: 'path/to/file.py::SymbolName' or 'path/to/file.py::Class.method'. Obtain these via muse code grep or muse code symbols before filing the issue. Example: ['musehub/services/musehub_issues.py::create_issue', 'musehub/db/musehub_models.py::MusehubIssue'] | | `title` | string | yes | Issue title. | --- #### `musehub_create_issue_comment` Add a comment to an existing issue. Example: musehub_create_issue_comment(repo_id='a3f2-...', issue_number=42, body='Fixed in commit abc...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `body` | string | yes | Markdown comment body. | | `issue_number` | integer | yes | Per-repo issue number. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_create_label` Create a repo-scoped label with a name and hex colour. Labels can be applied to issues and proposals for categorisation. Label names must be unique within the repository (max 50 chars). Color must be a 7-character hex string starting with '#' (e.g. '#d73a4a'). Example: musehub_create_label(repo_id='a3f2-...', name='bug', color='#d73a4a'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `color` | string | yes | 7-character hex colour starting with '#' (e.g. '#d73a4a'). | | `description` | string | no | Optional label description (max 200 chars). | | `name` | string | yes | Label name (unique per repo, max 50 chars). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_create_proposal` Open a new merge proposal proposing to merge from_branch into to_branch. Call musehub_list_branches first to confirm both branches exist. Supports draft proposals, domain-selective merge strategies, and DAG-based dependency ordering. Example: musehub_create_proposal(repo_id='a3f2-...', title='Add jazz bridge', from_branch='feature/jazz-bridge', to_branch='main', merge_strategy='weave'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `body` | string | no | Optional markdown description. | | `depends_on` | array | no | Proposal IDs that must be merged before this one (DAG ordering). | | `from_branch` | string | yes | Source branch name to merge from. | | `is_draft` | boolean | no | Open as a draft (not ready for review). Default false. | | `merge_conditions` | object | no | Optional JSON object with additional merge gate conditions. | | `merge_strategy` | string | no | How branches are merged. Default 'overlay'. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_type` | string | no | Semantic proposal type. Defaults to 'merge'. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `selective_domains` | array | no | Domain names to include when merge_strategy='selective'. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `title` | string | yes | Merge proposal title. | | `to_branch` | string | yes | Target branch name to merge into. | --- #### `musehub_create_proposal_comment` Post a comment on a merge proposal, optionally anchored to a specific symbol address. Use symbol_address to pin the comment directly to a named symbol in the Symbol Delta (e.g. 'core/engine.py::Engine.process'). For non-code domains, pass dimension_ref instead to target a track, beat region, or note. Omit both for a general proposal-level comment. Example: musehub_create_proposal_comment(repo_id='a3f2-...', proposal_id='b5e8-...', body='This symbol has a blast radius of 34 — needs test coverage', symbol_address='core/engine.py::Engine.process'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `body` | string | yes | Markdown comment body. | | `dimension_ref` | object | no | Optional domain-specific anchor for non-code domains (MIDI, genomics, etc.). Schema is defined by the repo's domain plugin. Prefer symbol_address for code-domain proposals. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `parent_comment_id` | string | no | ID of the parent comment when creating a threaded reply. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `symbol_address` | string | no | Symbol address to anchor this comment to (e.g. 'core/engine.py::Engine.process'). Use the addresses returned by musehub_read_proposal symAdded/symModified/symDeleted. Takes precedence over dimension_ref for code-domain proposals. | --- #### `musehub_create_proposal_review` Submit a formal review on a merge proposal. event='approve' approves the proposal; event='request_changes' blocks merge; event='comment' adds a neutral review comment. Example: musehub_create_proposal_review(repo_id='a3f2-...', proposal_id='b5e8-...', event='approve', body='Sounds great! The bridge lands perfectly.'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `body` | string | no | Optional review summary. | | `event` | string | yes | Review verdict: 'approve', 'request_changes', or 'comment'. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_create_release` Publish a new release for a MuseHub repository. A release pins a version tag to a commit and packages the state snapshot. Tags must be unique per repo (e.g. 'v1.0', 'final-mix'). For an interactive release flow with elicitation, use musehub_create_release_interactive. Example: musehub_create_release(repo_id='a3f2-...', tag='v1.0', title='First Release', body='Initial session recording.'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `body` | string | no | Markdown release notes. | | `commit_id` | string | no | Optional commit SHA to pin this release to. Defaults to HEAD of the default branch. | | `is_prerelease` | boolean | no | When true, marks as pre-release. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `tag` | string | yes | Version tag string (e.g. 'v1.0'). Must be unique per repo. | | `title` | string | yes | Human-readable release title. | --- #### `musehub_create_repo` Create a new MuseHub repository for any Muse domain. The slug is auto-generated from the name. Specify a domain scoped ID (e.g. '@gabriel/midi') to associate the repo with a domain plugin — this unlocks domain-specific viewers, insights, and CLI commands. Call musehub_list_domains first to discover available domains. Set initialize=true (default) to get an initial commit and default branch. Example: musehub_create_repo(name='Genome Edit Session', domain='@alice/genomics', visibility='public'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `description` | string | no | Optional markdown description of the repository. | | `domain` | string | no | Domain plugin scoped ID (e.g. '@gabriel/midi', '@gabriel/code'). Call musehub_list_domains first to discover available domains. | | `domain_meta` | object | no | Domain-specific metadata dict declared by the domain plugin. | | `initialize` | boolean | no | When true (default), creates an initial commit and default branch. | | `name` | string | yes | Human-readable repository name (slug auto-generated). | | `tags` | array | no | Free-form tags for discovery (e.g. ['jazz', 'trio']). | | `visibility` | string | no | Repository visibility: 'public' or 'private'. | --- #### `musehub_create_user_profile` Create a MuseHub user profile for the authenticated identity. Distinct from identity registration — the keypair-backed identity must already exist (muse auth register); this creates the social profile on top. Example: musehub_create_user_profile(username='gabriel', bio='Composer and engineer'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `avatar_url` | string | no | Avatar image URL. | | `bio` | string | no | Profile bio text. | | `username` | string | yes | URL-safe username to register. | --- #### `musehub_create_webhook` Register a new webhook subscription for a repository. The webhook URL will receive HTTP POST payloads for each subscribed event type. Valid event types: push, proposal, issue, release, branch, tag, session, analysis. Requires write/admin access or repo ownership. The secret is used to compute an HMAC-SHA256 signature on each payload (sent in the X-MuseHub-Signature header). Example: musehub_create_webhook(repo_id='a3f2-...', url='https://example.com/hook', events=['push', 'release']). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `events` | array | yes | Event types to subscribe to. Valid: push, proposal, issue, release, branch, tag, session, analysis. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `secret` | string | no | Optional HMAC-SHA256 signing secret (plaintext). Store securely. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `url` | string | yes | HTTPS URL that will receive event payloads. | --- #### `musehub_delete_coord_reservation` SYMBOL EDITING PROTOCOL — Step 3 of 3: Release a reservation when done editing. Always release after your work is committed so other agents can proceed. If you crash or forget, the TTL will expire the reservation automatically. Use the reservation_id returned by musehub_create_coord_reservation. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | yes | Agent ID that created the reservation. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `reservation_id` | string | yes | ID returned by musehub_create_coord_reservation. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_delete_issue_comment` Soft-delete a comment from an issue. Deleted comments are hidden from list results but preserved in the audit log. Requires write/admin access or repo ownership. Get comment_id from musehub_list_issue_comments or the comment creation response. Example: musehub_delete_issue_comment(repo_id='a3f2-...', issue_number=42, comment_id='sha256:...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `comment_id` | string | yes | sha256 genesis ID of the comment to delete. | | `issue_number` | integer | yes | Per-repo issue number. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_delete_label` Permanently delete a label from a MuseHub repository and remove it from every issue and proposal it is currently attached to. This operation is irreversible. Get label_id from musehub_list_labels. Example: musehub_delete_label(repo_id='sha256:...', label_id='sha256:...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `label_id` | string | yes | ID of the label to delete (from musehub_list_labels). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_delete_release_asset` Permanently remove an asset from a release. This operation is irreversible — the download URL remains valid only if the external storage is not also deleted. Requires write/admin access or repo ownership. Get asset_id from musehub_list_release_assets or the asset creation response. Example: musehub_delete_release_asset(repo_id='a3f2-...', tag='v1.2.3', asset_id='sha256:...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `asset_id` | string | yes | ID of the asset to remove (from musehub_list_release_assets). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `tag` | string | yes | Release tag the asset belongs to. | --- #### `musehub_delete_repo` Soft-delete a MuseHub repository. Only the repo owner may delete. Data is retained for audit; subsequent reads return 404. Example: musehub_delete_repo(repo_id='a3f2-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_delete_user_account` Delete a MuseHub account — the caller's own (GDPR Article 17 right to erasure), or, for an admin caller, a different account. Hard-deletes all registered auth keys and soft-deletes the identity. Deleting another account requires the caller to have admin privileges — enforced server-side. Example: musehub_delete_user_account(username='gabriel'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `username` | string | yes | Handle of the account to delete. | --- #### `musehub_delete_webhook` Delete a webhook subscription and all its delivery history. This operation is irreversible. Requires write/admin access or repo ownership. Get webhook_id from musehub_list_webhooks. Example: musehub_delete_webhook(repo_id='sha256:...', webhook_id='sha256:...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `webhook_id` | string | yes | ID of the webhook to delete (from musehub_list_webhooks). | --- #### `musehub_enqueue_coord_task` TASK QUEUE PROTOCOL — Orchestrator step: Enqueue a task for worker agents to claim. Full task lifecycle: Orchestrator: musehub_enqueue_coord_task(queue='...', payload={...}, agent_id='orchestrator') → task_id Worker: musehub_list_coord_tasks(status='pending') → find claimable tasks Worker: musehub_claim_coord_task(task_id='...', agent_id='worker-N') → atomic claim Worker: [do the work] Worker: musehub_complete_coord_task(task_id='...', agent_id='worker-N', result={...}) or musehub_fail_coord_task(task_id='...', agent_id='worker-N', reason='...') Priority 0–100 (higher = processed first). Default 50. Use depends_on to declare task_ids this task should wait for. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | yes | Agent creating this task (e.g. 'orchestrator', 'agentception-main'). | | `depends_on` | array | no | task_ids this task depends on (informational, not enforced by server). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `payload` | object | yes | Arbitrary JSON payload describing the task for the worker. | | `priority` | integer | no | Task priority 0–100. Higher is processed first. Default 50. | | `queue` | string | yes | Queue name (e.g. 'tasks', 'analysis', 'review'). | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_extend_coord_reservation` SYMBOL EDITING PROTOCOL — Optional: Extend a reservation's TTL mid-work. Call this if your editing work will exceed the original TTL before you can release. Extend by 30–3600 seconds (default 300 / 5 min). Better to extend proactively than to let the reservation expire — an expired reservation allows other agents to reserve the same symbols. Use the reservation_id returned by musehub_create_coord_reservation. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `extend_by_s` | integer | no | Seconds to add to the current expiry (30–3600, default 300). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `reservation_id` | string | yes | ID of the reservation to extend. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_fail_coord_task` TASK QUEUE PROTOCOL — Worker step 3b: Mark your claimed task as failed. Use this when the task cannot be completed (error, conflict, missing dependency). Include a reason so the orchestrator can diagnose and re-enqueue or escalate. The agent_id must match the agent that claimed the task. Returns task_not_found if the task is not claimed by this agent. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | yes | Agent ID that claimed this task. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `reason` | string | no | Human-readable reason the task failed. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `task_id` | string | yes | ID of the claimed task to fail. | --- #### `musehub_fork_repo` Fork a public MuseHub repository into your account. Creates a new repository owned by the authenticated caller, copies the source repo's tags and description, and records the fork relationship. Rules: the source repo must be public; you cannot fork your own repo; you cannot fork the same repo twice (returns conflict). The fork is public by default — pass visibility='private' for a private fork. Returns full fork metadata including fork_id, fork_repo_id, and source attribution. Example: musehub_fork_repo(source_repo_id='a3f2-...', name='my-fork'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `description` | string | no | Description for the fork. Defaults to 'Fork of {owner}/{slug}: {source description}'. | | `name` | string | no | Name for the new fork (slug auto-generated). Defaults to the source repo's name. | | `source_repo_id` | string | yes | sha256 genesis ID of the public repository to fork. | | `visibility` | string | no | Visibility of the fork: 'public' (default) or 'private'. | --- #### `musehub_get_mpay_ledger` Return the MPay ledger for a handle — sent and received claims with totals. limit is clamped to 500. Example: musehub_get_mpay_ledger(handle='gabriel', limit=50). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `handle` | string | yes | MSign handle whose ledger to return. | | `limit` | integer | no | Max claims per direction (clamped to 500). | --- #### `musehub_get_proposal` Read a single merge proposal with full enrichment: blocked_by, blocks, is_blocked, and latest_simulations (conflict_scan / risk_projection / dependency_order results). Use this when you need the complete proposal picture including DAG position and simulation cache. Authentication required. Example: musehub_get_proposal(repo_id='sha256:...', proposal_id='sha256:...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_get_proposal_simulation` Read the cached simulation result for a merge proposal without recomputing. Returns error_code='not_found' when no simulation has been run yet — call musehub_run_proposal_simulation first. Check is_stale: when True, the from-branch has advanced and results may be outdated. Example: musehub_get_proposal_simulation(repo_id='sha256:...', proposal_id='sha256:...', simulation_type='risk_projection'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `simulation_type` | string | yes | Type of simulation to read. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_invite_collaborator` Invite a user as a collaborator on a repository. Requires the caller to be the repo owner or have admin permission. Permission levels: read (view only), write (push + issue management), admin (write + invite/remove collaborators). Returns error_code='conflict' if the user is already a collaborator. Example: musehub_invite_collaborator(repo_id='a3f2-...', handle='carol', permission='write'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `handle` | string | yes | MSign handle of the user to invite. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `permission` | string | no | Permission level: 'read', 'write' (default), or 'admin'. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_issue_attestation` Issue a cryptographically-verified attestation about a MuseHub identity. The caller must supply an Ed25519 signature over ATTEST {attester} {subject} {claim} {issued_at_iso}. Idempotent — re-issuing the same attestation returns the existing record. Example: musehub_issue_attestation(attester='gabriel', subject='aria', claim='{"type":"human"}', issued_at_iso='2026-04-21T12:00:00+00:00', signature='ed25519:...', attester_public_key='ed25519:...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `attester` | string | yes | Handle of the attesting identity. | | `attester_public_key` | string | yes | Attester public key; 'ed25519:'. | | `claim` | string | yes | JSON claim payload. | | `issued_at_iso` | string | yes | ISO-8601 timestamp of issuance. | | `signature` | string | yes | Ed25519 signature; 'ed25519:'. | | `subject` | string | yes | Handle of the attested identity. | --- #### `musehub_list_attestations` List all attestations about a subject identity. Set include_revoked=true to include revoked attestations. Example: musehub_list_attestations(subject='aria'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `include_revoked` | boolean | no | Include revoked attestations. | | `subject` | string | yes | Handle of the identity whose attestations to list. | --- #### `musehub_list_collaborators` List all collaborators for a repository with their permission levels. Returns read, write, admin, and owner entries. Authentication required. Example: musehub_list_collaborators(repo_id='a3f2-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_list_issue_comments` List all non-deleted comments on an issue, oldest first. Returns commentId, author, body, createdAt for each comment. Call musehub_read_issue first to confirm the issue exists. Example: musehub_list_issue_comments(repo_id='a3f2-...', issue_number=42). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `cursor` | string | no | Pagination cursor from a previous nextCursor value. | | `issue_number` | integer | yes | Per-repo issue number. | | `limit` | integer | no | Max comments to return (default 100). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_list_proposal_comments` Return all review comments for a merge proposal, threaded by parent. Each top-level comment includes a 'replies' list of direct children. Authentication required. Example: musehub_list_proposal_comments(repo_id='sha256:...', proposal_id='sha256:...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_list_proposal_reviews` Return all reviews for a merge proposal, optionally filtered by state. States: 'pending', 'approved', 'changes_requested', 'dismissed'. Authentication required. Example: musehub_list_proposal_reviews(repo_id='sha256:...', proposal_id='sha256:...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `state` | string | no | Optional state filter. Omit to return all reviews. | --- #### `musehub_list_proposal_simulations` List all cached simulations for a merge proposal (up to 3 — one per type). Each entry includes is_stale so you can identify which simulations need refreshing. Returns an empty list when no simulations have been run. Example: musehub_list_proposal_simulations(repo_id='sha256:...', proposal_id='sha256:...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_list_release_assets` List all assets attached to a release. Returns assetId, name, label, contentType, size, downloadUrl, downloadCount. Example: musehub_list_release_assets(repo_id='a3f2-...', tag='v1.0.0'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `cursor` | string | no | | | `limit` | integer | no | | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `tag` | string | yes | Release tag. | --- #### `musehub_list_topics` Browse all topics registered on MuseHub with their repo counts. Filter by substring query. Example: musehub_list_topics(query='jazz'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | no | | | `query` | string | no | Substring filter on topic names. | --- #### `musehub_list_webhook_deliveries` List recent delivery attempts for a webhook. Returns deliveryId, event, status, statusCode, duration, createdAt per delivery. Use deliveryId with musehub_redeliver_webhook to retry a failed delivery. Example: musehub_list_webhook_deliveries(repo_id='sha256:...', webhook_id='sha256:...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `cursor` | string | no | | | `limit` | integer | no | | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `webhook_id` | string | yes | ID of the webhook. | --- #### `musehub_list_webhooks` List all webhook subscriptions for a repository. Returns webhook IDs, URLs, event subscriptions, and active status. Authentication required. Example: musehub_list_webhooks(repo_id='a3f2-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_merge_proposal` Merge an open merge proposal. Creates a merge commit on the target branch. The proposal must be in 'open' state. Obtain proposal_id from musehub_list_proposals. Example: musehub_merge_proposal(repo_id='a3f2-...', proposal_id='b5e8-...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `merge_strategy` | string | no | Merge strategy: 'merge_commit' (default), 'squash', or 'rebase'. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal to merge. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_publish_domain` Register a new Muse domain plugin in the MuseHub marketplace. After registration the domain appears in musehub_list_domains and can be selected when creating repos (musehub_create_repo). The scoped identifier '@{author_slug}/{slug}' must be globally unique. Authentication required: use `muse auth keygen` + `muse auth register --agent`. 'viewer_type' is a top-level parameter (not part of 'capabilities') and must be one of: 'generic', 'symbol_graph', 'piano_roll' — any other value is rejected with a 422; there is no custom-viewer option. The 'capabilities' object follows the Muse domain schema, all keys optional: dimensions: list of {name, description} objects (max 50) artifact_types: list of MIME types the domain produces merge_semantics: 'ot' | 'crdt' | 'three_way' supported_commands: list of muse CLI commands this domain supports Returns: {domain_id, scoped_id, manifest_hash} on success. Example: musehub_publish_domain(author_slug='gabriel', slug='genomics', display_name='Genomics', description='Version DNA sequences', capabilities={...}, viewer_type='generic', version='0.1.0'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `author_slug` | string | yes | Your MuseHub username (owner of the domain). | | `capabilities` | object | yes | Domain capabilities manifest. Recognized keys, all optional (default to empty/safe values): dimensions (list of {name, description}, max 50), artifact_types (list of MIME strings), merge_semantics ('ot'\|'crdt'\|'three_way'), supported_commands (list of muse CLI command names). Serialized manifest is capped at 16 KB. Does not include viewer_type — that is a separate top-level parameter. | | `description` | string | yes | What this domain models and why it benefits from semantic VCS. | | `display_name` | string | yes | Human-readable name shown in the marketplace. | | `slug` | string | yes | URL-safe domain name (e.g. 'genomics', 'spatial-3d'). | | `version` | string | no | Semver string (e.g. '0.1.0'). | | `viewer_type` | string | yes | Built-in viewer for rendering this domain's files. Must be one of: 'generic', 'symbol_graph', 'piano_roll' — any other value is rejected with a 422; there is no custom-viewer option. | --- #### `musehub_read_profile_manifest` Return the full archetype-aware profile manifest for a MuseHub identity. Includes identity_type, activity canvas (5 domains × 364-day grids), attestation badges, avax_address (human), agent_model + trust_chain (agent), org manifest (org), and MPay ledger totals. Example: musehub_read_profile_manifest(handle='gabriel'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `handle` | string | yes | MSign handle of the identity. | --- #### `musehub_read_user_profile` Fetch a user's public profile: bio, avatarUrl, repoCount, followerCount, followingCount, pinnedRepos. No auth required — profiles are publicly accessible. Example: musehub_read_user_profile(username='gabriel'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `username` | string | yes | MuseHub username. | --- #### `musehub_record_mpay_claim` Record a verified MPay micropayment claim. The caller must supply an Ed25519 signature over MPAY {sender} {recipient} {amount_nano} {nonce_hex}. Idempotent on nonce_hex. amount_nano must be > 0 and sender != recipient. Example: musehub_record_mpay_claim(sender='gabriel', recipient='aria', amount_nano=500000, nonce_hex='bb...bb', signature='ed25519:...', sender_public_key='ed25519:...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `amount_nano` | integer | yes | Payment in nanoMUSE (> 0). | | `memo` | string | no | Optional payment memo. | | `nonce_hex` | string | yes | 64-char hex nonce for replay protection. | | `recipient` | string | yes | Handle of the payee. | | `sender` | string | yes | Handle of the payer. | | `sender_public_key` | string | yes | Sender public key; 'ed25519:'. | | `signature` | string | yes | Ed25519 signature; 'ed25519:'. | --- #### `musehub_redeliver_webhook` Re-send a previously attempted webhook delivery. Requires the webhook_id and the delivery_id to retry. Example: musehub_redeliver_webhook(repo_id='sha256:...', webhook_id='sha256:...', delivery_id='sha256:...'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `delivery_id` | string | yes | ID of the delivery to redeliver. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `webhook_id` | string | yes | ID of the webhook. | --- #### `musehub_remove_collaborator` Remove a collaborator from a repository. Requires admin or owner access. The repository owner cannot be removed. Example: musehub_remove_collaborator(repo_id='a3f2-...', handle='carol'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `handle` | string | yes | MSign handle of the collaborator to remove. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_remove_issue_label` Remove a single label from an issue. Idempotent — no-ops when the label is not present. Use musehub_update_issue_labels to replace the entire label list. Example: musehub_remove_issue_label(repo_id='a3f2-...', issue_number=42, label='bug'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `issue_number` | integer | yes | Per-repo issue number. | | `label` | string | yes | Label name to remove. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_remove_proposal_reviewer` Remove a pending review request from a merge proposal. Only 'pending' rows can be removed — submitted reviews are immutable. Requires write/admin access or repo ownership. Example: musehub_remove_proposal_reviewer(repo_id='a3f2-...', proposal_id='sha256:...', reviewer='alice'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `reviewer` | string | yes | MSign handle of the reviewer to remove. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_reopen_issue` Reopen a closed issue. Idempotent — reopening an already-open issue returns the issue unchanged. Use musehub_close_issue to close. Example: musehub_reopen_issue(repo_id='a3f2-...', issue_number=42). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `issue_number` | integer | yes | Per-repo issue number. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_request_proposal_reviewers` Request one or more reviewers on a merge proposal. Idempotent: requesting an already-assigned reviewer leaves their state unchanged. Requires write/admin access or repo ownership. Example: musehub_request_proposal_reviewers(repo_id='a3f2-...', proposal_id='sha256:...', reviewers=['alice', 'bob']). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `reviewers` | array | yes | List of MSign handles to request as reviewers. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_revoke_attestation` Revoke an attestation by ID. Only the original attester may revoke their own attestation. Example: musehub_revoke_attestation(attestation_id='sha256:...', revoker='gabriel'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `attestation_id` | string | yes | sha256:-prefixed attestation ID. | | `revoker` | string | yes | MSign handle of the caller (must be original attester). | --- #### `musehub_run_proposal_simulation` Run a simulation for a merge proposal. Always recomputes — ignores the cache. Stores the result so musehub_get_proposal_simulation can return it without recomputing. simulation_type must be one of: 'conflict_scan', 'risk_projection', 'dependency_order'. conflict_scan: detects file-level conflicts between branches. risk_projection: projects multi-domain merge risk and returns a risk_band (low/medium/high). dependency_order: computes topological order of the proposal DAG; detects cycles. Check is_stale in the response to know if the from-branch has advanced. Example: musehub_run_proposal_simulation(repo_id='sha256:...', proposal_id='sha256:...', simulation_type='conflict_scan'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `simulation_type` | string | yes | Type of simulation to run. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_set_repo_topics` Replace all topics for a repository (max 20). Pass an empty list to clear all topics. Requires repo owner or write/admin collaborator. Example: musehub_set_repo_topics(repo_id='a3f2-...', topics=['jazz', 'midi', 'generative']). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `topics` | array | yes | Full topic list to apply (replaces existing topics). | --- #### `musehub_transfer_repo_ownership` Transfer ownership of a repository to another user. Only the current owner may initiate — admin collaborators are not permitted. After transfer the calling user loses owner privileges immediately. Example: musehub_transfer_repo_ownership(repo_id='a3f2-...', new_owner='alice'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `new_owner` | string | yes | MSign handle of the new owner. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_update_collaborator_permission` Update an existing collaborator's permission level. Requires admin or owner access. The repository owner's own permission cannot be changed through this tool. Example: musehub_update_collaborator_permission(repo_id='a3f2-...', handle='carol', permission='admin'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `handle` | string | yes | MSign handle of the collaborator to update. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `permission` | string | yes | New permission level: 'read', 'write', or 'admin'. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_update_issue` Update an existing issue's title, body, labels, symbol anchors, commit anchors, state, or assignee. Only provided fields are modified — omitted fields are left unchanged. Set state='closed' to close the issue, state='open' to reopen it. Use symbol_anchors / commit_anchors to add or replace the VCS links for an issue after discovering the relevant code (send the full replacement list, not a diff). Example: musehub_update_issue(repo_id='a3f2-...', issue_number=42, state='closed', symbol_anchors=['musehub/services/musehub_issues.py::create_issue']). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `assignee` | string | no | Username to assign, or empty string to unassign. | | `body` | string | no | New markdown body (optional). | | `commit_anchors` | array | no | Replacement commit anchor list (replaces all existing anchors). Obtain commit IDs via muse log --json. | | `issue_number` | integer | yes | Per-repo issue number. | | `labels` | array | no | Replacement label list (replaces all existing labels). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `state` | string | no | New state: 'open' or 'closed'. | | `symbol_anchors` | array | no | Replacement symbol anchor list (replaces all existing anchors). Format: 'path/to/file.py::SymbolName'. Obtain via muse code grep or muse code symbols. | | `title` | string | no | New title (optional). | --- #### `musehub_update_issue_labels` Bulk-replace the label list on an issue. The new list replaces all existing labels. Pass labels=[] to remove all labels. Use musehub_remove_issue_label to remove a single label without affecting others. Example: musehub_update_issue_labels(repo_id='a3f2-...', issue_number=42, labels=['bug', 'enhancement']). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `issue_number` | integer | yes | Per-repo issue number. | | `labels` | array | yes | Replacement label list (replaces all existing labels). Pass [] to clear all. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_update_label` Partially update an existing label — rename it, change its colour, or update its description. Only the fields you provide are changed; omitted fields stay as-is. The new name must still be unique within the repository. Get label_id from musehub_list_labels. Example: musehub_update_label(repo_id='sha256:...', label_id='sha256:...', name='critical-bug', color='#b60205'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `color` | string | no | New hex colour starting with '#' (optional, e.g. '#b60205'). | | `description` | string | no | New description (optional, max 200 chars; pass '' to clear). | | `label_id` | string | yes | ID of the label to update (from musehub_list_labels). | | `name` | string | no | New label name (optional, max 50 chars, must be unique per repo). | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- #### `musehub_update_release` Update a release's title, body, channel, or draft status. Only fields provided are changed — omitted fields are left unchanged. Requires repo owner or write/admin collaborator. Example: musehub_update_release(repo_id='a3f2-...', tag='v1.0.0', title='New title'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `body` | string | no | New release notes (Markdown). | | `channel` | string | no | Distribution channel. | | `is_draft` | boolean | no | Draft status. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `tag` | string | yes | Release tag to update (e.g. 'v1.0.0'). | | `title` | string | no | New release title. | --- #### `musehub_update_repo` Partially update mutable settings for a repository. Only non-null fields are written. Caller must be owner or admin collaborator. 'visibility' must be 'public' or 'private'. 'topics' replaces the full tag list. Example: musehub_update_repo(repo_id='a3f2-...', visibility='private', has_issues=true). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `allow_merge_commit` | boolean | no | Allow merge commits on proposals. | | `allow_rebase_merge` | boolean | no | Allow rebase merges on proposals. | | `allow_squash_merge` | boolean | no | Allow squash merges on proposals. | | `default_branch` | string | no | New default branch name. | | `delete_branch_on_merge` | boolean | no | Auto-delete head branch after proposal merge. | | `description` | string | no | New markdown description. | | `has_issues` | boolean | no | Enable or disable the issues tracker. | | `has_wiki` | boolean | no | Enable or disable the wiki. | | `homepage_url` | string | no | Project homepage URL. | | `name` | string | no | New repo name. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `repo_id` | string | yes | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `topics` | array | no | Full replacement topic tag list. | | `visibility` | string | no | 'public' or 'private'. | --- #### `musehub_update_user_profile` Update the authenticated user's profile. Accepts bio, avatarUrl, and pinnedRepoIds (list of repo sha256 genesis IDs). Caller must be the owner of the profile. Example: musehub_update_user_profile(username='gabriel', bio='Composer and engineer'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `avatar_url` | string | no | Avatar image URL. | | `bio` | string | no | Profile bio text. | | `pinned_repo_ids` | array | no | List of repo sha256 genesis IDs to pin (replaces all pinned repos). | | `username` | string | yes | Your MuseHub username. | --- ### Elicitation-Powered Tools (2) #### `musehub_create_release_interactive` Create a release interactively in two chained elicitation steps: (1) form-mode: collects tag, title, release notes, changelog highlight, and pre-release flag; (2) URL-mode (optional): offers streaming platform OAuth connection. Creates the release then returns distribution guidance for connected platforms. For a non-interactive release, use musehub_create_release with explicit arguments. ELICITATION BEHAVIOUR: requires an active MCP session with elicitation capability. Without a session, pass tag=, title=, notes= directly to bypass elicitation and create the release immediately (identical to musehub_create_release). Example: musehub_create_release_interactive(repo_id='a3f2-...') or musehub_create_release_interactive(repo_id='a3f2-...', tag='v1.0.0', title='First release', notes='Initial commit'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `notes` | string | no | Release notes markdown. Elicited if omitted. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `pre_release` | boolean | no | Whether this is a pre-release. Default: false. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `tag` | string | no | Semver tag string (e.g. 'v1.0.0'). Elicited if omitted. | | `title` | string | no | Release title. Elicited if omitted. | --- #### `musehub_review_proposal_interactive` Review a merge proposal interactively by first eliciting the reviewer's focus dimension and depth (quick / standard / thorough). Returns a deep structured review targeting the chosen dimensions with per-dimension divergence scores. Currently implements the MIDI domain's dimension vocabulary (melodic / harmonic / rhythmic / structural / dynamic / all). For repos on other domains, call musehub_read_domain first to learn the correct dimension names, then pass dimension= directly to skip elicitation. For a non-interactive review, use musehub_read_proposal + musehub_create_proposal_review instead. ELICITATION BEHAVIOUR: requires an active MCP session (Mcp-Session-Id header). Without a session, pass dimension= and depth= directly to skip elicitation. Example: musehub_review_proposal_interactive(repo_id='sha256:...', proposal_id='sha256:...') or musehub_review_proposal_interactive(repo_id='sha256:...', proposal_id='sha256:...', dimension='harmonic', depth='thorough'). | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `depth` | string | no | Review depth to bypass elicitation: quick, standard, or thorough. | | `dimension` | string | no | Focus dimension to bypass elicitation. One of: melodic, harmonic, rhythmic, structural, dynamic, all. | | `owner` | string | no | Repository owner username (e.g. 'gabriel'). Use with 'slug' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | | `proposal_id` | string | yes | sha256 genesis ID of the merge proposal to review. | | `repo_id` | string | no | sha256 genesis ID of the MuseHub repository. Alternatively, provide 'owner' + 'slug' to identify by URL path. All three can be omitted if session context is set via musehub_set_context. | | `slug` | string | no | Repository slug — the URL-safe name (e.g. 'jazz-standards'). Use with 'owner' as an alternative to 'repo_id'. Omit if session context is already set via musehub_set_context. | --- ## Resources Resources are side-effect-free, cacheable, URI-addressable reads. All resources return `application/json`. They are read via the `resources/read` method. ### Listing resources ```json {"jsonrpc":"2.0","id":1,"method":"resources/list"} {"jsonrpc":"2.0","id":2,"method":"resources/templates/list"} ``` ### Reading a resource ```json { "jsonrpc": "2.0", "id": 1, "method": "resources/read", "params": { "uri": "musehub://trending" } } ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "contents": [{ "uri": "musehub://trending", "mimeType": "application/json", "text": "[{\"repo_id\":\"...\",\"name\":\"my-song\",...}]" }] } } ``` --- ### Static Resources (9) #### `muse://docs/domains` Step-by-step guide for authoring and registering a new Muse domain plugin. Covers the MuseDomainPlugin scaffold, capability manifest schema, viewer registration, and publishing to the MuseHub domain registry. --- #### `muse://docs/overview` High-level introduction to the Muse paradigm: State, Commit, Branch, Merge, and Drift. Explains how Muse extends version control from text/code to any multidimensional state space. Essential first read for any agent new to Muse. --- #### `muse://docs/protocol` Full specification of the MuseDomainPlugin protocol — the six interfaces every domain plugin must implement: StateSerializer, DiffEngine, MergeStrategy, InsightProvider, ViewRenderer, and ArtifactManager. Read this to understand how domains work or to build a new one. --- #### `muse://domains` All domain plugins registered on this MuseHub instance, with their scoped IDs (@author/slug), dimension counts, viewer types, and install counts. Use musehub_list_domains for richer filtering. --- #### `musehub://me` Authenticated user's profile, public stats, and pinned repositories. Requires authentication. --- #### `musehub://me/feed` Recent activity (commits, proposals, issues) across repositories the authenticated user follows. Requires authentication. --- #### `musehub://me/notifications` Unread notification inbox for the authenticated user: Proposal reviews, issue mentions, and new comments. Requires authentication. --- #### `musehub://me/tokens` Active agent identities registered by the authenticated user. Returns identity metadata: agent_name, issued_at, expires_at, and last_used. Run `muse auth keygen` then `muse auth register --agent` to register new identities. Requires authentication. --- #### `musehub://trending` Top public MuseHub repositories ranked by recent commit activity across all domains. Use this to discover active state repositories before browsing or forking. --- ### Templated Resources (19) All templated resources follow RFC 6570 Level 1. `{owner}` and `{slug}` are resolved to a `repo_id` by the dispatcher — agents use human-readable names, not UUIDs. #### `muse://domains/{author}/{slug}` Full manifest for a specific registered domain plugin: capabilities, dimensions, viewer type, artifact types, merge semantics, and install instructions. Use {author}=gabriel and {slug}=midi to read the built-in MIDI domain. --- #### `musehub://mists/{owner}` All public Mists published by a specific user, newest first. Example: musehub://mists/gabriel --- #### `musehub://mists/{owner}/{mist_id}` Full metadata and content for a single Mist by its content-addressed ID. Public mists are readable by any caller. Secret mists require authentication as the owner. Example: musehub://mists/gabriel/aB3xKq9dPwNm --- #### `musehub://repos/{owner}/{slug}` Metadata, stats, and recent activity for a public repository. --- #### `musehub://repos/{owner}/{slug}/blob/{ref}/{path}` Metadata for a single artifact (path, size, MIME type, object ID). --- #### `musehub://repos/{owner}/{slug}/branches` All branches with their head commit IDs. --- #### `musehub://repos/{owner}/{slug}/commits` Paginated commit history (newest first) across all branches. --- #### `musehub://repos/{owner}/{slug}/commits/{commit_id}` Detailed commit metadata including parent IDs and artifact snapshot. --- #### `musehub://repos/{owner}/{slug}/insights/{ref}` Domain-specific insight dimensions at a given ref. The dimensions returned are sourced from the repo's domain plugin capabilities — e.g. harmony/rhythm/melody for MIDI repos, or symbols/hotspots/coupling for code repos. --- #### `musehub://repos/{owner}/{slug}/issues` Open issues for the repository. --- #### `musehub://repos/{owner}/{slug}/issues/{number}` A single issue with its full comment thread. --- #### `musehub://repos/{owner}/{slug}/proposals` Merge proposals for the repository. --- #### `musehub://repos/{owner}/{slug}/proposals/{number}` A single merge proposal with reviews and inline musical comments. --- #### `musehub://repos/{owner}/{slug}/releases` All releases ordered newest first. --- #### `musehub://repos/{owner}/{slug}/releases/{tag}` A specific release by tag with asset download counts. --- #### `musehub://repos/{owner}/{slug}/remote` Remote URL, push/pull API endpoints, and Muse CLI commands for a repository. Returns origin URL, push endpoint, pull endpoint, clone command, and the 'muse remote add origin' command. Equivalent to 'muse remote -v' for a MuseHub repo. --- #### `musehub://repos/{owner}/{slug}/timeline` Chronological evolution of the repository's state across all dimensions. Shows commits, branch divergences, and structural milestones over time. --- #### `musehub://repos/{owner}/{slug}/tree/{ref}` All artifact paths and MIME types at the given branch or commit ref. --- #### `musehub://users/{username}` Public profile and list of public repositories for a user. --- ## Prompts Prompts teach agents how to chain tools and resources to accomplish multi-step goals. They return a structured list of `role`/`content` messages that frame the task for the agent. ### Getting a prompt ```json { "jsonrpc": "2.0", "id": 1, "method": "prompts/get", "params": { "name": "musehub/orientation" } } ``` With arguments: ```json { "jsonrpc": "2.0", "id": 1, "method": "prompts/get", "params": { "name": "musehub/contribute", "arguments": { "repo_id": "abc123", "owner": "alice", "slug": "my-song" } } } ``` --- ### `musehub/orientation` **Arguments:** `caller_type` (optional: `"human"` or `"agent"`) The essential first read for any new agent or human. Explains MuseHub's model (repos, commits, branches, domain plugins, multidimensional state), the `musehub://` URI scheme, which tools to use for reads vs. writes, and how to authenticate. When `caller_type: "agent"` is passed, the response includes extended agent onboarding guidance — tool call sequencing, addressing scheme, and auth setup. --- ### `musehub/contribute` **Arguments:** `repo_id`, `owner`, `slug` End-to-end contribution workflow, including auth and push setup: 0. Confirm authentication and set up `muse remote` tracking 1. `musehub_get_context` — understand the repo 2. `musehub://repos/{owner}/{slug}/issues` — find open issues 3. `musehub_create_issue` — or create a new one 4. Make changes, push a commit via `muse_push` 5. `musehub_create_proposal` — open a proposal 6. `musehub_submit_proposal_review` — request review 7. `musehub_merge_proposal` — merge when approved --- ### `musehub/create` **Arguments:** `repo_id` Domain-agnostic creation workflow: 1. `musehub_get_context` — understand existing content and structure 2. `musehub://repos/{owner}/{slug}/analysis/{ref}` — study the domain-specific analysis 3. Create domain artifacts matching the repo's dimensional constraints 4. Push the commit via `muse_push` 5. Verify with `musehub_get_domain_insights` --- ### `musehub/review_proposal` **Arguments:** `repo_id`, `proposal_id` Dimension-aware proposal review: get proposal → read domain insights → compare branches → submit review with dimension_ref-anchored comments. 1. `musehub_get_proposal` — read the proposal metadata 2. `musehub_compare` — get per-dimension diff scores 3. `musehub_create_proposal_comment` — post dimension-anchored comments 4. `musehub_submit_proposal_review` — approve or request changes --- ### `musehub/issue_triage` **Arguments:** `repo_id` Triage open issues: list → label → assign → link to milestones. 1. `musehub_list_issues` — list open issues 2. Categorise by type (bug, feature, discussion) 3. `musehub_create_label` — create missing labels 4. `musehub_update_issue` — apply labels, assign, close duplicates --- ### `musehub/release_prep` **Arguments:** `repo_id` Prepare a release: check merged proposals → write release notes → create release with version tag. 1. `musehub_list_proposals` — find merged proposals since the last release 2. `musehub_list_releases` — check the latest release tag 3. `musehub_get_domain_insights` — summarise domain-specific changes 4. Draft release notes (Markdown) 5. `musehub_create_release` — publish --- ### `musehub/onboard` _(MCP 2025-11-25)_ **Arguments:** `username` Interactive creator onboarding (MCP 2025-11-25 elicitation-aware). Guides a new MuseHub creator through: profile setup → domain selection (via `musehub_list_domains`) → first repo creation → initial state scaffold → optional cloud integration. Requires an active session with elicitation capability. --- ### `musehub/safe-to-merge` **Arguments:** `repo_id`, `proposal_id` Pre-merge safety audit for a merge proposal. Runs: risk score → symbol diff → breakage check → blast radius → CI status → reviews. Produces a structured merge recommendation: APPROVE, APPROVE WITH CAUTION, or BLOCK. 1. `musehub_proposal_risk` — overall risk score 2. `musehub_proposal_symbol_diff` — symbol-level changes 3. `musehub_proposal_breakage` — structural breakage check --- ### `musehub/pre-release-audit` **Arguments:** `repo_id` Full repository health audit before cutting a release. Runs: health score → hotspots → dead code → blast risk → open proposals → recent breakages. Produces a structured GO / GO WITH CAUTION / NO-GO release recommendation. 1. `musehub_intel_health_score` — overall health 2. `musehub_intel_hotspots` — high-churn symbols 3. `musehub_intel_dead` — dead code detection 4. `musehub_intel_blast_risk` — highest-impact symbols --- ### `musehub/agent-onboarding` **Arguments:** `repo_id`, `agent_id`, `queue` Onboarding guide for a new agent joining a multi-agent swarm on a MuseHub repository. Covers: authenticate → get context → survey swarm state → reserve symbols → claim task → commit with provenance → complete task. Teaches the read-reserve-edit-commit cycle and how to avoid conflicts with concurrent agents. 1. `musehub_coord_swarm` — survey active agents 2. `musehub_coord_tasks` — see available work 3. `musehub_coord_claim_task` — claim a task 4. `musehub_coord_reserve` — reserve symbols before editing --- ### `musehub/symbol-investigation` **Arguments:** `repo_id`, `address` Deep-dive symbol investigation workflow: find a symbol → read its body → compute blast radius → trace provenance → surface co-change partners → check for active reservations. Produces a structured investigation report suitable for deciding whether to edit the symbol or delegate to another agent. 1. `musehub_get_symbol` — read symbol body and metadata 2. `musehub_symbol_impact` — compute blast radius 3. `musehub_coord_reservations` — check for active reservations --- ## Error Handling ### JSON-RPC error codes | Code | Meaning | |------|---------| | `-32700` | Parse error — request body is not valid JSON | | `-32600` | Invalid request — not an object or array | | `-32601` | Method not found | | `-32602` | Invalid params — required argument missing or wrong type | | `-32603` | Internal error — unexpected server exception | | `-32001` | Authentication required — write tool called without a valid MSign request | ### Tool errors Tool execution errors are not JSON-RPC errors. The envelope is always a success response; the error is signalled inside the result: ```json { "result": { "content": [{ "type": "text", "text": "repo not found: abc123" }], "isError": true } } ``` --- ## Usage Patterns ### Pattern 1: Discover and explore ``` 1. resources/read musehub://trending → pick a repo 2. resources/read musehub://repos/{owner}/{slug} → orientation 3. tools/call musehub_get_context → full AI context 4. resources/read musehub://repos/{owner}/{slug}/analysis/{ref} → musical detail ``` ### Pattern 2: Fix a bug, open a proposal ``` 1. tools/call musehub_list_issues { owner, slug, state: "open" } 2. tools/call musehub_get_issue { owner, slug, issue_number } 3. tools/call musehub_get_context { owner, slug } 4. tools/call musehub_read_file { owner, slug, path } 5. -- compose fix, push commit via muse_push -- 6. tools/call musehub_create_proposal { owner, slug, title, from_branch, to_branch } ``` ### Pattern 3: Full musical proposal review (elicitation-powered) ``` 1. tools/call musehub_review_proposal_interactive { repo_id, proposal_id } → elicitation: "Focus on harmonic divergence, thorough depth" → returns: per-dimension scores, findings, APPROVE/REQUEST_CHANGES recommendation ``` Or stateless: ``` 1. tools/call musehub_get_proposal { repo_id, proposal_id } 2. tools/call musehub_compare { repo_id, base_ref, head_ref } 3. tools/call musehub_create_proposal_comment { repo_id, proposal_id, body, target_type: "track", ... } 4. tools/call musehub_submit_proposal_review { repo_id, proposal_id, event: "APPROVE" } ``` ### Pattern 4: Publish a release (elicitation-powered) ``` 1. tools/call musehub_create_release_interactive { repo_id } → elicitation (form): tag, title, release notes, highlight → creates release + returns release record ``` Or stateless: ``` 1. tools/call musehub_list_releases { owner, slug } 2. tools/call musehub_list_proposals { owner, slug, state: "closed" } 3. tools/call musehub_get_domain_insights { owner, slug } 4. tools/call musehub_create_release { owner, slug, tag: "v1.2.0", title: "Spring Drop", body: "## What changed\n..." } ``` --- ## Architecture Diagrams ### Request flow ```mermaid flowchart TD subgraph transports [Transports — MCP 2025-11-25] POST["POST /mcp\nJSON + SSE stream"] GET["GET /mcp\nSSE push channel"] DEL["DELETE /mcp\nSession termination"] stdio["stdio\npython -m musehub.mcp.stdio_server"] end subgraph session [Session Layer] SID["Mcp-Session-Id"] ORIGIN["Origin validation"] SSE_Q["asyncio.Queue\nSSE queues"] FUTURES["asyncio.Future\nelicitation registry"] end subgraph dispatcher [musehub/mcp/dispatcher.py] D["handle_request()"] D --> INIT["initialize"] D --> TL["tools/list"] D --> TC["tools/call"] D --> RL["resources/list"] D --> RR["resources/read"] D --> PL["prompts/list"] D --> PG["prompts/get"] D --> NC["notifications/cancelled"] D --> NEC["notifications/elicitation/complete"] end subgraph execution [Execution Layer] READ["Read executors\nmusehub_mcp_executor.py"] WRITE["Write executors\nmcp/write_tools/"] ELICIT["Elicitation tools\nelicitation_tools.py"] CTX["ToolCallContext\ncontext.py"] RES["Resource handlers\nresources.py"] PROMPTS["Prompt assembler\nprompts.py"] end POST --> ORIGIN POST --> SID SID --> D GET --> SSE_Q DEL --> SID stdio --> D TC --> READ TC --> WRITE TC --> ELICIT ELICIT --> CTX CTX --> SSE_Q CTX --> FUTURES RR --> RES PG --> PROMPTS NC --> FUTURES NEC --> FUTURES READ --> DB[("AsyncSession / Postgres")] WRITE --> DB RES --> DB ``` ### Tool catalogue structure ```mermaid classDiagram class MUSEHUB_READ_TOOLS { <> musehub_set_context musehub_get_context musehub_list_branches musehub_list_commits musehub_read_file musehub_search musehub_get_commit musehub_compare musehub_list_issues musehub_get_issue musehub_list_proposals musehub_get_proposal musehub_proposal_risk musehub_proposal_symbol_diff musehub_proposal_breakage musehub_list_releases musehub_search_repos musehub_list_domains musehub_get_domain musehub_get_domain_insights musehub_get_view musehub_whoami musehub_get_prompt musehub_list_symbols musehub_get_symbol musehub_symbol_impact musehub_symbol_clones musehub_intel_index_status musehub_intel_health_score musehub_intel_hotspots musehub_intel_dead musehub_intel_blast_risk musehub_coord_swarm musehub_coord_reservations musehub_coord_check_conflicts musehub_coord_tasks musehub_cross_repo_impact musehub_workspace_intel } class MUSEHUB_CLI_TOOLS { <> muse_pull muse_remote muse_push muse_config } class MUSEHUB_WRITE_TOOLS { <> musehub_create_repo musehub_create_issue musehub_update_issue musehub_create_issue_comment musehub_create_proposal musehub_merge_proposal musehub_create_proposal_comment musehub_submit_proposal_review musehub_create_release musehub_create_label musehub_publish_domain musehub_agent_notify musehub_agent_broadcast musehub_coord_claim_task musehub_coord_complete_task musehub_coord_fail_task musehub_coord_extend_reservation musehub_coord_reserve musehub_coord_release musehub_coord_enqueue } class MUSEHUB_ELICITATION_TOOLS { <> musehub_review_proposal_interactive musehub_create_release_interactive } class MCPDispatcher { +handle_request(raw, user_id, session) +handle_batch(raw, user_id, session) } MCPDispatcher ..> MUSEHUB_READ_TOOLS : routes read calls MCPDispatcher ..> MUSEHUB_CLI_TOOLS : routes Muse VCS calls MCPDispatcher ..> MUSEHUB_WRITE_TOOLS : routes write calls (MSign auth required) MCPDispatcher ..> MUSEHUB_ELICITATION_TOOLS : routes interactive calls (session required) ``` ### Resource URI hierarchy ```mermaid flowchart TD root["musehub://"] root --> trending["trending"] root --> me["me"] root --> repos["repos/{owner}/{slug}"] root --> users["users/{username}"] me --> notifications["me/notifications"] me --> starred["me/starred"] me --> feed["me/feed"] repos --> branches["…/branches"] repos --> commits["…/commits"] commits --> commit["…/commits/{commit_id}"] repos --> tree["…/tree/{ref}"] repos --> blob["…/blob/{ref}/{path}"] repos --> issues["…/issues"] issues --> issue["…/issues/{number}"] repos --> pulls["…/pulls"] pulls --> pull["…/pulls/{number}"] repos --> releases["…/releases"] releases --> release["…/releases/{tag}"] repos --> analysis["…/analysis/{ref}"] repos --> timeline["…/timeline"] ``` ### Elicitation sequence (form mode) ```mermaid sequenceDiagram participant Agent participant MCP as POST /mcp participant Session as Session Store participant Tool as Elicitation Tool Agent->>MCP: POST initialize {capabilities: {elicitation: {form:{}, url:{}}}} MCP-->>Agent: 200 OK, Mcp-Session-Id: abc123 Agent->>MCP: GET /mcp (Accept: text/event-stream, Mcp-Session-Id: abc123) MCP-->>Agent: 200 text/event-stream (SSE channel open) Agent->>MCP: POST tools/call musehub_review_proposal_interactive {repo_id, proposal_id} Note over MCP: tool needs elicitation → SSE response MCP->>Session: create_pending_elicitation("elicit-1") MCP-->>Agent: 200 text/event-stream (POST SSE open) MCP-->>Agent: SSE: elicitation/create {mode:"form", schema:{dimension_focus,review_depth,...}} Note over Agent: Shows form UI to user Agent->>MCP: POST {jsonrpc:"2.0", id:"elicit-1", result:{action:"accept", content:{dimension_focus:"harmonic",...}}} MCP->>Session: resolve_elicitation("elicit-1", {action:"accept", content:...}) MCP-->>Agent: 202 Accepted Note over Tool: Future resolved, tool continues MCP-->>Agent: SSE: tools/call response {scores: {...}, recommendation: "APPROVE"} Note over MCP: SSE stream closes ```