### Initial Setup - Bash

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/developer-guide.md

Commands to clone the repository, install dependencies, and build the project.  Requires Node.js and npm.  The VS Code extension installation is optional.

```bash
# Clone the repository

```

```bash
git clone <repository-url>
```

```bash
# Install dependencies

```

```bash
npm install
```

```bash
# Build everything

```

```bash
npm run build
```

--------------------------------

### Starting MCP Server

Source: https://context7.com/pimzino/spec-workflow-mcp/llms.txt

Instructions and examples for starting the MCP server for a specific project. The server facilitates communication between AI clients via stdio transport.

```APIDOC
## Starting MCP Server

Start MCP server for a specific project. The server connects to AI clients via stdio transport.

### Usage

#### Start MCP server for current directory
```bash
npx -y @pimzino/spec-workflow-mcp@latest
```

#### Start MCP server for specific project
```bash
npx -y @pimzino/spec-workflow-mcp@latest /path/to/project
```

#### Start with home directory expansion
```bash
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/my-app
```

### Parameters

- **projectPath** (string, optional) - The path to the project directory. If not provided, the current directory is used.
```

--------------------------------

### TOML Configuration Example

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/CONFIGURATION.md

Example of a TOML configuration file. This format is used for defining various settings, such as port numbers and project directories. It supports nested tables for advanced configurations.

```toml
# config.toml
port = 3000

```

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

[advanced]
debugMode = true
verboseLogging = true

```

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

[advanced]
debugMode = false
verboseLogging = false

```

--------------------------------

### Install VSCode Extension (CLI)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md

Command to install the Spec Workflow MCP VSCode Extension directly from the command line.

```bash
code --install-extension Pimzino.spec-workflow-mcp
```

--------------------------------

### TypeScript: Complete Spec Workflow Example

Source: https://context7.com/pimzino/spec-workflow-mcp/llms.txt

A comprehensive TypeScript example demonstrating the full lifecycle of creating and managing project specifications using the MCP client. It covers loading guides and templates, generating documents, requesting and polling for approvals, managing tasks, implementing code, and logging progress. This snippet assumes an initialized 'mcpClient' object.

```typescript
// Step 1: Load workflow guide
const guide = await mcpClient.callTool('spec-workflow-guide', {});

// Step 2: Load requirements template
const reqTemplate = await mcpClient.callTool('get-template-context', {
  projectPath: "/home/user/projects/myapp",
  templateType: "spec",
  template: "requirements"
});

// Step 3: Create requirements document (AI generates content using template)
const reqDoc = await mcpClient.callTool('create-spec-doc', {
  projectPath: "/home/user/projects/myapp",
  specName: "user-authentication",
  document: "requirements",
  content: "# User Authentication Requirements\n\n[Generated content...]"
});

// Step 4: Request approval for requirements
const reqApproval = await mcpClient.callTool('request-approval', {
  projectPath: "/home/user/projects/myapp",
  title: "User Authentication Requirements Review",
  filePath: ".spec-workflow/specs/user-authentication/requirements.md",
  type: "document",
  category: "spec",
  categoryName: "user-authentication"
});

// Step 5: Poll for approval (repeat until approved)
let approved = false;
let approvalId = reqApproval.data.approvalId;
while (!approved) {
  await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
  const status = await mcpClient.callTool('get-approval-status', {
    projectPath: "/home/user/projects/myapp",
    approvalId: approvalId
  });

  if (status.data.status === 'approved') {
    approved = true;
  } else if (status.data.status === 'needs-revision') {
    // Handle revision request
    console.log('Revision needed:', status.data.comments);
    break;
  }
}

// Step 6: Delete approval after approval
if (approved) {
  await mcpClient.callTool('delete-approval', {
    projectPath: "/home/user/projects/myapp",
    approvalId: approvalId
  });
}

// Step 7-9: Repeat for design document (load template, create, approve, delete)
// Step 10-12: Repeat for tasks document (load template, create, approve, delete)

// Step 13: Check spec status
const specStatus = await mcpClient.callTool('spec-status', {
  projectPath: "/home/user/projects/myapp",
  specName: "user-authentication"
});
// Status should be "ready-for-implementation"

// Step 14: Start implementing tasks
const nextTask = await mcpClient.callTool('manage-tasks', {
  projectPath: "/home/user/projects/myapp",
  specName: "user-authentication",
  action: "next-pending"
});

// Step 15: Set task to in-progress
await mcpClient.callTool('manage-tasks', {
  projectPath: "/home/user/projects/myapp",
  specName: "user-authentication",
  action: "set-status",
  taskId: nextTask.data.task.id,
  status: "in-progress"
});

// Step 16: Implement the code (AI writes actual code files)

// Step 17: Mark task as completed
await mcpClient.callTool('manage-tasks', {
  projectPath: "/home/user/projects/myapp",
  specName: "user-authentication",
  action: "set-status",
  taskId: nextTask.data.task.id,
  status: "completed"
});

// Step 18: Log implementation
await mcpClient.callTool('log-implementation', {
  projectPath: "/home/user/projects/myapp",
  specName: "user-authentication",
  taskId: nextTask.data.task.id,
  summary: "Implemented user model with validation",
  filesModified: ["src/models/User.ts"],
  linesAdded: 120,
  linesDeleted: 5,
  testsCoverage: 98.0,
  notes: "Added comprehensive validation and unit tests"
});

// Repeat steps 14-18 for each remaining task
```

