spec-workflow-mcp Documentation

Technical Documentation: Pimzino/spec-workflow-mcp

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Spec Workflow MCP

I HAVE TAKEN A SMALL BREAK FROM THIS REPO FOR PERSONAL REASONS BUT I WILL BE BACK WITH SOME UPDATES IN THE NEAR FUTURE
THANK YOU FOR YOUR UNDERSTANDING

A Model Context Protocol (MCP) server for structured spec-driven development with real-time dashboard and VSCode extension.

☕ Support This Project Copy Chapter

📺 Showcase Copy Chapter

🔄 Approval System in Action Copy Section

See how the approval system works: create documents, request approval through the dashboard, provide feedback, and track revisions.

📊 Dashboard & Spec Management Copy Section

Explore the real-time dashboard: view specs, track progress, navigate documents, and monitor your development workflow.

✨ Key Features Copy Chapter

• Structured Development Workflow - Sequential spec creation (Requirements → Design → Tasks)
• Real-Time Web Dashboard - Monitor specs, tasks, and progress with live updates
• VSCode Extension - Integrated sidebar dashboard for VSCode users
• Approval Workflow - Complete approval process with revisions
• Task Progress Tracking - Visual progress bars and detailed status
• Implementation Logs - Searchable logs of all task implementations with code statistics
• Multi-Language Support - Available in 11 languages

🌍 Supported Languages Copy Chapter

🇺🇸 English • 🇯🇵 日本語 • 🇨🇳 中文 • 🇪🇸 Español • 🇧🇷 Português • 🇩🇪 Deutsch • 🇫🇷 Français • 🇷🇺 Русский • 🇮🇹 Italiano • 🇰🇷 한국어 • 🇸🇦 العربية

📖 Documentation in your language:

English | 日本語 | 中文 | Español | Português | Deutsch | Français | Русский | Italiano | 한국어 | العربية

🚀 Quick Start Copy Chapter

Step 1: Add to your AI tool Copy Section

Add to your MCP configuration (see client-specific setup below):

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

Step 2: Choose your interface Copy Section

Option A: Web Dashboard (Required for CLI users)
Start the dashboard (runs on port 5000 by default):

npx -y @pimzino/spec-workflow-mcp@latest --dashboard

The dashboard will be accessible at: http://localhost:5000

Note: Only one dashboard instance is needed. All your projects will connect to the same dashboard.

Option B: VSCode Extension (Recommended for VSCode users)

Install Spec Workflow MCP Extension from the VSCode marketplace.

📝 How to Use Copy Chapter

Simply mention spec-workflow in your conversation:

• "Create a spec for user authentication" - Creates complete spec workflow
• "List my specs" - Shows all specs and their status
• "Execute task 1.2 in spec user-auth" - Runs a specific task

See more examples →

🔧 MCP Client Setup Copy Chapter

Augment Code

Configure in your Augment settings:

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

Claude Code CLI

Add to your MCP configuration:

claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project

Important Notes:

• The -y flag bypasses npm prompts for smoother installation
• The -- separator ensures the path is passed to the spec-workflow script, not to npx
• Replace /path/to/your/project with your actual project directory path

Alternative for Windows (if the above doesn't work):

claude mcp add spec-workflow cmd.exe /c "npx @pimzino/spec-workflow-mcp@latest /path/to/your/project"

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

Important: Run the dashboard separately with --dashboard before starting the MCP server.

Cline/Claude Dev

Add to your MCP server configuration:

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

Continue IDE Extension

Add to your Continue configuration:

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

Cursor IDE

Add to your Cursor settings (settings.json):

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

OpenCode

Add to your opencode.json configuration file:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "spec-workflow": {
      "type": "local",
      "command": ["npx", "-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"],
      "enabled": true
    }
  }
}

Windsurf

Add to your ~/.codeium/windsurf/mcp_config.json configuration file:

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

Codex

Add to your ~/.codex/config.toml configuration file:

[mcp_servers.spec-workflow]
command = "npx"
args = ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]

🐳 Docker Deployment Copy Chapter

Run the dashboard in a Docker container for isolated deployment:

# Using Docker Compose (recommended)
cd containers
docker-compose up --build

# Or using Docker CLI
docker build -f containers/Dockerfile -t spec-workflow-mcp .
docker run -p 5000:5000 -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" spec-workflow-mcp

The dashboard will be available at: http://localhost:5000

See Docker setup guide →

🔒 Security Copy Chapter

Spec-Workflow MCP includes enterprise-grade security features suitable for corporate environments:

✅ Implemented Security Controls Copy Section

⚠️ Not Yet Implemented Copy Section

For External/Network Access Copy Section

If you need to expose the dashboard beyond localhost, we recommend:

1. Keep dashboard on localhost (127.0.0.1)
2. Use nginx or Apache as a reverse proxy with:
   • TLS/HTTPS termination
   • Basic authentication or OAuth2
3. Configure firewall rules to restrict access

# Example nginx reverse proxy with auth
server {
    listen 443 ssl;
    server_name dashboard.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    auth_basic "Dashboard Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
    
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

See Docker security guide →

🔒 Sandboxed Environments Copy Chapter

For sandboxed environments (e.g., Codex CLI with sandbox_mode=workspace-write) where $HOME is read-only, use the SPEC_WORKFLOW_HOME environment variable to redirect global state files to a writable location:

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

See Configuration Guide →

📚 Documentation Copy Chapter

• Configuration Guide - Command-line options, config files
• User Guide - Comprehensive usage examples
• Workflow Process - Development workflow and best practices
• Interfaces Guide - Dashboard and VSCode extension details
• Prompting Guide - Advanced prompting examples
• Tools Reference - Complete tools documentation
• Development - Contributing and development setup
• Troubleshooting - Common issues and solutions

📁 Project Structure Copy Chapter

your-project/
  .spec-workflow/
    approvals/
    archive/
    specs/
    steering/
    templates/
    user-templates/
    config.example.toml

🛠️ Development Copy Chapter

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

See development guide →

📄 License Copy Chapter

GPL-3.0

⭐ Star History Copy Chapter

Overview (`containers/README.md`) Copy Section

Spec-Workflow MCP Docker Setup

This directory contains Docker configuration files to run the Spec-Workflow MCP dashboard in a containerized environment. This setup provides isolation and easy deployment for the dashboard service.

📋 Table of Contents Copy Chapter

• Prerequisites
• Quick Start
• Testing the Docker Image
• Building the Image
• Running the Dashboard
• Using Docker Compose
• Configuration Options
• Security Configuration
• Troubleshooting

Prerequisites Copy Chapter

• Docker (version 20.10 or later)
• Docker Compose (optional, for simplified management)
• A project directory where you want to use spec-workflow

Quick Start Copy Chapter

Option 1: Using Docker Compose (Recommended) Copy Section

The easiest way to get started is with Docker Compose:

# From the repository root
cd containers
docker-compose up --build

The dashboard will be available at: http://localhost:5000

Option 2: Using Docker CLI Copy Section

Build and run manually:

# From the repository root
docker build -f containers/Dockerfile -t spec-workflow-mcp .
docker run -p 5000:5000 -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" spec-workflow-mcp

Testing the Docker Image Copy Chapter

A comprehensive test script is provided to validate the Docker image configurations:

# From the containers directory
./test-docker.sh

The test script validates:

Running Individual Tests Copy Section

You can also manually test specific configurations:

# Test default Docker config (localhost-only access)
docker run --rm \
  -p 127.0.0.1:5000:5000 \
  spec-workflow-mcp
# Expected: Dashboard starts, accessible only from host machine

# Test network access (exposes to all interfaces)
docker run --rm \
  -p 5000:5000 \
  spec-workflow-mcp
# Expected: Dashboard starts with security warning

# Test app-level security check (override Docker defaults)
docker run --rm \
  -e SPEC_WORKFLOW_ALLOW_EXTERNAL_ACCESS=false \
  spec-workflow-mcp
# Expected: SECURITY ERROR (app blocks external binding)

Building the Image Copy Chapter

Build from Repository Root Copy Section

Important: The Dockerfile must be built from the repository root directory, not from the containers directory, because it needs access to the source code.

# From the repository root
docker build -f containers/Dockerfile -t spec-workflow-mcp .

Build Arguments Copy Section

The image is built in two stages:

1. Builder stage: Installs dependencies and builds the TypeScript application
2. Runtime stage: Creates a minimal production image with only necessary files

Running the Dashboard Copy Chapter

Basic Usage Copy Section

Run the dashboard on the default port (5000):

docker run -p 5000:5000 \
  -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

Custom Port Copy Section

Run the dashboard on a custom port (e.g., 8080):

docker run -p 8080:8080 \
  -e DASHBOARD_PORT=8080 \
  -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

Using a Specific Project Path Copy Section

Mount your project's .spec-workflow directory:

docker run -p 5000:5000 \
  -v "/path/to/your/project/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

Using Docker Compose Copy Chapter

Docker Compose simplifies the management of the dashboard container.

Default Configuration Copy Section

Create a .env file (optional):

# .env file
DASHBOARD_PORT=5000
SPEC_WORKFLOW_PATH=./workspace

Then start the dashboard:

cd containers
docker-compose up -d

Custom Configuration Copy Section

Override environment variables when starting:

DASHBOARD_PORT=8080 SPEC_WORKFLOW_PATH=/path/to/project docker-compose up -d

Managing the Service Copy Section

# Start the dashboard
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the dashboard
docker-compose down

# Rebuild and restart
docker-compose up --build

Configuration Options Copy Chapter

Environment Variables Copy Section

Volume Mounts Copy Section

The dashboard requires access to the .spec-workflow directory to function properly.

Example:

-v "/path/to/project/.spec-workflow:/workspace/.spec-workflow:rw"

Important Notes:

• The volume mount must be read-write (:rw) for the dashboard to function
• Only the .spec-workflow directory needs to be mounted
• The directory will be created automatically if it doesn't exist

Port Mapping Copy Section

Map the container port to a host port:

-p <host-port>:<container-port>

Examples:

• Default: -p 5000:5000
• Custom: -p 8080:8080 (remember to set DASHBOARD_PORT=8080)

Security Configuration Copy Chapter

The Docker image includes several security features that are enabled by default.

Docker Networking Model Copy Section

In Docker, the application binds to 0.0.0.0 inside the container (required for Docker's port forwarding to work). Security is controlled by Docker's port mapping, not by the application's bind address.

Option 1: Localhost Only (Secure Default)

The default docker-compose.yml uses localhost-only port mapping:

ports:
  - "127.0.0.1:5000:5000"  # Only accessible from host machine

Or with Docker CLI:

docker run -p 127.0.0.1:5000:5000 \
  -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

✅ This is the recommended configuration. The dashboard is only accessible from your local machine.

Option 2: Network Access (Use with Caution)

To allow access from other machines on your network, use DASHBOARD_HOST=0.0.0.0:

With Docker Compose (recommended):

# Expose to all network interfaces
DASHBOARD_HOST=0.0.0.0 docker-compose up

# Or bind to a specific IP
DASHBOARD_HOST=192.168.1.100 docker-compose up

With Docker CLI:

docker run -p 0.0.0.0:5000:5000 \
  -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

# Or bind to a specific IP
docker run -p 192.168.1.100:5000:5000 \
  -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

⚠️ Security Warning: This exposes the dashboard to your network. The application will display a security warning in the logs. Only use when necessary and ensure proper network security measures (firewall, VPN) are in place.

Rate Limiting Copy Section

Rate limiting protects against abuse and DoS attacks. It's enabled by default (120 requests/minute per client).

# Disable rate limiting (not recommended)
docker run -e SPEC_WORKFLOW_RATE_LIMIT_ENABLED=false spec-workflow-mcp

Docker Compose Security Settings Copy Section

The provided docker-compose.yml includes additional security hardening:

# Read-only root filesystem
read_only: true

# Drop all Linux capabilities
cap_drop:
  - ALL

# Prevent privilege escalation
security_opt:
  - no-new-privileges:true

# Resource limits (prevent DoS)
deploy:
  resources:
    limits:
      cpus: '1.0'
      memory: 512M

Security Best Practices Copy Section

1. Use localhost port mapping when possible (127.0.0.1:5000:5000)
2. Never expose to public internet without proper authentication/firewall
3. Keep rate limiting enabled in production
4. Use the provided docker-compose.yml for security hardening
5. Run as non-root user (default in the image)
6. Mount volumes read-write only when necessary

Audit Logging Copy Section

All API requests are logged to a structured JSON audit log for compliance and debugging.

Log Location: /.spec-workflow/audit.log

Log Format:

{
  "timestamp": "2025-12-06T10:30:45.123Z",
  "actor": "127.0.0.1",
  "action": "GET /api/projects/list",
  "resource": "/api/projects/list",
  "result": "success",
  "details": {
    "statusCode": 200,
    "duration": 45,
    "userAgent": "Mozilla/5.0..."
  }
}

Viewing Logs:

# View recent logs
tail -f .spec-workflow/audit.log

# Parse as JSON (requires jq)
cat .spec-workflow/audit.log | jq '.'

# Filter by result
cat .spec-workflow/audit.log | jq 'select(.result == "denied")'

External Access with Authentication Copy Section

The dashboard does not include built-in authentication. For external access, use a reverse proxy:

Option 1: nginx with Basic Auth

server {
    listen 443 ssl;
    server_name dashboard.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    auth_basic "Dashboard Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
    
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Option 2: OAuth2 Proxy (for SSO)

oauth2-proxy \
  --upstream=http://127.0.0.1:5000 \
  --http-address=0.0.0.0:4180 \
  --provider=google \
  --client-id=YOUR_CLIENT_ID \
  --client-secret=YOUR_CLIENT_SECRET

MCP Server Configuration Copy Chapter

The dashboard runs independently of MCP servers. To connect MCP servers to the dashboard:

For Claude Desktop Copy Section

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

Note: The MCP server runs on your host machine and connects to the Docker dashboard automatically via port 5000.

For Other MCP Clients Copy Section

Use similar configuration with the appropriate MCP client settings. The MCP servers run independently and connect to the dashboard's WebSocket endpoint.

Troubleshooting Copy Chapter

Common Issues Copy Section

1. Port Already in Use

Error: Bind for 0.0.0.0:5000 failed: port is already allocated

Solution: Use a different port:

docker run -p 8080:8080 -e DASHBOARD_PORT=8080 ...
# or with docker-compose
DASHBOARD_PORT=8080 docker-compose up

2. Permission Denied

Error: Permission issues with .spec-workflow directory

Solutions:

• Ensure the directory has proper permissions: chmod -R 755 .spec-workflow
• On SELinux systems, add :z to the volume mount: -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw,z"

3. Dashboard Not Accessible

Check:

• Container is running: docker ps
• Port is properly mapped: docker port <container-id>
• Firewall allows connections on the port
• Access via: http://localhost:5000 (or your custom port)

4. Build Fails

Error: Build fails with COPY or dependency errors

Solutions:

• Ensure you're building from the repository root: docker build -f containers/Dockerfile -t spec-workflow-mcp .
• Check that all source files are present
• Verify package.json and package-lock.json exist

Viewing Logs Copy Section

Docker CLI

docker logs <container-id>
docker logs -f <container-id>  # Follow logs

Docker Compose

docker-compose logs
docker-compose logs -f  # Follow logs

Inspecting the Container Copy Section

# View container details
docker inspect <container-id>

# Access container shell
docker exec -it <container-id> /bin/sh

Advanced Configuration Copy Chapter

Running in Detached Mode Copy Section

docker run -d \
  --name spec-workflow-dashboard \
  -p 5000:5000 \
  -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

Auto-Restart on Failure Copy Section

docker run -d \
  --name spec-workflow-dashboard \
  --restart unless-stopped \
  -p 5000:5000 \
  -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

Health Checks Copy Section

The dashboard doesn't currently include health checks, but you can test connectivity:

curl http://localhost:5000

Security Considerations Copy Chapter

The Docker image implements enterprise-grade security controls:

Best Practices:

• Keep the base image updated: docker pull node:24-alpine
• Use read-only volume mounts where possible (:rw required for .spec-workflow)
• For network access, always use a reverse proxy with TLS and authentication
• Review audit logs regularly for security monitoring

Performance Tips Copy Chapter

• The container is optimized for production with:

  • Multi-stage builds to minimize image size
  • Only production dependencies in final image
  • Alpine Linux for small footprint

• Monitor resource usage:

  bash Copy

  docker stats <container-id>

Additional Resources Copy Chapter

• Main Documentation
• User Guide
• Troubleshooting Guide
• GitHub Repository

Support Copy Chapter

If you encounter issues:

1. Check the Troubleshooting section
2. Review logs: docker logs <container-id>
3. Open an issue on GitHub
4. Include:
   • Docker version: docker --version
   • Operating system
   • Error messages
   • Steps to reproduce

Overview (`vscode-extension/README.md`) Copy Section

Spec Workflow MCP Extension

A VSCode extension that provides an integrated dashboard for managing Spec-Workflow MCP projects directly in your workspace.

Features Copy Chapter

• Integrated Sidebar Dashboard: Access all your spec workflow data without leaving VSCode
• Real-time Updates: File system watchers automatically update the dashboard when .spec-workflow files change
• Project Overview: Comprehensive statistics showing active vs archived specs, tasks, and approvals
• Spec Management: Browse active and archived specifications with easy archiving/unarchiving
• Task Management: View and update task statuses directly from the sidebar
• Approval Workflow: Complete approval process with approve, reject, and revision requests
• Steering Documents: Manage product, tech, and structure steering documents
• Sound Notifications: Configurable audio alerts for approvals and task completions
• Editor Integration: Context menu actions for approvals and comments directly in code
• React + Tailwind UI: Modern, responsive interface built with React 19 and Tailwind CSS v4

Requirements Copy Chapter

• VSCode 1.99.0 or higher
• A workspace containing a .spec-workflow directory structure

Usage Copy Chapter

1. Open a workspace that contains a .spec-workflow directory
2. The Spec Workflow MCP icon will appear in the Activity Bar
3. Click the icon to open the dashboard sidebar
4. Use the tabbed interface to navigate between:
   • Overview: Project statistics showing active/archived specs breakdown and recent activity
   • Steering: Manage steering documents (product, tech, structure)
   • Specs: Browse active and archived specifications with archive management
   • Tasks: View and manage task progress for selected specifications
   • Approvals: Handle pending approval requests with full workflow support

Archive Management Copy Chapter

Specifications can be archived to keep dropdown menus clean and organized:

• Switch between Active and Archived views in the Specs tab
• Archive completed specifications to remove them from active dropdowns
• Unarchive specifications when needed
• Archive operations are blocked if pending approvals exist for the specification

Commands Copy Chapter

• Spec Workflow: Open Dashboard - Opens the sidebar dashboard
• Spec Workflow: Refresh Data - Manually refresh all data
• Spec Workflow: Open Spec - Quick pick to open specific specifications
• Spec Workflow: Approve - Approve current document (editor context)
• Spec Workflow: Reject - Reject current document (editor context)
• Spec Workflow: Request Revision - Request revision for current document
• Spec Workflow: Add Comment - Add comment to selected text
• Spec Workflow: Approval Actions - Show approval action menu

Extension Settings Copy Chapter

• specWorkflow.notifications.sounds.enabled - Enable sound notifications (default: true)
• specWorkflow.notifications.sounds.volume - Sound volume level 0.0-1.0 (default: 0.3)
• specWorkflow.notifications.sounds.approvalSound - Play sound for approval requests (default: true)
• specWorkflow.notifications.sounds.taskCompletionSound - Play sound for task completions (default: true)

Development Copy Chapter

This extension is built with:

• React 19 with TypeScript
• Vite for webview bundling
• Tailwind CSS v4 for styling
• ShadCN UI components
• VSCode Extension API

Release Notes Copy Chapter

0.0.1 Copy Section

Initial release of Spec Workflow MCP Extension:

• Dashboard Integration: Complete sidebar dashboard with real-time updates
• Specification Management: Active/archived spec organization with archive workflow
• Task Tracking: Interactive task management with status updates
• Approval System: Full approval workflow with approve/reject/revision capabilities
• Steering Documents: Product, tech, and structure document management
• Sound Notifications: Configurable audio alerts for key events
• Editor Integration: Context menu actions and comment system
• Modern UI: React 19 + Tailwind CSS v4 with responsive design

Support Copy Chapter

If you find this extension helpful, consider supporting the development:

☕ Buy Me a Coffee

License Copy Chapter

This project is licensed under the GPL-3.0 License.

Overview (`docs/technical-documentation/README.md`) Copy Section

Technical Documentation

Quick Reference: Jump to what you need most → Tools API | Architecture | Developer Guide | Troubleshooting

📋 Table of Contents Copy Chapter

Core Documentation Copy Section

• Architecture Overview - System design, components, and data flow
• MCP Tools API Reference - Complete tool documentation with examples
• Developer Workflow Guide - Step-by-step development workflows
• Context Management - How context switching and caching works
• File Structure - Project organization and directory layout
• Dashboard System - Web dashboard and real-time features
• Troubleshooting & FAQ - Common issues and solutions

Quick Start Guides Copy Section

• Setting Up Development Environment - Get up and running quickly
• Contributing Guidelines - How to contribute to the project
• Testing Guide - Running tests and writing new ones

🚀 Quick Start Copy Chapter

For AI Assistant Integration Copy Section

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/project"]
    }
  }
}

