@beforebuild.io/mcp

The BeforeBuild MCP server brings the trust layer for AI-generated code into your coding agent (Cursor, Claude Code, Windsurf): scan for security issues, verify the app actually runs in a sandbox, catch hallucinated dependencies, detect architecture drift, and plan/scaffold new projects — all without leaving the agent loop.

Every finding tool returns agent-executable fixes ({ summary, findings, fixes }) so the agent can fix-and-re-verify until green.

Quick start

Cursor / Windsurf

Add to ~/.cursor/mcp.json (or your Windsurf MCP config):

{
  "mcpServers": {
    "bb": {
      "command": "npx",
      "args": ["-y", "@beforebuild.io/mcp"]
    }
  }
}

The bb key becomes the slash-command prefix in your agent (e.g. /bb/plan, /bb/scan). Rename it if you prefer a different prefix.

Claude Code

claude mcp add bb -- npx -y @beforebuild.io/mcp

On first tool call the server opens a browser to securely connect your BeforeBuild account (OAuth 2.1 device flow). You can also pre-authenticate:

npx -y @beforebuild.io/mcp login

Tools

| Tool | What it does | | --- | --- | | verify_runtime | Boots the app in an isolated sandbox (install → build → start → HTTP probe). The hero check. | | scan_security | Fast security + maintainability scan with fixes. | | deep_scan | Semgrep / Gitleaks / Trivy deep static analysis. | | check_dependencies | Detects hallucinated / missing / deprecated packages. | | check_drift | Flags drift from the intended architecture. | | verify_claims | Confirms the README's claims are actually implemented. | | blueprint_plan | Turns an idea into an architecture blueprint. | | generate_builder_pack | Generates RUNBOOK / ARCHITECTURE / AGENTS / SECURITY / SPEC. | | export_agent_rules | Writes an AGENTS.md / .cursor/rules to keep agents on-architecture. | | search_marketplace / get_listing | Find reviewed, runtime-verified foundations. | | get_credits | Plan + remaining credits. |

Each tool works on your local working directory (default) or a GitHub repo (pass repo: "owner/repo").

Slash commands

User-invokable prompts surface as /bb/<command> in Cursor (and /mcp__bb__<command> in Claude Code):

| Command | What it does | | --- | --- | | /bb/plan | Blueprint — idea → architecture + matching Foundations. | | /bb/dossier | Generate the Agent Dossier (RUNBOOK / ARCHITECTURE / AGENTS / SECURITY / SPEC). | | /bb/scan | Security Scan — fast security + maintainability findings. | | /bb/deepscan | Deep Security Scan (Semgrep / Gitleaks / Trivy). | | /bb/drift | Drift Check — code vs. intended architecture. | | /bb/boot | Verify the app runs, then fix until green. | | /bb/fix | Auto-fix every high/critical finding, re-scan until clean. | | /bb/help | List every command. |

Configuration

| Env var | Default | Purpose | | --- | --- | --- | | BEFOREBUILD_URL | https://beforebuild.io | BeforeBuild deployment (auth + API). | | BEFOREBUILD_HOME | ~/.beforebuild | Token cache location. | | BEFOREBUILD_TOKEN | – | Bypass the cache with a fixed access token (CI). |

Credentials are cached at ~/.beforebuild/credentials.json (mode 0600). Secrets (.env, *.pem, keys) are never uploaded — they're scanned in place.

Local development & testing (no npm publish required)

You can run and test the whole thing from a local checkout — nothing needs to be published to npm.

1. Apply the DB migration (run packages/db/migrations/023_mcp_oauth.sql in the Supabase SQL editor) and start the BeforeBuild web app:

   pnpm --filter web dev          # http://localhost:3000

2. Build the MCP package:

   pnpm --filter @beforebuild.io/mcp build

3. Point an agent at the local build (note command: "node" + absolute path to dist/stdio.js, and BEFOREBUILD_URL → your local app):

   {
     "mcpServers": {
       "beforebuild": {
         "command": "node",
         "args": ["/ABS/PATH/vibes/packages/mcp-server/dist/stdio.js"],
         "env": { "BEFOREBUILD_URL": "http://localhost:3000" }
       }
     }
   }

4. Or test with the MCP Inspector (a UI to list/call tools — no agent needed):

   BEFOREBUILD_URL=http://localhost:3000 \
     npx @modelcontextprotocol/inspector node packages/mcp-server/dist/stdio.js

5. Or test the auth + API directly with curl (no client at all):

   curl http://localhost:3000/.well-known/oauth-protected-resource
   curl -X POST http://localhost:3000/api/mcp/call \
     -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
     -d '{"tool":"get_credits","args":{}}'

The first tool call (or login) starts the OAuth 2.1 device flow and opens http://localhost:3000/connect to approve.

Remote (hosted) mode

A hosted Streamable HTTP endpoint is also available for the one-click "Add to Cursor" flow; it supports GitHub-repo tools (no local filesystem access).

Run it locally:

pnpm --filter @beforebuild.io/mcp build
PORT=8787 BEFOREBUILD_URL=http://localhost:3000 node dist/http.js
# GET  /healthz  → 200
# POST /mcp      → Streamable HTTP transport (Bearer required, else 401)

Deploy it as a container (Fly.io, Cloud Run, Render, Railway, …) and point https://mcp.beforebuild.io at it:

pnpm --filter @beforebuild.io/mcp build
docker build -t beforebuild-mcp packages/mcp-server
docker run -p 8787:8787 -e BEFOREBUILD_URL=https://beforebuild.io beforebuild-mcp

Auth is fully delegated to BEFOREBUILD_URL's OAuth 2.1 Authorization Server + Resource Server, so the remote node holds no secrets and never sees user credentials — it forwards the agent's Bearer token per request.

License

MIT