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