Muse Command Protocol

Get an overview of a MuseHub repository: metadata, branches, and recent commits. Use this to orient yourself before reading files or analysing commit history. Example: musehub_browse_repo(repo_id='a3f2-...').

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

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

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_browse_repo first. Example: musehub_read_file(repo_id='a3f2-...', object_id='sha256:abc...').

[Deprecated — use musehub_get_domain_insights] Get structured analysis for a MuseHub repository. Dimensions: 'overview' returns repo stats + branch/commit/object counts; 'commits' returns commit activity summary; 'objects' returns artifact inventory grouped by MIME type. Example: musehub_get_analysis(repo_id='a3f2-...', dimension='overview').

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

Get the full AI context document for a MuseHub repository. This is the primary read-side interface for domain agents: it returns a structured summary of the repo's current state — domain plugin, branches, recent commits, artifact inventory, and repo metadata — in a single call. Feed this document to the agent before creating state changes to ensure coherence with the existing multidimensional state. Example: musehub_get_context(repo_id='a3f2-...').

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_get_commit(repo_id='a3f2-...', commit_id='sha256:abc...').

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

List issues for a MuseHub repository. Filter by state (open/closed/all), label string, or assignee. Example: musehub_list_issues(repo_id='a3f2-...', state='open', label='bug').

Get a single issue by its per-repo number, including the full comment thread. Example: musehub_get_issue(repo_id='a3f2-...', issue_number=42).

List pull requests for a MuseHub repository. Filter by state (open/merged/closed/all) and/or target branch. Example: musehub_list_prs(repo_id='a3f2-...', state='open').

Get a single pull request by ID, including reviews and inline comments. Example: musehub_get_pr(repo_id='a3f2-...', pr_id='b5e8-...').

List all releases for a MuseHub repository, ordered newest first. Each release includes tag, title, release notes, and asset counts. Example: musehub_list_releases(repo_id='a3f2-...').

Discover public MuseHub repositories across all domains by text query, domain plugin, or free-text tags. Filter by domain scoped ID (e.g. '@cgcardona/midi') to browse repos of a specific type. Returns repos sorted by relevance. Example: musehub_search_repos(query='jazz', domain='@cgcardona/midi').

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

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. Use this to understand what a domain can do before creating repos or generating domain-specific content. Example: musehub_get_domain(scoped_id='@cgcardona/midi').

Get structured insights for a MuseHub repository across any of its domain's dimensions. The available dimensions are defined by the repo's domain plugin — call musehub_get_domain first to learn the dimension names. dimension='overview' always returns cross-domain stats (commits, objects, collaborators). Domain-specific dimensions return per-dimension analytics (e.g. 'harmonic' for MIDI, 'syntax' for Code). Example: musehub_get_domain_insights(repo_id='a3f2-...', dimension='harmonic').

Fetch the universal viewer payload for a repo at a given ref. Returns a structured representation of the multidimensional state as rendered by the domain's viewer — including dimension slices, navigation strip entries, and any domain-specific viewer metadata. This is the MCP equivalent of the /{owner}/{repo}/view/{ref} page. Useful for agents that need to inspect or reason about the full state without screen-scraping the HTML viewer. Example: musehub_get_view(repo_id='a3f2-...', ref='main').

Return identity information for the currently authenticated caller. Call this first to confirm authentication, get your user_id, and see how many repos you own. Works for both human users and AI agent tokens. Returns {authenticated: false} when called without a Bearer token. Example: musehub_whoami().

Return the clone URL and Muse CLI command for a MuseHub repository. Use this to get the information needed to run 'muse clone' locally, or to fetch repo metadata before calling muse_pull. Example: muse_clone(owner='cgcardona', slug='neo-soul-experiment').

Fetch missing commits and objects from a MuseHub repository. Equivalent to 'muse pull' — returns new commits and object metadata since the given commit ID. Use since_commit_id to fetch incrementally. Pass object_ids to download specific binary objects. Example: muse_pull(repo_id='a3f2-...', branch='main', since_commit_id='abc123').

Return the remote URL and API endpoints for a MuseHub repository. Equivalent to 'muse remote -v' — returns the origin URL, push/pull API endpoints, and the CLI commands to add this repo as a remote. Example: muse_remote(owner='cgcardona', slug='neo-soul-experiment').

Create a new MuseHub repository for any Muse domain. The slug is auto-generated from the name. Specify a domain scoped ID (e.g. '@cgcardona/midi') to associate the repo with a domain plugin — this unlocks domain-specific viewers, insights, and CLI commands. 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').

Open a new issue in a MuseHub repository. Use issues to track musical problems, feature requests, or collaboration needs. Example: musehub_create_issue(repo_id='a3f2-...', title='Bass too muddy in bars 8-16').

Update an existing issue's title, body, labels, state, or assignee. Only provided fields are modified. Set state='closed' to close the issue, state='open' to reopen it. Example: musehub_update_issue(repo_id='a3f2-...', issue_number=42, state='closed').

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

