# MuseHub

**The collaboration hub for the agent era.**

MuseHub is what GitHub would look like if it were designed from scratch for AI agents,
multidimensional state, and version control that goes beyond text files.

Powered by [Muse VCS](/gabriel/muse) — the world's first domain-agnostic, multi-dimensional
version control system. Where Git tracks text, Muse tracks *structured state* across any
domain: Code, MIDI, Genomics, Circuit Design, 3D scenes — and any domain you define.

MuseHub is the remote layer: push commits, open merge proposals, track issues, browse repos,
publish releases, and give AI agents complete programmatic access via a best-in-class
MCP integration built in pure Python, no external SDK.

---

## Why MuseHub

**Git was designed in 2005 for one thing: tracking text diffs.**
It has no concept of multidimensional state, no first-class agent authorship, no symbol-level
intelligence, and no provenance trail. Every tool built on top of Git inherits those limits.

Muse starts over. MuseHub extends that foundation with the collaboration infrastructure the
agent era actually demands:

| Git + GitHub | Muse + MuseHub |
|---|---|
| Text-only diffs | Domain-defined multidimensional state |
| Commit authors are strings | Commits carry structured provenance: `agent_id`, `model_id`, `toolchain_id`, `signature` |
| No symbol awareness | Live symbol graph: impact, blast radius, dead code, coupling, velocity |
| Code review is line-diffing | Merge proposals with `dimension_ref`-anchored inline comments |
| CI is a separate product | Intel: health score, hotspots, breaking changes — baked into every repo |
| MCP is bolted on | MCP is the primary API — 40 tools, 29 resources, 10 prompts, zero external SDK |

---

## Quickstart

```bash
# 1. Start the stack (Postgres + app)
docker compose up -d

# 2. Run migrations
docker compose exec musehub alembic upgrade head

# 3. Seed development data
docker compose exec musehub python3 scripts/seed_musehub.py
```

> **Requirements:** Python 3.14+ · PostgreSQL 16+ · Node.js 22+

Web UI: `https://localhost:1337`
Interactive API docs: `https://localhost:1337/docs` (requires `DEBUG=true`)
OpenAPI spec: `https://localhost:1337/api/openapi.json`

---

## Connecting a Muse Repo

```bash
# Add MuseHub as a remote
muse remote add local https://localhost:1337/repos/gabriel/<repo>

# Push
muse push local dev

# Pull
muse pull local dev
```

Create a repo on MuseHub before the first push:

```bash
TOKEN=$(python3 -c "
import tomllib, pathlib
data = tomllib.loads(pathlib.Path.home().joinpath('.muse/identity.toml').read_text())
print(data['localhost:1337']['token'])
")

curl -s -X POST https://localhost:1337/api/repos \
  -H "Content-Type: application/json" \
  -H "Authorization: MSign handle=\"gabriel\" ts=<ts> sig=\"<sig>\"" \
  -d '{"owner":"gabriel","name":"my-repo","description":"..."}'
```

---

## Agent Provenance

Every commit pushed to MuseHub can carry structured agent metadata. The web UI and API
surface it everywhere — file tree, commit stream, merge proposals, releases.

```bash
muse commit -m "feat: redesign auth layer" \
  --agent-id    "agentception-worker-42" \
  --model-id    "claude-sonnet-4-6" \
  --toolchain-id "agentception/v1" \
  --sign
```

Fields stored on every commit:

| Field | Description |
|---|---|
| `agent_id` | Which agent instance produced this commit |
| `model_id` | Which model (`claude-sonnet-4-6`, `claude-opus-4-6`, …) |
| `toolchain_id` | Orchestration system (`agentception/v1`, `cursor/mcp`, …) |
| `prompt_hash` | SHA-256 of the prompt that drove this commit |
| `signature` | HMAC over the provenance payload — verified by `muse verify` |

---

## Symbol Intelligence (Intel)

The Intel layer computes a live health score for every repo from its symbol graph.
Available in the web UI under the **Intel** tab and via MCP.

