Specky

The open-source MCP server for Spec-Driven Development (SDD).

The fun name, the serious engine.

Created by Paula Silva (@paulanunes85) | Americas Software GBB

What is Specky?

Specky is an MCP server that transforms natural language project ideas — or meeting transcripts — into production-grade specifications. It enforces EARS notation (Easy Approach to Requirements Syntax), maintains a state machine across 7 pipeline phases, and writes real files to disk.

You ──→ AI Assistant ──→ Specky (17 tools) ──→ .specs/ files on disk
        (Copilot/Claude)                       CONSTITUTION.md
                                               SPECIFICATION.md
                                               DESIGN.md
                                               TASKS.md
                                               ANALYSIS.md

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools. Think of it like USB — a universal plug between any AI and any tool. Specky is a "device" that speaks MCP, giving Copilot and Claude the ability to create structured specification files.

Key Features

• 17 MCP tools for the full specification lifecycle
• EARS notation validation with 6 pattern types and improvement suggestions
• 7-phase pipeline with state machine enforcement
• Meeting transcript → full spec — VTT, SRT, TXT, MD formats
• Power Automate + OneDrive integration for automated workflows
• Quality gates with traceability matrix and coverage analysis
• Atomic file writes — safe, no corruption on crash
• Auto-steering — scans your codebase to tailor discovery questions
• Zero external dependencies — runs entirely local, no API calls
• GitHub Copilot agents + Claude Code commands included

Two Ways to Use

Quick Start

npx (recommended)

npx specky

npm global install

npm install -g specky
specky

Docker

docker compose up
# Server starts on http://localhost:3200

Setup

VS Code (GitHub Copilot)

Create or update .vscode/mcp.json:

{
  "servers": {
    "specky": {
      "command": "npx",
      "args": ["-y", "specky"],
      "env": {
        "SDD_WORKSPACE": "${workspaceFolder}"
      }
    }
  }
}

Claude Code

# Quick setup (one command):
claude mcp add specky npx -y specky --env SDD_WORKSPACE=$(pwd)

Or manually add to MCP settings:

{
  "mcpServers": {
    "specky": {
      "command": "npx",
      "args": ["-y", "specky"],
      "env": {
        "SDD_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "specky": {
      "command": "npx",
      "args": ["-y", "specky"],
      "env": {
        "SDD_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}

Meeting Transcript to Specs (Auto Pipeline)

One command. Full specification from a Teams/Zoom meeting.

/sdd:transcript meeting.vtt my-project

Or call the tool directly:

{
  "name": "sdd_auto_pipeline",
  "arguments": {
    "file_path": "meeting.vtt",
    "project_name": "my-project"
  }
}

What happens automatically:

1. Parses the VTT/SRT/TXT/MD transcript
2. Extracts participants, topics, decisions, action items
3. Generates EARS requirements from meeting content
4. Creates all 6 spec files in one call:

Supported formats:

Power Automate + OneDrive Integration

For fully automated meeting-to-spec workflows:

Teams Meeting → Power Automate → OneDrive/Transcripts/ → sdd_batch_transcripts → .specs/

Power Automate flow:

1. Trigger: "When a Teams meeting recording is available"
2. Action: Get the meeting transcript
3. Action: Convert to Markdown
4. Action: Save to OneDrive/Transcripts/{meeting-title}.md

Specky picks up from there:

{
  "name": "sdd_batch_transcripts",
  "arguments": {
    "transcripts_dir": "~/OneDrive/Transcripts"
  }
}

Each transcript in the folder becomes its own numbered feature spec package (001-sprint-planning/, 002-architecture-review/, etc.) with 6 files each.

Pipeline Overview

sdd_init → sdd_discover → sdd_write_spec → sdd_clarify → sdd_write_design → sdd_write_tasks → sdd_run_analysis

Each phase produces a Markdown artifact in .specs/001-your-feature/:

Tool Reference

Pipeline Tools (8)

Utility Tools (6)

Transcript Automation Tools (3)

EARS Notation

Specky validates all requirements against 6 EARS patterns:

GitHub Copilot Agents

Specky ships with 4 GitHub Copilot custom agents in .github/agents/:

Claude Code Commands

Environment Variables

HTTP Mode

For remote deployment or MCP Inspector testing:

# Direct
node dist/index.js --http

# Docker
docker compose up

The server listens on http://localhost:3200/mcp for Streamable HTTP transport.

Project Structure

.specs/
  001-your-feature/
    CONSTITUTION.md      # Project charter, principles, constraints
    SPECIFICATION.md     # EARS requirements with acceptance criteria
    DESIGN.md            # Architecture, Mermaid diagrams, ADRs
    TASKS.md             # Implementation tasks with gates
    ANALYSIS.md          # Traceability matrix, quality gate
  .sdd-state.json        # Pipeline state (phase, timestamps)

Comparison with Alternatives

How It Works Inside

┌─────────────────────────────────────────────────────────────┐
│                    SPECKY MCP SERVER                        │
│                                                             │
│  Transport: stdio (default) or HTTP (:3200)                 │
│  Protocol:  JSON-RPC 2.0 (MCP standard)                    │
│                                                             │
│  ┌─── 17 Tools ───────────────────────────────────────────┐ │
│  │  Pipeline (8)  │  Utility (6)  │  Transcript (3)       │ │
│  └────────────────┴───────────────┴───────────────────────┘ │
│                          │                                  │
│  ┌─── 6 Services ────────────────────────────────────────┐  │
│  │  FileManager       │ StateMachine   │ TemplateEngine   │  │
│  │  EarsValidator     │ CodebaseScanner│ TranscriptParser  │  │
│  └────────────────────┴────────────────┴─────────────────┘  │
│                          │                                  │
│  ┌─── 7 Templates ──────────────────────────────────────┐   │
│  │  constitution │ specification │ design │ tasks        │   │
│  │  analysis     │ bugfix        │ sync-report           │   │
│  └───────────────┴───────────────┴───────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Key design principle: Tools are thin (validate input, call service, format output). Services are fat (all business logic). FileManager owns all disk I/O.

Documentation

Development

# Clone and setup
git clone https://github.com/paulasilvatech/specky.git
cd specky
npm install

# Build
npm run build

# Development mode (auto-reload)
npm run dev

# Verify MCP handshake
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js 2>/dev/null

# Clean build artifacts
npm run clean

License

MIT License - see LICENSE for details.

Created by Paula Silva (@paulanunes85) | Americas Software GBB

Specky — The fun name, the serious engine.