Vision Driven Design (VDD) MCP Server

Vision Driven Design

From vision to verified impact — an AI-native, fully autonomous software development methodology.

Overview

Provide a human vision statement. The AI autonomously researches, audits your codebase, generates specs and plans, implements, and validates — with bi-directional verification at every junction to ensure nothing is missed or invented.

graph LR
    V[1. Vision<br/>Human Input] -->|<-->| S[2. Strategy<br/>AI Research]
    S -->|<-->| T[3. Tactics<br/>AI Audit]
    T -->|<-->| SP[4. Specs<br/>SDD]
    SP -->|<-->| PL[5. Plan]
    PL -->|<-->| TK[6. Tasks]
    TK -->|<-->| IM[7. Implement]
    IM -->|<-->| VS[8. Validate<br/>Impact Verified]

    style V fill:#4CAF50,color:#fff
    style S fill:#2196F3,color:#fff
    style T fill:#FF9800,color:#fff
    style SP fill:#9C27B0,color:#fff
    style VS fill:#4CAF50,color:#fff

Table of Contents

• Quick Start
• How It Works
• Commands
• Installation
• MCP API
• Domains Covered
• Best-Practice Benchmark
• Documentation
• Repository Structure
• Credits
• License

Quick Start (≤ 5 minutes)

Fastest path: no install — connect an MCP client to the hosted endpoint https://vdd.simonmak.com/api/mcp (Streamable HTTP); or run the one-line install below.

# One-line install
curl -sSL https://raw.githubusercontent.com/simonmak-ascent/vision-driven-design/main/scripts/install.sh | bash

Then in your project:

/vdd:init                          # Generate project constitution
/vdd:vision "your vision here"     # The only human input required

# Or run end-to-end in one command:
/vdd:e2e "your vision here"        # Full chain: init→vision→...→validate

The AI handles the rest — researching, auditing, generating specs, planning, implementing, and validating — with self-gating at 7 bi-directional verification junctions.

Skill reference → — commands, the 8-phase chain, and the quality gates.

# Want human gates? Add to constitution.md:
## VDD Mode: Gated

How It Works

VDD follows Goldratt's recursive Strategy-Tactic decomposition: every phase is simultaneously the Tactic for its parent and the Strategy for its child.

7 bi-directional gates verify both directions at every junction (108 total checks). Each gate validates 4 S&T assumptions: Necessity, Achievability, Sufficiency, Warnings.

Every code commit traces back to the original vision statement:

V-001 → S-002 → T-003 → SP-004 → PL-005 → TK-006 → commit

The pipeline and its 7 gates

flowchart TB
    C["Phase 0 · Constitution<br/>constitution.md"] --> V["Phase 1 · Vision<br/>vision.md"]
    V -.->|G1| S["Phase 2 · Strategy<br/>strategy.md"]
    S -.->|G2| T["Phase 3 · Tactics<br/>tactics.md"]
    T -.->|G3| SP["Phase 4 · Specs<br/>spec.md"]
    SP -.->|G4| PL["Phase 5 · Plan<br/>plan.md · data-model · contracts"]
    PL -.->|G5| TK["Phase 6 · Tasks<br/>tasks.md"]
    TK -.->|G6| I["Phase 7 · Implement<br/>code + per-task commits"]
    I -.->|G7| VA["Phase 8 · Validate<br/>impact-report.md"]

Bi-directional traceability

Each gate checks forward (parent → children) and backward (children → parent), 108 checks in total.

flowchart LR
    subgraph F["Forward: intent → code"]
      direction LR
      V1["Vision V-*"] --> S1["Strategy S-*"] --> T1["Tactics T-*"] --> SP1["Spec SP-*"] --> PL1["Plan PL-*"] --> TK1["Tasks TK-*"] --> C1["Commit"]
    end
    subgraph B["Backward: code → intent"]
      direction LR
      C2["Commit"] --> TK2["Tasks TK-*"] --> PL2["Plan PL-*"] --> SP2["Spec SP-*"] --> T2["Tactics T-*"] --> S2["Strategy S-*"] --> V2["Vision V-*"]
    end

Change cascade

flowchart TB
    CH["Requirement change<br/>/vdd:amend"] --> FIND["Find the highest affected level"]
    FIND --> U1["Update Vision"] --> U2["Update Strategy"] --> U3["Update Tactics"] --> U4["Update Specs"] --> U5["Update Plan"] --> U6["Update Tasks"]
    U6 --> REG["Re-run affected gates G1–G7"]
    REG --> IMPL["Re-implement only the changed tasks"]

Commands

Installation

# OpenCode
git clone https://github.com/simonmak-ascent/vision-driven-design.git \
  ~/.config/opencode/skills/vision-driven-design/