--------------------------------

### Start Spec Workflow MCP Dashboard (Bash)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md

Commands to start the Spec Workflow MCP Web Dashboard. It can be run standalone with an ephemeral or custom port, or auto-started with an MCP server.

```bash
# Uses ephemeral port
npx -y @pimzino/spec-workflow-mcp@latest /path/to/project --dashboard

# Custom port
npx -y @pimzino/spec-workflow-mcp@latest /path/to/project --dashboard --port 3000

# Auto-start with MCP
npx -y @pimzino/spec-workflow-mcp@latest /path/to/project --AutoStartDashboard
```

--------------------------------

### Run Spec Workflow MCP Testing Commands

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/developer-guide.md

Provides Bash commands for manual integration and dashboard testing, including starting the server and dashboard, and outlines test scenarios. Useful for developers to verify the workflow end‑to‑end. Relies on npm scripts defined in the project.

```Bash
# Integration testing workflow\n# 1. Start MCP server\nnpm run dev\n\n# 2. Connect AI client\n# (manual step)\n\n# 3. Test tool workflows\n# (manual verification)\n\n# Dashboard testing\n# Start dashboard in development mode\nnpm run dev:dashboard\n\n# Test scenarios:\n# 1. Create specifications\n# 2. Approval workflow\n# 3. Real-time updates\n# 4. File watching
```

--------------------------------

### Start Dashboard Development Mode (npm)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/dashboard.md

Command to initiate the dashboard's development server, enabling hot reloading for faster frontend development. It specifies the local development server URL and the backend connection endpoint. Requires npm and project setup.

```bash
# Start dashboard dev server (hot reload)
npm run dev:dashboard

# Available at http://localhost:5173
# Connects to backend at http://localhost:3456
```

--------------------------------

### Install Dependencies (npm)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/DEVELOPMENT.md

Installs project dependencies using npm. It depends on Node.js and npm being available in the environment. This command installs MCP SDK, TypeScript,  Express, WebSocket libraries, and testing frameworks.

```bash
npm install
```

--------------------------------

### Writing Unit Tests with Vitest

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/DEVELOPMENT.md

Example of a unit test file written using Vitest. Demonstrates importing testing utilities and the module under test, defining test suites and individual test cases with assertions for success and error handling.

```typescript
// src/tools/my-tool.test.ts
import { describe, it, expect } from 'vitest';
import { myTool } from './my-tool';

describe('myTool', () => {
  it('should process input correctly', async () => {
    const result = await myTool.handler({
      param1: 'test'
    });

    expect(result.success).toBe(true);
    expect(result.data).toContain('expected');
  });

  it('should handle errors', async () => {
    const result = await myTool.handler({
      param1: null
    });

    expect(result.success).toBe(false);
    expect(result.error).toBeDefined();
  });
});
```

--------------------------------

### Multi-Project Configuration Setup

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/CONFIGURATION.md

Illustrates how to set up separate and shared configurations for multiple projects. Separate configurations use project-specific `.spec-workflow/config.toml` files, while shared configurations involve a base file with project-specific overrides.

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

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

```

```bash
# 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

```

--------------------------------

### Writing Integration Tests

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/DEVELOPMENT.md

An example of an integration test file. It outlines a test for a complete workflow, suggesting steps like creating and approving requirements and designs, and creating tasks. This serves as a placeholder for detailed integration logic.

```typescript
// tests/integration/workflow.test.ts
describe('Complete Workflow', () => {
  it('should create spec from start to finish', async () => {
    // Create requirements
    // Approve requirements
    // Create design
    // Approve design
    // Create tasks
    // Verify structure
  });
});
```

--------------------------------

### Workflow Example: Creating a New Spec

Source: https://context7.com/pimzino/spec-workflow-mcp/llms.txt

A comprehensive TypeScript example demonstrating the workflow from creating requirements to managing tasks for a new specification.

```APIDOC
## Complete Workflow Example: Creating a New Spec from Start to Finish

This example demonstrates a typical workflow using the `mcpClient` to create and manage specifications and tasks.

### Workflow Steps

1.  **Load workflow guide**
    ```typescript
    const guide = await mcpClient.callTool('spec-workflow-guide', {});
    ```

2.  **Load requirements template**
    ```typescript
    const reqTemplate = await mcpClient.callTool('get-template-context', {
      projectPath: "/home/user/projects/myapp",
      templateType: "spec",
      template: "requirements"
    });
    ```

