Spec

A Model Context Protocol (MCP) server for managing software project specifications with intelligent tooling and AI-powered guidance.

Overview

Spec MCP provides a structured approach to managing software requirements, plans, components, decisions, and project constitutions through the Model Context Protocol. It enables AI assistants to help you create, query, and analyze project specifications in a standardized, traceable way using guided Q&A workflows and comprehensive validation.

Features

• 🤖 Guided Creation Flow - AI-powered Q&A workflow for creating specs with research and validation
• 📚 Built-in LLM Guidance - MCP resources with comprehensive workflow documentation and best practices
• 📋 Requirements Management - Define what needs to be built with measurable acceptance criteria
• 📐 Component Modeling - Structure your architecture (apps, services, libraries)
• 🗺️ Implementation Planning - Create detailed plans with tasks, test cases, flows, and API contracts
• ⚖️ Decision Tracking - Document architectural decisions and their rationale
• 📜 Project Constitutions - Define guiding principles and standards for your project
• 🔍 Intelligent Querying - Search, filter, sort with facets, dependency expansion, and next-task detection
• 📊 Dependency Analysis - Understand relationships with metrics (fan-in/fan-out, coupling, stability)
• ✅ Validation - Automated validation with reference checking, cycle detection, and health scoring

Installation

From npm (Recommended)

npm install -g @spec-mcp/server

Using pnpm

pnpm add -g @spec-mcp/server

Using npx (No Installation)

npx -y @spec-mcp/server

Quick Start

1. Configure Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "spec-mcp": {
      "command": "npx",
      "args": ["-y", "@spec-mcp/server"]
    }
  }
}

Optional Environment Variables:

• SPECS_PATH - Specs folder relative to git root (default: auto-detects specs or .specs)

2. Create Your Specs Directory

mkdir -p specs/{requirements,plans,components,constitutions,decisions}

Expected Directory Structure:

specs/
├── requirements/     # What needs to be built
│   └── req-001-user-auth.yml
├── plans/           # How to build it
│   └── pln-001-auth-impl.yml
├── components/      # System architecture
│   ├── app-001-web-client.yml
│   └── svc-001-api-server.yml
├── constitutions/   # Project principles
│   └── con-001-code-standards.yml
└── decisions/       # Architectural decisions
    └── dec-001-jwt-tokens.yml

3. Create Your First Requirement

Ask Claude: "Create a requirement for user authentication"

Claude will guide you through a Q&A flow:

1. Research - Search for similar specs and review constitutions
2. Define - Name, description, priority
3. Criteria - Measurable acceptance criteria
4. Finalize - Review and create

4. Query and Analyze

// Find next task to work on
query({ next_task: true })

// Search requirements
query({
  types: ["requirement"],
  search_terms: "authentication",
  mode: "summary"
})

// Validate system health
validate({
  check_references: true,
  check_cycles: true,
  include_health: true
})

Specification Types

Type	Purpose	Example
Requirement	Define what needs to be built with acceptance criteria	User authentication system with OAuth support
Component	Model system architecture (apps, services, libraries)	Authentication service with database schema
Plan	Implementation details with tasks and test cases	Plan for implementing OAuth provider
Decision	Document architectural decisions	Decision to use JWT for session management
Constitution	Project principles and guidelines	Code quality standards, security requirements

How It Works: Guided Creation Flow

Spec MCP uses an intelligent Q&A workflow to help you create high-quality specifications:

1️⃣ Research Phase

• Prevent Duplicates: Searches existing specs for similar work
• Constitution Alignment: Reviews project principles and standards
• Library Research: Looks up third-party documentation via Context7
• Best Practices: Fetches architectural patterns and standards

2️⃣ Definition Phase

• Structured Questions: Guides you through naming, description, priority
• Schema Validation: Validates input at each step
• Context-Aware: Adapts questions based on spec type

3️⃣ Detailed Planning

