MCP 服务器

Specky

An MCP server for Spec-Driven Development that transforms natural language ideas and meeting transcripts into structured, production-grade specifications using EARS notation. It automates a 7-phase pipeline to generate project artifacts like requirements, architecture designs, and task lists directly to disk.

README

<div align="center"> <h1>Specky</h1> <h3>The Complete Spec-Driven Development Platform</h3> <p><strong>42 MCP tools. 10-phase pipeline. Works in any IDE.</strong></p>

What is Specky?

Specky is an open-source MCP (Model Context Protocol) server that transforms how software is built. It provides a complete, deterministic pipeline from any input -- meeting transcripts, documents, designs, or user prompts -- through specifications, architecture, infrastructure as code, implementation, and deployment.

Unlike template-based tools, Specky enforces every step programmatically: a state machine blocks phase-skipping, an EARS validator ensures testable requirements, cross-artifact analysis catches drift, and compliance engines validate against frameworks like HIPAA and SOC2.

Specky works inside the tools you already use -- VS Code with GitHub Copilot, Claude Code, Cursor, Windsurf, or any AI agent that supports MCP.

Why Specky?

The Problem

AI coding assistants are fast but chaotic. They skip requirements, ignore architecture, and produce code that drifts from the original intent. Template-based approaches help but rely on the AI to follow instructions -- with no programmatic enforcement.

The Solution

Specky adds a deterministic engine between your intent and your code:

State Machine -- 10 mandatory phases, no skipping. Init, Discover, Specify, Clarify, Design, Tasks, Analyze, Implement, Verify, Release.
EARS Validator -- Every requirement validated against 6 patterns (Ubiquitous, Event-driven, State-driven, Optional, Unwanted, Complex). No vague statements pass.
Cross-Artifact Analysis -- Automatic alignment checking between spec, design, and tasks. Orphaned requirements are flagged instantly.
MCP-to-MCP Architecture -- Specky outputs structured JSON that your AI client routes to GitHub, Azure DevOps, Jira, Terraform, Figma, and Docker MCP servers. No vendor lock-in.

Differentiators

<details> <summary>View as table</summary>

Capability	Spec-Kit	Kiro	Cursor	Specky
Any input (PDF/DOCX/PPTX/transcript) to spec	No	No	No	Yes
EARS validation (programmatic)	No	AI-tries	No	Yes
State machine (10 phases)	No	No	No	Yes
Auto-diagrams every phase (Mermaid)	No	No	No	Yes
Terraform IaC generation	No	No	No	Yes
Azure Boards + Jira + GitHub Issues (MCP)	Extension	No	No	Yes
Figma design to spec (reverse)	No	No	No	Yes
FigJam diagram generation	No	No	No	Yes
Docker dev environment	No	No	No	Yes
Codespaces setup	No	No	No	Yes
Cross-artifact analysis	Yes	No	No	Yes
Compliance (HIPAA/SOC2/GDPR)	No	No	No	Yes
Phantom task detection	Extension	No	No	Yes
Complete auto-documentation	No	No	No	Yes
Educative outputs	No	No	No	Yes
42 MCP tools	N/A	N/A	N/A	Yes
Works in ANY IDE via MCP	Templates	IDE-locked	IDE-locked	Yes

</details>

Quick Start

Install

# npm (recommended)
npx specky-sdd

# Or install globally
npm install -g specky-sdd

Configure in VS Code (GitHub Copilot)

Create .vscode/mcp.json in your project:

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

Open Copilot Chat -- Specky's 42 tools are now available.

Configure in Claude Code

claude mcp add specky -- npx -y specky-sdd

Or add to your MCP settings manually:

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

Configure in Claude Desktop

Add to claude_desktop_config.json:

OS	Config File Location
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

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

Configure in Cursor

Add to Cursor's MCP settings (Settings > MCP Servers):

{
  "specky": {
    "command": "npx",
    "args": ["-y", "specky-sdd"]
  }
}

Docker

docker run -v $(pwd):/workspace ghcr.io/paulasilvatech/specky:latest

The 10-Phase Pipeline

Each phase is mandatory. The state machine blocks advancement until prerequisites are met.

Phase	What Happens	Required Output
Init	Create project structure, constitution, scan codebase	CONSTITUTION.md
Discover	Interactive discovery: 7 structured questions about scope, users, constraints	Discovery answers
Specify	Write EARS requirements with acceptance criteria	SPECIFICATION.md
Clarify	Resolve ambiguities, generate decision tree	Updated SPECIFICATION.md
Design	Architecture, data model, API contracts, research unknowns	DESIGN.md, RESEARCH.md
Tasks	Implementation breakdown by user story, dependency graph	TASKS.md
Analyze	Cross-artifact analysis, quality checklist, compliance check	ANALYSIS.md, CHECKLIST.md, CROSS_ANALYSIS.md
Implement	Ordered execution with checkpoints per user story	Implementation progress
Verify	Drift detection, phantom task detection	VERIFICATION.md
Release	PR generation, work item export, documentation	Complete package

All 42 Tools

Input and Conversion (5)

Tool	Description
`sdd_import_document`	Convert PDF, DOCX, PPTX, TXT, MD to Markdown
`sdd_import_transcript`	Parse meeting transcripts (Teams, Zoom, Google Meet)
`sdd_auto_pipeline`	Any input to complete spec pipeline (all documents)
`sdd_batch_import`	Process folder of mixed documents
`sdd_figma_to_spec`	Figma design to requirements specification

Pipeline Core (8)