3.  **Create requirements document** (AI generates content using template)
    ```typescript
    const reqDoc = await mcpClient.callTool('create-spec-doc', {
      projectPath: "/home/user/projects/myapp",
      specName: "user-authentication",
      document: "requirements",
      content: "# User Authentication Requirements\n\n[Generated content...]"
    });
    ```

4.  **Request approval for requirements**
    ```typescript
    const reqApproval = await mcpClient.callTool('request-approval', {
      projectPath: "/home/user/projects/myapp",
      title: "User Authentication Requirements Review",
      filePath: ".spec-workflow/specs/user-authentication/requirements.md",
      type: "document",
      category: "spec",
      categoryName: "user-authentication"
    });
    ```

5.  **Poll for approval** (repeat until approved)
    ```typescript
    let approved = false;
    let approvalId = reqApproval.data.approvalId;
    while (!approved) {
      await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
      const status = await mcpClient.callTool('get-approval-status', {
        projectPath: "/home/user/projects/myapp",
        approvalId: approvalId
      });

      if (status.data.status === 'approved') {
        approved = true;
      } else if (status.data.status === 'needs-revision') {
        // Handle revision request
        console.log('Revision needed:', status.data.comments);
        break;
      }
    }
    ```

6.  **Delete approval after approval**
    ```typescript
    if (approved) {
      await mcpClient.callTool('delete-approval', {
        projectPath: "/home/user/projects/myapp",
        approvalId: approvalId
      });
    }
    ```

7.  **Repeat steps for design document** (load template, create, approve, delete)

8.  **Repeat steps for tasks document** (load template, create, approve, delete)

9.  **Check spec status**
    ```typescript
    const specStatus = await mcpClient.callTool('spec-status', {
      projectPath: "/home/user/projects/myapp",
      specName: "user-authentication"
    });
    // Status should be "ready-for-implementation"
    ```

10. **Start implementing tasks**
    ```typescript
    const nextTask = await mcpClient.callTool('manage-tasks', {
      projectPath: "/home/user/projects/myapp",
      specName: "user-authentication",
      action: "next-pending"
    });
    ```

11. **Set task to in-progress**
    ```typescript
    await mcpClient.callTool('manage-tasks', {
      projectPath: "/home/user/projects/myapp",
      specName: "user-authentication",
      action: "set-status",
      taskId: nextTask.data.task.id,
      status: "in-progress"
    });
    ```

12. **Implement the code** (AI writes actual code files)

13. **Mark task as completed**
    ```typescript
    await mcpClient.callTool('manage-tasks', {
      projectPath: "/home/user/projects/myapp",
      specName: "user-authentication",
      action: "set-status",
      taskId: nextTask.data.task.id,
      status: "completed"
    });
    ```

14. **Log implementation**
    ```typescript
    await mcpClient.callTool('log-implementation', {
      projectPath: "/home/user/projects/myapp",
      specName: "user-authentication",
      taskId: nextTask.data.task.id,
      summary: "Implemented user model with validation",
      filesModified: ["src/models/User.ts"],
      linesAdded: 120,
      linesDeleted: 5,
      testsCoverage: 98.0,
      notes: "Added comprehensive validation and unit tests"
    });
    ```

15. **Repeat steps 14-18 for each remaining task**

### Client Methods Used

- `mcpClient.callTool(toolName, args)`: A generic method to call various tools provided by the MCP server.

### Tool Arguments (Examples)

- **spec-workflow-guide**: `{}`
- **get-template-context**: `{ projectPath: string, templateType: string, template: string }`
- **create-spec-doc**: `{ projectPath: string, specName: string, document: string, content: string }`
- **request-approval**: `{ projectPath: string, title: string, filePath: string, type: string, category: string, categoryName: string }`
- **get-approval-status**: `{ projectPath: string, approvalId: string }`
- **delete-approval**: `{ projectPath: string, approvalId: string }`
- **spec-status**: `{ projectPath: string, specName: string }`
- **manage-tasks**: `{ projectPath: string, specName: string, action: string, taskId?: string, status?: string }`
- **log-implementation**: `{ projectPath: string, specName: string, taskId: string, summary: string, filesModified: string[], linesAdded: number, linesDeleted: number, testsCoverage: number, notes?: string }`
```

--------------------------------

### Start dashboard server with Bash

Source: https://context7.com/pimzino/spec-workflow-mcp/llms.txt

Starts the unified multi-project dashboard for managing specs and projects. Supports default and custom port configurations. All MCP server instances connect to this single dashboard.

```bash
# Start dashboard on default port 5000
npx -y @pimzino/spec-workflow-mcp@latest --dashboard

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

# Dashboard will be accessible at http://localhost:5000
# All MCP server instances connect to this single dashboard
```

--------------------------------

### Load Spec Workflow Guide with mcpClient

Source: https://context7.com/pimzino/spec-workflow-mcp/llms.txt

Loads the complete workflow instructions for spec-driven development. This tool should be invoked first to initiate the spec creation or feature development process. It requires no parameters and returns a guide, dashboard URL, and next steps.

```typescript
const response = await mcpClient.callTool('spec-workflow-guide', {});