# Claude Code
git clone https://github.com/simonmak-ascent/vision-driven-design.git \
  ~/.claude/skills/vision-driven-design/

# Cursor
git clone https://github.com/simonmak-ascent/vision-driven-design.git \
  .cursor/skills/vision-driven-design/

Local MCP (from source)

To run the MCP server locally (stdio) instead of the hosted endpoint:

# 1. Clone the repo
git clone https://github.com/simonmak-ascent/vision-driven-design.git

# 2. Install deps + build the TypeScript packages
cd vision-driven-design
pnpm install
pnpm -r build

# 3. Point your agent at the built stdio entry point

OpenCode (opencode.json):

"vdd": {
  "type": "local",
  "command": ["node", "<repo>/packages/vdd-mcp/dist/stdio.js"],
  "enabled": true
}

Claude Desktop (claude_desktop_config.json):

"vdd": {
  "command": "node",
  "args": ["<repo>/packages/vdd-mcp/dist/stdio.js"],
  "type": "stdio"
}

MCP API

VDD is available as a public MCP server at https://vdd.simonmak.com — 15 tools, no API key required — over the MCP Streamable HTTP transport at https://vdd.simonmak.com/api/mcp (also reachable at /mcp). The legacy SSE endpoint is retired: https://vdd.simonmak.com/api/sse now returns an HTTP 308 redirect to /api/mcp.

Agent Configuration

OpenCode — add to opencode.json:

"vdd": {
  "type": "remote",
  "url": "https://vdd.simonmak.com/api/mcp",
  "timeout": 120000
}

Claude Desktop — add to claude_desktop_config.json:

"vdd": {
  "command": "npx",
  "args": ["-y", "@simonmak-ascent/mcp"],
  "type": "stdio"
}

Cursor — add MCP server URL: https://vdd.simonmak.com/api/mcp

Any Streamable HTTP client (Smithery, Claude Code, …) — MCP server URL: https://vdd.simonmak.com/api/mcp

MCP Tools (15)

vdd_init, vdd_vision, vdd_strategize, vdd_tactics, vdd_specify, vdd_clarify, vdd_plan, vdd_tasks, vdd_get_next_task, vdd_implement, vdd_validate, vdd_inspect, vdd_amend, vdd_clone, vdd_detect_environment.

The one-call e2e shortcut is not an MCP tool (it duplicates the phase sequence); use the CLI vdd e2e "vision" instead.

Each tool advertises only the parameters it reads. Shared inputs include statement, projectRoot, actionItemId, feature, taskId, description, and availableTools/capabilities (aliases) plus researchFindings. Filesystem-dependent tools additionally accept artifactFiles (path→content) — and vdd_tactics accepts codebaseAudit — for the hosted endpoint.

Hosted vs local (filesystem)

