README.md
markdown
| 1 | # MuseHub |
| 2 | |
| 3 |  |
| 4 |  |
| 5 |  |
| 6 | |
| 7 | **MuseHub** — the music composition version control platform powered by Muse VCS. |
| 8 | |
| 9 | GitHub for music. Push commits, open pull requests, track issues, browse public repos, publish releases, and give AI agents complete programmatic access via a best-in-class MCP integration. |
| 10 | |
| 11 | > **Requirements:** Python 3.14+ · PostgreSQL 16+ · Node.js 22+ |
| 12 | |
| 13 | ## URL scheme |
| 14 | |
| 15 | ``` |
| 16 | /{owner}/{slug} → repo home page |
| 17 | musehub://{owner}/{slug} → MCP resource URI (see MCP docs) |
| 18 | ``` |
| 19 | |
| 20 | ## Architecture |
| 21 | |
| 22 | ``` |
| 23 | musehub/ |
| 24 | api/routes/musehub/ 44 route handlers (thin HTTP) |
| 25 | api/routes/mcp.py POST /mcp — HTTP Streamable MCP endpoint |
| 26 | services/ 26 musehub_*.py business logic modules |
| 27 | db/ SQLAlchemy ORM models (Postgres) |
| 28 | models/ Pydantic request/response models |
| 29 | mcp/ |
| 30 | dispatcher.py Async JSON-RPC 2.0 engine (no SDK dependency) |
| 31 | tools/ 40-tool catalogue (20 read + 15 write + 5 elicitation) |
| 32 | resources.py 29 musehub:// resources (12 static + 17 templated) |
| 33 | prompts.py 10 workflow prompts |
| 34 | write_tools/ Write executor modules (repos, issues, PRs, releases, social) |
| 35 | stdio_server.py stdio transport for local dev / Cursor IDE |
| 36 | templates/musehub/ Jinja2 + HTMX + Alpine.js web UI |
| 37 | auth/ JWT auth dependencies |
| 38 | config.py Pydantic Settings (env vars) |
| 39 | |
| 40 | tools/ |
| 41 | typing_audit.py Static typing violation scanner (ratchet-safe) |
| 42 | ``` |
| 43 | |
| 44 | ## Running locally |
| 45 | |
| 46 | ```bash |
| 47 | # Start with Docker Compose (Postgres + app) |
| 48 | docker compose up -d |
| 49 | |
| 50 | # Run Alembic migrations |
| 51 | docker compose exec musehub alembic upgrade head |
| 52 | |
| 53 | # Seed development data |
| 54 | docker compose exec musehub python3 scripts/seed_musehub.py |
| 55 | ``` |
| 56 | |
| 57 | ## API |
| 58 | |
| 59 | Interactive docs available at `/docs` when `DEBUG=true`. |
| 60 | |
| 61 | OpenAPI spec always available at `/api/v1/openapi.json`. |
| 62 | |
| 63 | ## Auth |
| 64 | |
| 65 | Write endpoints and private-repo reads require: |
| 66 | |
| 67 | ``` |
| 68 | Authorization: Bearer <jwt> |
| 69 | ``` |
| 70 | |
| 71 | Public repo reads and all MCP read tools are unauthenticated. MCP write tools require the same JWT in the `Authorization` header. |
| 72 | |
| 73 | --- |
| 74 | |
| 75 | ## MCP Integration |
| 76 | |
| 77 | MuseHub implements the full [MCP 2025-11-25 specification](https://modelcontextprotocol.io/specification/2025-11-25) — no external MCP SDK, pure Python async. Agents get complete capability parity with the web UI. |
| 78 | |
| 79 | ### Transports |
| 80 | |
| 81 | | Transport | Endpoint | Use case | |
| 82 | |-----------|----------|----------| |
| 83 | | HTTP Streamable | `POST /mcp` | Production; any MCP client | |
| 84 | | stdio | `python -m musehub.mcp.stdio_server` | Local dev, Cursor IDE | |
| 85 | |
| 86 | **Cursor IDE integration** — add to `.cursor/mcp.json`: |
| 87 | |
| 88 | ```json |
| 89 | { |
| 90 | "mcpServers": { |
| 91 | "musehub": { |
| 92 | "command": "python", |
| 93 | "args": ["-m", "musehub.mcp.stdio_server"], |
| 94 | "cwd": "/path/to/musehub" |
| 95 | } |
| 96 | } |
| 97 | } |
| 98 | ``` |
| 99 | |
| 100 | ### Tools — 40 total |
| 101 | |
| 102 | **Read tools (20):** list branches, list/get commits, compare refs, read files, search in-repo, list/get issues, list/get PRs, list releases, search public repos, get full AI context, get domain info, get domain insights, get dimension view, list domains, get whoami, muse pull, muse remote. |
| 103 | |
| 104 | **Write tools (15):** create/fork repos, create/update issues, comment on issues, create/merge PRs, inline PR comments, submit PR reviews, create releases, star repos, create labels, create agent token, muse push, muse config. |
| 105 | |
| 106 | **Elicitation-powered tools (5, MCP 2025-11-25):** interactive creation planner, interactive PR review, streaming platform OAuth connect, cloud DAW OAuth connect, interactive release creator. |
| 107 | |
| 108 | > All repo-scoped tools accept either `repo_id` (UUID) or `owner` + `slug` (human-readable) — the dispatcher resolves transparently. |
| 109 | |
| 110 | > Write and elicitation tools require `Authorization: Bearer <jwt>`. Elicitation tools also require an active session (`Mcp-Session-Id`). They degrade gracefully for stateless clients. |
| 111 | |
| 112 | ### Transports — Full Streamable HTTP (2025-11-25) |
| 113 | |
| 114 | | Verb | Endpoint | Purpose | |
| 115 | |------|----------|---------| |
| 116 | | `POST` | `/mcp` | All client→server requests; SSE stream for elicitation-powered tools | |
| 117 | | `GET` | `/mcp` | Persistent SSE push channel for server→client notifications | |
| 118 | | `DELETE` | `/mcp` | Client-initiated session termination | |
| 119 | | stdio | `python -m musehub.mcp.stdio_server` | Local dev, Cursor IDE | |
| 120 | |
| 121 | **Session lifecycle:** `POST initialize` → receive `Mcp-Session-Id` → include on all subsequent requests → `DELETE /mcp` to close. |
| 122 | |
| 123 | ### Resources — 29 total |
| 124 | |
| 125 | Cacheable, URI-addressable reads via the `musehub://` scheme. |
| 126 | |
| 127 | | URI | Description | |
| 128 | |-----|-------------| |
| 129 | | `musehub://trending` | Top public repos by star count | |
| 130 | | `musehub://me` | Authenticated user profile + pinned repos | |
| 131 | | `musehub://me/notifications` | Unread notification inbox | |
| 132 | | `musehub://me/starred` | Repos the user has starred | |
| 133 | | `musehub://me/feed` | Activity feed for watched repos | |
| 134 | | `musehub://repos/{owner}/{slug}` | Repo overview + stats | |
| 135 | | `musehub://repos/{owner}/{slug}/branches` | All branches | |
| 136 | | `musehub://repos/{owner}/{slug}/commits` | Commit list | |
| 137 | | `musehub://repos/{owner}/{slug}/commits/{commit_id}` | Single commit | |
| 138 | | `musehub://repos/{owner}/{slug}/tree/{ref}` | File tree at ref | |
| 139 | | `musehub://repos/{owner}/{slug}/blob/{ref}/{path}` | File metadata | |
| 140 | | `musehub://repos/{owner}/{slug}/issues` | Issue list | |
| 141 | | `musehub://repos/{owner}/{slug}/issues/{number}` | Issue + comment thread | |
| 142 | | `musehub://repos/{owner}/{slug}/pulls` | PR list | |
| 143 | | `musehub://repos/{owner}/{slug}/pulls/{number}` | PR + reviews | |
| 144 | | `musehub://repos/{owner}/{slug}/releases` | All releases | |
| 145 | | `musehub://repos/{owner}/{slug}/releases/{tag}` | Single release | |
| 146 | | `musehub://repos/{owner}/{slug}/analysis/{ref}` | Musical analysis | |
| 147 | | `musehub://repos/{owner}/{slug}/timeline` | Musical evolution timeline | |
| 148 | | `musehub://users/{username}` | User profile + public repos | |
| 149 | |
| 150 | ### Prompts — 10 total |
| 151 | |
| 152 | Workflow guides that teach agents how to chain tools and resources: |
| 153 | |
| 154 | | Prompt | Purpose | |
| 155 | |--------|---------| |
| 156 | | `musehub/orientation` | Essential onboarding for humans and agents; pass `caller_type: "agent"` for agent-specific guidance | |
| 157 | | `musehub/contribute` | End-to-end contribution: orient → issue → commit → PR → merge (includes auth/push setup) | |
| 158 | | `musehub/create` | Create a new Muse project from scratch with domain selection | |
| 159 | | `musehub/review_pr` | Musical PR review with track/region-level inline comments | |
| 160 | | `musehub/issue_triage` | Triage open issues: label, assign, link to milestones | |
| 161 | | `musehub/release_prep` | Prepare a release: merged PRs → release notes → publish | |
| 162 | | `musehub/onboard` | Interactive artist onboarding via elicitation | |
| 163 | | `musehub/release_to_world` | Full release + streaming distribution pipeline | |
| 164 | | `musehub/domain-discovery` | Discover and evaluate available domain plugins | |
| 165 | | `musehub/domain-authoring` | Author a new domain plugin from scratch | |
| 166 | |
| 167 | ### What an agent can do |
| 168 | |
| 169 | ``` |
| 170 | 1. Discover repos musehub://trending or musehub_search_repos |
| 171 | 2. Understand a repo musehub_get_context → musehub://repos/{owner}/{slug}/analysis/{ref} |
| 172 | 3. Open an issue musehub_create_issue |
| 173 | 4. Push a fix musehub_get_context → compose MIDI → musehub_create_pr |
| 174 | 5. Review a PR musehub_review_pr_interactive (elicitation-powered) |
| 175 | 6. Create release musehub_create_release_interactive (form + platform OAuth) |
| 176 | 7. Build social graph musehub_star_repo, musehub_fork_repo |
| 177 | 8. Connect platforms musehub_connect_streaming_platform (Spotify, SoundCloud, …) |
| 178 | 9. Connect cloud DAW musehub_connect_daw_cloud (LANDR, Splice, Soundtrap, …) |
| 179 | 10. Compose with AI musehub_create_with_preferences (interviews user, returns plan) |
| 180 | ``` |
| 181 | |
| 182 | Full reference: [`docs/reference/mcp.md`](docs/reference/mcp.md) |
| 183 | |
| 184 | --- |
| 185 | |
| 186 | ## Developer Tools |
| 187 | |
| 188 | ```bash |
| 189 | # Type violation audit (ratchet at 0 violations) |
| 190 | python tools/typing_audit.py --dirs musehub/ tests/ --max-any 0 |
| 191 | |
| 192 | # With JSON output |
| 193 | python tools/typing_audit.py --dirs musehub/ tests/ --json artifacts/typing_audit.json |
| 194 | ``` |
| 195 | |
| 196 | ## License |
| 197 | |
| 198 | Proprietary — Muse VCS. |