// Example response structure
{
  "success": true,
  "message": "Complete spec workflow guide loaded - follow this workflow exactly",
  "data": {
    "guide": "# Spec Development Workflow\n\n## Overview\nThis workflow enforces a structured...",
    "dashboardUrl": "http://localhost:5000",
    "dashboardAvailable": true
  },
  "nextSteps": [
    "Follow sequence: Requirements → Design → Tasks → Implementation",
    "Load templates with get-template-context first",
    "Request approval after each document"
  ]
}
```

--------------------------------

### Start Dashboard Standalone Mode (CLI)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/dashboard.md

Commands to start the dashboard system in standalone mode using npx. Allows specifying a custom port and starting from a specific project directory. Dependencies include Node.js and npm.

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

# With custom port
npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080

# From specific project directory
cd /path/to/project
npx -y @pimzino/spec-workflow-mcp@latest --dashboard
```

--------------------------------

### Adding a New MCP Tool - TypeScript

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/developer-guide.md

Example TypeScript code for defining and handling a new MCP tool.  Provides structure for input schema, tool logic, and response handling.  Requires familiarity with the @modelcontextprotocol/sdk.

```typescript
// src/tools/my-new-tool.ts
import { Tool } from '@modelcontextprotocol/sdk/types.js';
import { ToolContext, ToolResponse } from '../types.js';

export const myNewToolTool: Tool = {
  name: 'my-new-tool',
  description: `Brief description of what this tool does.\n\n# Instructions\nClear instructions on when and how to use this tool.`,
  inputSchema: {
    type: 'object',
    properties: {
      projectPath: { 
        type: 'string',
        description: 'Absolute path to the project root'
      },
      // Add other parameters
      param1: { 
        type: 'string',
        description: 'Description of parameter'
      }
    },
    required: ['projectPath']
  }
};

export async function myNewToolHandler(
  args: any, 
  context: ToolContext
): Promise<ToolResponse> {
  const { projectPath, param1 } = args;

  try {
    // Implementation here
    
    return {
      success: true,
      message: 'Tool executed successfully',
      data: {
        // Response data
      },
      nextSteps: [
        'What user should do next',
        'Additional guidance'
      ]
    };
  } catch (error: any) {
    return {
      success: false,
      message: `Tool failed: ${error.message}`,
      nextSteps: [
        'Check input parameters',
        'Verify file permissions'
      ]
    };
  }
}
```

```typescript
// src/tools/index.ts
import { myNewToolTool, myNewToolHandler } from './my-new-tool.js';

export function registerTools(): Tool[] { 
  return [
    // ... existing tools
    myNewToolTool
  ];
}

export async function handleToolCall(name: string, args: any, context: ToolContext): Promise<MCPToolResponse> { 
  switch (name) {
    // ... existing cases
    case 'my-new-tool':
      response = await myNewToolHandler(args, context);
      break;
  }
}
```

--------------------------------

### Claude Code CLI Setup

Source: https://context7.com/pimzino/spec-workflow-mcp/llms.txt

Instructions for setting up the MCP server with Claude Code CLI, ensuring proper argument separation.

```APIDOC
## Claude Code CLI Setup

Configure the MCP server for Claude Code CLI with proper argument separation.

### Add MCP Server Command

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

### Notes

- The `--` separator ensures the project path is passed to the script, not to `npx`.
- The `-y` flag bypasses npm prompts for smoother installation.
```

--------------------------------

### Building Spec-Workflow MCP Docker Image

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/containers/README.md

Builds the Docker image for the Spec-Workflow MCP server from the containers directory. Requires Docker installed. Outputs a tagged image 'spec-workflow-mcp' for use in MCP configurations. No inputs beyond the Dockerfile; runs in the current directory.

```bash
docker build -t spec-workflow-mcp .
```

--------------------------------

### Start MCP Server for Project

Source: https://context7.com/pimzino/spec-workflow-mcp/llms.txt

Starts the MCP server for a specified project, enabling communication with AI clients via stdio transport. It uses npx to execute the latest version of the spec-workflow-mcp package. The command can target the current directory or a specific project path, with support for home directory expansion.

```bash
# Start MCP server for current directory
npx -y @pimzino/spec-workflow-mcp@latest

# Start MCP server for specific project
npx -y @pimzino/spec-workflow-mcp@latest /path/to/project

# Start with home directory expansion
npx -y @pimzino/spec-workflow-mcp@latest ~/projects/my-app
```

--------------------------------

### Modal Components i18n Provider Setup

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/i18n-guide.md

Configures i18n provider wrapper for modal or standalone components that need isolated translation context. Requires I18nextProvider import and i18n instance configuration. Provides translation fallback mechanisms and component isolation. Essential for components that don't have access to parent i18n context.

```TypeScript
import { I18nextProvider } from 'react-i18next';
import i18n from './i18n';