The hosted endpoint (https://vdd.simonmak.com/api/mcp) is stateless and has no filesystem. It returns artifacts and, for filesystem-dependent phases, a delegation envelope for the calling agent to execute locally:

• Artifact-producing phases (vdd_init, vdd_vision, vdd_strategize, vdd_tactics, vdd_specify, vdd_plan, vdd_tasks, vdd_validate, vdd_clone) return their content with persisted: false and a writeTargets list — the agent writes them.
• Read phases (vdd_tactics, vdd_clarify, vdd_get_next_task, vdd_inspect, vdd_validate, vdd_implement) return a delegation envelope when given no content; re-call the same tool with artifactFiles (and codebaseAudit for tactics) to receive the real result.

For direct read/write of a local project, run the local stdio server instead — npx -y @simonmak-ascent/mcp (see Local MCP). It performs real filesystem I/O and returns mode: "local", persisted: true.

MCP Prompts (3)

start_vdd_project (vision → validated task list), implement_next_task (one test-first task with traceability) and change_requirement (cascade a change and re-run the gates). Available on the stdio server and the hosted endpoint.

MCP Registry (Glama)

The server is listed on Glama, which builds it from source and publishes a hosted remote endpoint plus a Tool Definition Quality Score and maintenance rating:

Maintainer notes:

• glama.json (repo root) is Glama's registry file. Its schema consumes exactly one field — maintainers. Build/transport/description metadata belongs in package.json and this README, not here; Glama ignores it.

• Glama generates its own container build from the stdio entrypoint (packages/vdd-mcp/dist/stdio.js), wrapped with mcp-proxy. The root Dockerfile is for self-hosting the Streamable HTTP server, not for Glama.

• After tool-definition changes: sync the repository and run Build & Release in the Glama admin. Tool-level scores refresh on the next sweep; the server-level coherence score re-runs less often.

• Also published to the Official MCP Registry as com.ascent-partners/vision-driven-design (manifest: server.json) — PulseMCP and other directories ingest from there.

• Listed in the awesome-mcp-servers community list under Developer Tools.

• Listed on Agent Status — an outside-in MCP reliability index that probes reach, catalog, and tool calls from real hosts (Cursor, Claude, VS Code, ChatGPT). The submission created the Free dashboard account; the score populates after the first probe.

API Reference

# Streamable HTTP call example
curl -X POST https://vdd.simonmak.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# tools/call example
curl -X POST https://vdd.simonmak.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"vdd_validate","arguments":{"projectRoot":"."}},"id":1}'

The full TypeScript engine (packages/vdd-engine, packages/vdd-mcp, packages/vdd-cli) is included in this repo.

Domains Covered

VDD loads domain-specific research patterns during the Strategy phase based on your vision:

human-factors.md and verification-toolchain.md are loaded unconditionally for every project.

Best-Practice Benchmark

VDD is benchmarked against NASA SE, CMMI REQM, DO-178C, IEC 62304, DORA, ISO 29148, and GitHub Spec Kit:

47/47 criteria matched (100%), 11 exceeded, 0 gaps.

Standards & compliance evidence →

Documentation

Repository Structure

├── SKILL.md                         # Entry point — loaded by OpenCode
├── README.md                        # This file
├── AGENTS.md                        # Instructions for AI agents
├── constitution.md                  # Project constitution (dogfooded)
├── CHANGELOG.md                     # Versioned change history
├── CONTRIBUTING.md                  # Contribution guidelines
├── LICENSE                         # MIT
├── index.html                       # Vercel landing page (en / zh / hk)
├── pnpm-workspace.yaml              # Workspace config
├── package.json                     # Root package (Vercel + workspace)
├── vercel.json                      # Vercel deployment config
├── Dockerfile                       # Self-host build — Streamable HTTP MCP server
├── glama.json                       # Glama registry file (maintainers only)
├── server.json                      # Official MCP Registry manifest
├── domain-primers/                  # 7 domain research patterns
│   ├── webapp.md
│   ├── data-storage.md
│   ├── etl.md
│   ├── infrastructure.md
│   ├── human-factors.md             # Loaded unconditionally
│   ├── verification-toolchain.md    # Loaded unconditionally
│   └── safety-critical.md           # FMEA/FTA, DO-178C/IEC 62304
├── references/                      # 10 authoritative reference docs
│   ├── INDEX.md                     # Navigation map
│   ├── quick-reference.md           # 1-page cheat sheet
│   ├── workflow-phases.md           # Phase order (authoritative)
│   ├── artifact-templates.md        # 11 artifact templates (authoritative)
│   ├── prompt-patterns.md           # AI prompts (authoritative)
│   ├── quality-gates.md             # 7 gates + 108 checks (authoritative)
│   ├── ai-agent-patterns.md         # Agent orchestration (authoritative)
│   ├── anti-patterns.md             # 24 failure modes (authoritative)
│   ├── traceability-matrix.md       # RTM format + CI/CD
│   └── compliance-evidence.md       # Evidence maps
├── vdd/                             # VDD chain artifacts
│   ├── vision.md                    # Vision, impact model, 17 impacts
│   ├── strategy.md                  # 12 strategic pillars
│   ├── tactics.md                   # 38 action items (all DONE)
│   ├── impact-report.md             # Full-chain traceability + drift
│   ├── docs/                        # 16 guides and references
│   └── specs/                       # 3 feature specs
├── packages/                        # TypeScript monorepo
│   ├── vdd-engine/                  # Shared core — 18 phase functions + meta.ts
│   ├── vdd-mcp/                     # MCP server — 15 tools, stdio + Streamable HTTP
│   └── vdd-cli/                     # CLI binary — 17 subcommands
├── api/                             # Vercel MCP endpoint
│   ├── mcp.js                       # Streamable HTTP MCP endpoint (15 tools)
│   └── _vdd-rpc.js                  # Shared JSON-RPC core + browser docs page (not routed)
├── scripts/                         # 4 installer/helper scripts
└── .github/                         # GitHub config
    ├── CODEOWNERS
    ├── ISSUE_TEMPLATE/
    └── workflows/

Acknowledgements

Built on:

• Goldratt's Strategy-and-Tactic Tree — recursive decomposition at every phase
• Impact Mapping (Gojko Adzic) — goal → actors → impacts → deliverables
• GitHub Spec Kit — spec-driven development with AI agents
• NASA Systems Engineering — bidirectional traceability and verification chains
• CMMI Requirements Management — bidirectional traceability of requirements

Use with Context7

Up-to-date Vision Driven Design documentation is indexed on Context7, so coding agents can pull it into context on demand. With the Context7 MCP server or ctx7 CLI installed, name the library in your prompt:

use library /simonmak-ascent/vision-driven-design for API and docs

License

MIT — see LICENSE.

By Simon Mak.

If this saves you time, a ⭐ on GitHub helps others find it.