VIBE ENGINEERING MCP

An Agentic Software-Engineering Operating System & Control Plane that manages requirements, architecture, tasks, workspaces, execution, verification, integration, and checkpoints for autonomous software development.

💡 Core Philosophy

  ┌──────────────────────────────────────────────────────────────┐
  │                 WORKER INTELLIGENCE (LLM)                    │
  │        (Claude Code, Cursor, Gemini, GPT, Custom Agent)      │
  └──────────────────────────────┬───────────────────────────────┘
                                 │ JSON-RPC / MCP Protocol
  ┌──────────────────────────────▼───────────────────────────────┐
  │              ENGINEERING CONTROL PLANE (MCP)                 │
  │                     Vibe Engineering MCP                     │
  └──────────────────────────────┬───────────────────────────────┘
                                 │
     ┌───────────────────────────┼───────────────────────────┐
     │                           │                           │
┌────▼─────────────────┐   ┌─────▼────────────────┐   ┌──────▼─────────────────┐
│ Task DAG Scheduler   │   │  Completion Gate     │   │ Checkpoint & Resumption│
│ Cycle Detection      │   │  Observable Harness  │   │ Git Commit Snapshots   │
│ Topological Ordering │   │  Contract Verifier   │   │ Worker Continuation    │
└────┬─────────────────┘   └─────┬────────────────┘   └──────┬─────────────────┘
     │                           │                           │
     └───────────────────────────┼───────────────────────────┘
                                 │
  ┌──────────────────────────────▼───────────────────────────────┐
  │              ISOLATION & EXECUTION POLICIES                  │
  │   Git Worktrees  ·  Command Policy  ·  Path Policy  · Observer │
  └──────────────────────────────┬───────────────────────────────┘
                                 │
  ┌──────────────────────────────┴───────────────────────────────┐
  │                   DUAL-LAYER STATE STORAGE                   │
  │       SQLite (ACID Operational DB)  ·  .vibe/ (YAML Specs)   │
  └──────────────────────────────────────────────────────────────┘

• The LLM is NOT the source of truth for project state.

• The MCP server is the engineering operating system.

• A task cannot become VERIFIED merely because an LLM claims it is finished.

• A capability is complete only when: $$\text{Implementation} + \text{Runnable Harness} + \text{Observable Output} + \text{Contract Verification} + \text{Integration Compatibility} + \text{Checkpoint}$$ have all passed with reproducible evidence.

Related MCP server: agent-tasks

🔄 Task State Machine & Completion Gate

Tasks progress through strict state machine transitions:

$$\text{BLOCKED} \longrightarrow \text{READY} \longrightarrow \text{CLAIMED} \longrightarrow \text{BUILDING} \longrightarrow \text{VERIFYING} \longrightarrow \text{VERIFIED} \longrightarrow \text{INTEGRATING} \longrightarrow \text{VERIFIED}$$

The Completion Gate (task_complete)

When task_complete is invoked by a worker:

1. Inspects the task and active workspace.

2. Inspects Git working tree and modified files.

3. Inspects Git diff.

4. Executes unit and component tests.

5. Runs the module's registered Observable Harness (CLI, HTTP, DB, AI, UI).

6. Captures standard output, standard error, exit code, and execution time.

7. Evaluates contract rules (exit codes, regex patterns, JSON schema verification, artifact existence).

8. Checks cross-module integration requirements.

9. On Pass: Transitions task to VERIFIED, updates DAG readiness for dependent tasks, and records state.

10. On Fail: Rejects completion, transitions task to FAILED, and automatically schedules an Automated Repair Task in state READY populated with:

    • Original task ID

    • Failure reason

    • Failing command

    • Relevant stdout/stderr

    • Affected files

    • Suggested remediation action

🛡️ Git Worktree Workspace Isolation

Unlike naive implementations that share or pollute the project root directory, Vibe Engineering MCP provisions dedicated Git worktrees for each worker/task:

• Worktrees are created under .worktrees/ws-<workerId>-<taskId> on isolated Git branches (worker/<workerId>/task-<taskId>).

• The system never silently falls back to the project root. If worktree provisioning fails, it throws an explicit diagnostic error.

• Worktree metadata is fully tracked (workspaceId, taskId, branch, worktreePath, repositoryPath, status, createdAt).

• Worktrees can be safely cleaned up with cleanupWorkspace (git worktree remove --force).

🔒 Security Model

Command Policy (src/security/command-policy.ts)

• Scopes terminal command execution to the project or designated worktree.

• Blocks destructive commands (rm -rf /, formatting disks via mkfs, overwrite via dd, fork bombs :(){ :|:& };:, unauthorized sudo).

• Requires execution inside valid workspace boundaries.

• Every command execution records: execution ID, command, cwd, timestamp, exit code, stdout, stderr, and duration to SQLite.

Path Policy (src/security/path-policy.ts)

• Enforces strict containment within project/worktree root.

• Resolves symlinks and prevents directory traversal attacks (e.g. ../../etc/passwd).

🛠️ Registered MCP Tools (28 Tools)

Migrated to the current MCP TypeScript SDK V2 (@modelcontextprotocol/server):

🚀 Getting Started

Prerequisites

• Node.js: v20.0.0 or higher (Tested on Node 22 with built-in node:sqlite)

• Git: 2.30+ with worktree support

Installation

git clone https://github.com/prabhurajvardhan/Dev-MCP.git
cd Dev-MCP
npm ci

Typecheck & Test Suite

npm run typecheck
npm test

The test suite includes:

• 4 Unit test suites: Task DAG scheduler, SQLite state store, command security policy, contract engine.

• 4 Integration test suites: Real MCP client protocol over stdio (@modelcontextprotocol/client), 19-step autonomous engineering loop, task completion gate & repair generation, MCP server tools interface.

Build Project

npm run build

Compiles TypeScript into ./dist.

🔌 Running the MCP Server (Stdio)

The MCP server uses pure stdio JSON-RPC transport (serveStdio).

• Standard output (stdout) is strictly reserved for JSON-RPC messages.

• All logging and diagnostic outputs are routed to stderr.

npm run mcp
# or
npx tsx src/server/index.ts

Configuration in Claude Code / Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "vibe-engineering": {
      "command": "npx",
      "args": ["-y", "tsx", "/path/to/Dev-MCP/src/server/index.ts"]
    }
  }
}

Configuration in Cursor

In Cursor Settings $\to$ Features $\to$ MCP Servers:

• Name: vibe-engineering

• Type: command

• Command: npx -y tsx /path/to/Dev-MCP/src/server/index.ts

📂 .vibe/ Inspectable Project State

In addition to SQLite operational ACID storage, human-readable YAML state is maintained under .vibe/:

.vibe/
├── architecture.yaml       # System design, modular boundaries, contracts
├── requirements.yaml       # Product goals & acceptance criteria
├── modules.yaml            # Registered modules & runnable harnesses
├── tasks.yaml              # Task DAG and execution status
├── checkpoints/            # Frozen capability snapshots (latest.yaml + chk-*.yaml)
├── contracts/              # Interface contracts
├── observations/           # Reproducible evidence logs (evd-*.yaml)
└── decisions/              # Architectural decision records

⚠️ Current Scope & Limitations (V0)

• Local Focus: V0 is optimized for single-machine local development using Git worktrees and SQLite.

• No Remote Workers: Distributed worker pools or cloud message brokers are deferred to V1.

• Synchronous Worktree Operations: Worktree allocation is local to the filesystem where the MCP server runs.

📄 License

Licensed under the Apache License, Version 2.0. See LICENSE for details.