return (
  <I18nextProvider i18n={i18n}>
    <YourComponent />
  </I18nextProvider>
);
```

```TypeScript
const fallbackText = window.initialState?.selectedText || i18n.t('commentModal.noTextSelected');
```

--------------------------------

### Translate Function Unit Test Example (TypeScript)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/i18n-guide.md

An example of a unit test for the translate function, demonstrating how to test string interpolation with provided parameters. This ensures that translations are correctly rendered with dynamic content.

```typescript
// Unit test example
describe('translate function', () => {
  it('should handle interpolation', () => {
    const result = translate('welcome', 'en', { name: 'Test' });
    expect(result).toBe('Welcome, Test!');
  });
});
```

--------------------------------

### React i18n Hook Setup - TypeScript

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/i18n-guide.md

Essential steps for setting up internationalization in React components using react-i18next hooks. Shows import, hook declaration, and string replacement patterns. Requires react-i18next package and proper component structure. Enables dynamic translation loading and fallbacks.

```TypeScript
import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t } = useTranslation();
  // ... rest of component
  return (
    <button>{t('commentModal.title.edit')}</button>
  );
}
```

--------------------------------

### Modifying the Dashboard - TypeScript

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/developer-guide.md

Example code for adding a new page and API endpoint to the dashboard.  Demonstrates React component creation and server-side route handling.

```typescript
// src/dashboard_frontend/src/modules/pages/MyNewPage.tsx
import React from 'react';

export default function MyNewPage() {
  return (
    <div className="p-6">
      <h1 className="text-2xl font-bold mb-4">My New Page</h1>
      {/* Page content */}  
    </div>
  );
}
```

```typescript
// src/dashboard_frontend/src/modules/app/App.tsx
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import MyNewPage from '../pages/MyNewPage';

function App() {
  return (
    <Router>
      <Routes>
        <Route path="/my-page" element={<MyNewPage />} />
        {/* Other routes */}  
      </Routes>
    </Router>
  );
}
```

```typescript
// src/dashboard/multi-server.ts
export class MultiProjectDashboardServer {
  private async setupRoutes() {
    // Add new project-scoped endpoint
    this.app.get('/api/projects/:projectId/my-endpoint', async (request, reply) => {
      try {
        const { projectId } = request.params as { projectId: string };
        const project = this.projectManager.getProject(projectId);
        if (!project) {
          return reply.code(404).send({ error: 'Project not found' });
        }
        const data = await this.getMyData(project);
        reply.send({ success: true, data });
      } catch (error) {
        reply.status(500).send({ success: false, error: error.message });
      }
    });
  }

  private async getMyData(project: Project) {
    // Implementation
  }
}
```

--------------------------------

### Clone Repository (Bash)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/DEVELOPMENT.md

Clones the Spec Workflow MCP repository from GitHub and navigates into the project directory.  This command uses Git to download the source code.  No specific input is required; the only dependency is Git being installed and configured.

```bash
git clone https://github.com/Pimzino/spec-workflow-mcp.git
cd spec-workflow-mcp
```

--------------------------------

### Create New Tool (TypeScript)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/DEVELOPMENT.md

Demonstrates how to create a new tool within the MCP framework using TypeScript. The snippet includes example of `Tool` interface implementation, parameter definition, and handler function for processing the tool's input.  It utilizes the `@anthropic/mcp-sdk` library.

```typescript
// src/tools/my-new-tool.ts
import { Tool } from '@anthropic/mcp-sdk';

export const myNewTool: Tool = {
  name: 'my-new-tool',
  description: 'Description of what the tool does',
  parameters: {
    type: 'object',
    properties: {
      param1: { type: 'string', description: 'Parameter description' },
      param2: { type: 'number', optional: true } 
    },
    required: ['param1']
  },
  handler: async (params) => {
    // Tool implementation
    const { param1, param2 = 0 } = params;

    // Business logic here

    return {
      success: true,
      data: 'Tool response'
    };
  }
};

```

--------------------------------

### Publish VS Code Extension in Bash

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/developer-guide.md

Packages and publishes the VS Code extension to the marketplace using VSCE. Requires global VSCE installation and extension directory. No inputs, generates .vsix file; necessitates VS Code developer account for publishing.

```bash
cd vscode-extension

# Install VSCE
npm install -g @vscode/vsce

# Package extension
vsce package

# Publish to marketplace
vsce publish
```

--------------------------------

### Development Mode (npm)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/DEVELOPMENT.md

Starts the development server with auto-reloading and detailed error messages. This is intended for active development and debugging, offering features like hot reload and source maps. It depends on Node.js and npm.

```bash
npm run dev
```

--------------------------------

### Development Commands - Bash

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/developer-guide.md

Commands for running the MCP server, dashboard, building, cleaning, and testing.

```bash
# Start MCP server in development mode

