What can you do with this server?

The spec-builder-mcp server helps AI assistants plan and document software features using a structured Software Design Document (SDD) approach, storing documents locally in a .docs/features/ directory. * List features (spec_list): Retrieve all documented features in the workspace. * Search features (spec_search): Search feature names and document contents to find existing features. * Create feature (spec_create): Create a new feature folder (auto-prefixed with FEAT-) with requirements.md and technical_design.md initialized from templates. * Update document (spec_update): Write or overwrite markdown content to an existing feature's requirements.md or technical_design.md. * Delete feature (spec_delete): Permanently remove a feature folder and all its documents. * Guided workflow (spec_wizard prompt): An AI-driven assistant that iteratively walks through requirements gathering and technical design. All operations require a workspace_path (absolute path to your project), and feature-specific operations reference the feature name without the FEAT- prefix.

How do I use spec-builder-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@spec-builder-mcp Create a new feature for user profile editing" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

spec-builder-mcp

by dominique-boerner

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

spec-builder-mcp

An MCP (Model Context Protocol) server that helps AI assistants plan and document software features using a structured Software Design Document (SDD) approach.

Instead of jumping straight into code, the AI guides you through creating proper documentation — requirements and technical design — before any implementation begins.

How it works

When connected to an MCP-compatible client (e.g. Claude Desktop, Cursor, Junie), the server exposes tools and a workflow prompt that the AI uses to manage feature documentation in your project.

All documents are stored locally in your project under .docs/features/:

your-project/
└── .docs/
    └── features/
        └── user-login/
            ├── requirements.md
            └── technical_design.md

Workflow

You trigger the spec_wizard prompt in your MCP client.
The AI asks: "What do you want to build?" — or skip this step by passing a file (e.g. @ticket.json, @brief.md), which the AI uses as the basis for the spec.
It searches existing feature docs to check if the feature already exists.
If it's new, it creates the feature folder with both documents initialised from the built-in templates.
Both documents are filled out iteratively (requirements first, then technical design) and saved with spec_update.

Related MCP server: Vibe Coder MCP

Tools

Tool	Description
`spec_list`	Lists all documented features in `.docs/features/`
`spec_search`	Searches feature names and document contents for a query
`spec_create`	Creates a new feature folder (`FEAT-{name}/`) with both documents
`spec_update`	Writes content to an existing feature's `requirements.md` or `technical_design.md`
`spec_delete`	Permanently deletes a feature folder and all its documents

Example

An example specification generated with this tool is included in this repository:

FEAT-spec-wizard/
├── requirements.md       # functional & non-functional requirements for the Spec Wizard itself
└── technical_design.md   # architecture, components, and tool interaction flow

Setup

1. Build

npm install
npm run build

2. Configure your MCP client

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "spec-builder-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/spec-builder-mcp/build/index.js"]
    }
  }
}

3. Use

In your MCP client, select the spec_wizard prompt to begin a guided feature planning session.

Development

npm run build   # compile TypeScript + copy prompt files
npm start       # run the built server

Source structure:

src/
├── index.ts                        # entry point — registers tools and prompt
├── helpers/
│   └── directory.helper.ts         # resolves .docs/features/ path
├── prompts/
│   ├── sdd-workflow.prompt.json    # prompt metadata
│   └── sdd-workflow.prompt.md      # prompt content sent to the AI
├── templates/
│   ├── requirements.md             # template for requirements documents
│   └── technical_design.md        # template for technical design documents
└── tools/
    ├── list-features.tool.ts
    ├── search-feature.tool.ts
    ├── create-feature.tool.ts
    ├── update-feature.tool.ts
    └── delete-feature.tool.ts

Available Tools

5 tools

spec_createA

Creates a new feature folder (prefixed with FEAT-) and initializes both requirements.md and technical_design.md.

ParametersJSON Schema

Name	Required	Description	Default
`feature_name`	Yes	The name of the feature without prefix (e.g., 'user-login'). The folder will be created as 'FEAT-user-login'.
`workspace_path`	Yes	The absolute path to the user's current project workspace.

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that a folder with prefix and two files are created, but does not mention behavior on conflict (e.g., if folder exists), permissions required, or side effects. Basic but incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence that efficiently conveys the main action and outputs. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with only 2 parameters and no output schema. The description covers creation and files, but lacks any indication of return value, success confirmation, or error conditions. Adequate but could be more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already covers both parameters fully (100% coverage). The description adds valuable context by explaining that feature_name is used without prefix and the folder is created as FEAT-{name}. This goes beyond the schema's description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it creates a new feature folder with a specific prefix (FEAT-) and initializes two specific files. This clearly identifies the tool's action and distinguishes it from sibling tools like spec_delete or spec_update.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., spec_update or spec_search). There is no mention of prerequisites or scenarios where creation might not be appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_deleteA

Permanently deletes a feature folder and all its documents.

ParametersJSON Schema

Name	Required	Description	Default
`feature_name`	Yes	The name of the feature without prefix (e.g., 'user-login'). The folder 'FEAT-user-login' will be deleted.
`workspace_path`	Yes	The absolute path to the user's current project workspace.

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses destructive behavior and cascading deletion ('all its documents') but lacks details on permissions, reversibility, or dependencies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with the key action, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple destructive tool with full schema coverage, the description is adequate. It covers the essential behavior and resource scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds no additional meaning beyond what the schema already provides for both parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (deletes permanently) and the resource (feature folder and all its documents). It distinguishes itself from sibling tools like spec_create, spec_list, spec_search, and spec_update.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for deletion but provides no explicit guidance on when to use vs alternatives, no prerequisites, and no warnings beyond the word 'permanently'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_listB

