Overview

This MCP server (package: @bldbl/mcp) connects AI assistants to Buildable projects so they can pull structured work, act on it, and report results. It exposes a Model Context Protocol (MCP) endpoint that serves JSON tasks and project context to assistants (Claude, GPT-based agents, Cursor, etc.), so the agent can pick the next task, start work, update progress, and complete tasks. Two notable capabilities: it can create phased backlogs (ordered, dependency-aware task phases) and scaffold private CI repositories for autonomous or assisted work.

For developer teams, the server removes friction when collaborating with AI: it standardizes how tasks are presented to assistants, automates repo scaffolding for isolated CI-driven changes, and preserves an audit trail of what the assistant did via the Buildable project. The server ships with TypeScript types and CLI-friendly usage, so integrating it into desktop assistants or local tooling is straightforward.

Features

Phased backlog generation: breakdown work into phases and ordered tasks with dependencies and priorities.
Private CI repo scaffolding: create ephemeral repos with CI config so assistants can push and test code safely.
JSON MCP endpoints: get_project_context, get_next_task, start_task, update_progress, complete_task, create_discussion, health_check.
TypeScript-first client and type definitions for safe integrations.
CLI-friendly invocation for desktop assistants (Claude Desktop, Cursor, etc.).
Real-time progress reporting and discussion creation for human-in-the-loop workflows.

Installation / Configuration

Install via npm or use the CLI wrapper with npx.

Install locally:

npm install @bldbl/mcp

Install globally:

npm install -g @bldbl/mcp
# or run directly with npx:
npx -y @bldbl/mcp

Environment variables (recommended):

Variable	Required	Description
BUILDABLE_API_KEY	yes	Your Buildable API key
BUILDABLE_PROJECT_ID	yes	Target project identifier
BUILDABLE_AI_ASSISTANT_ID	recommended	Identifier for the AI assistant (e.g., “claude-desktop”)
BUILDABLE_API_URL	optional	API endpoint (defaults to Buildable’s hosted API)

Export example:

export BUILDABLE_API_KEY="bp_your_api_key_here"
export BUILDABLE_PROJECT_ID="project_abc123"
export BUILDABLE_AI_ASSISTANT_ID="claude-desktop"
# export BUILDABLE_API_URL="https://bldbl.dev/api"  # optional

Example: configure Claude Desktop (add to ~/.config/claude/claude_desktop_config.json)

{
  "mcpServers": {
    "buildable": {
      "command": "npx",
      "args": ["-y", "@bldbl/mcp"],
      "env": {
        "BUILDABLE_API_KEY": "bp_your_api_key_here",
        "BUILDABLE_PROJECT_ID": "project_abc123",
        "BUILDABLE_AI_ASSISTANT_ID": "claude-desktop"
      }
    }
  }
}

Cursor manual configuration is similar — set the same mcpServers entry and environment variables.

Available Tools

The server exposes MCP methods (JSON RPC-style) that assistants call:

get_project_context: returns repository layout, roadmap, and phased backlog metadata.
get_next_task: returns the highest-priority actionable item from the phased backlog.
start_task: locks/assigns the task to the assistant and creates any necessary CI scaffolding.
update_progress: send intermediate updates, status percentages, and artifact links.
complete_task: mark a task finished, include changelog notes and test results.
create_discussion: open a thread for human questions or blockers.
health_check: validate connectivity with Buildable API and server readiness.

Sample get_next_task response (trimmed):

{
  "task_id": "t-001",
  "title": "Add JWT auth middleware",
  "phase": "backend-auth",
  "priority": "high",
  "files": ["src/middleware/auth.ts"],
  "ci_scaffold": {
    "repo_url": "[email protected]/repo-xyz.git",
    "ci_workflow": ".github/workflows/ci.yml"
  }
}

Use Cases

Autonomous implementation: An assistant calls get_project_context → get_next_task → start_task, scaffolds a private CI repo, runs tests in CI, pushes a PR, and calls complete_task with test output.
Human-in-the-loop development: Assistant creates phased backlog items for a new feature, asks clarifying questions via create_discussion, and updates progress so humans can review incremental changes.
Safe experiment workspaces: Scaffold private CI repositories per task so agents can run integration tests and iterate without touching the main repo.
Prioritized triage: Use phased backlog to split a large initiative into incremental deliverables (phase 1: setup, phase 2: core features, phase 3: polish), enabling assistants to focus in order.

Best Practices & Notes

Provide a descriptive BUILDABLE_AI_ASSISTANT_ID to make activity logs easy to audit.
Use the server with an assistant that understands MCP-style JSON responses (many desktop assistants support MCP servers).
Treat scaffolded CI repos as ephemeral: clean them up once a task is merged or closed.
The package includes TypeScript types — prefer typed integrations to reduce runtime errors.

This MCP server is intended to be a practical bridge between Buildable’s project planning and AI-driven implementation workflows. It standardizes task delivery and automates safe scaffolding so assistants can focus on shipping code.

Buildable MCP Server: Phased Backlog, CI-Scaffolded Repos