docs/reference/mcp.md · gabriel/musehub

# MuseHub MCP Reference

> Protocol version: **2025-03-26** | Implementation: pure-Python async, no external MCP SDK

MuseHub treats AI agents as first-class citizens. The MCP integration gives agents complete capability parity with the web UI: they can browse, search, compose, review, and publish — over a standard protocol that every major agent runtime supports.

6

---

## Table of Contents

1. [Architecture](#architecture)

12

2. [Transports](#transports)

13

3. [Authentication](#authentication)

14

4. [Tools — 27 total](#tools)

15

- [Read Tools (15)](#read-tools-15)

16

- [Write Tools (12)](#write-tools-12)

17

5. [Resources — 20 total](#resources)

18

- [Static Resources (5)](#static-resources-5)

19

- [Templated Resources (15)](#templated-resources-15)

20

6. [Prompts — 6 total](#prompts)

21

7. [Error Handling](#error-handling)

22

8. [Usage Patterns](#usage-patterns)

23

9. [Architecture Diagrams](#architecture-diagrams)

---

## Architecture

```

MCP Client (Cursor, Claude Desktop, any SDK)

31

│

32

├─ HTTP POST /mcp (production)

33

└─ stdio python -m musehub.mcp.stdio_server (local dev)

34

│

35

musehub/mcp/dispatcher.py ← async JSON-RPC 2.0 engine

36

│

37

┌───────┼───────────────┐

38

│ │ │

39

tools/call resources/read prompts/get

40

│ │ │

41

Read executors Resource handlers Prompt assembler

42

(musehub_mcp_executor.py) (resources.py) (prompts.py)

Write executors

(mcp/write_tools/)

│

AsyncSession → Postgres

47

```

48

49

The dispatcher speaks JSON-RPC 2.0 directly. The HTTP envelope is always `200 OK` — tool errors are signalled via `isError: true` on the content block, not via HTTP status codes. Notifications (no `id` field) return `202 Accepted` with an empty body.

---

## Transports

### HTTP Streamable — `POST /mcp`

56

57

The production transport. Accepts `application/json`.

```http

POST /mcp HTTP/1.1

Content-Type: application/json

62

Authorization: Bearer <jwt>

63

64

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

65

```

66

67

**Batch requests** — send a JSON array; responses are returned as an array in the same order (notifications are filtered out):

```http

POST /mcp

[

{"jsonrpc":"2.0","id":1,"method":"tools/list"},

73

{"jsonrpc":"2.0","id":2,"method":"resources/list"}

]

```

**Notifications** (no `id`) return `202 Accepted` with an empty body.

78

79

### stdio — `python -m musehub.mcp.stdio_server`

80

81

The local dev and Cursor IDE transport. Reads newline-delimited JSON from `stdin`, writes JSON-RPC responses to `stdout`, logs to `stderr`.

82

83

**Cursor IDE integration** — create or update `.cursor/mcp.json` in your workspace:

```json

{

"mcpServers": {

"musehub": {

"command": "python",

"args": ["-m", "musehub.mcp.stdio_server"],

91

"cwd": "/path/to/musehub"

}

}

}

```

The stdio server runs without auth (trusted local process). Write tools are available unconditionally.

---

## Authentication

| Context | How |

|---------|-----|

| HTTP transport — read tools + public resources | No auth required |

106

| HTTP transport — write tools | `Authorization: Bearer <jwt>` |

107

| HTTP transport — private repo resources | `Authorization: Bearer <jwt>` |

108

| stdio transport | No auth (trusted process) |

109

110

The JWT is the same token issued by the MuseHub auth endpoints (`POST /api/v1/auth/token`). The `sub` claim is used as the acting `user_id` for all write operations.

111

112

Attempting a write tool without a valid token returns a JSON-RPC error (`code: -32001`, `message: "Authentication required for write tools"`).

---

## Tools

All 27 tools use `server_side: true`. The JSON-RPC envelope is always a success response — errors are represented inside the content block via `isError: true`.

### Calling a tool

```json

{

"jsonrpc": "2.0",

"id": 1,

"method": "tools/call",

127

"params": {

128

"name": "musehub_browse_repo",

129

"arguments": { "repo_id": "abc123" }

}

}

```

Response:

```json

{

"jsonrpc": "2.0",

"id": 1,

"result": {

"content": [{ "type": "text", "text": "{\"name\":\"my-song\", ...}" }],

"isError": false

}

}

```

---

### Read Tools (15)

#### `musehub_browse_repo`

152

153

Orientation snapshot for a repo: metadata, default branch, recent commits, top-level file list.

154

155

156

|-----------|------|----------|-------------|

---

#### `musehub_list_branches`

162

163

All branches with their head commit IDs and timestamps.

164

165

166

|-----------|------|----------|-------------|

---

#### `musehub_list_commits`

172

173

Paginated commit history, newest first.

174

175

176

|-----------|------|----------|-------------|

---

#### `musehub_read_file`

184

185

Metadata for a single artifact (MIDI, MP3, WebP, etc.) at a given commit.

186

187

188

|-----------|------|----------|-------------|

---

#### `musehub_get_analysis`

196

197

13-dimension musical analysis for a repo at a given ref.

198

199

200

|-----------|------|----------|-------------|

201

202

| `ref` | string | no | Branch, tag, or commit SHA |

---

#### `musehub_search`

208

209

Keyword/path search over commits and file paths within a repo.

210

211

212

|-----------|------|----------|-------------|

---

#### `musehub_get_context`

219

220

Full AI context document for a repo — combines metadata, analysis, recent activity, and usage hints into a single structured payload.

221

222

223

|-----------|------|----------|-------------|

---

#### `musehub_get_commit`

229

230

Single commit detail with the full snapshot manifest (all file paths and content hashes at that point in history).

231

232

233

|-----------|------|----------|-------------|

---

#### `musehub_compare`

240

241

Musical diff between two refs — returns per-dimension change scores (harmony, rhythm, groove, key, tempo) and a list of changed file paths.

242

243

244

|-----------|------|----------|-------------|

---

#### `musehub_list_issues`

252

253

Issues with optional state, label, and assignee filters.

254

255

256

|-----------|------|----------|-------------|

---

#### `musehub_get_issue`

265

266

Single issue with its full comment thread.

267

268

269

|-----------|------|----------|-------------|

---

#### `musehub_list_prs`

276

277

Pull requests with optional state and base branch filters.

278

279

280

|-----------|------|----------|-------------|

---

#### `musehub_get_pr`

288

289

Single PR with all inline comments and reviews.

290

291

292

|-----------|------|----------|-------------|

---

#### `musehub_list_releases`

299

300

All releases for a repo with asset counts and timestamps.

301

302

303

|-----------|------|----------|-------------|

---

#### `musehub_search_repos`

309

310

Discover public repos by text query or musical attributes.

311

312

313

|-----------|------|----------|-------------|

314

315

| `key` | string | no | Musical key filter (e.g. `"C major"`) |

---

### Write Tools (12)

> All write tools require `Authorization: Bearer <jwt>` on the HTTP transport.

326

327

#### `musehub_create_repo`

328

329

Create a new repository.

330

331

332

|-----------|------|----------|-------------|

---

#### `musehub_fork_repo`

346

347

Fork an existing repository into the authenticated user's account.

348

349

350

|-----------|------|----------|-------------|

---

#### `musehub_create_issue`

Open a new issue.

|-----------|------|----------|-------------|

---

#### `musehub_update_issue`

372

373

Update issue state or metadata.

374

375

376

|-----------|------|----------|-------------|

---

#### `musehub_create_issue_comment`

388

389

Post a comment on an issue.

390

391

392

|-----------|------|----------|-------------|

---

#### `musehub_create_pr`

Open a pull request.

|-----------|------|----------|-------------|

---

#### `musehub_merge_pr`

414

415

Merge an open pull request.

416

417

418

|-----------|------|----------|-------------|

---

#### `musehub_create_pr_comment`

426

427

Post an inline comment on a PR. Supports general, track-level, and beat-range comments — mirroring the musical diff view in the web UI.

428

429

430

|-----------|------|----------|-------------|

---

#### `musehub_submit_pr_review`

442

443

Submit a formal review on a PR.

444

445

446

|-----------|------|----------|-------------|

---

#### `musehub_create_release`

Publish a release.

|-----------|------|----------|-------------|

460

461

| `tag` | string | yes | Tag name (e.g. `"v1.0.0"`) |

---

#### `musehub_star_repo`

Star a repository.

|-----------|------|----------|-------------|

---

#### `musehub_create_label`

480

481

Create a label scoped to a repository.

482

483

484

|-----------|------|----------|-------------|

---

## Resources

Resources are side-effect-free, cacheable, URI-addressable reads. All resources return `application/json`. They are read via the `resources/read` method.

495

496

### Listing resources

497

498

```json

499

{"jsonrpc":"2.0","id":1,"method":"resources/list"}

500

{"jsonrpc":"2.0","id":2,"method":"resources/templates/list"}

501

```

502

503

### Reading a resource

```json

{

"jsonrpc": "2.0",

"id": 1,

"method": "resources/read",

510

"params": { "uri": "musehub://trending" }

}

```

Response:

```json

{

"jsonrpc": "2.0",

"id": 1,

"result": {

"contents": [{

"uri": "musehub://trending",

523

"mimeType": "application/json",

524

"text": "[{\"repo_id\":\"...\",\"name\":\"my-song\",...}]"

}]

}

}

```

---

### Static Resources (5)

533

534

#### `musehub://trending`

535

536

Top 20 public repos ordered by star count. Anonymous-accessible.

537

538

**Returns:** array of repo summaries with `repo_id`, `name`, `owner`, `slug`, `description`, `visibility`, `clone_url`, `created_at`.

---

#### `musehub://me`

Authenticated user's profile and their most recent 20 repos. Requires JWT.

545

546

**Returns:** `{ "user_id", "username", "repos": [...] }`

---

#### `musehub://me/notifications`

551

552

Unread notifications for the authenticated user. Requires JWT.

553

554

**Returns:** `{ "notifications": [{ "id", "event_type", "read", "created_at" }] }`

---

#### `musehub://me/starred`

559

560

Repos the authenticated user has starred. Requires JWT.

561

562

**Returns:** `{ "starred": [{ "repo_id", "name", "owner", "slug", "starred_at" }] }`

---

#### `musehub://me/feed`

567

568

Activity feed for repos the authenticated user watches. Requires JWT.

569

570

**Returns:** `{ "feed": [...] }`

---

### Templated Resources (15)

575

576

All templated resources follow RFC 6570 Level 1. `{owner}` and `{slug}` are resolved to a `repo_id` by the dispatcher — agents use human-readable names, not UUIDs.

577

578

#### `musehub://repos/{owner}/{slug}`

579

580

Repo overview: metadata, visibility, default branch, tag list, description.

---

#### `musehub://repos/{owner}/{slug}/branches`

585

586

All branches with their name, head commit ID, and last-updated timestamp.

---

#### `musehub://repos/{owner}/{slug}/commits`

591

592

20 most recent commits on the default branch. Includes commit message, author, timestamp.

---

#### `musehub://repos/{owner}/{slug}/commits/{commit_id}`

597

598

Single commit with its full snapshot manifest (all file paths and content hashes at that point).

---

#### `musehub://repos/{owner}/{slug}/tree/{ref}`

603

604

File tree at a given ref. Returns all object paths and guessed MIME types.

---

#### `musehub://repos/{owner}/{slug}/blob/{ref}/{path}`

609

610

Metadata for a single file at a given ref: path, content hash, MIME type, size.

---

#### `musehub://repos/{owner}/{slug}/issues`

615

616

Open issues list with labels, assignees, and comment counts.

---

#### `musehub://repos/{owner}/{slug}/issues/{number}`

621

622

Single issue with its full comment thread.

---

#### `musehub://repos/{owner}/{slug}/pulls`

627

628

Open PRs with source/target branches and review counts.

---

#### `musehub://repos/{owner}/{slug}/pulls/{number}`

633

634

Single PR with all inline comments and reviews (reviewer, state, body).

---

#### `musehub://repos/{owner}/{slug}/releases`

639

640

All releases ordered newest first: tag, title, body, asset count, timestamp.

---

#### `musehub://repos/{owner}/{slug}/releases/{tag}`

645

646

Single release matching a tag name, including the full release notes body.

---

#### `musehub://repos/{owner}/{slug}/analysis/{ref}`

651

652

Musical analysis at a given ref: key, tempo, time signature, per-dimension scores (harmony, rhythm, groove, dynamics, orchestration, …).

---

#### `musehub://repos/{owner}/{slug}/timeline`

657

658

Musical evolution timeline: commits, section events, and track events in chronological order.

---

#### `musehub://users/{username}`

663

664

User profile and their 20 most recent public repos.

---

## Prompts

Prompts teach agents how to chain tools and resources to accomplish multi-step goals. They return a structured list of `role`/`content` messages that frame the task for the agent.

### Getting a prompt

```json

{

"jsonrpc": "2.0",

"id": 1,

"method": "prompts/get",

679

"params": {

680

"name": "musehub/orientation"

}

}

```

With arguments:

```json

{

"jsonrpc": "2.0",

"id": 1,

"method": "prompts/get",

692

"params": {

693

"name": "musehub/contribute",

"arguments": {

"repo_id": "abc123",

"owner": "alice",

"slug": "my-song"

}

}

}

```

---

### `musehub/orientation`

**Arguments:** none

The essential first read for any new agent. Explains MuseHub's model (repos, commits, branches, musical analysis), the `musehub://` URI scheme, which tools to use for reads vs. writes, and how to authenticate.

---

### `musehub/contribute`

714

715

**Arguments:** `repo_id`, `owner`, `slug`

716

717

End-to-end contribution workflow:

718

719

1. `musehub_get_context` — understand the repo

720

2. `musehub://repos/{owner}/{slug}/issues` — find open issues

721

3. `musehub_create_issue` — or create a new one

722

4. Make changes, push a commit

723

5. `musehub_create_pr` — open a PR

724

6. `musehub_submit_pr_review` — request review

725

7. `musehub_merge_pr` — merge when approved

---

### `musehub/compose`

730

731

**Arguments:** `repo_id`

732

733

Musical composition workflow:

734

735

1. `musehub_get_context` — understand existing tracks and structure

736

2. `musehub://repos/{owner}/{slug}/analysis/{ref}` — study the musical analysis

737

3. Compose new MIDI matching key/tempo/style

738

4. Push the commit

739

5. Verify the new analysis with `musehub_get_analysis`

---

### `musehub/review_pr`

744

745

**Arguments:** `repo_id`, `pr_id`

Musical PR review:

1. `musehub_get_pr` — read the PR metadata

750

2. `musehub_compare` — get per-dimension diff scores

751

3. `musehub://repos/{owner}/{slug}/analysis/{ref}` — compare analyses for base and head

752

4. `musehub_create_pr_comment` — post track/region-level comments

753

5. `musehub_submit_pr_review` — approve or request changes

---

### `musehub/issue_triage`

758

759

**Arguments:** `repo_id`

Triage open issues:

1. `musehub_list_issues` — list open issues

764

2. Categorise by type (bug, feature, discussion)

765

3. `musehub_create_label` — create missing labels

766

4. `musehub_update_issue` — apply labels, assign, close duplicates

---

### `musehub/release_prep`

771

772

**Arguments:** `repo_id`

Prepare a release:

1. `musehub_list_prs` — find merged PRs since the last release

777

2. `musehub_list_releases` — check the latest release tag

778

3. `musehub_get_analysis` — summarise musical changes

779

4. Draft release notes (Markdown)

780

5. `musehub_create_release` — publish

---

## Error Handling

### JSON-RPC error codes

| Code | Meaning |

|------|---------|

| `-32700` | Parse error — request body is not valid JSON |

791

| `-32600` | Invalid request — not an object or array |

792

| `-32601` | Method not found |

793

| `-32602` | Invalid params — required argument missing or wrong type |

794

| `-32603` | Internal error — unexpected server exception |

795

| `-32001` | Authentication required — write tool called without valid JWT |

### Tool errors

Tool execution errors are not JSON-RPC errors. The envelope is always a success response; the error is signalled inside the result:

```json

{

"result": {

"content": [{ "type": "text", "text": "repo not found: abc123" }],

"isError": true

}

}

```

---

## Usage Patterns

### Pattern 1: Discover and explore

815

816

```

817

1. resources/read musehub://trending → pick a repo

818

2. resources/read musehub://repos/{owner}/{slug} → orientation

819

3. tools/call musehub_get_context → full AI context

820

4. resources/read musehub://repos/{owner}/{slug}/analysis/{ref} → musical detail

821

```

822

823

### Pattern 2: Fix a bug, open a PR

824

825

```

826

1. tools/call musehub_list_issues { repo_id, state: "open" }

827

2. tools/call musehub_get_issue { repo_id, issue_number }

828

3. tools/call musehub_browse_repo { repo_id }

829

4. tools/call musehub_read_file { repo_id, path }

830

5. -- compose fix, push commit --

831

6. tools/call musehub_create_pr { repo_id, title, from_branch, to_branch }

832

```

833

834

### Pattern 3: Full musical PR review

835

836

```

837

1. tools/call musehub_get_pr { repo_id, pr_number }

838

2. tools/call musehub_compare { repo_id, base_ref, head_ref }

839

3. resources/read musehub://repos/{owner}/{slug}/analysis/{base_ref}

840

4. resources/read musehub://repos/{owner}/{slug}/analysis/{head_ref}

841

5. tools/call musehub_create_pr_comment {

842

repo_id, pr_number, body: "...",

843

target_type: "track", target_track: "Bass",

844

target_beat_start: 0, target_beat_end: 32

845

}

846

6. tools/call musehub_submit_pr_review { repo_id, pr_number, state: "approved" }

847

```

848

849

### Pattern 4: Publish a release

850

851

```

852

1. tools/call musehub_list_releases { repo_id }

853

2. tools/call musehub_list_prs { repo_id, state: "closed" }

854

3. tools/call musehub_get_analysis { repo_id, ref: "main" }

855

4. tools/call musehub_create_release {

856

repo_id, tag: "v1.2.0", title: "Spring Drop",

857

body: "## What changed\n..."

}

```

---

## Architecture Diagrams

### Request flow

```mermaid

flowchart TD

subgraph transports [Transports]

870

HTTP["POST /mcp\nHTTP Streamable"]

871

stdio["stdio\npython -m musehub.mcp.stdio_server"]

872

end

873

874

subgraph dispatcher [musehub/mcp/dispatcher.py]

875

D["handle_request()"]

876

D --> INIT["initialize"]

877

D --> TL["tools/list"]

878

D --> TC["tools/call"]

879

D --> RL["resources/list\nresources/templates/list"]

880

D --> RR["resources/read"]

881

D --> PL["prompts/list"]

882

D --> PG["prompts/get"]

883

end

884

885

subgraph execution [Execution Layer]

886

READ["Read executors\nmusehub_mcp_executor.py"]

887

WRITE["Write executors\nmcp/write_tools/"]

888

RES["Resource handlers\nmcp/resources.py"]

889

PROMPTS["Prompt assembler\nmcp/prompts.py"]

end

HTTP --> D

stdio --> D

TC --> READ

TC --> WRITE

RR --> RES

PG --> PROMPTS

READ --> DB[("AsyncSession / Postgres")]

WRITE --> DB

RES --> DB

```

### Tool catalogue structure

```mermaid

classDiagram

class MUSEHUB_READ_TOOLS {

908

<<list of MCPToolDef — 15 tools>>

909

musehub_browse_repo

910

musehub_list_branches

musehub_list_commits

musehub_read_file

musehub_get_analysis

musehub_search

musehub_get_context

musehub_get_commit

musehub_compare

musehub_list_issues

musehub_get_issue

musehub_list_prs

musehub_get_pr

musehub_list_releases

923

musehub_search_repos

924

}

925

class MUSEHUB_WRITE_TOOLS {

926

<<list of MCPToolDef — 12 tools>>

musehub_create_repo

musehub_fork_repo

musehub_create_issue

musehub_update_issue

musehub_create_issue_comment

932

musehub_create_pr

933

musehub_merge_pr

934

musehub_create_pr_comment

935

musehub_submit_pr_review

936

musehub_create_release

musehub_star_repo

musehub_create_label

}

class MCPDispatcher {

941

+handle_request(raw, user_id)

942

+handle_batch(raw, user_id)

943

}

944

945

MCPDispatcher ..> MUSEHUB_READ_TOOLS : routes read calls

946

MCPDispatcher ..> MUSEHUB_WRITE_TOOLS : routes write calls (JWT required)

947

```

948

949

### Resource URI hierarchy

```mermaid

flowchart TD

root["musehub://"]

root --> trending["trending"]

955

root --> me["me"]

956

root --> repos["repos/{owner}/{slug}"]

957

root --> users["users/{username}"]

958

959

me --> notifications["me/notifications"]

960

me --> starred["me/starred"]

961

me --> feed["me/feed"]

962

963

repos --> branches["…/branches"]

964

repos --> commits["…/commits"]

965

commits --> commit["…/commits/{commit_id}"]

966

repos --> tree["…/tree/{ref}"]

967

repos --> blob["…/blob/{ref}/{path}"]

968

repos --> issues["…/issues"]

969

issues --> issue["…/issues/{number}"]

970

repos --> pulls["…/pulls"]

971

pulls --> pull["…/pulls/{number}"]

972

repos --> releases["…/releases"]

973

releases --> release["…/releases/{tag}"]

974

repos --> analysis["…/analysis/{ref}"]

975

repos --> timeline["…/timeline"]

976

```