@andrebuzeli/spec-mcp-tools

Universal MCP server for spec-driven development - designed to work with any IDE that supports the Model Context Protocol (MCP).

🌐 Universal IDE Compatibility

This MCP server is engineered for maximum compatibility across all MCP-supporting IDEs:

• ✅ Cursor AI - Full native support
• ✅ VSCode - Works with MCP extensions
• ✅ Kiro - Optimized compatibility
• ✅ Claude Desktop - Complete integration
• ✅ TRAE AI - Full functionality
• ✅ Any MCP-compatible IDE - Universal protocol compliance

🧪 Compatibilidade Testada

| IDE | Status | Versão Testada | Notas | |-----|--------|----------------|-------| | Cursor AI | ✅ Full | 0.x | Nativa | | VSCode | ✅ Full | 1.x | Via extensão MCP | | Kiro | ✅ Full | 1.x | Otimizada | | Claude Desktop | ✅ Full | 1.x | Completa | | TRAE AI | ✅ Full | 1.x | Total |

🔧 Troubleshooting por IDE

Cursor AI:

• Configuração nativa no settings.json
• Reiniciar Cursor após mudanças de configuração
• Verificar logs em Developer Tools

VSCode:

• Instalar extensão MCP oficial
• Configurar em settings.json do workspace
• Verificar se MCP server está rodando

Kiro:

• Compatibilidade otimizada para Spec-Driven Development
• Usar arquivos de steering para melhor integração
• Configuração automática detectada

Claude Desktop:

• Configuração em claude_desktop_config.json
• Reiniciar Claude Desktop após mudanças
• Verificar permissões de arquivo

TRAE AI:

• Suporte completo a todas as tools
• Configuração via interface web
• Logs disponíveis no dashboard

✨ Features

• 5 Tools: Complete spec-driven development workflow
• 4 Markdown Files: Structured documentation in .spec/ folder
• 5 Resources: Template access and usage documentation
• 2 Prompts: Automated project start and status checking
• Auto-Initialization: Any tool automatically creates .spec/ directory if needed
• Hierarchical Tasks: Support for 1, 1.1, 1.2, 2, 2.1 style task breakdown
• EARS Requirements: Easy Approach to Requirements Syntax validation
• Universal Compatibility: Engineered to work with ANY MCP-compatible IDE
• Environment Detection: Automatically adapts to different IDE environments
• Robust Error Handling: Graceful fallbacks for maximum compatibility

📁 Project Structure

.spec/
├── project.md          # Project overview and configuration
├── requirements.md     # EARS format requirements
├── design.md          # Technical design and architecture
└── tasks.md           # Hierarchical task breakdown

🛠️ Available Tools

1. spec-project

Purpose: Initialize and manage spec project structure

• create - Initialize new .spec/ directory and project.md (project name extracted from path)
• status - Check current project status

2. spec-archive

Purpose: Archive current spec files

• Archive current specs to timestamped archive folder

3. spec-requirements

Purpose: Generate and manage requirements.md with EARS format

• create - Create requirements from parameters
• createBatch - Create multiple requirements (batch)
• update - Update existing requirements
• validate - Validate EARS format compliance
• enhance-ears - Generate automatic EARS format suggestions

4. spec-design

Purpose: Generate and manage technical design.md

• generate - Create design based on requirements
• update - Update design specifications
• validate - Validate design consistency

5. spec-tasks

Purpose: Generate and manage hierarchical tasks.md (1, 1.1, 1.2, 2, etc.)

• create - Create single task
• createBatch - Create multiple tasks (batch)
• update - Update task status (pending/in-progress/completed)
• add-subtask - Add subtasks to existing tasks
• reorder - Reorder tasks
• list - List all tasks with status

📚 Available Resources

Templates

• spec://templates/project.md - Project overview template
• spec://templates/requirements.md - Requirements specification template
• spec://templates/design.md - Technical design template
• spec://templates/tasks.md - Hierarchical tasks template

Documentation

• spec://docs/usage.md - Complete usage guide and examples

🎯 Available Prompts

spec-start

Purpose: Start a new spec project - auto-archives existing specs, analyzes requirements, and generates all 4 .md files

Arguments:

• description (required) - Description of what to build

What it does:

1. Auto-detects current project path
2. Auto-archives existing specs if any exist
3. Creates temporary analysis tasks for planning
4. Generates all 4 .md files (project, requirements, design, tasks)
5. Cleans up temporary files

Example:

Use spec-start with description="Build a task management app with user authentication"

spec-status

Purpose: Show current spec status - total tasks and pending tasks with titles

Arguments: None (auto-detects current project)

What it shows:

• Total number of tasks
• Number of completed, in-progress, and pending tasks
• List of pending task titles
• List of tasks currently in progress

Example:

Use spec-status

🚀 Quick Start

Installation

npm install -g @andrebuzeli/spec-mcp-tools

IDE Configuration

Cursor

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

VSCode

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

Claude Desktop

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

📋 Workflow Example

1. Start New Project

   Use spec-start with description="Build a task management app with user authentication"

2. Check Status

   Use spec-status to see current progress

3. Update Tasks as You Work

   Use spec-tasks update with taskId="1" and status="completed"
   Use spec-tasks update with taskId="2" and status="in-progress"

4. Archive When Complete

   Use spec-archive with archiveName="v1.0-complete" to save current specs

Note: All tools automatically initialize the .spec/ directory if it doesn't exist, so you can start with any tool!

🎯 EARS Requirements Format

Requirements use the EARS (Easy Approach to Requirements Syntax):

• WHEN [condition] THEN [system] SHALL [response]
• GIVEN [context] WHEN [action] THEN [system] SHALL [response]
• WHERE [scope] IF [condition] THEN [system] SHALL [response]

📝 Task Hierarchy Format

Tasks support unlimited nesting:

- [ ] 1. Main task
  - [ ] 1.1 Subtask
    - [ ] 1.1.1 Sub-subtask
- [ ] 2. Another main task
  - [ ] 2.1 Another subtask