Model Context
Protocol

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').

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-...').

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').

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').

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').

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']).

Add a comment to an existing issue. Example: musehub_create_issue_comment(repo_id='a3f2-...', issue_number=42, body='Fixed in commit abc...').

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).

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).

Assign or unassign a collaborator on an issue. Pass assignee='' to unassign. Example: musehub_assign_issue(repo_id='a3f2-...', issue_number=42, assignee='gabriel').

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']).

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').

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='state_weave').

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-...').

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').

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.').

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.').

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').

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').

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:...').

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. The 'capabilities' object must follow the Muse domain schema: dimensions: list of {name, description} objects viewer_type: primary viewer identifier (e.g. 'midi', 'code', 'spatial') 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='sequence', version='0.1.0').

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.

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.

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:...').

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').

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').

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').

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']).

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:...').

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').

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:...').

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']).

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').

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:...').

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').

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').

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:...').

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-...').

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).

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').

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').

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').

Issue a cryptographically-verified attestation about a MuseHub identity. The caller must supply an Ed25519 signature over ATTEST\n{attester}\n{subject}\n{claim}\n{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:...').

Revoke an attestation by ID. Only the original attester may revoke their own attestation. Example: musehub_revoke_attestation(attestation_id='sha256:...', revoker='gabriel').

Record a verified MPay micropayment claim. The caller must supply an Ed25519 signature over MPAY\n{sender}\n{recipient}\n{amount_nano}\n{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:...').

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']).

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:...').

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

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.

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.

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.

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.

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.

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.