```
health_score      0–100 composite score
health_label      Excellent / Good / Fair / Poor / Critical
hotspots          Symbols changing too frequently (churn risk)
dead_candidates   Symbols untouched ≥ 90 days with non-zero blast radius
blast_risk        Symbols whose change triggers widespread co-changes
coupling_pairs    Pairs that always change together (hidden dependency signal)
velocity          Commit velocity by week
breaking_changes  Breaking commits in the last 30 days
```

---

## URL Scheme

```
/{owner}/{slug}                    Repo home — code, file tree, README
/{owner}/{slug}/commits            Commit history + DAG graph
/{owner}/{slug}/commits/{id}       Commit detail + provenance + diff
/{owner}/{slug}/proposals          Merge proposals
/{owner}/{slug}/issues             Issue tracker
/{owner}/{slug}/intel              Symbol intelligence dashboard
/{owner}/{slug}/insights           Velocity + agent attribution charts
/{owner}/{slug}/releases           Published releases
/{owner}/{slug}/graph              Commit DAG visualizer

musehub://{owner}/{slug}           MCP resource URI
mcp://musehub/{owner}/{slug}       MCP clone URI
```

---

## MCP Integration

MuseHub implements the full [MCP 2025-11-25 specification](https://modelcontextprotocol.io/specification/2025-11-25)
in pure Python async — no external MCP SDK. Agents get complete capability parity with
the web UI.

### Transports

| Transport | Endpoint | Use case |
|---|---|---|
| HTTP Streamable | `POST /mcp` | Production; any MCP client |
| stdio | `python -m musehub.mcp.stdio_server` | Local dev, Cursor, VS Code |

**Session lifecycle:**
`POST initialize` → receive `Mcp-Session-Id` → include on all subsequent requests → `DELETE /mcp` to close.

### Cursor / VS Code Setup

```json
{
  "mcpServers": {
    "musehub": {
      "command": "python",
      "args": ["-m", "musehub.mcp.stdio_server"],
      "cwd": "/path/to/musehub"
    }
  }
}
```

### Agent Onboarding Sequence

```python
musehub_whoami()                                    # 1. confirm auth
musehub_list_domains(verified=True)                 # 2. discover state models
musehub_get_context(owner="gabriel", slug="repo")   # 3. read before writing
musehub_create_issue(...)                           # 4. open work item
muse_push(repo_id=..., branch=..., commits=[...])  # 5. push state
musehub_create_proposal(...)                        # 6. open merge proposal
musehub_merge_proposal(...)                         # 7. merge
```

> All repo-scoped tools accept either `repo_id` (UUID) or `owner` + `slug`. The dispatcher resolves either form transparently.

### Tools — 40 total

**Read tools (20+)**

| Tool | What it does |
|---|---|
| `musehub_get_context` | Full repo context — your oracle before any write |
| `musehub_list_commits` | Paginated commit list with full provenance |
| `musehub_get_commit` | Single commit detail |
| `musehub_compare` | Diff two branches or commits |
| `musehub_read_file` | Read a file at any ref |
| `musehub_search` | Search paths or commit messages |
| `musehub_list_branches` | All branches |
| `musehub_list_issues` / `musehub_get_issue` | Issues + threads |
| `musehub_list_proposals` / `musehub_get_proposal` | Merge proposals + reviews |
| `musehub_proposal_risk` | Risk score for a merge |
| `musehub_proposal_symbol_diff` | Symbol-level diff for a proposal |
| `musehub_proposal_breakage` | Breaking change detection |
| `musehub_list_symbols` / `musehub_get_symbol` | Symbol index |
| `musehub_symbol_impact` | Blast radius of a symbol |
| `musehub_symbol_clones` | Near-duplicate symbol detection |
| `musehub_intel_health_score` | Repo health score |
| `musehub_intel_hotspots` | Top churn symbols |
| `musehub_intel_dead` | Dead code candidates |
| `musehub_intel_blast_risk` | High blast-radius symbols |
| `musehub_list_releases` | All releases |
| `musehub_search_repos` | Discover public repos |
| `musehub_list_domains` / `musehub_get_domain` | Domain plugin registry |
| `musehub_whoami` | Current auth status |
| `muse_pull` / `muse_remote` | VCS operations |

**Write tools (15+)**

| Tool | What it does |
|---|---|
| `muse_push` | Push commits and objects to MuseHub |
| `musehub_create_repo` / `musehub_fork_repo` | Repo management |
| `musehub_create_issue` / `musehub_update_issue` | Issue lifecycle |
| `musehub_create_issue_comment` | Comment on issues |
| `musehub_create_proposal` / `musehub_merge_proposal` | Merge proposal lifecycle |
| `musehub_create_proposal_comment` | Inline comments on proposals |
| `musehub_submit_proposal_review` | Submit a proposal review |
| `musehub_create_release` | Publish a release |
| `musehub_star_repo` | Star a repo |
| `musehub_create_label` | Create issue/proposal labels |

### Resources — 29 total

Cacheable, URI-addressable reads via the `musehub://` scheme.

```
musehub://trending
musehub://me
musehub://me/notifications
musehub://me/starred
musehub://me/feed
musehub://repos/{owner}/{slug}
musehub://repos/{owner}/{slug}/branches
musehub://repos/{owner}/{slug}/commits
musehub://repos/{owner}/{slug}/commits/{id}
musehub://repos/{owner}/{slug}/tree/{ref}
musehub://repos/{owner}/{slug}/blob/{ref}/{path}
musehub://repos/{owner}/{slug}/issues
musehub://repos/{owner}/{slug}/issues/{number}
musehub://repos/{owner}/{slug}/proposals
musehub://repos/{owner}/{slug}/proposals/{number}
musehub://repos/{owner}/{slug}/releases
musehub://repos/{owner}/{slug}/releases/{tag}
musehub://users/{username}
```

### Prompts — 10 total

Workflow guides that teach agents how to chain tools correctly:

| Prompt | Purpose |
|---|---|
| `musehub/orientation` | Essential onboarding — pass `caller_type: "agent"` for agent edition |
| `musehub/contribute` | Orient → issue → commit → proposal → merge |
| `musehub/create` | Create a new Muse project from scratch |
| `musehub/review_proposal` | Proposal review with `dimension_ref`-anchored inline comments |
| `musehub/issue_triage` | Label, assign, link issues to milestones |
| `musehub/release_prep` | Merged proposals → release notes → publish |
| `musehub/domain-discovery` | Discover and evaluate domain plugins |
| `musehub/domain-authoring` | Build and publish a new domain plugin |

Full reference: [`docs/reference/mcp.md`](docs/reference/mcp.md)

---

## Auth

```
Authorization: MSign handle="gabriel" ts=<ts> sig="<sig>"
```

Public repo reads and all MCP read tools are unauthenticated.
Write endpoints require an MSign request signature.

Register your Ed25519 public key via `muse hub connect` or the MuseHub identity API. The `muse` CLI signs requests automatically using the key registered in `~/.muse/identity.toml`.

Tokens live in `~/.muse/identity.toml`:

```toml
["localhost:1337"]
type  = "human"
name  = "gabriel"
```

---

## Architecture

```
musehub/
  api/routes/musehub/   Route handlers (thin HTTP layer)
  api/routes/mcp.py     POST /mcp — HTTP Streamable MCP endpoint
  services/             Business logic modules
  db/                   SQLAlchemy ORM models (Postgres)
  models/               Pydantic request/response models
  mcp/
    dispatcher.py       Async JSON-RPC 2.0 engine (no external SDK)
    tools/              40-tool catalogue
    resources.py        29 musehub:// resources
    prompts.py          10 workflow prompts
    stdio_server.py     stdio transport for local dev
  templates/musehub/    Jinja2 + HTMX + Alpine.js web UI
  auth/                 MSign auth middleware (Ed25519)
  config.py             Pydantic Settings (env vars)

tools/
  typing_audit.py       Static typing violation scanner (ratcheted at 0 violations)
```

---

## Developer Tools

```bash
# Type audit — ratcheted at 0 violations
python tools/typing_audit.py --dirs musehub/ tests/ --max-any 0

# JSON output
python tools/typing_audit.py --dirs musehub/ tests/ --json artifacts/typing_audit.json
```

---

## License

MIT — see [LICENSE](LICENSE).

bump prebuild mpack