An MCP server that walks your AI agent through a 4-step spec creation workflow — from idea to requirements, design, and implementation tasks. No prompts, just tools.
npm install create-spec-mcpStop 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.
---
Pick your editor. No API keys, no env vars — just add the config and go.
One command:
``bash`
claude mcp add --scope user --transport stdio create-spec -- npx -y create-spec-mcp
Or add it to .mcp.json in your project root (shared with your team):
`json`
{
"mcpServers": {
"create-spec": {
"command": "npx",
"args": ["-y", "create-spec-mcp"]
}
}
}
Verify with claude mcp list or type /mcp inside a session.
Open Settings > MCP and click Add new global MCP server, or edit the file directly.
Global (all projects): ~/.cursor/mcp.json
Project-level: in your repo root
`json`
{
"mcpServers": {
"create-spec": {
"command": "npx",
"args": ["-y", "create-spec-mcp"]
}
}
}
Open Settings > Cascade > MCP Servers > Add manually, or edit the file directly.
Config path: ~/.codeium/windsurf/mcp_config.json
`json`
{
"mcpServers": {
"create-spec": {
"command": "npx",
"args": ["-y", "create-spec-mcp"]
}
}
}
Run from the command palette: MCP: Add Server and choose Workspace or Global.
Or add to .vscode/mcp.json in your project (workspace-level):
`json`
{
"servers": {
"create-spec": {
"type": "stdio",
"command": "npx",
"args": ["-y", "create-spec-mcp"]
}
}
}
Or via CLI:
`bash`
code --add-mcp '{"name":"create-spec","command":"npx","args":["-y","create-spec-mcp"]}'
> Note: VS Code uses "servers" (not "mcpServers") and requires "type": "stdio".
`bash`
/mcp add
Then fill in the interactive form. Or edit ~/.copilot/mcp-config.json directly:
`json`
{
"servers": {
"create-spec": {
"command": "npx",
"args": ["-y", "create-spec-mcp"]
}
}
}
The server speaks stdio. Point your client at:
`
npx -y create-spec-mcp
No args, no env vars, no setup beyond that.
---
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.
---
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 headingAs a [role], I want...
- Includes user stories ()### Requirement 1
- Has WHEN/THEN acceptance criteria
- Has a non-functional requirements section
- At least 2 numbered requirements (, ### Requirement 2)
Design (5 checks):
- At least 800 chars
- Has ## Overview or ## Architecture section## Components
- Has or ## Interfaces section## Data Models
- Has or ## Error Handling
- Actually references the requirements
Tasks (5 checks):
- At least 600 chars
- Uses - [ ] checkbox format_Prompt:
- At least 3 tasks
- Each task has a field (Role | Task | Restrictions | Success)_Requirements:
- Each task has a reference
If validation fails, the agent gets a numbered error list and has to fix the file before the next phase unlocks. No shortcuts.
---
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 topicvalidate-requirements
2. Write a requirements doc following the template it received
3. Call — if checks fail, fix and re-callvalidate-design
4. Write a design doc
5. Call — if checks fail, fix and re-callfinalize-spec
6. Write a tasks doc
7. Call — 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.
---
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:
`markdownSpecification: [Your Topic]
_Generated by create-spec-mcp_
---
---
---
4. Writes the merged file to
in the parent directory
5. Deletes the working folder (rm -rf) — no cleanup needed on your endEach 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
$3
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 |$3
Validates what the agent wrote. If it passes, returns the design template.| Param | Type | Required | Description |
|-------|------|----------|-------------|
|
filePath | string | yes | Path to 01-requirements.md |$3
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 |$3
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:
`bash
List all 4 tools
npx @modelcontextprotocol/inspector --cli npx -y create-spec-mcp --method tools/listCall create-spec
npx @modelcontextprotocol/inspector --cli npx -y create-spec-mcp \
--method tools/call \
--tool-name create-spec \
--tool-arg 'topic=user authentication'
``---
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.
---
MIT