Lists all documented features in the .docs/features directory of the workspace.

ParametersJSON Schema

Name	Required	Description	Default
`workspace_path`	Yes	The absolute path to the user's current project workspace.

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully convey behavioral traits. It does not mention error handling, output format, or whether the operation is read-only. This is insufficient for an agent to understand side effects or safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that efficiently conveys the tool's purpose with no unnecessary words. It is well front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, but the description lacks details on what exactly is returned (e.g., file names, paths) and how errors are handled. Without an output schema, the description should provide more context about the list's format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with one parameter already described. The description adds no extra meaning about the workspace_path parameter beyond the schema's own description. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all documented features in a specific directory (.docs/features). It uses a specific verb 'Lists' and identifies the resource, distinguishing it from sibling tools like spec_create and spec_delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., spec_search for filtered listing). The description only states what it does without any contextual usage advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_searchA

Searches existing feature documentation for a specific query to see if a feature already exists.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	The search query to match against feature names and contents.
`workspace_path`	Yes	The absolute path to the user's current project workspace.

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full burden for behavioral disclosure. It explains that it searches documentation and checks existence, but lacks details on what is returned (e.g., matches, boolean), scope, or limitations. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is both concise and front-loaded with the key action and purpose. No unnecessary words, and every part contributes to understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, no output schema), the description covers the purpose and basic behavior. However, it is missing information about the return format or output, which is important for a search tool. Adequate but leaves a gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are already well-described. The description adds no extra meaning beyond the schema. Baseline score of 3 is appropriate since the schema already carries the semantic load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches feature documentation for a query to check if a feature exists. It uses a specific verb ('searches') and resource ('feature documentation'), and the purpose distinguishes it from sibling tools like spec_create or spec_delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for checking feature existence before creation but does not provide explicit when-to-use or when-not-to-use guidance. Sibling tools are listed but no direct comparison or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_updateB

Writes content to a document (requirements or technical_design) of an existing feature.

ParametersJSON Schema

Name	Required	Description
`type`	Yes	The document to update.
`content`	Yes	The full markdown content to write into the document.
`feature_name`	Yes	The name of the feature without prefix (e.g., 'user-login'). The folder 'FEAT-user-login' will be used.
`workspace_path`	Yes	The absolute path to the user's current project workspace.

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only notes the tool writes content, without disclosing whether it overwrites the entire document, error conditions, or required permissions. The behavior is implicit but insufficiently transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 15 words, conveying the essential purpose without extraneous information. It is appropriately concise but could benefit from slight restructuring for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema is provided, yet the description does not mention return values or success/failure indicators. For a mutation tool with four required parameters, the description leaves the agent without knowledge of what to expect after execution.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so each parameter is already documented in the schema. The description adds no new semantics beyond confirming the 'type' enum values (requirements, technical_design). Baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'writes' and the resource 'content to a document (requirements or technical_design) of an existing feature.' It distinguishes the tool from siblings like spec_create (which creates new features) by explicitly targeting existing features.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. While sibling tool names imply usage, the description lacks explicit context about prerequisites, when not to use, or comparisons to sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

5 tool updatesv1.0.0Jun 27, 2026
- First observedspec_create
- First observedspec_delete
- First observedspec_list
- First observedspec_search
- First observedspec_update

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored 2026-06-27 19:35 across 5 tools

Disambiguation5/5

Each tool targets a distinct operation (create, delete, list, search, update) with no overlap, ensuring an agent can clearly differentiate them.

Naming Consistency5/5

All tools follow a consistent 'spec_verb' pattern using snake_case, making naming predictable and easy to understand.

Tool Count5/5

With 5 tools, the set is well-scoped for managing feature specifications, covering essential operations without unnecessary bloat.

Completeness3/5

CRUD-like operations are present except for a dedicated read/get tool to retrieve the full content of a single feature, which is a notable gap.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

PlanExe A
io.github.PlanExeOrg
MCP server for generating rough-draft project plans from natural-language prompts.
Autonomous Agents Developer Tools Project Management
113399
microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21
slimaOAuth
io.github.slima-ai
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Developer Tools
21
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2

Related MCP Servers

Vibe-Coder MCP Server
Coding Agents Developer Tools
crazyrabbitLTC
A
license
D
quality
D
maintenance
An MCP server that implements a structured workflow for LLM-based coding, guiding development through feature clarification, documentation generation, phased implementation, and progress tracking.
Updated a year ago (2025-04-25 18:32 UTC)
10
41 npm
18
MIT
Vibe Coder MCP
Developer Tools Code Execution Autonomous Agents
freshtechbro
A
license
B
quality
C
maintenance
An MCP server that supercharges AI assistants with powerful tools for software development, enabling research, planning, code generation, and project scaffolding through natural language interaction.
Updated a year ago (2025-08-21 03:06 UTC)
11
41 npm
103
MIT
MCP SDD Server
Developer Tools Software Architecture Code Analysis
yi-john-huang
A
license
C
quality
A
maintenance
An MCP server implementing Spec-Driven Development workflows for AI-agent CLIs and IDEs like Claude Code and Cursor, enabling spec-first development with automated workflow guidance and quality checks.
Updated 2 months ago (2026-07-25 06:01 UTC)
16
12 npm
52
MIT
DocsHub MCP Server
Documentation Access Developer Tools
rkratky
F
license
A
quality
B
maintenance
An MCP server that provides AI clients with access to developer documentation via llms.txt files. Exposes tools, resources, and prompts.
Updated a month ago (2026-07-31 17:30 UTC)
3
1
-