Last updated: Nov 17, 2025, 05:25 PM UTC

DocBuilder MCP → Vercel Publishing Playbook

Goal: Provide a business-friendly, repeatable flow for turning markdown content into a polished Vercel site with optional Supabase-backed password protection.

1. Prerequisites

  • Node.js 20+ available locally
  • Vercel CLI installed and logged in (npm install -g vercel, then vercel login). Inside the Sliplane image this is pre-baked; the CLI ships globally, so no install is needed at runtime.
  • VERCEL_TOKEN exported for unattended deploys (ask DevOps for the team token). When Sasha’s Web Publishing Assistant saves the token it is encrypted to disk and injected into the MCP launcher automatically.
  • Supabase project ready if password protection is required (we reuse the shared Sasha Supabase instance)
  • Repo checked out locally; documentation lives under docs/, configuration at doc-builder.config.js
  • Vercel linkage captured in html/.vercel/project.json (contains the projectId / orgId). Keep this file checked in or mount it via volume so deployments know which Vercel project to target.
  • Quick validation: run scripts/validate-web-publishing.sh (or with --strict) to confirm the container sees the CLI, config, token, and .vercel/project.json before attempting a deploy.

2. Install & Build the MCP Server

cd claudecodeui/integrations/mcp/docbuilder
npm install        # installs @modelcontextprotocol/sdk, @knowcode/doc-builder, etc.

🔁 Docker images handle this automatically. The Sliplane Docker build runs the same install/prune sequence, so the container ships with a ready-to-register DocBuilder MCP server. Use the command above only when developing locally.

If the workstation blocks npm installs, raise an approval request; everything runs offline after the initial install.

Vercel Configuration Reference

  • doc-builder.config.js → deployment.vercel lists the Vercel project metadata (project name, projectId, orgId). Update these if you clone into a different Vercel project.
  • html/.vercel/project.json mirrors the same identifiers for the Vercel CLI. If you ever run docbuilder_build with clean=true, the MCP server automatically restores this file so the link persists.
  • Runtime requires VERCEL_TOKEN (and, if you want fully non-interactive deploys, optionally VERCEL_PROJECT_ID / VERCEL_ORG_ID env vars—already pre-populated from config when running through the MCP server).
  • Operators can edit all of these fields—including the encrypted Vercel token and Supabase keys—directly in Settings → Tools → Web Publishing Assistant; saving there rewrites doc-builder.config.js and the encrypted config/mcp/docbuilder.json in lockstep.
  • The MCP launcher reads doc-builder.config.cjs (a generated twin of the .js file) so Node treats the settings as CommonJS even though the main app runs in ESM mode.

3. Register with Claude / Sasha Studio

claude mcp add docbuilder \
  --env VERCEL_TOKEN=$VERCEL_TOKEN \
  -- $(pwd)/claudecodeui/integrations/mcp/docbuilder/run-docbuilder-mcp.js

Verification checklist:

  • claude mcp list shows docbuilder
  • Smoke test docbuilder_status tool returns site + directory info
  • scripts/validate-web-publishing.sh --strict exits cleanly (optional but recommended whenever the container is rebuilt)

4. Day-to-day Workflow

  1. Status Check – run docbuilder_status to confirm docs + output folders and current auth mode.
  2. Optional Auth Toggle – call docbuilder_set_auth with mode="supabase" when you need password protection, or mode="public" to open access.
  3. Build – run docbuilder_build (set clean=true if you want a fresh output folder).
  4. Deploy – run docbuilder_deploy:
    • production=false for preview links (default)
    • production=true when promoting the canonical site
    • passwordProtection="supabase" to force login before publish, or "public" to disable it on this push
  5. Share Links – console output includes the latest deploy URL and production alias.

Business Summary

  • Internal preview: docbuilder_deploy (preview) → share the preview URL for sign-off.
  • Public launch: docbuilder_deploy with production=true → announce production URL.
  • Client-gated launch: docbuilder_deploy with passwordProtection="supabase" → only invited Supabase users can sign in.

5. Approval Notes

  • npm install – network call; request approval if the environment blocks package download.
  • vercel login/link – interactive step; run once per machine, requires Vercel account permissions.
  • Supabase credentials – stored in doc-builder.config.js; confirm they are encrypted/managed per security handbook before enabling auth.

6. Troubleshooting Checklist

  • Missing entry point → ensure server.js exists and rerun npm install inside docbuilder.
  • VERCEL_TOKEN required → export token or use --env VERCEL_TOKEN=... in claude mcp add.
  • Supabase auth errors → confirm auth.supabaseUrl and auth.supabaseAnonKey in doc-builder.config.js, and that users exist in docbuilder_access.
  • Preview works but production fails → check Vercel project settings for stale Root Directory (html must be cleared) and ensure Deployment Protection is off for public docs.

7. Future Enhancements

  • Surface deploy history within Sasha UI via MCP status endpoint.
  • Add smoke tests that verify Supabase login before marking deploy “done”.
  • Wire docbuilder tools into Tools panel documentation (deployed-md-files/docs/tools/*.md).