musehub.py
python
| 1 | """MuseHub MCP tool definitions — server-side browsing tools for AI agents. |
| 2 | |
| 3 | These tools allow Cursor/Claude and other MCP clients to explore MuseHub |
| 4 | repositories, inspect commit history, read artifact metadata, query musical |
| 5 | analysis, and search — all without requiring a connected DAW. |
| 6 | |
| 7 | Every tool in this module is ``server_side: True``. The MCP server routes |
| 8 | them to ``musehub_mcp_executor`` rather than forwarding them to the DAW. |
| 9 | |
| 10 | Naming convention: ``musehub_<verb>_<noun>`` — distinct from DAW tools |
| 11 | which use the ``muse_`` prefix. |
| 12 | """ |
| 13 | from __future__ import annotations |
| 14 | |
| 15 | from musehub.contracts.mcp_types import MCPToolDef |
| 16 | |
| 17 | |
| 18 | MUSEHUB_TOOLS: list[MCPToolDef] = [ |
| 19 | { |
| 20 | "name": "musehub_browse_repo", |
| 21 | "server_side": True, |
| 22 | "description": ( |
| 23 | "Get an overview of a MuseHub repository: metadata, branches, and recent commits. " |
| 24 | "Use this to orient yourself before reading files or analysing commit history. " |
| 25 | "Example: musehub_browse_repo(repo_id='a3f2-...')." |
| 26 | ), |
| 27 | "inputSchema": { |
| 28 | "type": "object", |
| 29 | "properties": { |
| 30 | "repo_id": { |
| 31 | "type": "string", |
| 32 | "description": "UUID of the MuseHub repository (e.g. 'a3f2-...').", |
| 33 | }, |
| 34 | }, |
| 35 | "required": ["repo_id"], |
| 36 | }, |
| 37 | }, |
| 38 | { |
| 39 | "name": "musehub_list_branches", |
| 40 | "server_side": True, |
| 41 | "description": ( |
| 42 | "List all branches in a MuseHub repository with their head commit IDs. " |
| 43 | "Call before musehub_list_commits to identify the target branch ref. " |
| 44 | "Example: musehub_list_branches(repo_id='a3f2-...')." |
| 45 | ), |
| 46 | "inputSchema": { |
| 47 | "type": "object", |
| 48 | "properties": { |
| 49 | "repo_id": { |
| 50 | "type": "string", |
| 51 | "description": "UUID of the MuseHub repository.", |
| 52 | }, |
| 53 | }, |
| 54 | "required": ["repo_id"], |
| 55 | }, |
| 56 | }, |
| 57 | { |
| 58 | "name": "musehub_list_commits", |
| 59 | "server_side": True, |
| 60 | "description": ( |
| 61 | "List commits on a MuseHub repository (newest first). " |
| 62 | "Optionally filter by branch name and cap the result count. " |
| 63 | "Example: musehub_list_commits(repo_id='a3f2-...', branch='main', limit=10)." |
| 64 | ), |
| 65 | "inputSchema": { |
| 66 | "type": "object", |
| 67 | "properties": { |
| 68 | "repo_id": { |
| 69 | "type": "string", |
| 70 | "description": "UUID of the MuseHub repository.", |
| 71 | }, |
| 72 | "branch": { |
| 73 | "type": "string", |
| 74 | "description": "Branch name filter (e.g. 'main'). Omit to list across all branches.", |
| 75 | }, |
| 76 | "limit": { |
| 77 | "type": "integer", |
| 78 | "description": "Maximum commits to return (default: 20, max: 100).", |
| 79 | "default": 20, |
| 80 | "minimum": 1, |
| 81 | "maximum": 100, |
| 82 | }, |
| 83 | }, |
| 84 | "required": ["repo_id"], |
| 85 | }, |
| 86 | }, |
| 87 | { |
| 88 | "name": "musehub_read_file", |
| 89 | "server_side": True, |
| 90 | "description": ( |
| 91 | "Read the metadata for a stored artifact (MIDI, MP3, WebP piano roll) " |
| 92 | "in a MuseHub repo. Returns path, size_bytes, mime_type, and object_id. " |
| 93 | "Binary content is not returned — discover object IDs via musehub_browse_repo first. " |
| 94 | "Example: musehub_read_file(repo_id='a3f2-...', object_id='sha256:abc...')." |
| 95 | ), |
| 96 | "inputSchema": { |
| 97 | "type": "object", |
| 98 | "properties": { |
| 99 | "repo_id": { |
| 100 | "type": "string", |
| 101 | "description": "UUID of the MuseHub repository.", |
| 102 | }, |
| 103 | "object_id": { |
| 104 | "type": "string", |
| 105 | "description": "Content-addressed object ID (e.g. 'sha256:abc...').", |
| 106 | }, |
| 107 | }, |
| 108 | "required": ["repo_id", "object_id"], |
| 109 | }, |
| 110 | }, |
| 111 | { |
| 112 | "name": "musehub_get_analysis", |
| 113 | "server_side": True, |
| 114 | "description": ( |
| 115 | "Get structured analysis for a MuseHub repository. " |
| 116 | "Dimensions: 'overview' returns repo stats + branch/commit/object counts; " |
| 117 | "'commits' returns commit activity summary (authors, message samples); " |
| 118 | "'objects' returns artifact inventory grouped by MIME type. " |
| 119 | "MIDI audio analysis requires Storpheus integration (not yet available" |
| 120 | "dimension fields for key/tempo will be None until integrated). " |
| 121 | "Example: musehub_get_analysis(repo_id='a3f2-...', dimension='overview')." |
| 122 | ), |
| 123 | "inputSchema": { |
| 124 | "type": "object", |
| 125 | "properties": { |
| 126 | "repo_id": { |
| 127 | "type": "string", |
| 128 | "description": "UUID of the MuseHub repository.", |
| 129 | }, |
| 130 | "dimension": { |
| 131 | "type": "string", |
| 132 | "description": "Analysis dimension: 'overview', 'commits', or 'objects'.", |
| 133 | "enum": ["overview", "commits", "objects"], |
| 134 | "default": "overview", |
| 135 | }, |
| 136 | }, |
| 137 | "required": ["repo_id"], |
| 138 | }, |
| 139 | }, |
| 140 | { |
| 141 | "name": "musehub_search", |
| 142 | "server_side": True, |
| 143 | "description": ( |
| 144 | "Search within a MuseHub repository by substring query. " |
| 145 | "Mode 'path' matches artifact file paths (e.g. 'tracks/jazz'); " |
| 146 | "mode 'commit' searches commit messages (e.g. 'add bass'). " |
| 147 | "Returns matching items with their metadata. " |
| 148 | "Example: musehub_search(repo_id='a3f2-...', query='bass', mode='path')." |
| 149 | ), |
| 150 | "inputSchema": { |
| 151 | "type": "object", |
| 152 | "properties": { |
| 153 | "repo_id": { |
| 154 | "type": "string", |
| 155 | "description": "UUID of the MuseHub repository to search within.", |
| 156 | }, |
| 157 | "query": { |
| 158 | "type": "string", |
| 159 | "description": "Substring query string (case-insensitive).", |
| 160 | }, |
| 161 | "mode": { |
| 162 | "type": "string", |
| 163 | "description": "Search mode: 'path' searches object paths; 'commit' searches commit messages.", |
| 164 | "enum": ["path", "commit"], |
| 165 | "default": "path", |
| 166 | }, |
| 167 | }, |
| 168 | "required": ["repo_id", "query"], |
| 169 | }, |
| 170 | }, |
| 171 | { |
| 172 | "name": "musehub_get_context", |
| 173 | "server_side": True, |
| 174 | "description": ( |
| 175 | "Get the full AI context document for a MuseHub repository. " |
| 176 | "This is the primary read-side interface for music generation agents: it returns " |
| 177 | "a structured summary of the repo's musical state — branches, recent commits, " |
| 178 | "artifact inventory, and repo metadata — in a single call. " |
| 179 | "Feed this document to the agent before generating new music to ensure " |
| 180 | "harmonic and structural coherence with existing work. " |
| 181 | "Example: musehub_get_context(repo_id='a3f2-...')." |
| 182 | ), |
| 183 | "inputSchema": { |
| 184 | "type": "object", |
| 185 | "properties": { |
| 186 | "repo_id": { |
| 187 | "type": "string", |
| 188 | "description": "UUID of the MuseHub repository.", |
| 189 | }, |
| 190 | }, |
| 191 | "required": ["repo_id"], |
| 192 | }, |
| 193 | }, |
| 194 | ] |
| 195 | |
| 196 | MUSEHUB_TOOL_NAMES: set[str] = {t["name"] for t in MUSEHUB_TOOLS} |
| 197 | """Set of all musehub_* tool names — used by the MCP server to route calls.""" |