```

```bash
npm run dev
```

```bash
# Start dashboard in development mode  

```

```bash
npm run dev:dashboard
```

```bash
# Build for production

```

```bash
npm run build
```

```bash
# Clean build artifacts

```

```bash
npm run clean
```

```bash
# Run tests (when available)

```

```bash
npm test
```

--------------------------------

### Spec Workflow Guide

Source: https://context7.com/pimzino/spec-workflow-mcp/llms.txt

Loads complete workflow instructions for spec-driven development. This is the entry point tool that should be called first when users request spec creation or feature development.

```APIDOC
## spec-workflow-guide

### Description
Loads complete workflow instructions for spec-driven development. This is the entry point tool that should be called first when users request spec creation or feature development.

### Method
TOOL CALL

### Endpoint
N/A

### Parameters
#### Query Parameters
None

#### Request Body
* **None**

### Request Example
```typescript
const response = await mcpClient.callTool('spec-workflow-guide', {});
```

### Response
#### Success Response (200)
* **success** (boolean) - Indicates if the operation was successful.
* **message** (string) - A message describing the result of the operation.
* **data** (object) - Contains workflow guide details.
    * **guide** (string) - The spec development workflow instructions.
    * **dashboardUrl** (string) - The URL for the web dashboard.
    * **dashboardAvailable** (boolean) - Indicates if the dashboard is available.
* **nextSteps** (array of strings) - A list of recommended next actions.

#### Response Example
```json
{
  "success": true,
  "message": "Complete spec workflow guide loaded - follow this workflow exactly",
  "data": {
    "guide": "# Spec Development Workflow\n\n## Overview\nThis workflow enforces a structured...",
    "dashboardUrl": "http://localhost:5000",
    "dashboardAvailable": true
  },
  "nextSteps": [
    "Follow sequence: Requirements → Design → Tasks → Implementation",
    "Load templates with get-template-context first",
    "Request approval after each document"
  ]
}
```
```

--------------------------------

### VS Code Extension Development - Bash

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/developer-guide.md

Instructions on how to develop the VS Code extension. Involves opening the extension in VS Code and launching the Extension Development Host.

```bash
cd vscode-extension
npm install
```

```bash
# Open in VS Code
code .
```

```bash
# Press F5 to launch Extension Development Host
```

--------------------------------

### Install build dependencies on Linux distributions

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/TROUBLESHOOTING.md

Installs essential build tools and development libraries for compiling native Node.js modules. Platform-specific commands for Debian/Ubuntu and RHEL/CentOS. Requires sudo access. Ensures proper compilation environment.

```Bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential

# RHEL/CentOS
sudo yum groupinstall "Development Tools"
```

--------------------------------

### Create new specification with TypeScript prompt

Source: https://context7.com/pimzino/spec-workflow-mcp/llms.txt

Invokes the create-spec prompt to guide AI through creating a new specification. Requires specification name and description. Guides through requirements, design, and tasks creation with approval steps.

```typescript
// Invoke create-spec prompt
const promptResponse = await mcpClient.getPrompt('create-spec', {
  specName: "payment-gateway",
  description: "Integrate Stripe and PayPal payment processing"
});

// Returns formatted prompt messages that guide the AI through:
// 1. Loading workflow guide
// 2. Creating requirements document
// 3. Requesting approval
// 4. Creating design document
// 5. Requesting approval
// 6. Creating tasks document
// 7. Final approval
```

--------------------------------

### Claude Code CLI Setup for MCP Server

Source: https://context7.com/pimzino/spec-workflow-mcp/llms.txt

Setup instructions for the Claude Code CLI to manage MCP servers. This command adds a new MCP server configuration, specifying the command 'npx' and its arguments, including the package and project path. The '--' separator is crucial for correctly passing arguments to the script.

```bash
# Add MCP server with proper argument passing
claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project

# The -- separator ensures the path is passed to the script, not to npx
# The -y flag bypasses npm prompts for smoother installation
```

--------------------------------

### Execute Spec Workflow MCP Commands in Bash

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/CONFIGURATION.md

These bash commands utilize npx to launch the Spec Workflow MCP tool for managing projects or running a dashboard. Dependencies include Node.js and npx installation. Inputs are project paths and flags like --dashboard or --port, with outputs being active servers or dashboard interfaces. Limitations include enforcement of a single dashboard instance and requirement for available ports.

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

```bash
npx -y @pimzino/spec-workflow-mcp@latest --help
```

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

```bash
npx -y @pimzino/spec-workflow-mcp@latest --dashboard --port 8080
```

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

```bash
# 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
```

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

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

```bash
# 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
```

--------------------------------

### MCP protocol request and response examples

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/troubleshooting.md

Shows the JSON-RPC payloads used by an AI client to call the spec-workflow-guide tool and the corresponding server response.

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "spec-workflow-guide",
    "arguments": {}
  }
}

---

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Complete workflow guide content..."
      }
    ]
  }
}
```

