Skip to content
/

mcp-server-spec-driven-development

mcp-server-spec-driven-development · formulahendry/mcp-server-spec-driven-development · ★ 430 · last commit 2025-09-26

Provides a minimal MCP server with three EARS-format prompts that enforce the requirements→design→code spec-driven development pipeline in any MCP-compatible AI tool.

Best whenThe minimum viable spec-driven workflow is three prompts and two markdown files — any more complexity reduces adoption without proportionally improving outpu…
Skip ifVibe coding (writing code without structured specs)
vs seeds
spec-kit(Python CLI, 9 commands, 9 skills, 18 hooks), this is the minimum viable SDD implementation. The 430 stars despite minim…
Primitive shape 3 total
MCP tools 3
00

Summary

mcp-server-spec-driven-development (formulahendry) — Summary

mcp-server-spec-driven-development is a minimal TypeScript MCP server that exposes three structured prompts for the classic three-stage SDD pipeline: requirements (EARS format) → design → code. It wraps plain text instructions as MCP prompts and stores outputs in a specs/ directory. With 430 stars and 40 forks, it is the most popular minimal SDD framework in this batch — its appeal is simplicity: npx -y mcp-server-spec-driven-development@latest, add to any MCP client, and get three prompt commands that guide a sequential spec-driven workflow. There is no CLI, no skills, no hooks, no Kanban, no agent intelligence — just three MCP prompts that delegate to the connected AI tool. The author explicitly positions it against "vibe coding": "Goodbye, Vibe Coding! Hello, Spec-Driven Development MCP Server!" Closest seed is openspec (both are npm-distributed multi-tool SDD pipelines), but this is far simpler — 3 prompts vs openspec's 11 skills + 11 commands + 0 hooks, and no file-based storage beyond what the AI writes to specs/.

01

Overview

mcp-server-spec-driven-development — Origin & Philosophy

Origin

Created by formulahendry (Jun Han, Microsoft engineer and prolific open-source contributor, known for VS Code REST Client extension). Last commit September 2025. 430 stars, 40 forks, 2 contributors. Status: dormant (no commits since Sep 2025).

Core Philosophy (verbatim from README)

"Moving beyond Vibe Coding to a structured, specification-driven approach brings clarity, consistency, and maintainability to your development workflow. Instead of coding by intuition alone, Spec-Driven Development provides a systematic foundation that scales with your project's complexity."

"This MCP server enables developers to follow a structured spec-driven development approach by providing prompts that guide you through: Requirements Generation → Design Generation → Code Generation."

Positioning

The README links to a blog post: "Goodbye, Vibe Coding! Hello, Spec-Driven Development MCP Server!" This framing positions the tool against "vibe coding" (prompt-and-hope AI development) in favor of structured SDD.

Design Philosophy

Minimal — the framework does exactly three things via three MCP prompts, no more. The implementation is ~80 lines of TypeScript. All intelligence lives in the connected AI tool (VS Code Copilot, Claude Code, Cursor, etc.), not in the framework.

EARS Format

The requirements prompt specifies EARS (Easy Approach to Requirements Syntax) format, an industry-standard structured requirements notation. This is the same format used by Kiro in its spec generation workflow.

02

Architecture

mcp-server-spec-driven-development — Architecture

Distribution

npm package (mcp-server-spec-driven-development). Designed for npx one-shot use (no global install required).

Install

# VS Code (via mcp.json)
{
  "servers": {
    "spec-driven": {
      "command": "npx",
      "args": ["-y", "mcp-server-spec-driven-development@latest"]
    }
  }
}

# Cursor, Claude Code (via mcp.json)
{
  "mcpServers": {
    "spec-driven": {
      "command": "npx",
      "args": ["-y", "mcp-server-spec-driven-development@latest"]
    }
  }
}

Required Runtime

  • Node.js >= 20

Source Structure

src/
├── index.ts      # CLI entry point (stdio server)
├── server.ts     # McpServer definition with 3 prompts
└── streamableHttp.ts  # HTTP transport variant
package.json
server.json       # (metadata)

Directory Structure Created (in user project)

specs/
├── requirements.md   # output of generate-requirements prompt
├── design.md         # output of generate-design-from-requirements
└── (root folder)     # code output from generate-code-from-design

Target AI Tools

VS Code Copilot, Claude Code, Cursor, and any MCP-compatible AI tool.

Transport

  • stdio (default, via npx)
  • Streamable HTTP (via streamableHttp.ts for server deployments)
03

Components

mcp-server-spec-driven-development — Components

MCP Prompts (3 total)

Name Description Input Output
generate-requirements Generate requirements.md using EARS format requirements: string (high-level app description) specs/requirements.md
generate-design-from-requirements Generate design.md from requirements.md (none — reads from specs/requirements.md) specs/design.md
generate-code-from-design Generate code from design.md (none — reads from specs/design.md) Code in root folder

Note: These are MCP Prompts (not MCP Tools). They return a pre-formatted user message that the AI tool sends to the model — the AI tool executes the actual file read/write operations, not the MCP server.

