mcp.md markdown

2,690 lines 171.9 KB

sha256:b3e654170421616945cf1599d6bb4e8e219c3c2189458ed7f41af4b2d685f87a docs: regenerate docs/reference/mcp.md's tool/resource cata… Sonnet 5 patch 2 days ago

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.

Architecture
Transports
Authentication
Session Management
Elicitation

Tools — 127 total

Resources — 28 total
- Static Resources (9)
- Templated Resources (19)

Prompts — 11 total
Error Handling
Usage Patterns
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.

POST /mcp HTTP/1.1
Content-Type: application/json
Authorization: MSign handle="..." ts=... sig="..."
Mcp-Session-Id: <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):

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.

GET /mcp HTTP/1.1
Accept: text/event-stream
Mcp-Session-Id: <session-id>
Last-Event-ID: <last-seen-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

DELETE /mcp HTTP/1.1
Mcp-Session-Id: <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:

{
  "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:

POST /mcp
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{"elicitation":{"form":{},"url":{}}}}}

Response includes:

Mcp-Session-Id: <cryptographically-secure-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:

{ "repo_id": "abc-123-uuid" }
// or equivalently:
{ "owner": "gabriel", "slug": "jazz-standards" }

Calling a tool

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "musehub_get_context",
    "arguments": { "owner": "gabriel", "slug": "jazz-standards" }
  }
}

Response:

{
  "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

{"jsonrpc":"2.0","id":1,"method":"resources/list"}
{"jsonrpc":"2.0","id":2,"method":"resources/templates/list"}

Reading a resource

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": { "uri": "musehub://trending" }
}

Response:

{
  "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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/get",
  "params": {
    "name": "musehub/orientation"
  }
}

With arguments:

