Specs-Driven MCP Server

A Model Context Protocol (MCP) server that brings structured specification management to AI assistants like Claude. Organize features, requirements, acceptance criteria, and non-functional requirements in a hierarchical structure that AI can understand and navigate intelligently.

🎯 Why This Exists

When working with AI on software projects, maintaining clear, searchable specifications is crucial. This MCP server provides:

• Structured Knowledge: Organize project requirements in a hierarchy that AI can traverse
• Enhanced Search: Find relevant specs using structured queries, field filters, exact phrases, and relevance ranking
• Real-time Collaboration: Update specs through AI conversations and see changes immediately
• Context Preservation: Maintain relationships between features, requirements, and acceptance criteria
• Multi-Modal Access: Use via AI chat, web dashboard, or command line

Perfect for product managers, developers, and AI-assisted development workflows.

🚀 Installation

Global Installation (Recommended)

npm install -g specs-driven-mcp

📦 Optimized Dependencies: This package includes ~155 dependencies (down from 211+ in earlier versions). The web dashboard dependencies are bundled at build time, so you only install the essential runtime dependencies.

Using with npx (No Installation)

npx specs-driven-mcp --stdio --db ./my-project-specs.db

⚙️ MCP Server Setup

For Claude Desktop

Add to your mcp.json configuration file:

{
  "servers": {
    "specs-driven-mcp": {
      "type": "stdio",
      "command": "specs-driven-mcp",
      "args": ["--stdio", "--db", "/path/to/your/project-specs.db"]
    }
  }
}

Windows Example:

{
  "servers": {
    "specs-driven-mcp": {
      "type": "stdio", 
      "command": "specs-driven-mcp",
      "args": ["--stdio", "--db", "C:\\Projects\\MyApp\\specs.db"]
    }
  }
}

macOS/Linux Example:

{
  "servers": {
    "specs-driven-mcp": {
      "type": "stdio",
      "command": "specs-driven-mcp", 
      "args": ["--stdio", "--db", "/Users/username/projects/myapp/specs.db"]
    }
  }
}

For Other MCP Clients

The server uses standard MCP protocol over stdio. Configure your MCP client to run:

specs-driven-mcp --stdio --db /path/to/database.db

🤖 Available Tools (MCP/CLI/REST)

These tools are available across MCP, CLI, and mirrored REST endpoints.

Feature Management

• create_feature - Create new features with name and key
• get_feature - Retrieve feature details and spec count
• update_feature - Modify feature name or status
• delete_feature - Remove features (and all child specs)
• list_features - List all features with optional status filtering

Specification Management

• create_spec - Create requirements, acceptance criteria, or NFRs
• get_spec - Retrieve spec details with full hierarchy
• update_spec - Modify spec content, kind, or parent relationships
• delete_spec - Remove specifications
• list_specs - List specs with filtering by feature, kind, status, or parent

Search

• search - Unified search across features and specs. Supports field filters, quoted phrases, relevance ranking, and explain for syntax help.

Helper Tools

• bulk_create_specs - Create many specs at once (supports skip-existing/upsert)

✨ Advanced Automation Tools

• apply_batch - Execute multiple commands in batch with fail-fast, dry-run, and quiet options
• verify - Check database integrity: find orphaned specs, detect cycles, cross-feature links

Example AI Conversations (illustrative)

You: "Create a feature for user authentication"
AI: I'll create a user authentication feature for you.
[Uses create_feature tool]

You: "Add a requirement that users must login with email and password"  
AI: I'll add that requirement to the authentication feature.
[Uses create_spec tool with kind="REQUIREMENT"]

You: "What are all the security-related requirements?"
AI: Let me search for security-related specifications.
[Uses search_specs tool with 'kind:REQUIREMENT security' query]

You: "Find failing tests related to authentication"  
AI: I'll search for failing specifications about authentication.
[Uses search tool with 'authentication status:FAILING' query]

🌐 Web Dashboard

Start the built-in web dashboard:

# Dashboard only
specs-driven-mcp --dashboard --port 8765

# Dashboard + MCP server together  
specs-driven-mcp --dashboard --stdio --db ./specs.db