Note: To use the dashboard, start it separately in a terminal:

npx -y @pimzino/spec-workflow-mcp@latest --dashboard

For Local Development Copy Section

# Clone and setup
git clone <repository-url>
cd spec-workflow-mcp
npm install

# Start development server
npm run dev

# Build for production  
npm run build

🔍 Comprehensive Capability Analysis Copy Chapter

Critical Questions Answered Copy Section

Based on comprehensive codebase analysis, here are definitive answers to key technical questions:

**Question 1: Web Scraping & Research Capabilities**

Answer: No independent web scraping - leverages LLM's built-in web search

**Question 2: AI Calls & Context Window Management**

Answer: Pure MCP - uses only connected LLM, no independent AI calls

**Question 3: Document Planning Process**

Answer: Template-guided LLM intelligence - no separate AI planning

**Question 4: Auto Review Process**

Answer: Human-only approval system - no automated AI review

**Question 5: Best Practice Standards**

Answer: LLM built-in knowledge - no external standards fetching

Competitive Positioning Analysis Copy Section

Strengths vs Other AI Agents:

interface CompetitiveAdvantages {
  humanOversight: "Mandatory approval prevents runaway AI behavior";
  llmLeverage: "Uses full power of connected LLM without limitations";
  structuredOutput: "Templates ensure consistent, professional documentation";
  realTimeUI: "Dashboard and VS Code integration for seamless workflow";
  simplicity: "No complex setup or API key management required";
  reliability: "Proven workflow sequence with validation and error handling";
}

Current Limitations vs Market Leaders:

interface LimitationsAnalysis {
  automationLevel: "Less automated than fully autonomous agents";
  integrationEcosystem: "Limited external service integrations";
  multiProject: "Single project scope vs enterprise-wide solutions";
  aiDiversity: "Single LLM vs multi-model approaches";
  workflowFlexibility: "Fixed sequence vs adaptive workflows";
}

Expansion Opportunities Identified:

interface ExpansionRoadmap {
  immediateWins: {
    githubIntegration: "PR creation, issue sync, code analysis";
    qualityGates: "Optional automated quality checks";
    templateDynamism: "Project-type aware template selection";
  };
  
  mediumTerm: {
    multiProjectSupport: "Enterprise dashboard for multiple projects";
    advancedIntegrations: "Jira, Confluence, Slack notifications";
    workflowCustomization: "Configurable workflow sequences";
  };
  
  longTerm: {
    aiOrchestration: "Multi-agent coordination capabilities";
    predictiveAnalytics: "Project success prediction and risk analysis";
    enterpriseFeatures: "SSO, compliance, audit trails";
  };
}

⚠️ Technical Limitations & Capabilities Copy Chapter

What This MCP Does NOT Do Copy Section

No Independent External Calls:

• ❌ No separate web scraping or API calls by the MCP server
• ❌ No independent external research by the MCP server
• ❌ No direct calls to AI services from the MCP server
• ✅ Leverages connected LLM's built-in web search and knowledge

No Separate AI Service Integration:

• ❌ No additional calls to OpenAI, Anthropic, or other AI services
• ❌ No independent AI processing outside the connected LLM
• ❌ No separate AI models or services
• ✅ Uses only the LLM provided through MCP connection

No Context Window Management:

• ❌ Does not extend or manage AI client context windows
• ❌ No conversation history or memory management
• ❌ No cross-session AI context preservation
• ✅ Provides structured project data for AI client consumption

Human-Only Approval System:

• ❌ No automated AI-powered document review
• ❌ No AI-based approval recommendations
• ❌ Verbal approval not accepted
• ✅ All approvals require dashboard or VS Code interaction

What This MCP Excels At Copy Section

Leveraging LLM Built-in Capabilities:

• ✅ Provides structured templates for LLM to fill with intelligent content
• ✅ Supplies project context for LLM analysis and understanding
• ✅ Enables LLM to use its built-in knowledge for best practices
• ✅ Allows LLM to perform web research when generating content

Structured Workflow Enforcement:

• ✅ Enforces spec-driven development sequence
• ✅ Template-based document structure for consistent LLM output
• ✅ Workflow validation and blocking
• ✅ Human oversight integration for LLM-generated content

Intelligent Project Data Management:

• ✅ Efficient context loading for LLM consumption
• ✅ Real-time file watching and updates
• ✅ Cross-platform path handling
• ✅ Structured project organization that LLM can understand

Enhanced Developer Experience:

• ✅ Web dashboard for reviewing LLM-generated content
• ✅ VS Code extension integration
• ✅ Real-time WebSocket updates
• ✅ Comprehensive error handling

🎯 Key Concepts Copy Chapter

MCP Tools Copy Section

The server provides 12 MCP tools for spec-driven development:

• Workflow Tools: spec-workflow-guide, steering-guide
• Content Tools: create-spec-doc, create-steering-doc, get-template-context
• Search Tools: get-spec-context, get-steering-context, spec-list
• Status Tools: spec-status, manage-tasks
• Approval Tools: request-approval, get-approval-status, delete-approval

File Organization Copy Section

.spec-workflow/
├── specs/           # Specification documents
├── steering/        # Project guidance documents
├── approvals/       # Approval workflow data
└── archive/         # Archived specifications

Workflow Phases Copy Section

1. Requirements → 2. Design → 3. Tasks → 4. Implementation

Each phase requires approval before proceeding to the next.

🔧 Development Workflow Copy Chapter

Adding a New MCP Tool Copy Section

1. Create tool file in src/tools/
2. Export tool definition and handler
3. Register in src/tools/index.ts
4. Update API documentation
5. Add tests

Dashboard Development Copy Section

# Start dashboard in development mode
npm run dev:dashboard

# Build dashboard assets
npm run build:dashboard

VSCode Extension Development Copy Section

cd vscode-extension
npm install
npm run compile
# Press F5 in VSCode to launch extension host

📚 Documentation Standards Copy Chapter

• Code Examples: Always include working examples
• Error Handling: Document expected error conditions
• Performance: Note any performance considerations
• Security: Highlight security implications
• Breaking Changes: Mark breaking changes clearly

🤝 Getting Help Copy Chapter

1. Check the Troubleshooting Guide first
2. Search existing GitHub Issues
3. Create a new issue with detailed reproduction steps
4. Join the community for real-time support

📊 Technical Architecture Summary Copy Chapter

Pure MCP Server Design Copy Section

This project implements a pure Model Context Protocol (MCP) server that:

Key Files & Implementation Copy Section