Open a new pull request proposing to merge from_branch into to_branch. Call musehub_list_branches first to confirm both branches exist. Example: musehub_create_pr(repo_id='a3f2-...', title='Add jazz bridge', from_branch='feature/jazz-bridge', to_branch='main').

Merge an open pull request. Creates a merge commit on the target branch. The PR must be in 'open' state. Obtain pr_id from musehub_list_prs. Example: musehub_merge_pr(repo_id='a3f2-...', pr_id='b5e8-...').

Post a comment on a pull request, optionally anchored to a specific dimension reference. Pass a dimension_ref object to pinpoint exactly where in the multidimensional state the comment applies — the shape of this object is defined by the repo's domain plugin. For MIDI: {"dimension": "rhythmic", "track": "Drums", "beat_start": 8.0, "beat_end": 12.0}. For Code: {"dimension": "syntax", "file": "src/main.py", "line_start": 42, "line_end": 55}. Omit dimension_ref for a general (PR-level) comment. Example: musehub_create_pr_comment(repo_id='a3f2-...', pr_id='b5e8-...', body='Unexpected state divergence here', dimension_ref={"dimension": "structural", "node": "bridge"}).

Submit a formal review on a pull request. event='approve' approves the PR; event='request_changes' blocks merge; event='comment' adds a neutral review comment. Example: musehub_submit_pr_review(repo_id='a3f2-...', pr_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 musical snapshot. Tags must be unique per repo (e.g. 'v1.0', 'final-mix'). Example: musehub_create_release(repo_id='a3f2-...', tag='v1.0', title='First Release', body='Initial jazz session recording.').

Star a MuseHub repository to show appreciation and follow its activity. Starred repos appear in the user's starred list. Idempotent. Example: musehub_star_repo(repo_id='a3f2-...').

Fork a public MuseHub repository under the authenticated user's account. Creates a new repo with all branches and establishes fork lineage. Only public repos can be forked. Example: musehub_fork_repo(repo_id='a3f2-...').

Create a repo-scoped label with a name and hex colour. Labels can be applied to issues and PRs for categorisation. Label names must be unique within the repository. Example: musehub_create_label(repo_id='a3f2-...', name='harmonic-issue', color='e11d48').

Mint a long-lived JWT agent token for programmatic MuseHub access. Agent tokens have higher rate limits than user tokens and appear with an 'agent' badge in the MuseHub activity feed. After creating a token, store it with: muse config set musehub.token <token>. Requires an authenticated session (the token is issued for the calling user). Example: musehub_create_agent_token(agent_name='my-composer-bot/1.0', expires_in_days=90).

Push commits and binary objects to a MuseHub repository. Equivalent to 'muse push' — uploads new commits and base64-encoded binary objects in a single batch. Enforces fast-forward semantics unless force=true. Authentication required: call musehub_whoami or musehub_create_agent_token first. Example: muse_push(repo_id='a3f2-...', branch='main', head_commit_id='abc123', commits=[...], objects=[...]).

Read info about Muse configuration keys or generate a 'muse config set' command. Equivalent to 'muse config get <key>' or 'muse config set <key> <value>'. Call without arguments to list all known MuseHub-related config keys. Pass key and value to get the exact CLI command to run. Key examples: musehub.token, musehub.url, musehub.username, user.name. Example: muse_config(key='musehub.token', value='eyJhbGc...').

Interactively compose a musical piece by collecting user preferences via form-mode elicitation. Asks the user for key signature, tempo, time signature, mood, genre, reference artist, and duration. Returns a complete composition plan with chord progressions, section structure, harmonic tension profile, and a step-by-step Muse project workflow. Requires an active MCP session with elicitation capability. Example: musehub_compose_with_preferences(repo_id='a3f2-...').

Review a pull request interactively by first eliciting the reviewer's focus dimension (melodic / harmonic / rhythmic / structural / dynamic / all) and depth (quick / standard / thorough). Returns a deep structured review targeting the user-chosen dimensions with harmonic tension and rhythmic consistency checks. Requires an active MCP session with elicitation capability. Example: musehub_review_pr_interactive(repo_id='a3f2-...', pr_id='pr-uuid').

Connect a streaming platform account (Spotify, SoundCloud, Bandcamp, YouTube Music, Apple Music, TIDAL, Amazon Music, Deezer) via URL-mode elicitation (OAuth). Directs the user to a MuseHub OAuth start page; once authorised, the agent can distribute Muse releases directly to the platform. Requires an active MCP session with URL elicitation capability. Example: musehub_connect_streaming_platform(platform='Spotify', repo_id='a3f2-...').

Connect a cloud DAW or mastering service (LANDR, Splice, Soundtrap, BandLab, Audiotool) via URL-mode elicitation (OAuth). Once connected, agents can trigger cloud renders, stems exports, and AI mastering jobs directly from MuseHub workflows. Requires an active MCP session with URL elicitation capability. Example: musehub_connect_daw_cloud(service='LANDR').

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. Requires an active MCP session with elicitation capability. Example: musehub_create_release_interactive(repo_id='a3f2-...').