berbotu-mcp

Model Context Protocol server for the Berbotu vault. Currently stage 3 — four tools over stdio:

• ping — health check (no args)
• list_demos — lists demo submissions, optional stage filter + limit
• list_releases — lists tracks + EPs, optional stage filter, format filters, limit
• add_demo ✍️ — creates a new demo file via GitHub commit (write tool)

Quick start

npm install
npm run build            # compile TS → dist/
npm run inspect          # open MCP Inspector (web UI) to call tools

Or attach to Claude Desktop by adding to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "berbotu": {
      "command": "node",
      "args": ["/path/to/berbotu-mcp/dist/index.js"],
      "env": {
        "BERBOTU_VAULT_PATH": "/path/to/Berbotu OS"
      }
    }
  }
}

Restart Claude Desktop. The ping tool will appear under "Search and tools".

Tools

ping

No arguments. Returns server name + version + vault path + timestamp + pid + node version. Use to confirm the server is alive and pointing at the right vault.

list_demos

Lists demo submissions from <vault>/00 Releases/Demos/, sorted newest-first by received_date.

Arguments (all optional):

• stage (string) — case-insensitive substring of the demo stage. Common values: Listening, Review, Interested, Hold, Pass, Converted.
• limit (integer 1–200) — cap on returned items.

Returns one line per demo: [stage] artist — title ⭐score (received YYYY-MM-DD).

Example: ask Claude "what demos came in this week that I haven't decided on yet?" → it calls list_demos with stage: "Listening".

list_releases

Lists track + EP releases from <vault>/00 Releases/Tracks/ and <vault>/00 Releases/EPs/, sorted newest-first by release_date.

Arguments (all optional):

• stage (string) — case-insensitive substring filter. Common: Released, Scheduled, DITTO Submitted, On Hold.
• includeEps (boolean, default true) — include EPs.
• includeTracks (boolean, default true) — include single-track releases.
• limit (integer 1–200).

Returns one line per release: [stage] YYYY-MM-DD · artist — title (single|EP · genre).

Example: "what's the next release scheduled?" → list_releases with stage: "Scheduled", limit: 1.

Error handling

All tools return a friendly isError: true message instead of throwing when:

• BERBOTU_VAULT_PATH env var is not set (read tools)
• VAULT_WRITE_PAT env var is not set (write tools only)
• The path exists but the Demos/ / Tracks/ / EPs/ folder is missing
• Individual files are unreadable (silently skipped per file)
• A YAML frontmatter is malformed (treated as empty data)
• GitHub API returns a non-2xx (422 = file already exists, 401 = bad PAT, etc.)
• Network unreachable
• add_demo invoked with empty artist or track (zod rejects pre-flight)

add_demo

Creates a new demo file in the vault by committing to the berbotu/vault GitHub repo. Write tool — declares destructiveHint: true, openWorldHint: true so MCP-aware clients can warn before invoking.

Required:

• artist (string, 1–120 chars) — producer alias
• track (string, 1–200 chars) — track title (use UNTITLED if none)

Optional:

• stage (enum) — Listening (default) / Review / Interested / Hold / Pass / Converted
• received_date (string YYYY-MM-DD) — defaults to today UTC
• notes (string ≤ 2000 chars) — free-text card notes

Refuses to overwrite. If a demo at 00 Releases/Demos/{ARTIST} - {TITLE}.md already exists, returns isError with a "use the admin website to edit" message.

Success returns the file path, the frontmatter that was written, the commit SHA, and a permalink to the commit on github.com.

Requires VAULT_WRITE_PAT env (GitHub fine-grained PAT with Contents: Read and write on berbotu/vault).

Scripts

• npm run build — compile TS to dist/
• npm run dev — tsx watch mode (re-runs on src change)
• npm run start — run compiled server (stdio)
• npm run inspect — build + open MCP Inspector
• npm run typecheck — type check without emit

Roadmap

See CLAUDE.md. Stage 1 done; stages 2–5 pending.

License

Internal. Not for redistribution.