{
  "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:

Confirm authentication and set up muse remote tracking
musehub_get_context — understand the repo
musehub://repos/{owner}/{slug}/issues — find open issues
musehub_create_issue — or create a new one
Make changes, push a commit via muse_push
musehub_create_proposal — open a proposal
musehub_submit_proposal_review — request review
musehub_merge_proposal — merge when approved

`musehub/create`

Arguments: repo_id

Domain-agnostic creation workflow:

musehub_get_context — understand existing content and structure
musehub://repos/{owner}/{slug}/analysis/{ref} — study the domain-specific analysis
Create domain artifacts matching the repo's dimensional constraints
Push the commit via muse_push
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.

musehub_get_proposal — read the proposal metadata
musehub_compare — get per-dimension diff scores
musehub_create_proposal_comment — post dimension-anchored comments
musehub_submit_proposal_review — approve or request changes

`musehub/issue_triage`

Arguments: repo_id

Triage open issues: list → label → assign → link to milestones.

musehub_list_issues — list open issues
Categorise by type (bug, feature, discussion)
musehub_create_label — create missing labels
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.

musehub_list_proposals — find merged proposals since the last release
musehub_list_releases — check the latest release tag
musehub_get_domain_insights — summarise domain-specific changes
Draft release notes (Markdown)
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.

musehub_proposal_risk — overall risk score
musehub_proposal_symbol_diff — symbol-level changes
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.

musehub_intel_health_score — overall health
musehub_intel_hotspots — high-churn symbols
musehub_intel_dead — dead code detection
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.

musehub_coord_swarm — survey active agents
musehub_coord_tasks — see available work
musehub_coord_claim_task — claim a task
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.

musehub_get_symbol — read symbol body and metadata
musehub_symbol_impact — compute blast radius
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:

{
  "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

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

classDiagram
    class MUSEHUB_READ_TOOLS {
        <<list of MCPToolDef — 38 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 {
        <<list of MCPToolDef — 4 tools>>
        muse_pull
        muse_remote
        muse_push
        muse_config
    }
    class MUSEHUB_WRITE_TOOLS {
        <<list of MCPToolDef — 21 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 {
        <<list of MCPToolDef — 2 tools — MCP 2025-11-25>>
        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

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)

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

File History 1 commit

sha256:b3e654170421616945cf1599d6bb4e8e219c3c2189458ed7f41af4b2d685f87a docs: regenerate docs/reference/mcp.md's tool/resource cata… Sonnet 5 patch 2 days ago

MuseHub MCP Reference

Table of Contents

Architecture

Transports

HTTP Streamable — Full 2025-11-25 Transport

POST /mcp

GET /mcp — SSE Push Channel

DELETE /mcp — Session Termination

stdio — python -m musehub.mcp.stdio_server

Authentication

Session Management

Elicitation

Form Mode

Elicitation Schemas

Tools

Repo identification: repo_id or owner + slug

Calling a tool

Read Tools (52)

muse_mist_embed

muse_mist_list

muse_mist_list_forks

muse_mist_raw

muse_mist_read

muse_pull

muse_remote

musehub_compare

musehub_get_fork_network

musehub_get_repo

musehub_get_user_forks

musehub_list_branches

musehub_list_commits

musehub_list_coord_reservations

musehub_list_coord_tasks

musehub_list_domains

musehub_list_issues

musehub_list_labels

musehub_list_proposals

musehub_list_proposals_context

musehub_list_releases

musehub_list_repo_forks

musehub_list_repos

musehub_list_symbols

musehub_read_commit

musehub_read_context

musehub_read_coord_conflicts

musehub_read_coord_swarm

musehub_read_cross_repo_impact

musehub_read_domain

musehub_read_domain_insights

musehub_read_file

musehub_read_intel_blast_risk

musehub_read_intel_dead

musehub_read_intel_health_score

musehub_read_intel_hotspots

musehub_read_intel_index_status

musehub_read_issue

musehub_read_prompt

musehub_read_proposal

musehub_read_proposal_breakage

musehub_read_proposal_diff

musehub_read_proposal_risk

musehub_read_symbol

musehub_read_view

musehub_read_workspace_intel

musehub_search

musehub_search_repos

musehub_set_context

musehub_symbol_clones

musehub_symbol_impact

musehub_whoami

Write Tools (73)

muse_config

muse_mist_create

muse_mist_delete

muse_mist_fork

muse_mist_update

muse_push

musehub_accept_collaborator_invite

musehub_agent_broadcast

musehub_agent_notify

`POST /mcp`

`GET /mcp` — SSE Push Channel

`DELETE /mcp` — Session Termination

stdio — `python -m musehub.mcp.stdio_server`

Repo identification: `repo_id` or `owner` + `slug`

`muse_mist_embed`

`muse_mist_list`

`muse_mist_list_forks`

`muse_mist_raw`

`muse_mist_read`

`muse_pull`

`muse_remote`

`musehub_compare`

`musehub_get_fork_network`

`musehub_get_repo`

`musehub_get_user_forks`

`musehub_list_branches`

`musehub_list_commits`

`musehub_list_coord_reservations`

`musehub_list_coord_tasks`

`musehub_list_domains`

`musehub_list_issues`

`musehub_list_labels`

`musehub_list_proposals`

`musehub_list_proposals_context`

`musehub_list_releases`

`musehub_list_repo_forks`

`musehub_list_repos`

`musehub_list_symbols`

`musehub_read_commit`

`musehub_read_context`

`musehub_read_coord_conflicts`

`musehub_read_coord_swarm`

`musehub_read_cross_repo_impact`

`musehub_read_domain`

`musehub_read_domain_insights`

`musehub_read_file`

`musehub_read_intel_blast_risk`

`musehub_read_intel_dead`

`musehub_read_intel_health_score`

`musehub_read_intel_hotspots`

`musehub_read_intel_index_status`

`musehub_read_issue`

`musehub_read_prompt`

`musehub_read_proposal`

`musehub_read_proposal_breakage`

`musehub_read_proposal_diff`

`musehub_read_proposal_risk`

`musehub_read_symbol`

`musehub_read_view`

`musehub_read_workspace_intel`

`musehub_search`

`musehub_search_repos`

`musehub_set_context`

`musehub_symbol_clones`

`musehub_symbol_impact`

`musehub_whoami`

`muse_config`

`muse_mist_create`

`muse_mist_delete`

`muse_mist_fork`

`muse_mist_update`

`muse_push`

`musehub_accept_collaborator_invite`

`musehub_agent_broadcast`

`musehub_agent_notify`

`musehub_assign_issue`

`musehub_attach_release_asset`

`musehub_claim_coord_task`

`musehub_close_issue`

`musehub_complete_coord_task`

`musehub_create_coord_reservation`

`musehub_create_issue`

`musehub_create_issue_comment`

`musehub_create_label`

`musehub_create_proposal`

`musehub_create_proposal_comment`

`musehub_create_proposal_review`

`musehub_create_release`

`musehub_create_repo`