• MCP Tools: src/tools/*.ts - 13 tools for workflow management
• Templates: src/markdown/templates/*.md - Static document structures
• Approval System: src/dashboard/approval-storage.ts - Human-only review
• Context Loading: src/core/*.ts - File-based context structuring
• Web Dashboard: src/dashboard_frontend/ - React-based approval UI

Performance Characteristics Copy Section

• Memory Usage: 50KB templates + 10-100KB per spec context
• File System: Local .spec-workflow/ directory only
• Network: Localhost dashboard + NPM version check
• Scaling: Linear per project, 50-100 specs recommended
• Security: Local-only, no external data transmission

📊 Market Analysis & Strategic Insights Copy Chapter

Competitive Landscape Analysis Copy Section

Category 1: Autonomous AI Agents (e.g., AutoGPT, LangChain Agents)

interface AutonomousAgents {
  capabilities: {
    webScraping: "Advanced - Custom scrapers, API integrations";
    aiCalls: "Multiple models, specialized AI services";
    automation: "Fully autonomous operation";
    integrations: "Extensive third-party ecosystem";
  };
  
  limitations: {
    humanOversight: "Limited or optional";
    reliability: "Can go off-track or produce errors";
    complexity: "Complex setup, API management";
    cost: "High due to multiple AI calls";
  };
  
  differentiator: "Full automation vs structured human-guided workflow";
}

Category 2: Development Workflow Tools (e.g., GitHub Copilot, Cursor)

interface DevelopmentTools {
  capabilities: {
    codeGeneration: "Excellent within editors";
    contextAwareness: "Good for code context";
    realTimeAssistance: "Integrated development support";
    aiPowered: "Built-in LLM capabilities";
  };
  
  limitations: {
    workflowStructure: "Limited structured spec processes";
    documentationFocus: "Code-centric, not spec-driven";
    approvalProcess: "No formal review workflows";
    projectPlanning: "Limited high-level planning";
  };
  
  differentiator: "Code-first vs spec-driven development approach";
}

Category 3: Project Management + AI (e.g., Notion AI, Linear)

interface ProjectManagementAI {
  capabilities: {
    projectTracking: "Excellent project organization";
    collaboration: "Team coordination features";
    aiAssistance: "AI-powered content generation";
    integration: "Extensive third-party connections";
  };
  
  limitations: {
    technicalDepth: "Limited technical specification focus";
    workflowEnforcement: "Flexible but not enforced";
    developerWorkflow: "Not developer-workflow optimized";
    codeIntegration: "Limited code context understanding";
  };
  
  differentiator: "General project management vs developer-specific workflows";
}

Strategic Market Position Copy Section

Spec-Workflow-MCP's Unique Position:

interface MarketPosition {
  blueOcean: {
    category: "LLM-Enhanced Structured Development Workflows";
    uniqueValue: "Human-supervised LLM intelligence with enforced spec-driven process";
    targetUser: "Development teams needing structured processes with AI assistance";
  };
  
  competitiveAdvantages: {
    llmLeverage: "Full LLM power without additional API costs";
    humanOversight: "Prevents AI errors through mandatory approval";
    structuredProcess: "Enforces proven development methodology";
    simplicity: "No complex setup or API key management";
    realTimeUI: "Superior user experience with dashboard";
  };
  
  marketOpportunities: {
    enterpriseAdoption: "Companies wanting AI benefits with human control";
    consultingFirms: "Standardized processes across client projects";
    startups: "Structured development without overhead";
    education: "Teaching proper development workflows";
  };
}

Expansion Strategy Insights Copy Section

Phase 1: Leverage Core Strengths

interface Phase1Strategy {
  buildOnStrengths: {
    enhanceHumanOversight: "Advanced approval workflows, review templates";
    improveStructure: "Dynamic templates, adaptive workflows";
    expandLLMUsage: "Better context utilization, smarter suggestions";
  };
  
  addressGaps: {
    basicIntegrations: "GitHub, GitLab, Bitbucket connections";
    qualityGates: "Optional automated checks before human review";
    teamFeatures: "Multi-developer coordination";
  };
}

Phase 2: Strategic Differentiation

interface Phase2Strategy {
  uniqueCapabilities: {
    hybridIntelligence: "Best of LLM automation + human oversight";
    contextMastery: "Superior project context understanding";
    processExcellence: "Industry-leading structured workflows";
  };
  
  competitiveFeatures: {
    multiModelSupport: "Support multiple LLM providers";
    enterpriseFeatures: "SSO, compliance, audit trails";
    aiOrchestration: "Multi-agent coordination while maintaining oversight";
  };
}

Strategic Recommendations for Creators Copy Section

Immediate Opportunities (0-6 months):

1. GitHub Integration: Leverage LLM to create PRs, analyze codebases
2. Quality Templates: Add project-type detection for smarter templates
3. Team Coordination: Multi-developer approval workflows
4. Performance Analytics: Track spec-to-delivery success rates

Medium-term Differentiators (6-18 months):

1. Hybrid AI Workflows: Optional automated gates with human oversight
2. Enterprise Dashboard: Multi-project management interface
3. Advanced Integrations: Jira, Slack, Confluence, CI/CD pipelines
4. Predictive Analytics: Project risk analysis using LLM insights

Long-term Vision (18+ months):

1. AI Orchestration Platform: Multi-agent coordination with human oversight
2. Industry Templates: Specialized workflows for different domains
3. Compliance Integration: SOX, GDPR, HIPAA workflow templates
4. Educational Platform: Teaching structured development at scale

Market Validation Insights Copy Section

This analysis reveals that Spec-Workflow-MCP occupies a unique market position:

• ✅ Underserved Market: Structured development workflows with AI enhancement
• ✅ Clear Differentiation: Human oversight + LLM power combination
• ✅ Expansion Potential: Multiple clear paths for feature enhancement
• ✅ Strategic Moat: Proven workflow methodology that competitors would struggle to replicate

Last Updated: December 2024 | Version: 0.0.23

CONFIGURATION.Ar (`docs/CONFIGURATION.ar.md`) Copy Section

دليل التكوين

يغطي هذا الدليل جميع خيارات التكوين لـ Spec Workflow MCP.

خيارات سطر الأوامر Copy Chapter

الاستخدام الأساسي Copy Section

npx -y @pimzino/spec-workflow-mcp@latest [project-path] [options]

الخيارات المتاحة Copy Section

ملاحظات مهمة Copy Section

• مثيل واحد للوحة التحكم: تعمل لوحة تحكم واحدة فقط في كل مرة. جميع خوادم MCP تتصل بنفس لوحة التحكم.
• المنفذ الافتراضي: تستخدم لوحة التحكم المنفذ 5000 بشكل افتراضي. استخدم --port فقط إذا كان 5000 غير متاح.
• لوحة تحكم منفصلة: قم دائمًا بتشغيل لوحة التحكم بشكل منفصل عن خوادم MCP.

أمثلة الاستخدام Copy Chapter

سير العمل النموذجي Copy Section

1. ابدأ لوحة التحكم (قم بذلك أولاً، مرة واحدة فقط):

# يستخدم المنفذ الافتراضي 5000
npx -y @pimzino/spec-workflow-mcp@latest --dashboard

2. ابدأ خوادم MCP (واحد لكل مشروع، في نوافذ طرفية منفصلة):

# المشروع 1
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app1

# المشروع 2
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app2

# المشروع 3
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app3

ستظهر جميع المشاريع في لوحة التحكم على http://localhost:5000

لوحة تحكم مع منفذ مخصص Copy Section

استخدم منفذًا مخصصًا فقط إذا كان المنفذ 5000 غير متاح:

# ابدأ لوحة التحكم على المنفذ 8080
npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080

متغيرات البيئة Copy Chapter

SPEC_WORKFLOW_HOME Copy Section

تجاوز دليل الحالة العامة الافتراضي (~/.spec-workflow-mcp). هذا مفيد للبيئات المعزولة حيث يكون $HOME للقراءة فقط.

الملفات المخزنة في هذا الدليل:

• activeProjects.json - سجل المشاريع
• activeSession.json - معلومات جلسة لوحة التحكم
• settings.json - الإعدادات العامة
• job-execution-history.json - سجل تنفيذ المهام
• migration.log - تتبع ترحيل سجل التنفيذ

أمثلة الاستخدام:

# مسار مطلق
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

# مسار نسبي (يُحل مقابل دليل العمل الحالي)
SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest .

# لوضع لوحة التحكم
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest --dashboard

البيئات المعزولة (مثل Codex CLI):

عند التشغيل في بيئات معزولة مثل Codex CLI مع sandbox_mode=workspace-write، قم بتعيين SPEC_WORKFLOW_HOME إلى موقع قابل للكتابة داخل مساحة العمل الخاصة بك:

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

إدارة جلسة لوحة التحكم Copy Chapter

تخزن لوحة التحكم معلومات جلستها في ~/.spec-workflow-mcp/activeSession.json (أو $SPEC_WORKFLOW_HOME/activeSession.json إذا تم تعيينه). هذا الملف:

• يفرض مثيل واحد للوحة التحكم
• يسمح لخوادم MCP باكتشاف لوحة التحكم قيد التشغيل
• ينظف تلقائيًا عند توقف لوحة التحكم

فرض مثيل واحد Copy Section

يمكن تشغيل لوحة تحكم واحدة فقط في أي وقت. إذا حاولت بدء لوحة تحكم ثانية:

Dashboard is already running at: http://localhost:5000

You can:
  1. Use the existing dashboard at: http://localhost:5000
  2. Stop it first (Ctrl+C or kill PID), then start a new one

Note: Only one dashboard instance is needed for all your projects.

إدارة المنافذ Copy Chapter

المنفذ الافتراضي: 5000
المنفذ المخصص: استخدم --port <number> فقط إذا كان المنفذ 5000 غير متاح

تعارضات المنافذ Copy Section

إذا كان المنفذ 5000 قيد الاستخدام بالفعل بواسطة خدمة أخرى:

Failed to start dashboard: Port 5000 is already in use.

This might be another service using port 5000.
To use a different port:
  spec-workflow-mcp --dashboard --port 8080

ملف التكوين (قديم) Copy Chapter

الموقع الافتراضي Copy Section

يبحث الخادم عن التكوين في: /.spec-workflow/config.toml

تنسيق الملف Copy Section

يستخدم التكوين تنسيق TOML. إليك مثال كامل:

# دليل المشروع (افتراضيًا الدليل الحالي)
projectDir = "/path/to/your/project"

# منفذ لوحة التحكم (1024-65535)
port = 3456

# تشغيل وضع لوحة التحكم فقط
dashboardOnly = false

# لغة الواجهة
# الخيارات: en, ja, zh, es, pt, de, fr, ru, it, ko, ar
lang = "en"

# إشعارات صوتية (إضافة VSCode فقط)
[notifications]
enabled = true
volume = 0.5

# الإعدادات المتقدمة
[advanced]
# محاولات إعادة الاتصال بـ WebSocket
maxReconnectAttempts = 10

# إعدادات مراقب الملفات
[watcher]
enabled = true
debounceMs = 300

خيارات التكوين Copy Section

الإعدادات الأساسية

ملاحظة: تمت إزالة خيار autoStartDashboard في الإصدار 2.0.0. تستخدم لوحة التحكم الآن وضع متعدد المشاريع الموحد المتاح عبر علامة --dashboard.

خيارات اللغة

• en - الإنجليزية
• ja - اليابانية (日本語)
• zh - الصينية (中文)
• es - الإسبانية (Español)
• pt - البرتغالية (Português)
• de - الألمانية (Deutsch)
• fr - الفرنسية (Français)
• ru - الروسية (Русский)
• it - الإيطالية (Italiano)
• ko - الكورية (한국어)
• ar - العربية (العربية)

إنشاء تكوين مخصص Copy Section

1. انسخ التكوين المثالي:

cp .spec-workflow/config.example.toml .spec-workflow/config.toml

2. حرر التكوين:

# تكوين مشروعي
projectDir = "/Users/myname/projects/myapp"
port = 3000
lang = "en"

3. استخدم التكوين:

# يستخدم .spec-workflow/config.toml تلقائيًا
npx -y @pimzino/spec-workflow-mcp@latest

# أو حدد صراحةً
npx -y @pimzino/spec-workflow-mcp@latest --config .spec-workflow/config.toml

أسبقية التكوين Copy Chapter

يتم تطبيق قيم التكوين بهذا الترتيب (من الأعلى إلى الأدنى أولوية):

1. وسائط سطر الأوامر - لها الأولوية دائمًا
2. ملف تكوين مخصص - محدد مع --config
3. ملف التكوين الافتراضي - .spec-workflow/config.toml
4. الافتراضيات المدمجة - قيم احتياطية

مثال على الأسبقية Copy Section

# config.toml
port = 3000

# وسيط سطر الأوامر يتجاوز ملف التكوين
npx -y @pimzino/spec-workflow-mcp@latest --config config.toml --port 4000
# النتيجة: port = 4000 (CLI تفوز)

تكوينات خاصة بالبيئة Copy Chapter

تكوين التطوير Copy Section

# dev-config.toml
projectDir = "./src"
port = 3000
lang = "en"

[advanced]
debugMode = true
verboseLogging = true

الاستخدام:

npx -y @pimzino/spec-workflow-mcp@latest --config dev-config.toml

تكوين الإنتاج Copy Section

# prod-config.toml
projectDir = "/var/app"
port = 8080
lang = "en"

[advanced]
debugMode = false
verboseLogging = false

الاستخدام:

npx -y @pimzino/spec-workflow-mcp@latest --config prod-config.toml

تكوين المنفذ Copy Chapter

نطاق المنفذ الصالح Copy Section

يجب أن تكون المنافذ بين 1024 و 65535.

المنافذ المؤقتة Copy Section

عندما لا يتم تحديد منفذ، يختار النظام تلقائيًا منفذًا مؤقتًا متاحًا. هذا موصى به لـ:

• بيئات التطوير
• مشاريع متعددة متزامنة
• تجنب تعارضات المنافذ

المنافذ الثابتة Copy Section

استخدم منافذ ثابتة عندما تحتاج:

• عناوين URL متسقة للإشارات المرجعية
• التكامل مع أدوات أخرى
• التعاون الجماعي مع تكوينات مشتركة

حل تعارض المنفذ Copy Section

إذا كان المنفذ قيد الاستخدام بالفعل:

1. تحقق مما يستخدم المنفذ:

   • Windows: netstat -an | findstr :3000
   • macOS/Linux: lsof -i :3000

2. الحلول:

   • استخدم منفذًا مختلفًا: --port 3001
   • أنهِ العملية التي تستخدم المنفذ
   • احذف --port لاستخدام منفذ مؤقت

إعداد متعدد المشاريع Copy Chapter

تكوينات منفصلة Copy Section

أنشئ تكوينات خاصة بالمشروع:

# المشروع أ
project-a/
  .spec-workflow/
    config.toml  # port = 3000

# المشروع ب
project-b/
  .spec-workflow/
    config.toml  # port = 3001

تكوين مشترك Copy Section

استخدم تكوينًا مشتركًا مع تجاوزات:

# تكوين أساسي مشترك
~/configs/spec-workflow-base.toml

# تجاوزات خاصة بالمشروع
npx -y @pimzino/spec-workflow-mcp@latest \
  --config ~/configs/spec-workflow-base.toml \
  --port 3000 \
  /path/to/project-a

تكوين إضافة VSCode Copy Chapter

إضافة VSCode لها إعداداتها الخاصة:

1. افتح إعدادات VSCode (Cmd/Ctrl + ,)
2. ابحث عن "Spec Workflow"
3. قم بالتكوين:
   • تفضيل اللغة
   • الإشعارات الصوتية
   • رؤية الأرشيف
   • فترة التحديث التلقائي

استكشاف أخطاء التكوين وإصلاحها Copy Chapter

التكوين لا يتم تحميله Copy Section

1. تحقق من موقع الملف:

   bash Copy

   ls -la .spec-workflow/config.toml

2. تحقق من صحة بناء جملة TOML:

   bash Copy

   # ثبت أداة TOML CLI
   npm install @iarna/toml
   
   # تحقق من الصحة
   toml .spec-workflow/config.toml

3. تحقق من الأذونات:

   bash Copy

   # تأكد من أن الملف قابل للقراءة
   chmod 644 .spec-workflow/config.toml

المشكلات الشائعة Copy Section

أفضل الممارسات Copy Chapter

1. استخدم التحكم في الإصدار لملفات التكوين
2. وثق الإعدادات المخصصة في ملف README الخاص بمشروعك
3. استخدم منافذ مؤقتة في التطوير
4. احتفظ بالبيانات الحساسة خارج ملفات التكوين
5. أنشئ تكوينات خاصة بالبيئة
6. اختبر تغييرات التكوين قبل النشر

التوثيق ذو الصلة Copy Chapter

• دليل المستخدم - استخدام الخادم المُكوَّن
• دليل الواجهات - إعدادات لوحة التحكم والإضافة
• استكشاف الأخطاء وإصلاحها - مشكلات التكوين الشائعة

CONFIGURATION.De (`docs/CONFIGURATION.de.md`) Copy Section

Konfigurationsanleitung

Diese Anleitung deckt alle Konfigurationsoptionen für Spec Workflow MCP ab.

Befehlszeilenoptionen Copy Chapter

Grundlegende Verwendung Copy Section

npx -y @pimzino/spec-workflow-mcp@latest [projekt-pfad] [optionen]

Verfügbare Optionen Copy Section

Wichtige Hinweise Copy Section

• Einzelne Dashboard-Instanz: Nur ein Dashboard läuft gleichzeitig. Alle MCP-Server verbinden sich mit demselben Dashboard.
• Standardport: Dashboard verwendet standardmäßig Port 5000. Verwenden Sie --port nur, wenn 5000 nicht verfügbar ist.
• Separates Dashboard: Führen Sie das Dashboard immer separat von MCP-Servern aus.

Verwendungsbeispiele Copy Chapter

Typischer Workflow Copy Section

1. Dashboard starten (zuerst tun, nur einmal):

# Verwendet Standardport 5000
npx -y @pimzino/spec-workflow-mcp@latest --dashboard

2. MCP-Server starten (einer pro Projekt, in separaten Terminals):

# Projekt 1
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app1

# Projekt 2
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app2

# Projekt 3
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app3

Alle Projekte werden im Dashboard unter http://localhost:5000 angezeigt

Dashboard mit benutzerdefiniertem Port Copy Section

Verwenden Sie einen benutzerdefinierten Port nur, wenn Port 5000 nicht verfügbar ist:

# Dashboard auf Port 8080 starten
npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080

Umgebungsvariablen Copy Chapter

SPEC_WORKFLOW_HOME Copy Section

Überschreiben Sie das standardmäßige globale Zustandsverzeichnis (~/.spec-workflow-mcp). Dies ist nützlich für Sandbox-Umgebungen, in denen $HOME schreibgeschützt ist.

In diesem Verzeichnis gespeicherte Dateien:

• activeProjects.json - Projektregister
• activeSession.json - Dashboard-Sitzungsinformationen
• settings.json - Globale Einstellungen
• job-execution-history.json - Job-Ausführungsverlauf
• migration.log - Tracking der Implementierungs-Log-Migration

Verwendungsbeispiele:

# Absoluter Pfad
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

# Relativer Pfad (wird gegen das aktuelle Arbeitsverzeichnis aufgelöst)
SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest .

# Für Dashboard-Modus
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest --dashboard

Sandbox-Umgebungen (z.B. Codex CLI):

Bei Ausführung in Sandbox-Umgebungen wie Codex CLI mit sandbox_mode=workspace-write, setzen Sie SPEC_WORKFLOW_HOME auf einen beschreibbaren Ort innerhalb Ihres Arbeitsbereichs:

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

Dashboard-Sitzungsverwaltung Copy Chapter

Das Dashboard speichert seine Sitzungsinformationen in ~/.spec-workflow-mcp/activeSession.json (oder $SPEC_WORKFLOW_HOME/activeSession.json falls gesetzt). Diese Datei:

• Erzwingt einzelne Dashboard-Instanz
• Ermöglicht MCP-Servern das laufende Dashboard zu finden
• Räumt automatisch auf, wenn das Dashboard stoppt

Durchsetzung einer einzelnen Instanz Copy Section

Nur ein Dashboard kann gleichzeitig laufen. Wenn Sie versuchen, ein zweites Dashboard zu starten:

Dashboard läuft bereits unter: http://localhost:5000

Sie können:
  1. Das vorhandene Dashboard verwenden unter: http://localhost:5000
  2. Es zuerst stoppen (Strg+C oder kill PID), dann ein neues starten

Hinweis: Nur eine Dashboard-Instanz wird für alle Ihre Projekte benötigt.

Port-Verwaltung Copy Chapter

Standardport: 5000
Benutzerdefinierter Port: Verwenden Sie --port <nummer> nur, wenn Port 5000 nicht verfügbar ist

Port-Konflikte Copy Section

Wenn Port 5000 bereits von einem anderen Dienst verwendet wird:

Dashboard konnte nicht gestartet werden: Port 5000 wird bereits verwendet.

Dies könnte ein anderer Dienst sein, der Port 5000 verwendet.
Um einen anderen Port zu verwenden:
  spec-workflow-mcp --dashboard --port 8080

Konfigurationsdatei (Veraltet) Copy Chapter

Standardspeicherort Copy Section

Der Server sucht die Konfiguration unter: /.spec-workflow/config.toml

Dateiformat Copy Section

Die Konfiguration verwendet das TOML-Format. Hier ist ein vollständiges Beispiel:

# Projektverzeichnis (standardmäßig aktuelles Verzeichnis)
projectDir = "/pfad/zu/ihrem/projekt"

# Dashboard-Port (1024-65535)
port = 3456

# Nur-Dashboard-Modus ausführen
dashboardOnly = false

# Oberflächensprache
# Optionen: en, ja, zh, es, pt, de, fr, ru, it, ko, ar
lang = "de"

# Sound-Benachrichtigungen (nur VSCode-Extension)
[notifications]
enabled = true
volume = 0.5

# Erweiterte Einstellungen
[advanced]
# WebSocket-Wiederverbindungsversuche
maxReconnectAttempts = 10

# Datei-Watcher-Einstellungen
[watcher]
enabled = true
debounceMs = 300

Konfigurationsoptionen Copy Section

Grundeinstellungen

Hinweis: Die Option autoStartDashboard wurde in v2.0.0 entfernt. Das Dashboard verwendet jetzt einen einheitlichen Mehrprojekt-Modus, der über das --dashboard Flag zugänglich ist.

Sprachoptionen

• en - English
• ja - Japanese (日本語)
• zh - Chinese (中文)
• es - Spanish (Español)
• pt - Portuguese (Português)
• de - German (Deutsch)
• fr - French (Français)
• ru - Russian (Русский)
• it - Italian (Italiano)
• ko - Korean (한국어)
• ar - Arabic (العربية)

Eine benutzerdefinierte Konfiguration erstellen Copy Section

1. Die Beispielkonfiguration kopieren:

cp .spec-workflow/config.example.toml .spec-workflow/config.toml

2. Die Konfiguration bearbeiten:

# Meine Projektkonfiguration
projectDir = "/Users/meinname/projects/meineapp"
port = 3000
lang = "de"

3. Die Konfiguration verwenden:

# Verwendet automatisch .spec-workflow/config.toml
npx -y @pimzino/spec-workflow-mcp@latest

# Oder explizit angeben
npx -y @pimzino/spec-workflow-mcp@latest --config .spec-workflow/config.toml

Konfigurationspriorität Copy Chapter

Konfigurationswerte werden in dieser Reihenfolge angewendet (höchste bis niedrigste Priorität):

1. Befehlszeilenargumente - Haben immer Vorrang
2. Benutzerdefinierte Konfigurationsdatei - Mit --config angegeben
3. Standard-Konfigurationsdatei - .spec-workflow/config.toml
4. Eingebaute Standards - Fallback-Werte

Beispiel-Priorität Copy Section

# config.toml
port = 3000

# Befehlszeilenargument überschreibt Konfigurationsdatei
npx -y @pimzino/spec-workflow-mcp@latest --config config.toml --port 4000
# Ergebnis: port = 4000 (CLI gewinnt)

Umgebungsspezifische Konfigurationen Copy Chapter

Entwicklungskonfiguration Copy Section

# dev-config.toml
projectDir = "./src"
port = 3000
lang = "de"

[advanced]
debugMode = true
verboseLogging = true

Verwendung:

npx -y @pimzino/spec-workflow-mcp@latest --config dev-config.toml

Produktionskonfiguration Copy Section

# prod-config.toml
projectDir = "/var/app"
port = 8080
lang = "de"

[advanced]
debugMode = false
verboseLogging = false

Verwendung:

npx -y @pimzino/spec-workflow-mcp@latest --config prod-config.toml

Port-Konfiguration Copy Chapter

Gültiger Port-Bereich Copy Section

Ports müssen zwischen 1024 und 65535 liegen.

Ephemere Ports Copy Section

Wenn kein Port angegeben ist, wählt das System automatisch einen verfügbaren ephemeren Port. Dies wird empfohlen für:

• Entwicklungsumgebungen
• Mehrere gleichzeitige Projekte
• Vermeidung von Port-Konflikten

Feste Ports Copy Section

Verwenden Sie feste Ports, wenn Sie benötigen:

• Konsistente URLs für Lesezeichen
• Integration mit anderen Tools
• Teamzusammenarbeit mit gemeinsamen Konfigurationen

Port-Konfliktlösung Copy Section

Wenn ein Port bereits verwendet wird:

1. Prüfen Sie, was den Port verwendet:

   • Windows: netstat -an | findstr :3000
   • macOS/Linux: lsof -i :3000

2. Lösungen:

   • Einen anderen Port verwenden: --port 3001
   • Den Prozess beenden, der den Port verwendet
   • --port weglassen, um einen ephemeren Port zu verwenden

Mehrprojekt-Setup Copy Chapter

Separate Konfigurationen Copy Section

Erstellen Sie projektspezifische Konfigurationen:

# Projekt A
projekt-a/
  .spec-workflow/
    config.toml  # port = 3000

# Projekt B
projekt-b/
  .spec-workflow/
    config.toml  # port = 3001

Gemeinsame Konfiguration Copy Section

Verwenden Sie eine gemeinsame Konfiguration mit Überschreibungen:

# Gemeinsame Basiskonfiguration
~/configs/spec-workflow-base.toml

# Projektspezifische Überschreibungen
npx -y @pimzino/spec-workflow-mcp@latest \
  --config ~/configs/spec-workflow-base.toml \
  --port 3000 \
  /pfad/zu/projekt-a

VSCode Extension-Konfiguration Copy Chapter

Die VSCode Extension hat eigene Einstellungen:

1. VSCode-Einstellungen öffnen (Cmd/Strg + ,)
2. Nach "Spec Workflow" suchen
3. Konfigurieren:
   • Sprachpräferenz
   • Sound-Benachrichtigungen
   • Archiv-Sichtbarkeit
   • Auto-Aktualisierungsintervall

Fehlerbehebung bei der Konfiguration Copy Chapter

Konfiguration lädt nicht Copy Section

1. Dateispeicherort überprüfen:

   bash Copy

   ls -la .spec-workflow/config.toml

2. TOML-Syntax validieren:

   bash Copy

   # TOML CLI-Tool installieren
   npm install @iarna/toml
   
   # Validieren
   toml .spec-workflow/config.toml

3. Berechtigungen überprüfen:

   bash Copy

   # Sicherstellen, dass die Datei lesbar ist
   chmod 644 .spec-workflow/config.toml

Häufige Probleme Copy Section

Best Practices Copy Chapter

1. Versionskontrolle verwenden für Konfigurationsdateien
2. Benutzerdefinierte Einstellungen dokumentieren in Ihrer Projekt-README
3. Ephemere Ports verwenden in der Entwicklung
4. Sensible Daten fernhalten aus Konfigurationsdateien
5. Umgebungsspezifische Konfigurationen erstellen
6. Konfigurationsänderungen testen vor dem Deployment

Verwandte Dokumentation Copy Chapter

• Benutzerhandbuch - Verwendung des konfigurierten Servers
• Oberflächen-Leitfaden - Dashboard- und Extension-Einstellungen
• Fehlerbehebung - Häufige Konfigurationsprobleme

CONFIGURATION.Es (`docs/CONFIGURATION.es.md`) Copy Section

Guía de Configuración

Esta guía cubre todas las opciones de configuración para Spec Workflow MCP.

Opciones de Línea de Comandos Copy Chapter

Uso Básico Copy Section

npx -y @pimzino/spec-workflow-mcp@latest [ruta-proyecto] [opciones]

Opciones Disponibles Copy Section

Notas Importantes Copy Section

• Una Sola Instancia del Panel: Solo se ejecuta un panel de control a la vez. Todos los servidores MCP se conectan al mismo panel.
• Puerto Predeterminado: El panel usa el puerto 5000 por defecto. Usa --port solo si 5000 no está disponible.
• Panel Separado: Siempre ejecuta el panel de control por separado de los servidores MCP.

Ejemplos de Uso Copy Chapter

Flujo de Trabajo Típico Copy Section

1. Iniciar el Panel de Control (hazlo primero, solo una vez):

# Usa el puerto predeterminado 5000
npx -y @pimzino/spec-workflow-mcp@latest --dashboard

2. Iniciar Servidores MCP (uno por proyecto, en terminales separados):

# Proyecto 1
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app1

# Proyecto 2
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app2

# Proyecto 3
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app3

Todos los proyectos aparecerán en el panel de control en http://localhost:5000

Panel de Control con Puerto Personalizado Copy Section

Solo usa un puerto personalizado si el puerto 5000 no está disponible:

# Iniciar el panel en el puerto 8080
npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080

Variables de Entorno Copy Chapter

SPEC_WORKFLOW_HOME Copy Section

Sobrescribir el directorio de estado global predeterminado (~/.spec-workflow-mcp). Esto es útil para entornos en sandbox donde $HOME es de solo lectura.

Archivos almacenados en este directorio:

• activeProjects.json - Registro de proyectos
• activeSession.json - Información de sesión del panel
• settings.json - Configuración global
• job-execution-history.json - Historial de ejecución de trabajos
• migration.log - Registro de migración de implementación

Ejemplos de uso:

# Ruta absoluta
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

# Ruta relativa (resuelta contra el directorio de trabajo actual)
SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest .

# Para modo panel de control
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest --dashboard

Entornos en sandbox (por ejemplo, Codex CLI):

Al ejecutar en entornos en sandbox como Codex CLI con sandbox_mode=workspace-write, establece SPEC_WORKFLOW_HOME en una ubicación con permisos de escritura dentro de tu espacio de trabajo:

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

Gestión de Sesión del Panel de Control Copy Chapter

El panel de control almacena su información de sesión en ~/.spec-workflow-mcp/activeSession.json (o $SPEC_WORKFLOW_HOME/activeSession.json si está configurado). Este archivo:

• Fuerza una sola instancia del panel
• Permite a los servidores MCP descubrir el panel en ejecución
• Se limpia automáticamente cuando el panel se detiene

Aplicación de Instancia Única Copy Section

Solo un panel de control puede ejecutarse en cualquier momento. Si intentas iniciar un segundo panel:

El panel de control ya se está ejecutando en: http://localhost:5000

Puedes:
  1. Usar el panel existente en: http://localhost:5000
  2. Detenerlo primero (Ctrl+C o kill PID), luego iniciar uno nuevo

Nota: Solo se necesita una instancia del panel para todos tus proyectos.

Gestión de Puertos Copy Chapter

Puerto Predeterminado: 5000
Puerto Personalizado: Usa --port <número> solo si el puerto 5000 no está disponible

Conflictos de Puertos Copy Section

Si el puerto 5000 ya está en uso por otro servicio:

Error al iniciar el panel: El puerto 5000 ya está en uso.

Esto podría ser otro servicio usando el puerto 5000.
Para usar un puerto diferente:
  spec-workflow-mcp --dashboard --port 8080

Archivo de Configuración (Obsoleto) Copy Chapter

Ubicación Predeterminada Copy Section

El servidor busca la configuración en: <directorio-proyecto>/.spec-workflow/config.toml

Formato del Archivo Copy Section

La configuración usa formato TOML. Aquí hay un ejemplo completo:

# Directorio del proyecto (predeterminado al directorio actual)
projectDir = "/ruta/a/tu/proyecto"

# Puerto del panel (1024-65535)
port = 3456

# Ejecutar en modo solo panel
dashboardOnly = false

# Idioma de la interfaz
# Opciones: en, ja, zh, es, pt, de, fr, ru, it, ko, ar
lang = "es"

# Notificaciones de sonido (solo extensión VSCode)
[notifications]
enabled = true
volume = 0.5

# Configuración avanzada
[advanced]
# Intentos de reconexión WebSocket
maxReconnectAttempts = 10

# Configuración del observador de archivos
[watcher]
enabled = true
debounceMs = 300

Opciones de Configuración Copy Section

Configuración Básica

Nota: La opción autoStartDashboard fue eliminada en v2.0.0. El panel ahora usa un modo multi-proyecto unificado accesible mediante la bandera --dashboard.

Opciones de Idioma

• en - English
• ja - Japanese (日本語)
• zh - Chinese (中文)
• es - Spanish (Español)
• pt - Portuguese (Português)
• de - German (Deutsch)
• fr - French (Français)
• ru - Russian (Русский)
• it - Italian (Italiano)
• ko - Korean (한국어)
• ar - Arabic (العربية)

Crear una Configuración Personalizada Copy Section

1. Copiar la configuración de ejemplo:

cp .spec-workflow/config.example.toml .spec-workflow/config.toml

2. Editar la configuración:

# Mi configuración de proyecto
projectDir = "/Users/minombre/proyectos/miapp"
port = 3000
lang = "es"

3. Usar la configuración:

# Usa .spec-workflow/config.toml automáticamente
npx -y @pimzino/spec-workflow-mcp@latest

# O especificar explícitamente
npx -y @pimzino/spec-workflow-mcp@latest --config .spec-workflow/config.toml

Precedencia de Configuración Copy Chapter

Los valores de configuración se aplican en este orden (de mayor a menor prioridad):

1. Argumentos de línea de comandos - Siempre tienen precedencia
2. Archivo de configuración personalizado - Especificado con --config
3. Archivo de configuración predeterminado - .spec-workflow/config.toml
4. Valores predeterminados integrados - Valores de respaldo

Ejemplo de Precedencia Copy Section

# config.toml
port = 3000

# El argumento de línea de comandos sobrescribe el archivo de configuración
npx -y @pimzino/spec-workflow-mcp@latest --config config.toml --port 4000
# Resultado: port = 4000 (CLI gana)

Configuraciones Específicas del Entorno Copy Chapter

Configuración de Desarrollo Copy Section

# dev-config.toml
projectDir = "./src"
port = 3000
lang = "es"

[advanced]
debugMode = true
verboseLogging = true

Uso:

npx -y @pimzino/spec-workflow-mcp@latest --config dev-config.toml

Configuración de Producción Copy Section

# prod-config.toml
projectDir = "/var/app"
port = 8080
lang = "es"

[advanced]
debugMode = false
verboseLogging = false

Uso:

npx -y @pimzino/spec-workflow-mcp@latest --config prod-config.toml

Configuración de Puerto Copy Chapter

Rango de Puerto Válido Copy Section

Los puertos deben estar entre 1024 y 65535.

Puertos Efímeros Copy Section

Cuando no se especifica un puerto, el sistema selecciona automáticamente un puerto efímero disponible. Esto se recomienda para:

• Entornos de desarrollo
• Múltiples proyectos simultáneos
• Evitar conflictos de puertos

Puertos Fijos Copy Section

Usa puertos fijos cuando necesites:

• URLs consistentes para marcadores
• Integración con otras herramientas
• Colaboración en equipo con configuraciones compartidas

Resolución de Conflictos de Puerto Copy Section

Si un puerto ya está en uso:

1. Verifica qué está usando el puerto:

   • Windows: netstat -an | findstr :3000
   • macOS/Linux: lsof -i :3000

2. Soluciones:

   • Usar un puerto diferente: --port 3001
   • Terminar el proceso que usa el puerto
   • Omitir --port para usar un puerto efímero

Configuración Multi-Proyecto Copy Chapter

Configuraciones Separadas Copy Section

Crear configuraciones específicas por proyecto:

# Proyecto A
proyecto-a/
  .spec-workflow/
    config.toml  # port = 3000

# Proyecto B
proyecto-b/
  .spec-workflow/
    config.toml  # port = 3001

Configuración Compartida Copy Section

Usar una configuración compartida con sobrescrituras:

# Configuración base compartida
~/configs/spec-workflow-base.toml

# Sobrescrituras específicas del proyecto
npx -y @pimzino/spec-workflow-mcp@latest \
  --config ~/configs/spec-workflow-base.toml \
  --port 3000 \
  /ruta/a/proyecto-a

Configuración de la Extensión para VSCode Copy Chapter

La extensión para VSCode tiene su propia configuración:

1. Abrir Configuración de VSCode (Cmd/Ctrl + ,)
2. Buscar "Spec Workflow"
3. Configurar:
   • Preferencia de idioma
   • Notificaciones de sonido
   • Visibilidad del archivo
   • Intervalo de auto-actualización

Solución de Problemas de Configuración Copy Chapter

La Configuración No Se Carga Copy Section

1. Verificar ubicación del archivo:

   bash Copy

   ls -la .spec-workflow/config.toml

2. Validar sintaxis TOML:

   bash Copy

   # Instalar herramienta CLI toml
   npm install @iarna/toml
   
   # Validar
   toml .spec-workflow/config.toml

3. Verificar permisos:

   bash Copy

   # Asegurar que el archivo es legible
   chmod 644 .spec-workflow/config.toml

Problemas Comunes Copy Section

Mejores Prácticas Copy Chapter

1. Usar control de versiones para archivos de configuración
2. Documentar configuraciones personalizadas en tu README del proyecto
3. Usar puertos efímeros en desarrollo
4. Mantener datos sensibles fuera de archivos de configuración
5. Crear configuraciones específicas del entorno
6. Probar cambios de configuración antes de desplegar

Documentación Relacionada Copy Chapter

• Guía del Usuario - Usando el servidor configurado
• Guía de Interfaces - Configuración del panel y extensión
• Solución de Problemas - Problemas comunes de configuración

CONFIGURATION.Fr (`docs/CONFIGURATION.fr.md`) Copy Section

Guide de configuration

Ce guide couvre toutes les options de configuration pour Spec Workflow MCP.

Options de ligne de commande Copy Chapter

Utilisation de base Copy Section

npx -y @pimzino/spec-workflow-mcp@latest [chemin-projet] [options]

Options disponibles Copy Section

Notes importantes Copy Section

• Instance unique de tableau de bord : Un seul tableau de bord s'exécute à la fois. Tous les serveurs MCP se connectent au même tableau de bord.
• Port par défaut : Le tableau de bord utilise le port 5000 par défaut. Utilisez --port uniquement si le port 5000 n'est pas disponible.
• Tableau de bord séparé : Exécutez toujours le tableau de bord séparément des serveurs MCP.

Exemples d'utilisation Copy Chapter

Flux de travail typique Copy Section

1. Démarrer le tableau de bord (faites ceci en premier, une seule fois) :

# Utilise le port par défaut 5000
npx -y @pimzino/spec-workflow-mcp@latest --dashboard

2. Démarrer les serveurs MCP (un par projet, dans des terminaux séparés) :

# Projet 1
npx -y @pimzino/spec-workflow-mcp@latest ~/projets/app1

# Projet 2
npx -y @pimzino/spec-workflow-mcp@latest ~/projets/app2

# Projet 3
npx -y @pimzino/spec-workflow-mcp@latest ~/projets/app3

Tous les projets apparaîtront dans le tableau de bord à http://localhost:5000

Tableau de bord avec port personnalisé Copy Section

Utilisez un port personnalisé uniquement si le port 5000 n'est pas disponible :

# Démarrer le tableau de bord sur le port 8080
npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080

Variables d'environnement Copy Chapter

SPEC_WORKFLOW_HOME Copy Section

Remplace le répertoire d'état global par défaut (~/.spec-workflow-mcp). Ceci est utile pour les environnements isolés où $HOME est en lecture seule.

Fichiers stockés dans ce répertoire :

• activeProjects.json - Registre des projets
• activeSession.json - Informations de session du tableau de bord
• settings.json - Paramètres globaux
• job-execution-history.json - Historique d'exécution des tâches
• migration.log - Suivi de la migration du journal d'implémentation

Exemples d'utilisation :

# Chemin absolu
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

# Chemin relatif (résolu par rapport au répertoire de travail actuel)
SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest .

# Pour le mode tableau de bord
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest --dashboard

Environnements isolés (par exemple, Codex CLI) :

Lors de l'exécution dans des environnements isolés comme Codex CLI avec sandbox_mode=workspace-write, définissez SPEC_WORKFLOW_HOME sur un emplacement accessible en écriture dans votre espace de travail :

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

Gestion de session du tableau de bord Copy Chapter

Le tableau de bord stocke ses informations de session dans ~/.spec-workflow-mcp/activeSession.json (ou $SPEC_WORKFLOW_HOME/activeSession.json si défini). Ce fichier :

• Impose une instance unique de tableau de bord
• Permet aux serveurs MCP de découvrir le tableau de bord en cours d'exécution
• Se nettoie automatiquement lorsque le tableau de bord s'arrête

Application d'instance unique Copy Section

Un seul tableau de bord peut s'exécuter à la fois. Si vous essayez de démarrer un deuxième tableau de bord :

Le tableau de bord est déjà en cours d'exécution à : http://localhost:5000

Vous pouvez :
  1. Utiliser le tableau de bord existant à : http://localhost:5000
  2. L'arrêter d'abord (Ctrl+C ou kill PID), puis en démarrer un nouveau

Remarque : Une seule instance de tableau de bord est nécessaire pour tous vos projets.

Gestion des ports Copy Chapter

Port par défaut : 5000
Port personnalisé : Utilisez --port <numéro> uniquement si le port 5000 n'est pas disponible

Conflits de ports Copy Section

Si le port 5000 est déjà utilisé par un autre service :

Échec du démarrage du tableau de bord : Le port 5000 est déjà utilisé.

Il peut s'agir d'un autre service utilisant le port 5000.
Pour utiliser un port différent :
  spec-workflow-mcp --dashboard --port 8080

Fichier de configuration (Obsolète) Copy Chapter

Emplacement par défaut Copy Section

Le serveur recherche la configuration à : <répertoire-projet>/.spec-workflow/config.toml

Format de fichier Copy Section

La configuration utilise le format TOML. Voici un exemple complet :

# Répertoire du projet (par défaut le répertoire actuel)
projectDir = "/chemin/vers/votre/projet"

# Port du tableau de bord (1024-65535)
port = 3456

# Exécuter en mode tableau de bord uniquement
dashboardOnly = false

# Langue de l'interface
# Options : en, ja, zh, es, pt, de, fr, ru, it, ko, ar
lang = "fr"

# Notifications sonores (extension VSCode uniquement)
[notifications]
enabled = true
volume = 0.5

# Paramètres avancés
[advanced]
# Tentatives de reconnexion WebSocket
maxReconnectAttempts = 10

# Paramètres du surveillant de fichiers
[watcher]
enabled = true
debounceMs = 300

Options de configuration Copy Section

Paramètres de base

Remarque : L'option autoStartDashboard a été supprimée dans la v2.0.0. Le tableau de bord utilise désormais un mode multi-projet unifié accessible via le flag --dashboard.

Options de langue

• en - English
• ja - Japanese (日本語)
• zh - Chinese (中文)
• es - Spanish (Español)
• pt - Portuguese (Português)
• de - German (Deutsch)
• fr - French (Français)
• ru - Russian (Русский)
• it - Italian (Italiano)
• ko - Korean (한국어)
• ar - Arabic (العربية)

Créer une configuration personnalisée Copy Section

1. Copiez l'exemple de configuration :

cp .spec-workflow/config.example.toml .spec-workflow/config.toml

2. Modifiez la configuration :

# Configuration de mon projet
projectDir = "/Users/monnom/projets/monapp"
port = 3000
lang = "fr"

3. Utilisez la configuration :

# Utilise .spec-workflow/config.toml automatiquement
npx -y @pimzino/spec-workflow-mcp@latest

# Ou spécifiez explicitement
npx -y @pimzino/spec-workflow-mcp@latest --config .spec-workflow/config.toml

Priorité de configuration Copy Chapter

Les valeurs de configuration sont appliquées dans cet ordre (priorité la plus élevée à la plus basse) :

1. Arguments de ligne de commande - Toujours prioritaires
2. Fichier de configuration personnalisé - Spécifié avec --config
3. Fichier de configuration par défaut - .spec-workflow/config.toml
4. Valeurs par défaut intégrées - Valeurs de repli

Exemple de priorité Copy Section

# config.toml
port = 3000

# L'argument de ligne de commande remplace le fichier de configuration
npx -y @pimzino/spec-workflow-mcp@latest --config config.toml --port 4000
# Résultat : port = 4000 (CLI gagne)

Configurations spécifiques à l'environnement Copy Chapter

Configuration de développement Copy Section

# dev-config.toml
projectDir = "./src"
port = 3000
lang = "fr"

[advanced]
debugMode = true
verboseLogging = true

Utilisation :

npx -y @pimzino/spec-workflow-mcp@latest --config dev-config.toml

Configuration de production Copy Section

# prod-config.toml
projectDir = "/var/app"
port = 8080
lang = "fr"

[advanced]
debugMode = false
verboseLogging = false

Utilisation :

npx -y @pimzino/spec-workflow-mcp@latest --config prod-config.toml

Configuration des ports Copy Chapter

Plage de ports valide Copy Section

Les ports doivent être entre 1024 et 65535.

Ports éphémères Copy Section

Lorsqu'aucun port n'est spécifié, le système sélectionne automatiquement un port éphémère disponible. Ceci est recommandé pour :

• Les environnements de développement
• Plusieurs projets simultanés
• Éviter les conflits de ports

Ports fixes Copy Section

Utilisez des ports fixes lorsque vous avez besoin de :

• URL cohérentes pour les signets
• Intégration avec d'autres outils
• Collaboration d'équipe avec des configurations partagées

Résolution des conflits de ports Copy Section

Si un port est déjà utilisé :

1. Vérifiez ce qui utilise le port :

   • Windows : netstat -an | findstr :3000
   • macOS/Linux : lsof -i :3000

2. Solutions :

   • Utilisez un port différent : --port 3001
   • Tuez le processus utilisant le port
   • Omettez --port pour utiliser un port éphémère

Configuration multi-projet Copy Chapter

Configurations séparées Copy Section

Créez des configurations spécifiques au projet :

# Projet A
projet-a/
  .spec-workflow/
    config.toml  # port = 3000

# Projet B
projet-b/
  .spec-workflow/
    config.toml  # port = 3001

Configuration partagée Copy Section

Utilisez une configuration partagée avec des remplacements :

# Configuration de base partagée
~/configs/spec-workflow-base.toml

# Remplacements spécifiques au projet
npx -y @pimzino/spec-workflow-mcp@latest \
  --config ~/configs/spec-workflow-base.toml \
  --port 3000 \
  /chemin/vers/projet-a

Configuration de l'extension VSCode Copy Chapter

L'extension VSCode a ses propres paramètres :

1. Ouvrez les paramètres VSCode (Cmd/Ctrl + ,)
2. Recherchez "Spec Workflow"
3. Configurez :
   • Préférence de langue
   • Notifications sonores
   • Visibilité des archives
   • Intervalle de rafraîchissement automatique

Dépannage de la configuration Copy Chapter

La configuration ne se charge pas Copy Section

1. Vérifiez l'emplacement du fichier :

   bash Copy

   ls -la .spec-workflow/config.toml

2. Validez la syntaxe TOML :

   bash Copy

   # Installez l'outil CLI toml
   npm install @iarna/toml
   
   # Validez
   toml .spec-workflow/config.toml

3. Vérifiez les permissions :

   bash Copy

   # Assurez-vous que le fichier est lisible
   chmod 644 .spec-workflow/config.toml

Problèmes courants Copy Section

Bonnes pratiques Copy Chapter

1. Utilisez le contrôle de version pour les fichiers de configuration
2. Documentez les paramètres personnalisés dans le README de votre projet
3. Utilisez des ports éphémères en développement
4. Gardez les données sensibles hors des fichiers de configuration
5. Créez des configurations spécifiques à l'environnement
6. Testez les modifications de configuration avant le déploiement

Documentation associée Copy Chapter

• Guide utilisateur - Utilisation du serveur configuré
• Guide des interfaces - Paramètres du tableau de bord et de l'extension
• Dépannage - Problèmes de configuration courants

CONFIGURATION.It (`docs/CONFIGURATION.it.md`) Copy Section

Guida alla Configurazione

Questa guida copre tutte le opzioni di configurazione per Spec Workflow MCP.

Opzioni da Riga di Comando Copy Chapter

Uso Base Copy Section

npx -y @pimzino/spec-workflow-mcp@latest [project-path] [opzioni]

Opzioni Disponibili Copy Section

Note Importanti Copy Section

• Singola Istanza Dashboard: Solo una dashboard viene eseguita alla volta. Tutti i server MCP si connettono alla stessa dashboard.
• Porta Predefinita: La dashboard usa la porta 5000 di default. Usa --port solo se 5000 non è disponibile.
• Dashboard Separata: Esegui sempre la dashboard separatamente dai server MCP.

Esempi di Utilizzo Copy Chapter

Flusso di Lavoro Tipico Copy Section

1. Avvia la Dashboard (fallo prima, solo una volta):

# Usa la porta predefinita 5000
npx -y @pimzino/spec-workflow-mcp@latest --dashboard

2. Avvia i Server MCP (uno per progetto, in terminali separati):

# Progetto 1
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app1

# Progetto 2
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app2

# Progetto 3
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app3

Tutti i progetti appariranno nella dashboard a http://localhost:5000

Dashboard con Porta Personalizzata Copy Section

Usa una porta personalizzata solo se la porta 5000 non è disponibile:

# Avvia la dashboard sulla porta 8080
npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080

Variabili d'Ambiente Copy Chapter

SPEC_WORKFLOW_HOME Copy Section

Sostituisci la directory di stato globale predefinita (~/.spec-workflow-mcp). Questo è utile per ambienti sandboxed dove $HOME è in sola lettura.

File memorizzati in questa directory:

• activeProjects.json - Registro dei progetti
• activeSession.json - Info sessione dashboard
• settings.json - Impostazioni globali
• job-execution-history.json - Cronologia esecuzione job
• migration.log - Tracciamento migrazione log implementazione

Esempi di utilizzo:

# Percorso assoluto
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

# Percorso relativo (risolto rispetto alla directory di lavoro corrente)
SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest .

# Per modalità dashboard
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest --dashboard

Ambienti sandboxed (es. Codex CLI):

Quando si esegue in ambienti sandboxed come Codex CLI con sandbox_mode=workspace-write, imposta SPEC_WORKFLOW_HOME su una posizione scrivibile all'interno del tuo workspace:

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

Gestione Sessione Dashboard Copy Chapter

La dashboard memorizza le informazioni di sessione in ~/.spec-workflow-mcp/activeSession.json (o $SPEC_WORKFLOW_HOME/activeSession.json se impostato). Questo file:

• Applica l'istanza singola della dashboard
• Consente ai server MCP di scoprire la dashboard in esecuzione
• Si pulisce automaticamente quando la dashboard si ferma

Applicazione Istanza Singola Copy Section

Solo una dashboard può essere eseguita alla volta. Se provi ad avviare una seconda dashboard:

Dashboard già in esecuzione a: http://localhost:5000

Puoi:
  1. Usare la dashboard esistente a: http://localhost:5000
  2. Fermarla prima (Ctrl+C o kill PID), poi avviarne una nuova

Nota: È necessaria solo un'istanza della dashboard per tutti i tuoi progetti.

Gestione Porte Copy Chapter

Porta Predefinita: 5000
Porta Personalizzata: Usa --port <numero> solo se la porta 5000 non è disponibile

Conflitti di Porta Copy Section

Se la porta 5000 è già in uso da un altro servizio:

Impossibile avviare la dashboard: La porta 5000 è già in uso.

Potrebbe essere un altro servizio che usa la porta 5000.
Per usare una porta diversa:
  spec-workflow-mcp --dashboard --port 8080

File di Configurazione (Deprecato) Copy Chapter

Posizione Predefinita Copy Section

Il server cerca la configurazione in: /.spec-workflow/config.toml

Formato File Copy Section

La configurazione usa il formato TOML. Ecco un esempio completo:

# Directory del progetto (predefinita alla directory corrente)
projectDir = "/path/to/your/project"

# Porta dashboard (1024-65535)
port = 3456

# Esegui solo modalità dashboard
dashboardOnly = false

# Lingua interfaccia
# Opzioni: en, ja, zh, es, pt, de, fr, ru, it, ko, ar
lang = "it"

# Notifiche sonore (solo estensione VSCode)
[notifications]
enabled = true
volume = 0.5

# Impostazioni avanzate
[advanced]
# Tentativi di riconnessione WebSocket
maxReconnectAttempts = 10

# Impostazioni watcher file
[watcher]
enabled = true
debounceMs = 300

Opzioni di Configurazione Copy Section

Impostazioni Base

Nota: L'opzione autoStartDashboard è stata rimossa nella v2.0.0. La dashboard ora usa una modalità multi-progetto unificata accessibile tramite il flag --dashboard.

Opzioni Lingua

• en - English
• ja - Japanese (日本語)
• zh - Chinese (中文)
• es - Spanish (Español)
• pt - Portuguese (Português)
• de - German (Deutsch)
• fr - French (Français)
• ru - Russian (Русский)
• it - Italian (Italiano)
• ko - Korean (한국어)
• ar - Arabic (العربية)

Creare una Configurazione Personalizzata Copy Section

1. Copia la configurazione di esempio:

cp .spec-workflow/config.example.toml .spec-workflow/config.toml

2. Modifica la configurazione:

# Configurazione del mio progetto
projectDir = "/Users/myname/projects/myapp"
port = 3000
lang = "it"

3. Usa la configurazione:

# Usa automaticamente .spec-workflow/config.toml
npx -y @pimzino/spec-workflow-mcp@latest

# Oppure specificalo esplicitamente
npx -y @pimzino/spec-workflow-mcp@latest --config .spec-workflow/config.toml

Precedenza Configurazione Copy Chapter

I valori di configurazione vengono applicati in questo ordine (dalla priorità più alta alla più bassa):

1. Argomenti da riga di comando - Hanno sempre la precedenza
2. File config personalizzato - Specificato con --config
3. File config predefinito - .spec-workflow/config.toml
4. Predefiniti integrati - Valori di fallback

Esempio Precedenza Copy Section

# config.toml
port = 3000

# L'argomento da riga di comando sovrascrive il file di configurazione
npx -y @pimzino/spec-workflow-mcp@latest --config config.toml --port 4000
# Risultato: port = 4000 (vince CLI)

Configurazioni Specifiche per Ambiente Copy Chapter

Configurazione Sviluppo Copy Section

# dev-config.toml
projectDir = "./src"
port = 3000
lang = "it"

[advanced]
debugMode = true
verboseLogging = true

Uso:

npx -y @pimzino/spec-workflow-mcp@latest --config dev-config.toml

Configurazione Produzione Copy Section

# prod-config.toml
projectDir = "/var/app"
port = 8080
lang = "it"

[advanced]
debugMode = false
verboseLogging = false

Uso:

npx -y @pimzino/spec-workflow-mcp@latest --config prod-config.toml

Configurazione Porta Copy Chapter

Intervallo Porte Valide Copy Section

Le porte devono essere comprese tra 1024 e 65535.

Porte Effimere Copy Section

Quando non viene specificata alcuna porta, il sistema seleziona automaticamente una porta effimera disponibile. Questo è consigliato per:

• Ambienti di sviluppo
• Progetti multipli simultanei
• Evitare conflitti di porta

Porte Fisse Copy Section

Usa porte fisse quando hai bisogno di:

• URL coerenti per i segnalibri
• Integrazione con altri strumenti
• Collaborazione di team con configurazioni condivise

Risoluzione Conflitti Porta Copy Section

Se una porta è già in uso:

1. Controlla cosa sta usando la porta:

   • Windows: netstat -an | findstr :3000
   • macOS/Linux: lsof -i :3000

2. Soluzioni:

   • Usa una porta diversa: --port 3001
   • Termina il processo che usa la porta
   • Ometti --port per usare una porta effimera

Configurazione Multi-Progetto Copy Chapter

Configurazioni Separate Copy Section

Crea configurazioni specifiche per progetto:

# Progetto A
project-a/
  .spec-workflow/
    config.toml  # port = 3000

# Progetto B
project-b/
  .spec-workflow/
    config.toml  # port = 3001

Configurazione Condivisa Copy Section

Usa una configurazione condivisa con sovrascritture:

# Config base condiviso
~/configs/spec-workflow-base.toml

# Sovrascritture specifiche per progetto
npx -y @pimzino/spec-workflow-mcp@latest \
  --config ~/configs/spec-workflow-base.toml \
  --port 3000 \
  /path/to/project-a

Configurazione Estensione VSCode Copy Chapter

L'estensione VSCode ha le proprie impostazioni:

1. Apri Impostazioni VSCode (Cmd/Ctrl + ,)
2. Cerca "Spec Workflow"
3. Configura:
   • Preferenza lingua
   • Notifiche sonore
   • Visibilità archivio
   • Intervallo auto-refresh

Risoluzione Problemi Configurazione Copy Chapter

Configurazione Non Caricata Copy Section

1. Verifica posizione file:

   bash Copy

   ls -la .spec-workflow/config.toml

2. Valida sintassi TOML:

   bash Copy

   # Installa strumento CLI toml
   npm install @iarna/toml
   
   # Valida
   toml .spec-workflow/config.toml

3. Verifica permessi:

   bash Copy

   # Assicurati che il file sia leggibile
   chmod 644 .spec-workflow/config.toml

Problemi Comuni Copy Section

Best Practice Copy Chapter

1. Usa controllo versione per i file di configurazione
2. Documenta impostazioni personalizzate nel README del progetto
3. Usa porte effimere in sviluppo
4. Mantieni dati sensibili fuori dai file di configurazione
5. Crea configurazioni specifiche per ambiente
6. Testa modifiche configurazione prima del deploy

Documentazione Correlata Copy Chapter

• Guida Utente - Usare il server configurato
• Guida Interfacce - Impostazioni dashboard ed estensione
• Risoluzione Problemi - Problemi comuni di configurazione

CONFIGURATION.Ja (`docs/CONFIGURATION.ja.md`) Copy Section

設定ガイド

このガイドは、Spec Workflow MCPのすべての設定オプションをカバーしています。

コマンドラインオプション Copy Chapter

基本的な使用方法 Copy Section

npx -y @pimzino/spec-workflow-mcp@latest [project-path] [options]

利用可能なオプション Copy Section

重要な注意事項 Copy Section

• 単一のダッシュボードインスタンス：ダッシュボードは一度に1つだけ実行されます。すべてのMCPサーバーが同じダッシュボードに接続します。
• デフォルトポート：ダッシュボードはデフォルトでポート5000を使用します。5000が使用できない場合のみ--portを使用してください。
• 別途ダッシュボード：常にMCPサーバーとは別にダッシュボードを実行してください。

使用例 Copy Chapter

典型的なワークフロー Copy Section

1. ダッシュボードを起動する（最初に一度だけ実行）：

# デフォルトポート5000を使用
npx -y @pimzino/spec-workflow-mcp@latest --dashboard

2. MCPサーバーを起動する（プロジェクトごとに1つ、別々のターミナルで）：

# プロジェクト1
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app1

# プロジェクト2
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app2

# プロジェクト3
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app3

すべてのプロジェクトが http://localhost:5000 のダッシュボードに表示されます

カスタムポートのダッシュボード Copy Section

ポート5000が使用できない場合のみカスタムポートを使用してください：

# ポート8080でダッシュボードを起動
npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080

環境変数 Copy Chapter

SPEC_WORKFLOW_HOME Copy Section

デフォルトのグローバル状態ディレクトリ（~/.spec-workflow-mcp）をオーバーライドします。これは$HOMEが読み取り専用のサンドボックス環境で役立ちます。

このディレクトリに保存されるファイル：

• activeProjects.json - プロジェクトレジストリ
• activeSession.json - ダッシュボードセッション情報
• settings.json - グローバル設定
• job-execution-history.json - ジョブ実行履歴
• migration.log - 実装ログ移行追跡

使用例：

# 絶対パス
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

# 相対パス（現在の作業ディレクトリに対して解決されます）
SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest .

# ダッシュボードモード用
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest --dashboard

サンドボックス環境（例：Codex CLI）：

Codex CLIのsandbox_mode=workspace-writeなどのサンドボックス環境で実行する場合は、SPEC_WORKFLOW_HOMEをワークスペース内の書き込み可能な場所に設定します：

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

ダッシュボードセッション管理 Copy Chapter

ダッシュボードは~/.spec-workflow-mcp/activeSession.json（または設定されている場合は$SPEC_WORKFLOW_HOME/activeSession.json）にセッション情報を保存します。このファイルは：

• 単一のダッシュボードインスタンスを強制
• MCPサーバーが実行中のダッシュボードを発見できるようにする
• ダッシュボードが停止すると自動的にクリーンアップされる

単一インスタンスの強制 Copy Section

一度に1つのダッシュボードのみを実行できます。2つ目のダッシュボードを起動しようとすると：

Dashboard is already running at: http://localhost:5000

You can:
  1. Use the existing dashboard at: http://localhost:5000
  2. Stop it first (Ctrl+C or kill PID), then start a new one

Note: Only one dashboard instance is needed for all your projects.

ポート管理 Copy Chapter

デフォルトポート：5000
カスタムポート：ポート5000が使用できない場合のみ--port <number>を使用

ポートの競合 Copy Section

ポート5000が別のサービスで既に使用されている場合：

Failed to start dashboard: Port 5000 is already in use.

This might be another service using port 5000.
To use a different port:
  spec-workflow-mcp --dashboard --port 8080

設定ファイル（非推奨） Copy Chapter

デフォルトの場所 Copy Section

サーバーは次の場所で設定を検索します：/.spec-workflow/config.toml

ファイル形式 Copy Section

設定はTOML形式を使用します。完全な例を以下に示します：

# プロジェクトディレクトリ（デフォルトは現在のディレクトリ）
projectDir = "/path/to/your/project"

# ダッシュボードポート（1024-65535）
port = 3456

# ダッシュボード専用モードで実行
dashboardOnly = false

# インターフェース言語
# オプション：en, ja, zh, es, pt, de, fr, ru, it, ko, ar
lang = "en"

# サウンド通知（VSCode拡張機能のみ）
[notifications]
enabled = true
volume = 0.5

# 詳細設定
[advanced]
# WebSocket再接続試行回数
maxReconnectAttempts = 10

# ファイルウォッチャー設定
[watcher]
enabled = true
debounceMs = 300

設定オプション Copy Section

基本設定

注意：autoStartDashboardオプションはv2.0.0で削除されました。ダッシュボードは--dashboardフラグでアクセスできる統合マルチプロジェクトモードを使用するようになりました。

言語オプション

• en - English
• ja - Japanese（日本語）
• zh - Chinese（中文）
• es - Spanish（Español）
• pt - Portuguese（Português）
• de - German（Deutsch）
• fr - French（Français）
• ru - Russian（Русский）
• it - Italian（Italiano）
• ko - Korean（한국어）
• ar - Arabic（العربية）

カスタム設定の作成 Copy Section

1. 例の設定をコピーします：

cp .spec-workflow/config.example.toml .spec-workflow/config.toml

2. 設定を編集します：

# 私のプロジェクト設定
projectDir = "/Users/myname/projects/myapp"
port = 3000
lang = "en"

3. 設定を使用します：

# 自動的に.spec-workflow/config.tomlを使用
npx -y @pimzino/spec-workflow-mcp@latest

# または明示的に指定
npx -y @pimzino/spec-workflow-mcp@latest --config .spec-workflow/config.toml

設定の優先順位 Copy Chapter

設定値は次の順序で適用されます（優先順位の高い順）：

1. コマンドライン引数 - 常に優先される
2. カスタム設定ファイル - --configで指定
3. デフォルト設定ファイル - .spec-workflow/config.toml
4. 組み込みデフォルト - フォールバック値

優先順位の例 Copy Section

# config.toml
port = 3000

# コマンドライン引数が設定ファイルをオーバーライド
npx -y @pimzino/spec-workflow-mcp@latest --config config.toml --port 4000
# 結果：port = 4000（CLIが優先）

環境固有の設定 Copy Chapter

開発設定 Copy Section

# dev-config.toml
projectDir = "./src"
port = 3000
lang = "en"

[advanced]
debugMode = true
verboseLogging = true

使用方法：

npx -y @pimzino/spec-workflow-mcp@latest --config dev-config.toml

本番設定 Copy Section

# prod-config.toml
projectDir = "/var/app"
port = 8080
lang = "en"

[advanced]
debugMode = false
verboseLogging = false

使用方法：

npx -y @pimzino/spec-workflow-mcp@latest --config prod-config.toml

ポート設定 Copy Chapter

有効なポート範囲 Copy Section

ポートは1024から65535の間である必要があります。

エフェメラルポート Copy Section

ポートが指定されていない場合、システムは自動的に利用可能なエフェメラルポートを選択します。これは以下の場合に推奨されます：

• 開発環境
• 複数の同時プロジェクト
• ポート競合の回避

固定ポート Copy Section

以下が必要な場合は固定ポートを使用してください：

• ブックマークのための一貫したURL
• 他のツールとの統合
• 共有設定を使用したチームコラボレーション

ポート競合の解決 Copy Section

ポートが既に使用されている場合：

1. ポートを使用しているものを確認：

   • Windows：netstat -an | findstr :3000
   • macOS/Linux：lsof -i :3000

2. 解決策：

   • 別のポートを使用：--port 3001
   • ポートを使用しているプロセスを終了
   • --portを省略してエフェメラルポートを使用

マルチプロジェクトセットアップ Copy Chapter

個別の設定 Copy Section

プロジェクト固有の設定を作成します：

# プロジェクトA
project-a/
  .spec-workflow/
    config.toml  # port = 3000

# プロジェクトB
project-b/
  .spec-workflow/
    config.toml  # port = 3001

共有設定 Copy Section

オーバーライドを含む共有設定を使用します：

# 共有ベース設定
~/configs/spec-workflow-base.toml

# プロジェクト固有のオーバーライド
npx -y @pimzino/spec-workflow-mcp@latest \
  --config ~/configs/spec-workflow-base.toml \
  --port 3000 \
  /path/to/project-a

VSCode拡張機能の設定 Copy Chapter

VSCode拡張機能には独自の設定があります：

1. VSCode設定を開く（Cmd/Ctrl + ,）
2. 「Spec Workflow」を検索
3. 設定：
   • 言語設定
   • サウンド通知
   • アーカイブの表示
   • 自動更新間隔

設定のトラブルシューティング Copy Chapter

設定が読み込まれない Copy Section

1. ファイルの場所を確認：

   bash Copy

   ls -la .spec-workflow/config.toml

2. TOML構文を検証：

   bash Copy

   # TOML CLIツールをインストール
   npm install @iarna/toml
   
   # 検証
   toml .spec-workflow/config.toml

3. 権限を確認：

   bash Copy

   # ファイルが読み取り可能であることを確認
   chmod 644 .spec-workflow/config.toml

一般的な問題 Copy Section

ベストプラクティス Copy Chapter

1. 設定ファイルにバージョン管理を使用
2. プロジェクトREADMEにカスタム設定を文書化
3. 開発ではエフェメラルポートを使用
4. 設定ファイルに機密データを含めない
5. 環境固有の設定を作成
6. デプロイ前に設定変更をテスト

関連ドキュメント Copy Chapter

• ユーザーガイド - 設定されたサーバーの使用
• インターフェースガイド - ダッシュボードと拡張機能の設定
• トラブルシューティング - 一般的な設定問題

CONFIGURATION.Ko (`docs/CONFIGURATION.ko.md`) Copy Section

구성 가이드

이 가이드는 Spec Workflow MCP의 모든 구성 옵션을 다룹니다.

명령줄 옵션 Copy Chapter

기본 사용법 Copy Section

npx -y @pimzino/spec-workflow-mcp@latest [project-path] [options]

사용 가능한 옵션 Copy Section

중요 참고사항 Copy Section

• 단일 대시보드 인스턴스: 한 번에 하나의 대시보드만 실행됩니다. 모든 MCP 서버가 동일한 대시보드에 연결됩니다.
• 기본 포트: 대시보드는 기본적으로 포트 5000을 사용합니다. 5000이 사용 불가능한 경우에만 --port를 사용하세요.
• 별도 대시보드: 항상 MCP 서버와 별도로 대시보드를 실행하세요.

사용 예제 Copy Chapter

일반적인 워크플로우 Copy Section

1. 대시보드 시작 (먼저 한 번만 수행):

# 기본 포트 5000 사용
npx -y @pimzino/spec-workflow-mcp@latest --dashboard

2. MCP 서버 시작 (프로젝트당 하나, 별도 터미널에서):

# 프로젝트 1
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app1

# 프로젝트 2
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app2

# 프로젝트 3
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app3

모든 프로젝트가 http://localhost:5000 의 대시보드에 표시됩니다.

사용자 지정 포트가 있는 대시보드 Copy Section

포트 5000을 사용할 수 없는 경우에만 사용자 지정 포트를 사용하세요:

# 포트 8080에서 대시보드 시작
npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080

환경 변수 Copy Chapter

SPEC_WORKFLOW_HOME Copy Section

기본 전역 상태 디렉터리(~/.spec-workflow-mcp)를 재정의합니다. $HOME이 읽기 전용인 샌드박스 환경에 유용합니다.

이 디렉터리에 저장되는 파일:

• activeProjects.json - 프로젝트 레지스트리
• activeSession.json - 대시보드 세션 정보
• settings.json - 전역 설정
• job-execution-history.json - 작업 실행 기록
• migration.log - 구현 로그 마이그레이션 추적

사용 예제:

# 절대 경로
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

# 상대 경로 (현재 작업 디렉터리에 대해 확인됨)
SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest .

# 대시보드 모드용
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest --dashboard

샌드박스 환경 (예: Codex CLI):

sandbox_mode=workspace-write가 있는 Codex CLI와 같은 샌드박스 환경에서 실행할 때 SPEC_WORKFLOW_HOME을 작업 공간 내의 쓰기 가능한 위치로 설정하세요:

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

대시보드 세션 관리 Copy Chapter

대시보드는 세션 정보를 ~/.spec-workflow-mcp/activeSession.json(또는 설정된 경우 $SPEC_WORKFLOW_HOME/activeSession.json)에 저장합니다. 이 파일은:

• 단일 대시보드 인스턴스 강제 적용
• MCP 서버가 실행 중인 대시보드를 찾을 수 있도록 허용
• 대시보드가 중지되면 자동으로 정리

단일 인스턴스 강제 적용 Copy Section

한 번에 하나의 대시보드만 실행할 수 있습니다. 두 번째 대시보드를 시작하려고 하면:

대시보드가 이미 실행 중입니다: http://localhost:5000

다음을 수행할 수 있습니다:
  1. 기존 대시보드 사용: http://localhost:5000
  2. 먼저 중지한 다음(Ctrl+C 또는 PID 종료) 새 대시보드 시작

참고: 모든 프로젝트에 하나의 대시보드 인스턴스만 필요합니다.

포트 관리 Copy Chapter

기본 포트: 5000
사용자 지정 포트: 포트 5000을 사용할 수 없는 경우에만 --port <number> 사용

포트 충돌 Copy Section

포트 5000이 다른 서비스에서 이미 사용 중인 경우:

대시보드 시작 실패: 포트 5000이 이미 사용 중입니다.

포트 5000을 사용하는 다른 서비스일 수 있습니다.
다른 포트를 사용하려면:
  spec-workflow-mcp --dashboard --port 8080

구성 파일 (사용 중단됨) Copy Chapter

기본 위치 Copy Section

서버는 다음 위치에서 구성을 찾습니다: /.spec-workflow/config.toml

파일 형식 Copy Section

구성은 TOML 형식을 사용합니다. 완전한 예제:

# 프로젝트 디렉터리 (기본값은 현재 디렉터리)
projectDir = "/path/to/your/project"

# 대시보드 포트 (1024-65535)
port = 3456

# 대시보드 전용 모드 실행
dashboardOnly = false

# 인터페이스 언어
# 옵션: en, ja, zh, es, pt, de, fr, ru, it, ko, ar
lang = "en"

# 사운드 알림 (VSCode 확장 프로그램만)
[notifications]
enabled = true
volume = 0.5

# 고급 설정
[advanced]
# WebSocket 재연결 시도
maxReconnectAttempts = 10

# 파일 감시자 설정
[watcher]
enabled = true
debounceMs = 300

구성 옵션 Copy Section

기본 설정

참고: autoStartDashboard 옵션은 v2.0.0에서 제거되었습니다. 대시보드는 이제 --dashboard 플래그를 통해 액세스할 수 있는 통합 다중 프로젝트 모드를 사용합니다.

언어 옵션

• en - English
• ja - Japanese (日本語)
• zh - Chinese (中文)
• es - Spanish (Español)
• pt - Portuguese (Português)
• de - German (Deutsch)
• fr - French (Français)
• ru - Russian (Русский)
• it - Italian (Italiano)
• ko - Korean (한국어)
• ar - Arabic (العربية)

사용자 지정 구성 생성 Copy Section

1. 예제 구성 복사:

cp .spec-workflow/config.example.toml .spec-workflow/config.toml

2. 구성 편집:

# 내 프로젝트 구성
projectDir = "/Users/myname/projects/myapp"
port = 3000
lang = "en"

3. 구성 사용:

# .spec-workflow/config.toml 자동 사용
npx -y @pimzino/spec-workflow-mcp@latest

# 또는 명시적으로 지정
npx -y @pimzino/spec-workflow-mcp@latest --config .spec-workflow/config.toml

구성 우선순위 Copy Chapter

구성 값은 다음 순서로 적용됩니다 (우선순위가 높은 것부터):

1. 명령줄 인수 - 항상 우선
2. 사용자 지정 구성 파일 - --config로 지정
3. 기본 구성 파일 - .spec-workflow/config.toml
4. 내장 기본값 - 폴백 값

예제 우선순위 Copy Section

# config.toml
port = 3000

# 명령줄 인수가 구성 파일 재정의
npx -y @pimzino/spec-workflow-mcp@latest --config config.toml --port 4000
# 결과: port = 4000 (CLI 승리)

환경별 구성 Copy Chapter

개발 구성 Copy Section

# dev-config.toml
projectDir = "./src"
port = 3000
lang = "en"

[advanced]
debugMode = true
verboseLogging = true

사용법:

npx -y @pimzino/spec-workflow-mcp@latest --config dev-config.toml

프로덕션 구성 Copy Section

# prod-config.toml
projectDir = "/var/app"
port = 8080
lang = "en"

[advanced]
debugMode = false
verboseLogging = false

사용법:

npx -y @pimzino/spec-workflow-mcp@latest --config prod-config.toml

포트 구성 Copy Chapter

유효한 포트 범위 Copy Section

포트는 1024에서 65535 사이여야 합니다.

임시 포트 Copy Section

포트가 지정되지 않은 경우 시스템이 자동으로 사용 가능한 임시 포트를 선택합니다. 다음에 권장됩니다:

• 개발 환경
• 여러 동시 프로젝트
• 포트 충돌 방지

고정 포트 Copy Section

다음이 필요할 때 고정 포트 사용:

• 북마크를 위한 일관된 URL
• 다른 도구와의 통합
• 공유 구성을 통한 팀 협업

포트 충돌 해결 Copy Section

포트가 이미 사용 중인 경우:

1. 포트를 사용하는 것 확인:

   • Windows: netstat -an | findstr :3000
   • macOS/Linux: lsof -i :3000

2. 해결책:

   • 다른 포트 사용: --port 3001
   • 포트를 사용하는 프로세스 종료
   • --port를 생략하여 임시 포트 사용

다중 프로젝트 설정 Copy Chapter

별도 구성 Copy Section

프로젝트별 구성 생성:

# 프로젝트 A
project-a/
  .spec-workflow/
    config.toml  # port = 3000

# 프로젝트 B
project-b/
  .spec-workflow/
    config.toml  # port = 3001

공유 구성 Copy Section

재정의가 있는 공유 구성 사용:

# 공유 기본 구성
~/configs/spec-workflow-base.toml

# 프로젝트별 재정의
npx -y @pimzino/spec-workflow-mcp@latest \
  --config ~/configs/spec-workflow-base.toml \
  --port 3000 \
  /path/to/project-a

VSCode 확장 프로그램 구성 Copy Chapter

VSCode 확장 프로그램에는 자체 설정이 있습니다:

1. VSCode 설정 열기 (Cmd/Ctrl + ,)
2. "Spec Workflow" 검색
3. 구성:
   • 언어 기본 설정
   • 사운드 알림
   • 아카이브 가시성
   • 자동 새로고침 간격

구성 문제 해결 Copy Chapter

구성이 로드되지 않음 Copy Section

1. 파일 위치 확인:

   bash Copy

   ls -la .spec-workflow/config.toml

2. TOML 구문 검증:

   bash Copy

   # TOML CLI 도구 설치
   npm install @iarna/toml
   
   # 검증
   toml .spec-workflow/config.toml

3. 권한 확인:

   bash Copy

   # 파일이 읽기 가능한지 확인
   chmod 644 .spec-workflow/config.toml

일반적인 문제 Copy Section

모범 사례 Copy Chapter

1. 구성 파일에 버전 제어 사용
2. 프로젝트 README에 사용자 지정 설정 문서화
3. 개발에서 임시 포트 사용
4. 구성 파일에서 민감한 데이터 제외
5. 환경별 구성 생성
6. 배포 전 구성 변경 사항 테스트

관련 문서 Copy Chapter

• 사용자 가이드 - 구성된 서버 사용
• 인터페이스 가이드 - 대시보드 및 확장 프로그램 설정
• 문제 해결 - 일반적인 구성 문제

CONFIGURATION (`docs/CONFIGURATION.md`) Copy Section

Configuration Guide

This guide covers all configuration options for Spec Workflow MCP.

Command-Line Options Copy Chapter

Basic Usage Copy Section

npx -y @pimzino/spec-workflow-mcp@latest [project-path] [options]

Available Options Copy Section

Important Notes Copy Section

• Single Dashboard Instance: Only one dashboard runs at a time. All MCP servers connect to the same dashboard.
• Default Port: Dashboard uses port 5000 by default. Use --port only if 5000 is unavailable.
• Separate Dashboard: Always run the dashboard separately from MCP servers.

Usage Examples Copy Chapter

Typical Workflow Copy Section

1. Start the Dashboard (do this first, only once):

# Uses default port 5000
npx -y @pimzino/spec-workflow-mcp@latest --dashboard

2. Start MCP Servers (one per project, in separate terminals):

# Project 1
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app1

# Project 2
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app2

# Project 3
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app3

All projects will appear in the dashboard at http://localhost:5000

Dashboard with Custom Port Copy Section

Only use a custom port if port 5000 is unavailable:

# Start dashboard on port 8080
npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080

Environment Variables Copy Chapter

SPEC_WORKFLOW_HOME Copy Section

Override the default global state directory (~/.spec-workflow-mcp). This is useful for sandboxed environments where $HOME is read-only.

Files stored in this directory:

• activeProjects.json - Project registry
• activeSession.json - Dashboard session info
• settings.json - Global settings
• job-execution-history.json - Job execution history
• migration.log - Implementation log migration tracking

Usage examples:

# Absolute path
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

# Relative path (resolved against current working directory)
SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest .

# For dashboard mode
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest --dashboard

Sandboxed environments (e.g., Codex CLI):

When running in sandboxed environments like Codex CLI with sandbox_mode=workspace-write, set SPEC_WORKFLOW_HOME to a writable location within your workspace:

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

SPEC_WORKFLOW_SHARED_ROOT Copy Section

Override the automatic git worktree detection. By default, when running in a git worktree, specs are stored in the main repository's .spec-workflow/ directory so all worktrees share the same specs.

Automatic behavior (no env var set):

• Main git repo: Specs stored in /.spec-workflow/
• Git worktree: Specs stored in <main-repo>/.spec-workflow/ (shared with all worktrees)
• Non-git directory: Specs stored in /.spec-workflow/

When to use this variable:

Use SPEC_WORKFLOW_SHARED_ROOT to override the automatic detection:

# Force specs to be stored in the current worktree (opt-out of sharing)
SPEC_WORKFLOW_SHARED_ROOT=$(pwd) npx -y @pimzino/spec-workflow-mcp@latest .

# Force a specific shared location
SPEC_WORKFLOW_SHARED_ROOT=/path/to/shared/specs npx -y @pimzino/spec-workflow-mcp@latest ~/my-worktree

Git worktree example:

# In main repo: /home/user/myproject
git worktree add ../myproject-feature feature-branch

# Start MCP server in worktree - specs automatically shared with main repo
cd ../myproject-feature
npx -y @pimzino/spec-workflow-mcp@latest .
# Output: Git worktree detected. Using main repo: /home/user/myproject

# Both the main repo and worktree see the same specs in /home/user/myproject/.spec-workflow/

Git Worktree Configuration Copy Chapter

Git worktrees are fully supported with two operating modes:

Default Mode: Shared Specs Copy Section

By default, all worktrees of a repository share the same .spec-workflow/ directory (stored in the main repo). However, each worktree registers as its own project in the dashboard with a distinct identity.

Dashboard behavior:

• Each worktree appears as a separate project in the project dropdown
• Project names show repo · worktree format (e.g., myproject · feature-auth)
• Approval file resolution prioritizes the worktree path, then falls back to shared workflow root

# Main repo
npx -y @pimzino/spec-workflow-mcp@latest ~/myproject
# Dashboard shows: "myproject"

# Worktree
npx -y @pimzino/spec-workflow-mcp@latest ~/myproject-feature
# Dashboard shows: "myproject · myproject-feature"
# Specs are shared from ~/myproject/.spec-workflow/

Isolated Mode: Workspace-Local Specs Copy Section

Use --no-shared-worktree-specs when you want each worktree to have its own independent .spec-workflow/ directory:

npx -y @pimzino/spec-workflow-mcp@latest ~/myproject-feature --no-shared-worktree-specs
# Output: Shared worktree specs disabled. Using workspace-local .spec-workflow.
# Specs stored in ~/myproject-feature/.spec-workflow/

When to use isolated mode:

• Different worktrees have completely different feature scopes
• You want to experiment with specs without affecting other worktrees
• Team members working on different worktrees need independent spec histories

Comparison:

Dashboard Session Management Copy Chapter

The dashboard stores its session information in ~/.spec-workflow-mcp/activeSession.json (or $SPEC_WORKFLOW_HOME/activeSession.json if set). This file:

• Enforces single dashboard instance
• Allows MCP servers to discover the running dashboard
• Automatically cleans up when dashboard stops

Single Instance Enforcement Copy Section

Only one dashboard can run at any time. If you try to start a second dashboard:

Dashboard is already running at: http://localhost:5000

You can:
  1. Use the existing dashboard at: http://localhost:5000
  2. Stop it first (Ctrl+C or kill PID), then start a new one

Note: Only one dashboard instance is needed for all your projects.

Port Management Copy Chapter

Default Port: 5000
Custom Port: Use --port <number> only if port 5000 is unavailable

Port Conflicts Copy Section

If port 5000 is already in use by another service:

Failed to start dashboard: Port 5000 is already in use.

This might be another service using port 5000.
To use a different port:
  spec-workflow-mcp --dashboard --port 8080

Configuration File (Deprecated) Copy Chapter

Default Location Copy Section

The server looks for configuration at: /.spec-workflow/config.toml

File Format Copy Section

Configuration uses TOML format. Here's a complete example:

# Project directory (defaults to current directory)
projectDir = "/path/to/your/project"

# Dashboard port (1024-65535)
port = 3456

# Run dashboard-only mode
dashboardOnly = false

# Interface language
# Options: en, ja, zh, es, pt, de, fr, ru, it, ko, ar
lang = "en"

# Sound notifications (VSCode extension only)
[notifications]
enabled = true
volume = 0.5

# Advanced settings
[advanced]
# WebSocket reconnection attempts
maxReconnectAttempts = 10

# File watcher settings
[watcher]
enabled = true
debounceMs = 300

Configuration Options Copy Section

Basic Settings

Note: The autoStartDashboard option was removed in v2.0.0. The dashboard now uses a unified multi-project mode accessible via --dashboard flag.

Language Options

• en - English
• ja - Japanese (日本語)
• zh - Chinese (中文)
• es - Spanish (Español)
• pt - Portuguese (Português)
• de - German (Deutsch)
• fr - French (Français)
• ru - Russian (Русский)
• it - Italian (Italiano)
• ko - Korean (한국어)
• ar - Arabic (العربية)

Creating a Custom Configuration Copy Section

1. Copy the example configuration:

cp .spec-workflow/config.example.toml .spec-workflow/config.toml

2. Edit the configuration:

# My project configuration
projectDir = "/Users/myname/projects/myapp"
port = 3000
lang = "en"

3. Use the configuration:

# Uses .spec-workflow/config.toml automatically
npx -y @pimzino/spec-workflow-mcp@latest

# Or specify explicitly
npx -y @pimzino/spec-workflow-mcp@latest --config .spec-workflow/config.toml

Configuration Precedence Copy Chapter

Configuration values are applied in this order (highest to lowest priority):

1. Command-line arguments - Always take precedence
2. Custom config file - Specified with --config
3. Default config file - .spec-workflow/config.toml
4. Built-in defaults - Fallback values

Example Precedence Copy Section

# config.toml
port = 3000

# Command-line argument overrides config file
npx -y @pimzino/spec-workflow-mcp@latest --config config.toml --port 4000
# Result: port = 4000 (CLI wins)

Environment-Specific Configurations Copy Chapter

Development Configuration Copy Section

# dev-config.toml
projectDir = "./src"
port = 3000
lang = "en"

[advanced]
debugMode = true
verboseLogging = true

Usage:

npx -y @pimzino/spec-workflow-mcp@latest --config dev-config.toml

Production Configuration Copy Section

# prod-config.toml
projectDir = "/var/app"
port = 8080
lang = "en"

[advanced]
debugMode = false
verboseLogging = false

Usage:

npx -y @pimzino/spec-workflow-mcp@latest --config prod-config.toml

Port Configuration Copy Chapter

Valid Port Range Copy Section

Ports must be between 1024 and 65535.

Ephemeral Ports Copy Section

When no port is specified, the system automatically selects an available ephemeral port. This is recommended for:

• Development environments
• Multiple simultaneous projects
• Avoiding port conflicts

Fixed Ports Copy Section

Use fixed ports when you need:

• Consistent URLs for bookmarking
• Integration with other tools
• Team collaboration with shared configurations

Port Conflict Resolution Copy Section

If a port is already in use:

1. Check what's using the port:

   • Windows: netstat -an | findstr :3000
   • macOS/Linux: lsof -i :3000

2. Solutions:

   • Use a different port: --port 3001
   • Kill the process using the port
   • Omit --port to use an ephemeral port

Multi-Project Setup Copy Chapter

Separate Configurations Copy Section

Create project-specific configurations:

# Project A
project-a/
  .spec-workflow/
    config.toml  # port = 3000

# Project B
project-b/
  .spec-workflow/
    config.toml  # port = 3001

Shared Configuration Copy Section

Use a shared configuration with overrides:

# Shared base config
~/configs/spec-workflow-base.toml

# Project-specific overrides
npx -y @pimzino/spec-workflow-mcp@latest \
  --config ~/configs/spec-workflow-base.toml \
  --port 3000 \
  /path/to/project-a

VSCode Extension Configuration Copy Chapter

The VSCode extension has its own settings:

1. Open VSCode Settings (Cmd/Ctrl + ,)
2. Search for "Spec Workflow"
3. Configure:
   • Language preference
   • Sound notifications
   • Archive visibility
   • Auto-refresh interval

Troubleshooting Configuration Copy Chapter

Configuration Not Loading Copy Section

1. Check file location:

   bash Copy

   ls -la .spec-workflow/config.toml

2. Validate TOML syntax:

   bash Copy

   # Install toml CLI tool
   npm install @iarna/toml
   
   # Validate
   toml .spec-workflow/config.toml

3. Check permissions:

   bash Copy

   # Ensure file is readable
   chmod 644 .spec-workflow/config.toml

Common Issues Copy Section

Best Practices Copy Chapter

1. Use version control for configuration files
2. Document custom settings in your project README
3. Use ephemeral ports in development
4. Keep sensitive data out of configuration files
5. Create environment-specific configurations
6. Test configuration changes before deploying

Related Documentation Copy Chapter

• User Guide - Using the configured server
• Interfaces Guide - Dashboard and extension settings
• Troubleshooting - Common configuration issues

CONFIGURATION.Pt (`docs/CONFIGURATION.pt.md`) Copy Section

Guia de Configuração

Este guia cobre todas as opções de configuração para Spec Workflow MCP.

Opções de Linha de Comando Copy Chapter

Uso Básico Copy Section

npx -y @pimzino/spec-workflow-mcp@latest [project-path] [options]

Opções Disponíveis Copy Section

Notas Importantes Copy Section

• Instância Única do Dashboard: Apenas um dashboard é executado por vez. Todos os servidores MCP se conectam ao mesmo dashboard.
• Porta Padrão: O dashboard usa a porta 5000 por padrão. Use --port apenas se 5000 não estiver disponível.
• Dashboard Separado: Sempre execute o dashboard separadamente dos servidores MCP.

Exemplos de Uso Copy Chapter

Fluxo de Trabalho Típico Copy Section

1. Iniciar o Dashboard (faça isso primeiro, apenas uma vez):

# Usa a porta padrão 5000
npx -y @pimzino/spec-workflow-mcp@latest --dashboard

2. Iniciar Servidores MCP (um por projeto, em terminais separados):

# Projeto 1
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app1

# Projeto 2
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app2

# Projeto 3
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app3

Todos os projetos aparecerão no dashboard em http://localhost:5000

Dashboard com Porta Personalizada Copy Section

Use uma porta personalizada apenas se a porta 5000 não estiver disponível:

# Inicia o dashboard na porta 8080
npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080

Variáveis de Ambiente Copy Chapter

SPEC_WORKFLOW_HOME Copy Section

Substitui o diretório de estado global padrão (~/.spec-workflow-mcp). Útil para ambientes isolados onde $HOME é somente leitura.

Arquivos armazenados neste diretório:

• activeProjects.json - Registro de projetos
• activeSession.json - Informações de sessão do dashboard
• settings.json - Configurações globais
• job-execution-history.json - Histórico de execução de trabalhos
• migration.log - Rastreamento de migração de logs de implementação

Exemplos de uso:

# Caminho absoluto
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

# Caminho relativo (resolvido em relação ao diretório de trabalho atual)
SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest .

# Para modo dashboard
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest --dashboard

Ambientes isolados (por exemplo, Codex CLI):

Ao executar em ambientes isolados como Codex CLI com sandbox_mode=workspace-write, defina SPEC_WORKFLOW_HOME para um local gravável dentro do seu workspace:

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

Gerenciamento de Sessão do Dashboard Copy Chapter

O dashboard armazena suas informações de sessão em ~/.spec-workflow-mcp/activeSession.json (ou $SPEC_WORKFLOW_HOME/activeSession.json se definido). Este arquivo:

• Impõe instância única do dashboard
• Permite que servidores MCP descubram o dashboard em execução
• Limpa automaticamente quando o dashboard para

Imposição de Instância Única Copy Section

Apenas um dashboard pode ser executado por vez. Se você tentar iniciar um segundo dashboard:

Dashboard já está em execução em: http://localhost:5000

Você pode:
  1. Usar o dashboard existente em: http://localhost:5000
  2. Pará-lo primeiro (Ctrl+C ou kill PID), depois iniciar um novo

Nota: Apenas uma instância do dashboard é necessária para todos os seus projetos.

Gerenciamento de Portas Copy Chapter

Porta Padrão: 5000
Porta Personalizada: Use --port <number> apenas se a porta 5000 não estiver disponível

Conflitos de Porta Copy Section

Se a porta 5000 já estiver em uso por outro serviço:

Falha ao iniciar dashboard: Porta 5000 já está em uso.

Pode ser outro serviço usando a porta 5000.
Para usar uma porta diferente:
  spec-workflow-mcp --dashboard --port 8080

Arquivo de Configuração (Descontinuado) Copy Chapter

Localização Padrão Copy Section

O servidor procura a configuração em: /.spec-workflow/config.toml

Formato do Arquivo Copy Section

A configuração usa formato TOML. Aqui está um exemplo completo:

# Diretório do projeto (padrão: diretório atual)
projectDir = "/path/to/your/project"

# Porta do dashboard (1024-65535)
port = 3456

# Executar apenas modo dashboard
dashboardOnly = false

# Idioma da interface
# Opções: en, ja, zh, es, pt, de, fr, ru, it, ko, ar
lang = "pt"

# Notificações sonoras (apenas extensão VSCode)
[notifications]
enabled = true
volume = 0.5

# Configurações avançadas
[advanced]
# Tentativas de reconexão WebSocket
maxReconnectAttempts = 10

# Configurações do observador de arquivos
[watcher]
enabled = true
debounceMs = 300

Opções de Configuração Copy Section

Configurações Básicas

Nota: A opção autoStartDashboard foi removida na v2.0.0. O dashboard agora usa um modo multi-projeto unificado acessível via flag --dashboard.

Opções de Idioma

• en - English
• ja - Japanese (日本語)
• zh - Chinese (中文)
• es - Spanish (Español)
• pt - Portuguese (Português)
• de - German (Deutsch)
• fr - French (Français)
• ru - Russian (Русский)
• it - Italian (Italiano)
• ko - Korean (한국어)
• ar - Arabic (العربية)

Criando uma Configuração Personalizada Copy Section

1. Copie a configuração de exemplo:

cp .spec-workflow/config.example.toml .spec-workflow/config.toml

2. Edite a configuração:

# Configuração do meu projeto
projectDir = "/Users/myname/projects/myapp"
port = 3000
lang = "pt"

3. Use a configuração:

# Usa .spec-workflow/config.toml automaticamente
npx -y @pimzino/spec-workflow-mcp@latest

# Ou especifique explicitamente
npx -y @pimzino/spec-workflow-mcp@latest --config .spec-workflow/config.toml

Precedência de Configuração Copy Chapter

Os valores de configuração são aplicados nesta ordem (maior para menor prioridade):

1. Argumentos de linha de comando - Sempre têm precedência
2. Arquivo de configuração personalizado - Especificado com --config
3. Arquivo de configuração padrão - .spec-workflow/config.toml
4. Padrões internos - Valores de fallback

Exemplo de Precedência Copy Section

# config.toml
port = 3000

# Argumento de linha de comando substitui arquivo de configuração
npx -y @pimzino/spec-workflow-mcp@latest --config config.toml --port 4000
# Resultado: port = 4000 (CLI vence)

Configurações Específicas do Ambiente Copy Chapter

Configuração de Desenvolvimento Copy Section

# dev-config.toml
projectDir = "./src"
port = 3000
lang = "pt"

[advanced]
debugMode = true
verboseLogging = true

Uso:

npx -y @pimzino/spec-workflow-mcp@latest --config dev-config.toml

Configuração de Produção Copy Section

# prod-config.toml
projectDir = "/var/app"
port = 8080
lang = "pt"

[advanced]
debugMode = false
verboseLogging = false

Uso:

npx -y @pimzino/spec-workflow-mcp@latest --config prod-config.toml

Configuração de Porta Copy Chapter

Intervalo de Porta Válido Copy Section

As portas devem estar entre 1024 e 65535.

Portas Efêmeras Copy Section

Quando nenhuma porta é especificada, o sistema seleciona automaticamente uma porta efêmera disponível. Recomendado para:

• Ambientes de desenvolvimento
• Múltiplos projetos simultâneos
• Evitar conflitos de porta

Portas Fixas Copy Section

Use portas fixas quando precisar:

• URLs consistentes para favoritos
• Integração com outras ferramentas
• Colaboração em equipe com configurações compartilhadas

Resolução de Conflito de Porta Copy Section

Se uma porta já estiver em uso:

1. Verifique o que está usando a porta:

   • Windows: netstat -an | findstr :3000
   • macOS/Linux: lsof -i :3000

2. Soluções:

   • Use uma porta diferente: --port 3001
   • Encerre o processo usando a porta
   • Omita --port para usar uma porta efêmera

Configuração Multi-Projeto Copy Chapter

Configurações Separadas Copy Section

Crie configurações específicas do projeto:

# Projeto A
project-a/
  .spec-workflow/
    config.toml  # port = 3000

# Projeto B
project-b/
  .spec-workflow/
    config.toml  # port = 3001

Configuração Compartilhada Copy Section

Use uma configuração compartilhada com substituições:

# Configuração base compartilhada
~/configs/spec-workflow-base.toml

# Substituições específicas do projeto
npx -y @pimzino/spec-workflow-mcp@latest \
  --config ~/configs/spec-workflow-base.toml \
  --port 3000 \
  /path/to/project-a

Configuração da Extensão VSCode Copy Chapter

A extensão VSCode tem suas próprias configurações:

1. Abra Configurações do VSCode (Cmd/Ctrl + ,)
2. Pesquise "Spec Workflow"
3. Configure:
   • Preferência de idioma
   • Notificações sonoras
   • Visibilidade do arquivo
   • Intervalo de atualização automática

Solução de Problemas de Configuração Copy Chapter

Configuração Não Carregando Copy Section

1. Verifique a localização do arquivo:

   bash Copy

   ls -la .spec-workflow/config.toml

2. Valide a sintaxe TOML:

   bash Copy

   # Instalar ferramenta CLI TOML
   npm install @iarna/toml
   
   # Validar
   toml .spec-workflow/config.toml

3. Verifique as permissões:

   bash Copy

   # Certifique-se de que o arquivo é legível
   chmod 644 .spec-workflow/config.toml

Problemas Comuns Copy Section

Melhores Práticas Copy Chapter

1. Use controle de versão para arquivos de configuração
2. Documente configurações personalizadas no README do seu projeto
3. Use portas efêmeras em desenvolvimento
4. Mantenha dados sensíveis fora dos arquivos de configuração
5. Crie configurações específicas do ambiente
6. Teste mudanças de configuração antes de implantar

Documentação Relacionada Copy Chapter

• Guia do Usuário - Usando o servidor configurado
• Guia de Interfaces - Configurações do dashboard e extensão
• Solução de Problemas - Problemas comuns de configuração

CONFIGURATION.Ru (`docs/CONFIGURATION.ru.md`) Copy Section

Руководство по конфигурации

Это руководство охватывает все параметры конфигурации для Spec Workflow MCP.

Параметры командной строки Copy Chapter

Базовое использование Copy Section

npx -y @pimzino/spec-workflow-mcp@latest [project-path] [options]

Доступные параметры Copy Section

Важные замечания Copy Section

• Один экземпляр панели управления: Запускается только одна панель управления одновременно. Все серверы MCP подключаются к одной панели.
• Порт по умолчанию: Панель управления использует порт 5000 по умолчанию. Используйте --port только если 5000 недоступен.
• Отдельная панель управления: Всегда запускайте панель управления отдельно от серверов MCP.

Примеры использования Copy Chapter

Типичный рабочий процесс Copy Section

1. Запустите панель управления (сделайте это первым, только один раз):

# Использует порт 5000 по умолчанию
npx -y @pimzino/spec-workflow-mcp@latest --dashboard

2. Запустите серверы MCP (по одному на проект, в отдельных терминалах):

# Проект 1
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app1

# Проект 2
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app2

# Проект 3
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/app3

Все проекты появятся на панели управления по адресу http://localhost:5000

Панель управления с пользовательским портом Copy Section

Используйте пользовательский порт только если порт 5000 недоступен:

# Запустить панель управления на порту 8080
npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080

Переменные окружения Copy Chapter

SPEC_WORKFLOW_HOME Copy Section

Переопределяет каталог глобального состояния по умолчанию (~/.spec-workflow-mcp). Это полезно для изолированных сред, где $HOME доступен только для чтения.

Файлы, хранящиеся в этом каталоге:

• activeProjects.json - Реестр проектов
• activeSession.json - Информация о сеансе панели управления
• settings.json - Глобальные настройки
• job-execution-history.json - История выполнения задач
• migration.log - Отслеживание миграции журнала реализации

Примеры использования:

# Абсолютный путь
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

# Относительный путь (разрешается относительно текущего рабочего каталога)
SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest .

# Для режима панели управления
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest --dashboard

Изолированные среды (например, Codex CLI):

При работе в изолированных средах, таких как Codex CLI с sandbox_mode=workspace-write, установите SPEC_WORKFLOW_HOME на доступное для записи место в вашем рабочем пространстве:

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace

Управление сеансом панели управления Copy Chapter

Панель управления хранит информацию о сеансе в ~/.spec-workflow-mcp/activeSession.json (или $SPEC_WORKFLOW_HOME/activeSession.json, если установлено). Этот файл:

• Обеспечивает один экземпляр панели управления
• Позволяет серверам MCP обнаружить работающую панель управления
• Автоматически очищается при остановке панели управления

Обеспечение одного экземпляра Copy Section

Только одна панель управления может работать одновременно. Если вы попытаетесь запустить вторую панель управления:

Dashboard is already running at: http://localhost:5000

You can:
  1. Use the existing dashboard at: http://localhost:5000
  2. Stop it first (Ctrl+C or kill PID), then start a new one

Note: Only one dashboard instance is needed for all your projects.

Управление портами Copy Chapter

Порт по умолчанию: 5000
Пользовательский порт: Используйте --port <number> только если порт 5000 недоступен

Конфликты портов Copy Section

Если порт 5000 уже используется другим сервисом:

Failed to start dashboard: Port 5000 is already in use.

This might be another service using port 5000.
To use a different port:
  spec-workflow-mcp --dashboard --port 8080

Конфигурационный файл (устарело) Copy Chapter

Расположение по умолчанию Copy Section

Сервер ищет конфигурацию по адресу: /.spec-workflow/config.toml

Формат файла Copy Section

Конфигурация использует формат TOML. Вот полный пример:

# Каталог проекта (по умолчанию текущий каталог)
projectDir = "/path/to/your/project"

# Порт панели управления (1024-65535)
port = 3456

# Запустить режим только панели управления
dashboardOnly = false

# Язык интерфейса
# Варианты: en, ja, zh, es, pt, de, fr, ru, it, ko, ar
lang = "en"

# Звуковые уведомления (только расширение VSCode)
[notifications]
enabled = true
volume = 0.5

# Дополнительные настройки
[advanced]
# Попытки повторного подключения WebSocket
maxReconnectAttempts = 10

# Настройки наблюдателя файлов
[watcher]
enabled = true
debounceMs = 300

Параметры конфигурации Copy Section

Базовые настройки

Примечание: Параметр autoStartDashboard был удален в версии 2.0.0. Панель управления теперь использует унифицированный многопроектный режим, доступный через флаг --dashboard.

Языковые параметры

• en - English
• ja - Japanese (日本語)
• zh - Chinese (中文)
• es - Spanish (Español)
• pt - Portuguese (Português)
• de - German (Deutsch)
• fr - French (Français)
• ru - Russian (Русский)
• it - Italian (Italiano)
• ko - Korean (한국어)
• ar - Arabic (العربية)

Создание пользовательской конфигурации Copy Section

1. Скопируйте пример конфигурации:

cp .spec-workflow/config.example.toml .spec-workflow/config.toml

2. Отредактируйте конфигурацию:

# Конфигурация моего проекта
projectDir = "/Users/myname/projects/myapp"
port = 3000
lang = "en"

3. Используйте конфигурацию:

# Использует .spec-workflow/config.toml автоматически
npx -y @pimzino/spec-workflow-mcp@latest

# Или укажите явно
npx -y @pimzino/spec-workflow-mcp@latest --config .spec-workflow/config.toml

Приоритет конфигурации Copy Chapter

Значения конфигурации применяются в следующем порядке (от наивысшего к низшему приоритету):

1. Аргументы командной строки - Всегда имеют приоритет
2. Пользовательский конфигурационный файл - Указанный с --config
3. Конфигурационный файл по умолчанию - .spec-workflow/config.toml
4. Встроенные значения по умолчанию - Резервные значения

Пример приоритета Copy Section

# config.toml
port = 3000

# Аргумент командной строки переопределяет конфигурационный файл
npx -y @pimzino/spec-workflow-mcp@latest --config config.toml --port 4000
# Результат: port = 4000 (CLI выигрывает)

Конфигурации для конкретных сред Copy Chapter

Конфигурация для разработки Copy Section

# dev-config.toml
projectDir = "./src"
port = 3000
lang = "en"

[advanced]
debugMode = true
verboseLogging = true

Использование:

npx -y @pimzino/spec-workflow-mcp@latest --config dev-config.toml

Производственная конфигурация Copy Section

# prod-config.toml
projectDir = "/var/app"
port = 8080
lang = "en"

[advanced]
debugMode = false
verboseLogging = false

Использование:

npx -y @pimzino/spec-workflow-mcp@latest --config prod-config.toml

Конфигурация порта Copy Chapter

Допустимый диапазон портов Copy Section

Порты должны быть в диапазоне от 1024 до 65535.

Эфемерные порты Copy Section

Когда порт не указан, система автоматически выбирает доступный эфемерный порт. Это рекомендуется для:

• Сред разработки
• Нескольких одновременных проектов
• Избежания конфликтов портов

Фиксированные порты Copy Section

Используйте фиксированные порты, когда вам нужно:

• Последовательные URL для закладок
• Интеграция с другими инструментами
• Совместная работа в команде с общими конфигурациями

Разрешение конфликтов портов Copy Section

Если порт уже используется:

1. Проверьте, что использует порт:

   • Windows: netstat -an | findstr :3000
   • macOS/Linux: lsof -i :3000

2. Решения:

   • Используйте другой порт: --port 3001
   • Завершите процесс, использующий порт
   • Пропустите --port для использования эфемерного порта

Настройка нескольких проектов Copy Chapter

Отдельные конфигурации Copy Section

Создайте конфигурации для конкретных проектов:

# Проект A
project-a/
  .spec-workflow/
    config.toml  # port = 3000

# Проект B
project-b/
  .spec-workflow/
    config.toml  # port = 3001

Общая конфигурация Copy Section

Используйте общую конфигурацию с переопределениями:

# Общая базовая конфигурация
~/configs/spec-workflow-base.toml

# Переопределения для конкретных проектов
npx -y @pimzino/spec-workflow-mcp@latest \
  --config ~/configs/spec-workflow-base.toml \
  --port 3000 \
  /path/to/project-a

Конфигурация расширения VSCode Copy Chapter

Расширение VSCode имеет свои настройки:

1. Откройте настройки VSCode (Cmd/Ctrl + ,)
2. Найдите "Spec Workflow"
3. Настройте:
   • Языковые предпочтения
   • Звуковые уведомления
   • Видимость архива
   • Интервал автообновления