• Requirements: Define measurable acceptance criteria
• Components: Specify capabilities, constraints, dependencies
• Plans: Break down into tasks, flows, test cases, APIs
• Decisions: Document options, rationale, and impact

4️⃣ Finalization

• Auto-Mapping: Converts Q&A data to proper schema
• File Creation: Generates well-formatted YAML
• Validation: Ensures all references and structure are valid

Available Tools

Creation Flow (Guided Q&A)

• start_draft - Begin creating a spec with guided Q&A workflow
  • Supports: requirement, component, plan, constitution, decision
  • Auto-research similar specs and constitutions
• update_draft - Answer questions step-by-step to build the spec
  • Collects data through structured questions
  • Validates input at each step
• finalize_draft - Complete the draft and create the specification
  • Maps collected data to schema
  • Creates final YAML file

Management

• update_spec - Modify finalized specifications with validation
  • Update any field (name, description, priority, tasks, etc.)
  • Validates changes against schema
  • Locked specs only allow progress tracking updates
• delete_spec - Remove specifications or drafts
  • Auto-detects type from ID
  • Supports all spec types

Querying

• query - Comprehensive unified query tool
  • Modes: summary, full, custom (with field selection)
  • Lookup: By ID, multiple IDs, or list/search
  • Search: Full-text with fuzzy matching support
  • Filters: Type-specific (priority, status, completion, dates, orphans, coverage)
  • Sorting: Multi-field sorting (relevance, date, priority, name)
  • Pagination: Offset/limit with metadata
  • Facets: Count aggregations by type, priority, status, folder
  • Expansion: Include dependencies, references, parent entities with metrics
  • Next Task: Auto-detect highest priority unblocked task
  • Sub-entities: Access tasks, test cases, flows, APIs, data models directly

Validation

• validate - System-wide validation and health scoring
  • Reference checking (broken links)
  • Circular dependency detection
  • Health score (0-100) with breakdown
  • Entity-specific or system-wide validation

MCP Resources & Prompts

Resources

Spec MCP exposes comprehensive guidance documentation as MCP resources that AI assistants can discover and read automatically:

• spec-mcp://guide/getting-started - Quick start guide for spec-driven development
• spec-mcp://guide/planning-workflow - Complete workflow for planning features with specs
• spec-mcp://guide/implementation-workflow - Development workflow for implementing from specs
• spec-mcp://guide/best-practices - Patterns, anti-patterns, and tips
• spec-mcp://guide/query-guide - Complete guide for querying and analyzing specs

These resources help LLMs understand:

• When to use each spec type
• How to link specs together (requirements → plans via criteria_id)
• Best practices for creating effective specs
• Common workflows for planning and implementation
• Advanced querying patterns

Prompts

Spec MCP provides interactive prompts for guided setup and workflows:

setup-project - Interview-Style Setup Guide

An interactive setup assistant that asks about your project and provides tailored guidance.

How it works:

1. Asks about your project type (web-app, API, library, fullstack, etc.)
2. Asks if you have existing code or starting fresh
3. Asks about your team size (solo or team)
4. Generates personalized setup instructions based on your answers

What you get:

1. Directory Structure - Commands to create specs/ folders
2. Project Constitution - Example constitutions tailored to your project type
   • API projects: API-first design, versioning, error handling
   • Web apps: Accessibility, performance, component architecture
   • Libraries: Public API design, semantic versioning
3. First Requirement - Example requirement creation walkthrough
4. Claude Code Agents - Ready-to-use agent configurations:
   • Planning Agent (.claude/agents/planning-agent.md) - Plans features using spec-mcp workflows
   • Implementation Agent (.claude/agents/implementation-agent.md) - Implements tasks from specs
5. Slash Commands - Optional command shortcuts (/plan, /next, /validate)

Usage in Claude Code:

Help me set up spec-mcp for my project

The assistant will ask questions conversationally and adapt recommendations based on your specific context.

AI assistants can read these resources to provide better guidance without manual instruction.