Visit your configured dashboard URL (default http://localhost:8765) for:

• Visual feature and spec management
• Interactive hierarchy browser
• Real-time updates from AI interactions
• System metrics and overview

🖥️ CLI Commands

For automation and scripting, the CLI supports universal output formats and batch operations:

Global Options

--db <path>           Database file path (default: ./specs.db)
--format <format>     Output format: json, csv (default: json)

Basic Operations

Feature Operations

# Create features (key optional; auto-generated from name when omitted)
specs-driven-cli create-feature "User Authentication System" --key AUTH
specs-driven-cli create-feature "Payment Processing"

# List and view features  
specs-driven-cli list-features
specs-driven-cli get-feature AUTH

Specification Operations

# Create specs (key optional; auto-generated using feature and kind)
specs-driven-cli create-spec AUTH REQUIREMENT --content "Users must authenticate with email/password" --key REQ-AUTH-001
specs-driven-cli create-spec AUTH AC --content "Login form validates email format"
specs-driven-cli create-spec AUTH NFR --content "Login must complete within 2 seconds"

# List and search specs
specs-driven-cli list-specs --feature AUTH
specs-driven-cli search "password security validation"
specs-driven-cli search '"performance requirements" kind:NFR'

# Bulk operations from file (array or { specs: [...] })
specs-driven-cli bulk-create AUTH --file ./specs.json --mode upsert

🔍 Enhanced Search Capabilities

The search system supports advanced query syntax for precise specification discovery:

Search Syntax

# Basic keyword search
specs-driven-cli search "authentication login"

# Exact phrase matching
specs-driven-cli search '"user authentication"'

# Field filtering
specs-driven-cli search "kind:REQUIREMENT authentication"
specs-driven-cli search "status:VERIFIED login"
specs-driven-cli search "feature_key:AUTH password"

# Complex combinations
specs-driven-cli search '"password reset" kind:AC status:VERIFIED'
specs-driven-cli search "api endpoint kind:NFR status:FAILING"

Advanced Search Features

# Get search syntax help and examples
specs-driven-cli search --explain

# Filter by multiple criteria
specs-driven-cli search "authentication kind:REQUIREMENT status:VERIFIED" --limit 10

REST API Search Endpoints

# POST /api/search with body
{
  "query": "authentication kind:REQUIREMENT",
  "features": ["AUTH", "API"],
  "limit": 20
}

specs-driven-cli search "password security validation" specs-driven-cli search '"performance requirements" kind:NFR'

✨ Advanced: Batch Operations

Execute multiple commands from a file with robust error handling:

# Basic batch execution
specs-driven-cli apply-batch --file operations.txt

# With options
specs-driven-cli apply-batch --file operations.txt --fail-fast --quiet --dry-run

Batch file format (operations.txt):

# Create a feature and its specs
create-feature "Search System" --key SEARCH
create-spec SEARCH REQUIREMENT --content "System must support full-text search" --key REQ-SEARCH-001
create-spec SEARCH AC --content "Search returns results within 500ms" --parent-key REQ-SEARCH-001

Batch options:

• --fail-fast: Stop on first error
• --quiet: Only show summary and errors

Link specs (validates parent is REQUIREMENT, same feature)

specs-driven-cli search "implementation requirements"

Integrity checking

specs-driven-cli verify # Check for cycles, orphans, invalid links specs-driven-cli list-orphans # AC/NFR specs without valid parents

### Output Format Examples

**JSON (default):**
```bash
specs-driven-cli list-specs --feature AUTH --format json

CSV for data analysis:

specs-driven-cli list-specs --feature AUTH --format csv > auth-specs.csv
specs-driven-cli verify --format csv > integrity-issues.csv

System Management

# System and DB
specs-driven-cli health            # Health and database counts
specs-driven-cli status            # System overview with summaries
specs-driven-cli db-path           # Show database path
specs-driven-cli reset-db          # ⚠️ Destructive: clears all data

🌐 REST API

All MCP tools are also available as REST endpoints when running with --dashboard:

Core Endpoints

• GET /features - List features
• POST /features - Create feature
• GET /specs - List specs (with filters)
• POST /specs - Create spec

✨ New Advanced Endpoints

• POST /batch/apply - Execute batch commands
• POST /specs/link - Link child to parent spec
• POST /specs/unlink - Remove parent relationship
• GET /integrity/verify - Check database integrity
• GET /integrity/orphans - List orphaned specs
• GET /integrity/unlinked-acs - List unlinked ACs

All endpoints accept and return JSON. See tool schemas for request/response formats.

🤝 Contributing

## 📋 Specification Types

The system supports three types of specifications:

- **`REQUIREMENT`** - Functional requirements and user stories
- **`AC`** - Acceptance criteria and test conditions  
- **`NFR`** - Non-functional requirements (performance, security, etc.)

## 🏗️ Hierarchical Organization

Organize specifications in parent-child relationships:

Feature: User Authentication ├── REQ-001: Users must authenticate with email/password │ ├── AC-001: Login form validates email format │ ├── AC-002: Password must be at least 8 characters │ └── AC-003: Failed login shows error message └── NFR-001: Login must complete within 2 seconds

## 🔧 Advanced Configuration

### Custom Database Location
```bash
export SPECS_DB="/path/to/shared/project-specs.db"
specs-driven-mcp --stdio

Multiple Projects

Use different database files for different projects:

# Project A
specs-driven-mcp --stdio --db ./project-a-specs.db

# Project B  
specs-driven-mcp --stdio --db ./project-b-specs.db

Port Configuration

# Custom dashboard port
specs-driven-mcp --dashboard --port 3000

📊 Status Tracking

This server uses execution-driven statuses that reflect verification outcomes:

• UNTESTED - No verification events recorded
• FAILING - Last recorded outcome failed/blocked
• PARTIAL - Mixed outcomes across a feature (rolled up)
• VERIFIED - Last recorded outcome passed; all required specs verified

Tip: Use specs-driven-cli ci-help and the /api/events:batch endpoint to update statuses from your test runs.

🗄️ Sample Data

To quickly explore the dashboard and features with realistic test data:

# Install and seed with sample data
npm install -g specs-driven-mcp
npm run seed

# Or for development
git clone https://github.com/tiagomelobr/spec-driven-mcp
npm install && npm run seed

This creates 18 features, 390+ specifications, and 2,600+ verification events to demonstrate:

• Hierarchical requirements with acceptance criteria
• Verification event tracking and status rollup
• Parent-child relationships and orphaned specs
• Feature detail dashboard with interactive event viewing

🤝 Contributing

This project uses specifications-driven development. View the project specs:

specs-driven-cli list-features
specs-driven-cli search "implementation requirements"

For development setup, see .docs/DEVELOPMENT.md.

CI: Verification Events

To auto-update spec and feature status from your test runs:

• Tag tests with [<SPEC_KEY>] in the title (e.g., [AUTH-AC-LOGIN]).
• Publish minimal events to the batch endpoint: POST /api/events:batch.
• Quick commands:
  • CLI help: specs-driven-cli ci-help
  • CLI ingest: specs-driven-cli submit-events ./events.json
• See .docs/CI_INTEGRATION.md for format and adapters.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Repository: https://github.com/tiagomelobr/spec-driven-mcp
• Issues: https://github.com/tiagomelobr/spec-driven-mcp/issues
• NPM Package: https://www.npmjs.com/package/specs-driven-mcp (if published)

🧭 Versioning Policy ⚠️ IMPORTANT

This project uses PATCH version bumps only for all improvements and new features.

• ✅ Patch releases (0.0.x → 0.0.y): New MCP tools, CLI commands, documentation updates, bug fixes, feature improvements
• ❌ Minor releases (0.x.0): Reserved for major architectural changes only
• ❌ Major releases (x.0.0): Breaking changes to MCP protocol or CLI interface

Examples:

• Adding new tools like apply_batch, verify: 0.0.3 → 0.0.4 ✅
• Documentation improvements: 0.0.4 → 0.0.5 ✅
• Bug fixes and enhancements: 0.0.5 → 0.0.6 ✅

This ensures compatibility for AI assistants and automation tools that depend on this MCP server.