Skip to main content
Glama
spec-builder-mcp

spec-builder-mcp

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

  1. You trigger the spec_wizard prompt in your MCP client.

  2. 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.

  3. It searches existing feature docs to check if the feature already exists.

  4. If it's new, it creates the feature folder with both documents initialised from the built-in templates.

  5. 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.

Inputs: feature_name (required), workspace_path (required).

spec_deleteA

Permanently deletes a feature folder and all its documents.

Inputs: feature_name (required), workspace_path (required).

spec_listB

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

Inputs: workspace_path (required).

spec_updateB

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

Inputs: type (required), content (required), feature_name (required), workspace_path (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored 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.

    Related MCP Connectors

    Related MCP Servers