Tool	Description
`sdd_init`	Initialize project with constitution and scope diagram
`sdd_discover`	Interactive discovery with stakeholder mapping
`sdd_write_spec`	Write EARS requirements with flow diagrams
`sdd_clarify`	Resolve ambiguities with decision tree
`sdd_write_design`	Architecture with sequence diagrams, ERD, API flow
`sdd_write_tasks`	Task breakdown with dependency graph
`sdd_run_analysis`	Quality gate analysis with coverage heatmap
`sdd_advance_phase`	Move to next pipeline phase

Quality and Validation (5)

Tool	Description
`sdd_checklist`	Mandatory quality checklist (security, accessibility, etc.)
`sdd_verify_tasks`	Detect phantom completions
`sdd_compliance_check`	HIPAA, SOC2, GDPR, PCI-DSS, ISO 27001 validation
`sdd_cross_analyze`	Spec-design-tasks alignment with consistency score
`sdd_validate_ears`	Batch EARS requirement validation

Diagrams and Visualization (4)

Tool	Description
`sdd_generate_diagram`	Single Mermaid diagram (10 types)
`sdd_generate_all_diagrams`	All diagrams for a feature at once
`sdd_generate_user_stories`	User stories with flow diagrams
`sdd_figma_diagram`	FigJam-ready diagram via Figma MCP

Infrastructure as Code (3)

Tool	Description
`sdd_generate_iac`	Terraform/Bicep from architecture design
`sdd_validate_iac`	Validation via Terraform MCP + Azure MCP
`sdd_generate_dockerfile`	Dockerfile + docker-compose from tech stack

Dev Environment (3)

Tool	Description
`sdd_setup_local_env`	Docker-based local dev environment
`sdd_setup_codespaces`	GitHub Codespaces configuration
`sdd_generate_devcontainer`	.devcontainer/devcontainer.json generation

Integration and Export (5)

Tool	Description
`sdd_create_branch`	Git branch naming convention
`sdd_export_work_items`	Tasks to GitHub Issues, Azure Boards, or Jira
`sdd_create_pr`	PR payload with spec summary
`sdd_implement`	Ordered implementation plan with checkpoints
`sdd_research`	Resolve unknowns in RESEARCH.md

Documentation (4)

Tool	Description
`sdd_generate_docs`	Complete auto-documentation
`sdd_generate_api_docs`	API documentation from design
`sdd_generate_runbook`	Operational runbook
`sdd_generate_onboarding`	Developer onboarding guide

Utility (5)

Tool	Description
`sdd_get_status`	Pipeline status with guided next action
`sdd_get_template`	Get any template
`sdd_scan_codebase`	Detect tech stack and structure
`sdd_metrics`	Project metrics dashboard
`sdd_amend`	Amend project constitution

MCP Integration Architecture

Specky outputs structured JSON with routing instructions. Your AI client calls the appropriate external MCP server:

Specky --> sdd_export_work_items(platform: "azure_boards") --> JSON payload
  --> AI Client --> Azure DevOps MCP --> create_work_item()

Specky --> sdd_validate_iac(provider: "terraform") --> validation payload
  --> AI Client --> Terraform MCP --> plan/validate

Specky --> sdd_figma_to_spec(file_key: "abc123") --> Figma request
  --> AI Client --> Figma MCP --> get_design_context()

Supported External MCP Servers

MCP Server	Integration
GitHub MCP	Issues, PRs, Codespaces
Azure DevOps MCP	Work Items, Boards
Jira MCP	Issues, Projects
Terraform MCP	Plan, Validate, Apply
Azure MCP	Template validation
Figma MCP	Design context, FigJam diagrams
Docker MCP	Local dev environments

EARS Notation

Every requirement in Specky follows EARS (Easy Approach to Requirements Syntax):

Pattern	Format	Example
Ubiquitous	The system shall...	The system shall encrypt all data at rest
Event-driven	When [event], the system shall...	When a user submits login, the system shall validate credentials
State-driven	While [state], the system shall...	While offline, the system shall queue requests
Optional	Where [condition], the system shall...	Where 2FA is enabled, the system shall require OTP
Unwanted	If [condition], then the system shall...	If session expires, the system shall redirect to login
Complex	While [state], when [event]...	While in maintenance, when request arrives, queue it

The EARS validator programmatically checks every requirement against these 6 patterns. Vague terms like "fast", "good", "easy" are flagged automatically.

Compliance Frameworks

Built-in compliance checking against:

HIPAA -- Access control, audit, encryption, PHI protection
SOC 2 -- Logical access, monitoring, change management, incident response
GDPR -- Lawful processing, right to erasure, data portability, breach notification
PCI-DSS -- Firewall, stored data protection, encryption, user identification
ISO 27001 -- Security policies, access control, cryptography, incident management

Educative Outputs

Every tool response includes structured guidance:

{
  "explanation": "What was done and why",
  "next_steps": "Guided next action with command suggestion",
  "learning_note": "Educational context about the concept",
  "diagram": "Mermaid diagram relevant to the output"
}

End-to-End Flow

From any input to production — fully automated, MCP-orchestrated, with artifacts and diagrams generated at every step.

Project Structure

.specs/
  001-feature-name/
    CONSTITUTION.md       -- Project principles and governance
    SPECIFICATION.md      -- EARS requirements with acceptance criteria
    DESIGN.md             -- Architecture, data model, API contracts
    RESEARCH.md           -- Resolved unknowns and decisions
    TASKS.md              -- Implementation breakdown
    ANALYSIS.md           -- Quality gate report
    CHECKLIST.md          -- Mandatory quality checklist
    CROSS_ANALYSIS.md     -- Spec-design-tasks alignment
    COMPLIANCE.md         -- Compliance framework report
    VERIFICATION.md       -- Phantom detection results

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

Contributing

See CONTRIBUTING.md for architecture details and how to add tools, templates, or services.

License

MIT -- Created by Paula Silva | Americas Software GBB, Microsoft