No Other Components

  • Zero skills
  • Zero hooks
  • Zero slash commands
  • Zero CLI binary
  • Zero subagents

Implementation (src/server.ts — full relevant content)

server.registerPrompt(
  "generate-requirements",
  { argsSchema: { requirements: z.string() } },
  ({ requirements }) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Based on below requirements, generate requirements.md using EARS format in 'specs' folder:\n\n${requirements}`
      }
    }]
  })
);

server.registerPrompt("generate-design-from-requirements", {}, () => ({
  messages: [{
    role: "user",
    content: { type: "text", text: `Based on specs/requirements.md, generate specs/design.md` }
  }]
}));

server.registerPrompt("generate-code-from-design", {}, () => ({
  messages: [{
    role: "user",
    content: { type: "text", text: `Based on specs/design.md, generate code on the root folder` }
  }]
}));
05

Prompts

mcp-server-spec-driven-development — Prompt Files

Excerpt 1: generate-requirements Prompt (verbatim from src/server.ts)

server.registerPrompt(
  "generate-requirements",
  {
    title: "Generate Requirements Document",
    description: "Generate requirements.md using EARS format",
    argsSchema: { 
      requirements: z.string().describe(
        "High-level requirements of the application. Example: 'A Vue.js todo application with task creation, completion tracking, and local storage persistence'"
      )
    }
  },
  ({ requirements }) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Based on below requirements, generate requirements.md using EARS format in 'specs' folder:\n\n${requirements}`
      }
    }]
  })
);

Technique: MCP Prompt as wrapper — the framework wraps a simple string interpolation (requirements.md using EARS format) as a formal MCP prompt. This is the minimal viable implementation of prompt-as-protocol: the prompt itself contains one sentence plus the user's input, no more. No persona assignment, no chain-of-thought instruction, no output schema.

Excerpt 2: generate-design-from-requirements Prompt (verbatim)

server.registerPrompt(
  "generate-design-from-requirements",
  {
    title: "Generate Design Document from Requirements Document",
    description: "Generate design.md from requirements.md",
  },
  () => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Based on specs/requirements.md, generate specs/design.md`
      }
    }]
  })
);

Technique: Zero-shot file reference — the prompt contains only a file path reference. All intelligence is delegated to the connected AI tool (VS Code Copilot, Claude Code) to read the file, understand the format, and generate the next artifact. This is the most minimal possible prompt engineering.

Excerpt 3: generate-code-from-design Prompt (verbatim)

server.registerPrompt(
  "generate-code-from-design",
  {
    title: "Generate Code from Design Document",
    description: "Generate code from design.md"
  },
  () => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Based on specs/design.md, generate code on the root folder`
      }
    }]
  })
);

Technique: Implicit convention reliance — "generate code on the root folder" assumes the AI understands conventional project layout. No language specification, no framework hint, no output validation. Maximum simplicity, minimum guardrails.

Prompting Techniques Summary

  1. MCP Prompt as protocol wrapper — structured way to deliver pre-formatted user messages via MCP
  2. File reference chaining — each prompt references the output file of the previous stage
  3. Zero-shot with format hint — only "EARS format" in requirements prompt; rest is fully delegated
  4. Minimal intervention design — the framework intentionally does nothing except trigger the AI to work on a specific artifact
09

Uniqueness

mcp-server-spec-driven-development — Uniqueness & Positioning

differs_from_seeds

Closest to openspec (both are npm-distributed, multi-tool SDD pipelines), but openspec ships 11 commands + 11 skills with detailed prompt engineering for each stage, while this framework provides 3 MCP prompts containing one sentence each. Against spec-kit (Python CLI, 9 commands, 9 skills, 18 hooks), this is nearly two orders of magnitude simpler. The framework most closely resembles what you'd get if you distilled the kiro spec pattern to its absolute minimum: requirements → design → code, formalized as MCP protocol, no more. The EARS format requirement is the one element shared with Kiro.

Unique Positioning

This framework occupies the "minimum viable SDD" position in the space:

  • Lowest possible install complexity (npx one-liner, no config)
  • Narrowest possible API surface (3 prompts, each ≤ 1 sentence)
  • Highest portability (pure MCP, any client)
  • Zero lock-in (stateless server, files are just markdown)

Its 430 stars despite this minimal implementation suggest strong demand for friction-free SDD scaffolding.

Observable Failure Modes

  1. No guidance quality: the prompts contain no domain knowledge, examples, or validation rules — output quality is entirely dependent on the AI tool's own capability.
  2. No EARS validation: the requirements prompt specifies "EARS format" but cannot verify the output follows it.
  3. No chaining enforcement: nothing prevents the user from running generate-code-from-design before generate-requirements.
  4. Dormant maintenance: last commit September 2025, 2 contributors — likely not actively maintained.
  5. No TDD: code is generated directly from design with no test-first discipline.
  6. No approval gates: human has no required checkpoint before code is generated.

Explicit Antipatterns (inferred)

  • "Vibe coding" (prompting without structured specs) — the raison d'être of the framework is avoiding this
