/spec-workflow-setup

allowed-tools: Bash, Read, Write, Edit, TodoWrite, WebFetch

Spec-Workflow MCP Server Setup

Complete installation and configuration guide for integrating the spec-workflow MCP (Model Context Protocol) server with Claude Code to enable advanced task management and parallel execution capabilities.

Overview

The spec-workflow MCP server enables Claude to:

• Connect to your project's specification-based workflow system
• Manage tasks with full CRUD operations
• Track task status and dependencies
• Enable parallel task execution with multiple AI agents
• Maintain synchronization between specifications and implementation

Instructions

This command provides a comprehensive setup guide for the spec-workflow MCP server. When executed, follow these steps in order:

1. Check prerequisites (Node.js 18+, npm, Claude Code) 2. Choose an installation method (NPM, GitHub, or Claude Command Suite) 3. Configure the MCP server (using .mcp.json or global settings) 4. Create project-specific configuration files 5. Verify the installation 6. Test the connection with spec-workflow commands

The guide below provides detailed instructions for each step.

Prerequisites

Before installation, ensure you have:

• Node.js 18+ installed
• npm or yarn package manager
• Claude Code with MCP support enabled
• Git for cloning repositories

Installation Methods

Method 1: Direct Installation from NPM (Recommended)

# Install globally
npm install -g @pimzino/spec-workflow-mcp

# Or install locally in your project
npm install --save-dev @pimzino/spec-workflow-mcp

Method 2: Install from GitHub Repository

# Clone the repository
git clone https://github.com/Pimzino/spec-workflow-mcp.git

# Navigate to the directory
cd spec-workflow-mcp

# Install dependencies
npm install

# Build the server
npm run build

# Link globally for use
npm link

Method 3: Install from Claude Command Suite

# Navigate to Claude Command Suite directory
cd Claude-Command-Suite

# Run the spec-workflow installer
./scripts/install-spec-workflow-mcp.sh

Configuration

Step 1: Configure MCP Server (Choose One Method)

Method A: Project-Level Configuration (Recommended)

Create a `.mcp.json` file in your project root. This is the simplest and most portable method:

**Location:** `.mcp.json` (in project root)

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", ".", "--AutoStartDashboard"],
      "env": {}
    }
  }
}

**Quick Setup:**

# Run this command in your project root
./scripts/add-spec-workflow-mcp.sh

# Or manually create the file
cat > .mcp.json << 'EOF'
{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", ".", "--AutoStartDashboard"],
      "env": {}
    }
  }
}
EOF

**Benefits of .mcp.json:**

• Project-specific configuration
• Automatically loaded when Claude Code opens the project
• Can be committed to version control for team consistency
• No global configuration needed

Method B: Global Claude Configuration

Add the spec-workflow server to your global Claude configuration file:

**Location:** `~/.claude/settings.json`

{
  "mcp": {
    "servers": {
      "spec-workflow": {
        "command": "npx",
        "args": ["-y", "@pimzino/spec-workflow-mcp@latest"],
        "env": {
          "SPEC_WORKFLOW_PROJECT_PATH": "${PROJECT_PATH}",
          "SPEC_WORKFLOW_AUTO_SYNC": "true",
          "SPEC_WORKFLOW_LOG_LEVEL": "info"
        }
      }
    }
  }
}

Step 2: Project-Specific Configuration

Create a `.spec-workflow.json` file in your project root:

{
  "version": "1.0.0",
  "project": {
    "name": "My Project",
    "description": "Project using spec-workflow for task management"
  },
  "specifications": {
    "directory": "./specifications",
    "pattern": "**/*.spec.md",
    "autoDiscovery": true
  },
  "tasks": {
    "directory": "./tasks",
    "statuses": ["todo", "in_progress", "review", "qa", "completed", "blocked"],
    "defaultStatus": "todo",
    "trackDependencies": true
  },
  "agents": {
    "maxParallel": 4,
    "autoAssign": true,
    "conflictResolution": "abort"
  },
  "sync": {
    "github": {
      "enabled": false,
      "repository": "owner/repo",
      "labelMapping": {
        "todo": "task:todo",
        "in_progress": "task:in-progress",
        "completed": "task:done"
      }
    },
    "linear": {
      "enabled": false,
      "teamId": "TEAM_ID",
      "projectId": "PROJECT_ID"
    }
  }
}

Step 3: Environment Variables

Set up environment variables for the MCP server:

# Add to ~/.bashrc, ~/.zshrc, or equivalent
export SPEC_WORKFLOW_PROJECT_PATH="$HOME/projects"
export SPEC_WORKFLOW_AUTO_SYNC="true"
export SPEC_WORKFLOW_LOG_LEVEL="info"
export SPEC_WORKFLOW_CACHE_DIR="$HOME/.cache/spec-workflow"

Verification

Test MCP Server Connection

After configuration, verify the connection:

# Start Claude Code
claude code

# In Claude, test the connection
/spec-workflow:test-connection

Expected output:

✅ Spec-Workflow MCP Server Connected
Version: 1.0.0
Project: My Project
Specifications Found: 5
Tasks Available: 23
Status: Ready

List Available Specifications

# In Claude Code
/spec-workflow:list-specs

Check Task Status

# In Claude Code
/spec-workflow:task-status

Usage Examples

Basic Task Management

# List all tasks in a specification
/spec-workflow:list-tasks --spec-name user-authentication

# Create a new task
/spec-workflow:create-task --spec-name payment-integration --description "Implement Stripe webhook handling"

# Update task status
/spec-workflow:update-task --task-id TASK-001 --status in_progress

# Assign task to agent
/spec-workflow:assign-task --task-id TASK-001 --agent typescript-pro

Parallel Task Execution

# Execute tas