# @andrebuzeli/spec-mcp-tools

[![npm version](https://img.shields.io/npm/v/@andrebuzeli/spec-mcp-tools.svg)](https://www.npmjs.com/package/@andrebuzeli/spec-mcp-tools)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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

```bash
npm install -g @andrebuzeli/spec-mcp-tools
```

### IDE Configuration

#### Cursor
```json
{
  "mcpServers": {
    "spec-mcp-tools": {
      "command": "npx",
      "args": ["@andrebuzeli/spec-mcp-tools"]
    }
  }
}
```

#### VSCode
```json
{
  "mcpServers": {
    "spec-mcp-tools": {
      "command": "npx",
      "args": ["@andrebuzeli/spec-mcp-tools"]
    }
  }
}
```

#### Claude Desktop
```json
{
  "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:
```markdown
- [ ] 1. Main task
  - [ ] 1.1 Subtask
    - [ ] 1.1.1 Sub-subtask
- [ ] 2. Another main task
  - [ ] 2.1 Another subtask
```