04

Workflow

mcp-server-spec-driven-development — Workflow

Three-Stage Pipeline

Stage MCP Prompt Input Output
1. Requirements generate-requirements Free-text requirements specs/requirements.md (EARS format)
2. Design generate-design-from-requirements specs/requirements.md specs/design.md
3. Code generate-code-from-design specs/design.md Implementation code

Example Workflow (from README)

  1. Use generate-requirements prompt with initial requirements text
  2. Use generate-design-from-requirements to create design document
  3. Use generate-code-from-design to generate implementation

Approval Gates

None enforced programmatically. The human implicitly approves by deciding when to trigger the next prompt. No explicit "wait for review" mechanism.

Prompt Chaining

Yes — explicit. Each stage's output is the next stage's input:

  • requirements prompt output → specs/requirements.md
  • design prompt reads specs/requirements.md → outputs specs/design.md
  • code prompt reads specs/design.md → outputs implementation

EARS Format (Requirements)

The requirements prompt specifies EARS (Easy Approach to Requirements Syntax) format, which uses structured sentences like:

  • [Optional] WHEN <optional precondition> WHILE <optional in-state> THE <system> SHALL <system response>
  • WHERE <feature is included> THE <system> SHALL <system response>
06

Memory Context

mcp-server-spec-driven-development — Memory & Context

State Storage

File-based — the AI tool writes to specs/requirements.md and specs/design.md in the project directory. The MCP server itself is stateless.

Cross-Session Handoff

Yes — specs/requirements.md and specs/design.md persist between sessions. Any session can pick up by invoking the next prompt in the chain.

Context Loading

None automatic. Agents must explicitly read specs/requirements.md or specs/design.md if they need context from previous stages. The MCP prompts reference the file paths, which instructs the AI to read them.

Compaction

None. No compaction or summarization mechanism.

Memory Type

File-based (plain markdown files).

Persistence Scope

Project-scoped (files in specs/ directory).

Server State

The MCP server (npx -y mcp-server-spec-driven-development@latest) is stateless — it maintains no state between prompt invocations. Each prompt returns a static message.

07

Orchestration

mcp-server-spec-driven-development — Orchestration

Multi-Agent

No. The MCP server is stateless and single-prompt. One agent uses it at a time.

Orchestration Pattern

Sequential. The three prompts must be invoked in order: requirements → design → code.

Execution Mode

One-shot per prompt invocation.

Isolation Mechanism

None. File writes happen in-place.

Multi-Model

No. Whatever model the connected AI tool uses.

Consensus Mechanism

None.

Auto-Validators

None. No linting, testing, or self-review.

TDD Enforcement

None.

Git Automation

None.

Prompt Chaining

Yes — the design prompt reads specs/requirements.md (output of prompt 1), and the code prompt reads specs/design.md (output of prompt 2). Explicit file-based chaining.

Cross-Tool Portability

High. Pure MCP prompts work with any MCP-compatible AI tool: VS Code Copilot, Claude Code, Cursor, and others.

08

Ui Cli Surface

mcp-server-spec-driven-development — UI & CLI Surface

CLI Binary

None. The package is a server, not a user-facing CLI.

Local UI

None. No web dashboard, TUI, or desktop app.

MCP Server (Primary Interface)

  • Package: mcp-server-spec-driven-development (npm)
  • Protocol: stdio (default), Streamable HTTP (alternative)
  • Launch: npx -y mcp-server-spec-driven-development@latest
  • Prompts: 3 (generate-requirements, generate-design-from-requirements, generate-code-from-design)

VS Code Install (One-click)

README includes a VS Code deeplink button that auto-configures the MCP server in VS Code settings.

Compatible AI Tools (from README)

VS Code Copilot, Claude Code, Cursor, and any MCP-compatible AI tool.

Observability

None. The server is stateless; no logging or audit trail.

Install Complexity

One-liner: npx -y mcp-server-spec-driven-development@latest — no global install, no config files, no API keys.

Related frameworks

same archetype · same primary tool · same memory type

OpenHarness ★ 13k

Open-source Python agent runtime providing complete harness infrastructure: tools, memory, governance, swarm coordination, and…

Trae Agent ★ 12k

Research-friendly open-source CLI coding agent by ByteDance, designed for academic ablation studies and modular LLM provider…

Sweep AI ★ 7.7k

Autonomous GitHub bot that converts issues to pull requests using a sequential multi-agent pipeline.

Agent Governance Toolkit (microsoft) ★ 2.3k

Enterprise-grade AI agent governance: YAML policy enforcement, 12-vector prompt injection defense, zero-trust identity,…

TDD Guard ★ 2.1k

Mechanically enforces the Red-Green-Refactor TDD cycle by blocking file writes that violate TDD principles via a PreToolUse hook…

Agentic Coding Flywheel Setup (ACFS) ★ 1.5k

Take a complete beginner from laptop to three AI coding agents running on a VPS in 30 minutes via an idempotent manifest-driven…