--------------------------------

### Bash Commands for Testing

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/contributing.md

Provides a set of bash commands for executing tests and build processes for the project. Includes starting development servers, testing the VS Code extension, cleaning and building the project, and running the CLI interface.

```bash
# 1. Basic MCP server functionality
npm run dev
# Connect AI client and test tools

# 2. Dashboard functionality
npm run dev:dashboard
# Test all pages and features

# 3. VS Code extension (if modified)
cd vscode-extension
# Press F5 in VS Code to test

# 4. Build process
npm run clean
npm run build
# Verify dist/ contents

# 5. CLI interface
node dist/index.js --help
node dist/index.js --dashboard
```

--------------------------------

### Translation Key Structure - JSON

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/i18n-guide.md

Example structure for organizing translation keys in locale files. Shows hierarchical organization with nested objects for component-specific translations. Requires valid JSON format and matching key references in components. Supports complex translation scenarios with multiple nested levels.

```JSON
{
  "commentModal": {
    "title": {
      "edit": "Edit Comment",
      "add": "Add Comment"
    },
    "selectedText": "Selected Text",
    "cancel": "Cancel",
    "noTextSelected": "No text selected"
  }
}
```

--------------------------------

### Start Dashboard (Bash)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/README.md

This bash command starts the Spec Workflow MCP dashboard, which provides a real-time view of specs, tasks, and progress. The dashboard runs on port 5000 by default and is required for CLI users.

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

--------------------------------

### TypeScript File Organization Example

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/contributing.md

Demonstrates a standard file structure for TypeScript projects, separating external imports, internal imports, type definitions, constants, and main implementations.

```typescript
// 1. External library imports
import { Tool } from '@modelcontextprotocol/sdk/types.js';
import { readFile } from 'fs/promises';

// 2. Internal imports
import { ToolContext, ToolResponse } from '../types.js';
import { PathUtils } from '../core/path-utils.js';

// 3. Type definitions
interface LocalInterface {
  // ...
}

// 4. Constants
const CONSTANTS = {
  // ...
};

// 5. Main implementation
export class MyClass {
  // ...
}
```

--------------------------------

### Configure MCP client with absolute path arguments

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/troubleshooting.md

Provides a JSON example of passing absolute paths to the MCP client via the args array to avoid relative path resolution issues.

```json
{
  "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/full/path/to/project"]
}
```

--------------------------------

### Configure Dynamic Translation Loading (.env)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/i18n-guide.md

Enables dynamic translation loading by setting the VITE_I18N_DYNAMIC environment variable to true. This reduces the initial bundle size by loading translations on-demand.

```env
VITE_I18N_DYNAMIC=true
```

--------------------------------

### Set Up Local Development Environment

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/README.md

Provides shell commands to clone the repository, install dependencies, and run development or production builds. Requires Git, Node.js, and npm. Takes a repository URL as input and outputs a functional local development environment with hot-reload and build capabilities.

```shell
# 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
```

--------------------------------

### Checking Configuration File Location

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/CONFIGURATION.md

Command to verify the presence and accessibility of the `.spec-workflow/config.toml` file. This is a primary step in troubleshooting configuration loading issues.

```bash
ls -la .spec-workflow/config.toml

```

--------------------------------

### VSCode Extension Settings JSON

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/INTERFACES.md

Configuration options for the Spec Workflow VSCode extension, allowing customization of language, notifications, task refresh, and theme.

```json
{
  "specWorkflow.language": "en",
  "specWorkflow.notifications.enabled": true,
  "specWorkflow.notifications.sound": true,
  "specWorkflow.notifications.volume": 0.5,
  "specWorkflow.archive.showInExplorer": true,
  "specWorkflow.tasks.autoRefresh": true,
  "specWorkflow.tasks.refreshInterval": 5000,
  "specWorkflow.theme.followVSCode": true
}
```

--------------------------------

### Committing Changes with Conventional Commits

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/DEVELOPMENT.md

Example of a Git commit message following the conventional commits format. This specific example uses the 'feat:' prefix to indicate a new feature.

```bash
git commit -m "feat: add new feature"
```

--------------------------------

### Configure Auto-Start Dashboard with MCP Server (JSON)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/dashboard.md

JSON configuration for automatically starting the dashboard alongside the MCP server. Specifies the command to execute and its arguments, including the project path and the --AutoStartDashboard flag. Requires a valid MCP server configuration.

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

--------------------------------

### Command-Line Argument Override Example

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/CONFIGURATION.md

Demonstrates how command-line arguments can override settings defined in configuration files. The `--port` argument is used here to set a different port than what is specified in the `config.toml` file.

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

```

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

```

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