Architecture

This is a monorepo powered by Turborepo and pnpm workspaces:

Packages

• @spec-mcp/server (v0.3.0) - MCP server implementation with tool registration
• @spec-mcp/core (v0.1.0) - Core business logic, operations, and validation engines
• @spec-mcp/data (v0.0.1) - Data schemas, YAML operations, and Zod validation
• @spec-mcp/cli (v0.1.0) - CLI tool for validating specs (spec-validate)
• @spec-mcp/utils (v0.1.0) - Shared utilities for file operations
• @spec-mcp/tsconfig - Shared TypeScript configuration

Tech Stack

• Runtime: Node.js ≥18.0.0
• Package Manager: pnpm ≥8.0.0
• Build System: Turborepo + TypeScript
• Testing: Vitest with coverage
• Linting/Formatting: Biome
• Protocol: Model Context Protocol SDK v1.18.2
• Validation: Zod v3.23.8
• Data Format: YAML

Development

Prerequisites

• Node.js >= 18.0.0
• pnpm >= 8.0.0

Setup

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Start development mode
pnpm dev

# Run MCP inspector for debugging
pnpm inspector

Project Scripts

# Building
pnpm build          # Build all packages (turbo)
pnpm dev            # Watch mode for all packages (turbo)
pnpm clean          # Clean all build artifacts (turbo)

# Quality Checks
pnpm typecheck      # Type check all packages (turbo)
pnpm lint           # Lint with Biome
pnpm lint:fix       # Lint and auto-fix
pnpm format         # Format with Biome
pnpm format:check   # Check formatting
pnpm check          # Lint + format check
pnpm check:fix      # Lint + format and auto-fix

# Testing
pnpm test           # Run all tests (turbo)
pnpm test:watch     # Run tests in watch mode (turbo)
pnpm test:coverage  # Run tests with coverage (turbo)

# Utilities
pnpm pre-commit     # Pre-commit hook (lint + typecheck + test)
pnpm inspector      # Launch MCP Inspector for debugging
pnpm knip           # Find unused dependencies

Documentation

Detailed documentation for each specification type:

• Requirements
• Components
• Plans
• Decisions
• Constitutions

Common Workflows

Developer Flow: Finding What to Work On

// 1. Get next recommended task (highest priority, unblocked)
query({ next_task: true })

// 2. Get full plan details with dependencies
query({
  entity_id: "pln-001-auth-impl",
  mode: "full",
  expand: {
    dependencies: true,
    dependency_metrics: true
  }
})

// 3. Mark task as completed
update_spec({
  id: "pln-001-auth-impl",
  updates: {
    tasks: [
      { id: "task-001", completed: true, verified: true }
    ]
  }
})

// 4. Validate system health
validate({
  check_references: true,
  check_cycles: true,
  include_health: true
})

Advanced Querying

// Multi-filter search with facets
query({
  types: ["plan", "requirement"],
  search_terms: "authentication security",
  filters: {
    plan_priority: ["critical", "high"],
    plan_completed: false
  },
  include_facets: true,
  facet_fields: ["type", "priority", "status"],
  sort_by: [
    { field: "priority", order: "desc" },
    { field: "created_at", order: "desc" }
  ],
  limit: 20
})

// Find orphaned or uncovered specs
query({
  types: ["requirement"],
  filters: {
    uncovered: true  // Requirements without plans
  }
})

// Dependency analysis with metrics
query({
  entity_id: "req-001-user-auth",
  expand: {
    dependencies: true,
    dependency_metrics: true,
    depth: 2
  }
})

Sub-Entity Access

// Access specific task from plan
query({
  entity_id: "pln-001-auth-impl",
  sub_entity_id: "task-002"
})

// Access test case
query({
  entity_id: "pln-001-auth-impl",
  sub_entity_id: "tc-001"
})

License

MIT License - see LICENSE for details

Repository

https://github.com/lucasilverentand/spec-mcp

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.