Dolt MCP Vcs

dolt-mcp-vcs

One skill for every make and model of Dolt: detect the flavor and mode first, then do version-control work over the beads (bd) backend and DoltHub.

Formerly beads-dolt — same plugin, renamed to its Dolt-first identity. The beads-dolt install slug still resolves (a deprecated catalog alias) and /beads-dolt is still an accepted trigger, so existing installs keep working — beads is now use-case adapter #1, not the whole skill.

The Dolt and DoltHub-aware layer for the beads (bd) task tracker. It composes with — does not replace — the global beads skill: that skill runs the bead work cycle; this one handles the Dolt backend, DoltHub visibility, and the bd plus Dolt failure modes.

Overview

bd stores every issue in a version-controlled Dolt database. Two things bite teams repeatedly:

1. "My beads aren't showing in DoltHub." The overwhelmingly common cause is that the workspace's Dolt repo has no remote configured — so nothing is ever pushed. A file-protocol or GitHub backup does not make beads appear on DoltHub; only a Dolt remote plus a push does.
2. JSONL appears stale after rapid writes. This is the export throttle, not data loss. As of bd 1.0.4 the historical rapid-write race (failure mode 6) is fixed at the SQL-transaction level; the database is always correct, only the issues.jsonl file can lag.

This skill diagnoses both, applies the fixes, and routes deeper work to five bundled agents. It keeps no frozen copy of bd/Dolt internals — a baked snapshot goes stale the moment upstream ships a release; the installed binary wins on any conflict. Verify version-specific behavior live (bd --help, bd <cmd> --help, bd dolt show) and consult the upstream docs; Read references/dolt-internals.md for the directory of those authoritative sources. The agents fetch current truth in their own context, so answers track the installed binary rather than a guess.

The fix for invisible-on-DoltHub, up front (don't stop at diagnosis): the cause is almost always no remote, and the fix is two commands — bd dolt remote add origin https://doltremoteapi.dolthub.com/ORG/REPO then bd dolt push --remote origin. The DoltHub database must already exist (the push does NOT create it). Always carry the user all the way to these commands, not just the bd dolt remote list diagnostic.

Prerequisites

• bd >= 1.0.4 with a Dolt-backed workspace (bd dolt show succeeds).
• For DoltHub: a dolt creds keypair authorized on your DoltHub account, and the DoltHub database must already exist (create it in the DoltHub UI — the push does not auto-create it).
• For the SQL-capable agents: the dolt-mcp-server binary on PATH, pinned to the exact version in the plugin README's install section (never @latest — the plugin's correctness rests on this binary). The plugin's .mcp.json wires it.

Authentication

DoltHub pushes authenticate with a dolt creds keypair tied to your account (run dolt login once to create and authorize it), or with the DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD environment variables. The dolt-mcp connection uses DOLT_USER and DOLT_PASSWORD (bd's local server is unauthenticated by default — user root, empty password).

Instructions

Step 0: Detect — "what kind of Dolt database are we working with?"

Always start here when the flavor/mode is not already known (invoked with no args, a new workspace, or any "connect me / what is this" ask). Run the detector and present the findings before doing anything else:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/dolt-detect.py            # inspect cwd (read-only)
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/dolt-detect.py PATH --json
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/dolt-detect.py --emit-descriptor  # write connection.descriptor.json

It returns ranked findings (live-server > repo > embedded > file), each a ready-to-use connection descriptor. Report them verbatim-honest, e.g.: "found: dolt/server on 127.0.0.1:39353 (beads, actual bound port from /proc — not config.yaml), and dolt/embedded at .beads/embeddeddolt/spine — read-only, the .lock is owned by bd." Then route:

Degrade honestly: an open MySQL port whose greeting doesn't name the flavor is reported as unconfirmed (the detector cross-checks live dolt processes for evidence); undetected states are reported, never guessed.

Step 1: Diagnose visibility ("my beads aren't in DoltHub")

bd dolt show            # confirm the database name and server port
bd dolt remote list     # the smoking gun: "No remotes configured" means nothing is pushed

If no remote is configured, that is the root cause. Proceed to Step 2.

Step 2: Configure the DoltHub remote and push

The DoltHub database must exist first (create it at dolthub.com, "Create Database"). Then:

# Use the bd wrapper (tracks the remote at the SQL layer and sets sync.remote for scheduled pushes)
bd dolt remote add origin https://doltremoteapi.dolthub.com/ORG/REPO
bd dolt push --remote origin

• The push is history-preserving — it transfers the full Dolt commit history, not a snapshot. (Flat-file dolt table import would lose history; do not use it for an existing bd database.)
• A PermissionDenied that reaches "Uploading…" first means the creds work but the DoltHub repo doesn't exist yet — create it, then re-push.
• Verify without cloning, via DoltHub's SQL API:

  curl -s "https://www.dolthub.com/api/v1alpha1/ORG/REPO/main?q=SELECT%20COUNT(*)%20FROM%20issues"

Step 3: Keep it fresh (don't push per-command)

A per-command push is too slow. Schedule a push on the existing backup cadence (every 15–30 min, after bd export) rather than inline. See scripts/dolt-push-dolthub.sh.