```

--------------------------------

### Configure MCP Server for AI Assistant Integration

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/README.md

Configures the Model Context Protocol server for integrating spec-workflow-mcp with AI assistants. Specifies the npx command to execute the package with automatic dashboard startup enabled. Requires Node.js and npm, takes a project path as input, and establishes the MCP server connection.

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

--------------------------------

### Test Endpoints Directly (Bash)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/dashboard.md

This Bash snippet shows examples of testing API endpoints directly using the `curl` command.  These commands perform various HTTP requests to endpoints, including GET and POST requests.

```bash
# Test endpoints directly
curl -X GET http://localhost:3456/api/specs
```

```bash
curl -X GET http://localhost:3456/api/health
```

```bash
curl -X POST http://localhost:3456/api/approvals/test-id/approve
```

--------------------------------

### Add Dashboard Feature (HTML)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/DEVELOPMENT.md

Adds a new button element to the dashboard's HTML structure to trigger a new feature by sending a message over WebSocket. This is a starting point for adding new interactive elements to the dashboard.

```html
&lt;div class="new-feature"&gt;
  &lt;h3&gt;New Feature&lt;/h3&gt;
  &lt;button id="new-action"&gt;Action&lt;/button&gt;
&lt;/div&gt;
```

--------------------------------

### Debug MCP Server in Bash

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/developer-guide.md

Enables debugging for the MCP server using environment variables and client modes. Requires npm and the spec-workflow-mcp package. No inputs, outputs debug logs; useful for protocol message inspection but assumes development environment setup.

```bash
# Enable debug logging
DEBUG=spec-workflow-mcp npm run dev

# Check MCP protocol messages
# Use MCP client debug modes
```

--------------------------------

### Run Tests (npm scripts)

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/i18n-guide.md

Provides commands to run all tests, including internationalization tests, in watch mode for development, or to generate a coverage report. These are essential for ensuring code quality and translation accuracy.

```bash
npm test          # Run all tests including i18n
npm run test:watch # Watch mode for development
npm run test:coverage # Generate coverage report
```

--------------------------------

### New Component Template - React TypeScript

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/i18n-guide.md

Standard template for creating new React components with i18n support. Includes necessary imports, hook usage, and basic component structure. Serves as starting point for new i18n-enabled components. Requires React and react-i18next dependencies.

```TypeScript
import React from 'react';
import { useTranslation } from 'react-i18next';

function NewComponent() {
  const { t } = useTranslation();
  
  return (
    <div>
      <h1>{t('newComponent.title')}</h1>
      <button>{t('newComponent.action')}</button>
    </div>
  );
}

export default NewComponent;
```

--------------------------------

### Build for Production in Bash

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/developer-guide.md

Cleans previous builds, compiles the project, and verifies output directories. Requires npm scripts and build tools. No inputs, ensures clean dist/ folder; assumes package.json with defined build commands.

```bash
# Clean previous builds
npm run clean

# Build everything
npm run build

# Verify build output
ls -la dist/
```

--------------------------------

### Running Tests with NPM

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/DEVELOPMENT.md

Commands for executing tests using npm. Includes options for running all tests, specific files, with coverage, and in watch mode. Relies on the npm test script configured in package.json.

```bash
# Run all tests
npm test

# Run specific test file
npm test -- src/tools/my-tool.test.ts

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch
```

--------------------------------

### Manage State in React TypeScript

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/developer-guide.md

Implements local state and real-time updates using React hooks in the dashboard frontend. Requires React and WebSocket for message handling. Inputs WebSocket messages, outputs updated spec data; assumes proper setup of useState and useEffect for reactivity.

```typescript
// Use React hooks for local state
const [specs, setSpecs] = useState<SpecData[]>([]);

// Use WebSocket for real-time updates
useEffect(() => {
  if (wsMessage?.type === 'specs-updated') {
    setSpecs(wsMessage.data);
  }
}, [wsMessage]);
```

--------------------------------

### Deploying Dashboard with Docker Compose

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/containers/README.md

Starts the Spec-Workflow dashboard in a container using Docker Compose, setting environment variables for project path and port. Requires Docker Compose and SPEC_WORKFLOW_PATH matching the MCP config; inputs are env vars; outputs accessible dashboard at localhost port. Limitation: Port conflicts if already in use; use custom port via DASHBOARD_PORT.

```bash
# Replace with your actual project path
SPEC_WORKFLOW_PATH=/home/username/project docker-compose up -d
```

```bash
DASHBOARD_PORT=3456 SPEC_WORKFLOW_PATH=/home/username/project docker-compose up -d
```

```bash
docker-compose down
```

--------------------------------

### Debug template loading and file existence

Source: https://github.com/pimzino/spec-workflow-mcp/blob/main/docs/technical-documentation/troubleshooting.md

Shell commands to list template files, check their sizes, and preview the beginning of each template to ensure they are readable and not corrupted.

```bash
ls -la src/markdown/templates/
find src/markdown/templates -name "*.md" -exec wc -c {} \;

for template in src/markdown/templates/*.md; do
  echo "=== $template ==="
  head -5 "$template"
done
```