mcp-createspec

Stop writing vague specs. This MCP server turns your AI agent into a spec-writing machine that actually follows a process.

You say "create a spec for user auth" and it walks your agent through three phases — requirements, design, and implementation tasks — validating each step before moving on. No hand-holding, no skipped sections, no half-baked docs.

The output? A single, clean markdown spec file ready to hand off to a developer (or another agent). The working folder gets auto-deleted after the merge — you're left with one file, zero mess.

Setup

Pick your editor. No API keys, no env vars — just add the config and go.

Claude Code

One command:

claude mcp add --scope user --transport stdio create-spec -- npx -y mcp-createspec

Or add it to .mcp.json in your project root (shared with your team):

{
  "mcpServers": {
    "create-spec": {
      "command": "npx",
      "args": ["-y", "mcp-createspec"]
    }
  }
}

Verify with claude mcp list or type /mcp inside a session.

Cursor

Open Settings > MCP and click Add new global MCP server, or edit the file directly.

Global (all projects): ~/.cursor/mcp.json Project-level: .cursor/mcp.json in your repo root

{
  "mcpServers": {
    "create-spec": {
      "command": "npx",
      "args": ["-y", "mcp-createspec"]
    }
  }
}

Windsurf

Open Settings > Cascade > MCP Servers > Add manually, or edit the file directly.

Config path: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "create-spec": {
      "command": "npx",
      "args": ["-y", "mcp-createspec"]
    }
  }
}

VS Code (GitHub Copilot)

Run from the command palette: MCP: Add Server and choose Workspace or Global.

Or add to .vscode/mcp.json in your project (workspace-level):

{
  "servers": {
    "create-spec": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-createspec"]
    }
  }
}

Or via CLI:

code --add-mcp '{"name":"create-spec","command":"npx","args":["-y","mcp-createspec"]}'

Note: VS Code uses "servers" (not "mcpServers") and requires "type": "stdio".

GitHub Copilot CLI

/mcp add

Then fill in the interactive form. Or edit ~/.copilot/mcp-config.json directly:

{
  "servers": {
    "create-spec": {
      "command": "npx",
      "args": ["-y", "mcp-createspec"]
    }
  }
}

Any other MCP client

The server speaks stdio. Point your client at:

npx -y mcp-createspec

No args, no env vars, no setup beyond that.

How it works

It's a 4-tool chain. Each tool validates the previous step and feeds the next one:

You: "create a spec for [topic]"

  1. create-spec            creates a working folder, returns a requirements prompt
     Agent writes 01-requirements.md

  2. validate-requirements  checks the doc (7 validations), returns a design prompt
     Agent writes 02-design.md

  3. validate-design        checks against requirements (5 validations), returns a tasks prompt
     Agent writes 03-tasks.md

  4. finalize-spec          validates tasks, merges all 3 into one file, auto-deletes the folder
     Output: spec-[topic].md

Four tools, zero prompts, zero config. The agent does the writing, the server keeps it honest.

The sequencing is enforced — each tool's response includes the next tool name and all required arguments, so the agent can't skip ahead or forget a step.

What gets validated

The server isn't doing AI magic — it's doing string-match checks to make sure the agent didn't cut corners:

Requirements (7 checks):

• Not empty, at least 500 chars
• Has a ## Requirements heading
• Includes user stories (As a [role], I want...)
• Has WHEN/THEN acceptance criteria
• Has a non-functional requirements section
• At least 2 numbered requirements (### Requirement 1, ### Requirement 2)

Design (5 checks):

• At least 800 chars
• Has ## Overview or ## Architecture section
• Has ## Components or ## Interfaces section
• Has ## Data Models or ## Error Handling
• Actually references the requirements

Tasks (5 checks):

• At least 600 chars
• Uses - [ ] checkbox format
• At least 3 tasks
• Each task has a _Prompt: field (Role | Task | Restrictions | Success)
• Each task has a _Requirements: reference

If validation fails, the agent gets a numbered error list and has to fix the file before the next phase unlocks. No shortcuts.

Usage

Just ask your agent to create a spec. Seriously, that's it.

You: "Create a spec for adding real-time chat to our app"

The agent will:

1. Call create-spec with your topic
2. Write a requirements doc following the template it received
3. Call validate-requirements — if checks fail, fix and re-call
4. Write a design doc
5. Call validate-design — if checks fail, fix and re-call
6. Write a tasks doc
7. Call finalize-spec — get back a single merged spec-*.md file

You can also pass extra context:

You: "Create a spec for payment processing — we use Stripe, need to support
      subscriptions and one-time payments, must be PCI compliant"

The context parameter gets embedded right into the requirements prompt so the agent factors it in from the start.

What the finalize step actually does

This is the interesting part. When finalize-spec runs:

1. Validates the tasks doc (5 checks — checkboxes, prompt fields, requirement refs)
2. Reads all three files (requirements, design, tasks)
3. Merges them into a single markdown file with this structure:

# Specification: [Your Topic]

_Generated by mcp-createspec_

---

## Part 1: Requirements
(full requirements doc — user stories, acceptance criteria, NFRs)

---

## Part 2: Design
(architecture, components, data models, error handling, testing strategy)

---

## Part 3: Tasks
(atomic tasks with checkboxes, _Prompt: fields, _Requirements: references)

4. Writes the merged file to spec-[folder-name].md in the parent directory
5. Deletes the working folder (rm -rf) — no cleanup needed on your end

Each task in the output includes a _Prompt: field formatted as Role | Task | Restrictions | Success — designed to be fed directly to another agent for implementation.

The tools

create-spec

Kick things off. Creates a working folder and returns the requirements template.

| Param | Type | Required | Description | |-------|------|----------|-------------| | topic | string | yes | What the spec is about | | context | string | no | Extra background, constraints, or details |

validate-requirements

Validates what the agent wrote. If it passes, returns the design template.

| Param | Type | Required | Description | |-------|------|----------|-------------| | filePath | string | yes | Path to 01-requirements.md |

validate-design

Validates the design against requirements. If it passes, returns the tasks template.

| Param | Type | Required | Description | |-------|------|----------|-------------| | filePath | string | yes | Path to 02-design.md | | requirementsFilePath | string | yes | Path to 01-requirements.md |

finalize-spec

Validates tasks, merges all 3 files, writes the output, deletes the folder.

| Param | Type | Required | Description | |-------|------|----------|-------------| | filePath | string | yes | Path to 03-tasks.md | | requirementsFilePath | string | yes | Path to 01-requirements.md | | designFilePath | string | yes | Path to 02-design.md |

Verify it works

You can test the server directly with the MCP Inspector:

# List all 4 tools
npx @modelcontextprotocol/inspector --cli npx -y mcp-createspec --method tools/list

# Call create-spec
npx @modelcontextprotocol/inspector --cli npx -y mcp-createspec \
  --method tools/call \
  --tool-name create-spec \
  --tool-arg 'topic=user authentication'

Why this exists

Writing specs is boring. Agents are happy to do it, but they tend to skip sections, forget acceptance criteria, and produce vague designs that don't reference the actual requirements.

This server forces the process. Three phases, validation between each one, mandatory structure. The agent can't move to design until requirements pass. Can't move to tasks until design passes. Can't finalize until tasks pass.

It's opinionated and that's the point.

License

MIT