Spec Workflow MCP

🚀 Spec Workflow MCP

AI支援によるソフトウェア開発のための構造化された仕様駆動型開発ワークフローツールを提供するモデルコンテキストプロトコル（MCP）サーバーです。リアルタイムのウェブダッシュボードを備え、プロジェクトの進捗状況を監視および管理できます。

📺 デモ

🔄 承認システムの実際の動作

承認システムの動作を確認しましょう。ドキュメントを作成し、ダッシュボードを通じて承認を要求し、フィードバックを提供し、修正を追跡することができます。

📊 ダッシュボードと仕様管理

リアルタイムのダッシュボードを探索しましょう。仕様を表示し、進捗状況を追跡し、ドキュメントをナビゲートし、開発ワークフローを監視することができます。

☕ このプロジェクトを支援する

✨ 主な機能

• 構造化された開発ワークフロー - 仕様の逐次作成（要件 → 設計 → タスク）
• リアルタイムウェブダッシュボード - 仕様、タスク、および進捗状況をリアルタイムで監視
• ドキュメント管理 - ダッシュボードからすべての仕様ドキュメントを表示および管理
• タスク進捗追跡 - 視覚的な進捗バーと詳細なタスクステータス
• ステアリングドキュメント - プロジェクトビジョン、技術的決定、および構造ガイダンス
• バグワークフロー - 完全なバグ報告と解決追跡
• テンプレートシステム - すべてのドキュメントタイプの事前構築済みテンプレート
• クロスプラットフォーム - Windows、macOS、およびLinuxで動作

🚀 クイックスタート

1. AIツールの設定に追加する（以下のMCPクライアント設定を参照）：

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

   注意：プロジェクトへのパスを指定せずに使用することもできますが、一部のMCPクライアントでは現在のディレクトリからサーバーを起動できない場合があります。

2. ウェブダッシュボードを起動する（必須）：

   # デフォルト（エフェメラルポートを使用）
   npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project --dashboard
   
   # カスタムポート
   npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project --dashboard --port 3000
   
   # 代替構文
   npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project --dashboard --port=8080
   

   オプション：

   • --dashboard - ウェブダッシュボードを起動する（必須）
   • --port <number> - オプションのカスタムポート（1024 - 65535）。指定しない場合は、エフェメラルポートが使用されます。

   重要：ダッシュボードはワークフローを機能させるために必須です。ダッシュボードがない場合：

   • ドキュメントの承認が機能しません。
   • タスクの進捗追跡が無効になります。
   • 仕様のステータス更新が利用できません。
   • 承認システムが機能しません。

注意：MCPサーバーとダッシュボードは現在別のサービスです。両方を実行する必要があります。AIツールとの統合にはMCPサーバーを、ワークフロー管理、承認、および進捗追跡にはダッシュボードを使用します。

💻 使用例

会話の中でspec-workflowまたはMCPサーバーに付けた任意の名前を指定するだけです。AIが完全なワークフローを自動的に処理します。または、以下の例のプロンプトを使用することもできます。

仕様の作成

• "Create a spec for user authentication" - その機能に対する完全な仕様ワークフローを作成します。
• "Create a spec called payment-system" - 完全な要件 → 設計 → タスクを構築します。
• "Build a spec for @prd" - 既存のPRDを使用して、完全な仕様ワークフローを作成します。
• "Create a spec for shopping-cart - include add to cart, quantity updates, and checkout integration" - 詳細な機能仕様を作成します。

情報の取得

• "List my specs" - すべての仕様とその現在のステータスを表示します。
• "Show me the user-auth progress" - 詳細な進捗情報を表示します。

実装

• "Execute task 1.2 in spec user-auth" - 仕様内の特定のタスクを実行します。
• ダッシュボードからプロンプトをコピーする - ダッシュボードのタスクリストにある「Copy Prompt」ボタンを使用します。

エージェントは自動的に承認ワークフロー、タスク管理を処理し、各フェーズをガイドします。

🔧 MCPクライアント設定

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

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

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

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

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

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

{
  "$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
    }
  }
}

注意：/path/to/your/projectを、仕様ワークフローを動作させたいプロジェクトディレクトリの実際のパスに置き換えてください。

📚 ドキュメント

ワークフローガイド

• spec-workflow-guide - 仕様駆動型ワークフロープロセスの完全なガイド
• steering-guide - プロジェクトステアリングドキュメントの作成ガイド

仕様管理

• create-spec-doc - 仕様ドキュメント（要件、設計、タスク）を作成/更新
• spec-list - ステータス情報付きですべての仕様をリスト表示
• spec-status - 特定の仕様の詳細なステータスを取得
• manage-tasks - 仕様実装のための包括的なタスク管理

コンテキストとテンプレート

• get-template-context - すべてのドキュメントタイプのMarkdownテンプレートを取得
• get-steering-context - プロジェクトステアリングコンテキストとガイダンスを取得
• get-spec-context - 特定の仕様のコンテキストを取得

ステアリングドキュメント

• create-steering-doc - プロジェクトステアリングドキュメント（製品、技術、構造）を作成

承認システム

• request-approval - ドキュメントのユーザー承認を要求
• get-approval-status - 承認ステータスを確認
• delete-approval - 完了した承認をクリーンアップ

📄 ウェブダッシュボード

ダッシュボードは、MCPサーバーとは別に手動で起動する必要があるサービスです。各プロジェクトには、エフェメラルポートで実行される専用のダッシュボードが用意されています。ダッシュボードは以下を提供します：

• リアルタイムのプロジェクト概要 - 仕様と進捗状況のリアルタイム更新
• ドキュメントビューア - 要件、設計、およびタスクドキュメントを読むことができます。
• タスク進捗追跡 - 視覚的な進捗バーとタスクステータス
• ステアリングドキュメント - プロジェクトガイダンスへの迅速なアクセス
• ダークモード - 読みやすさを向上させるために自動的に有効になります。

ダッシュボードの機能

• 仕様カード - ステータスインジケータ付きの各仕様の概要
• ドキュメントナビゲーション - 要件、設計、およびタスク間を切り替えることができます。
• タスク管理 - タスクの進捗状況を表示し、実装プロンプトをコピーすることができます。
• リアルタイム更新 - リアルタイムのプロジェクトステータスのためのWebSocket接続

🔧 ワークフロープロセス

1. プロジェクトセットアップ（推奨）

steering-guide → create-steering-doc (product, tech, structure)

プロジェクト開発をガイドする基礎ドキュメントを作成します。

2. 機能開発

spec-workflow-guide → create-spec-doc → [review] → implementation

逐次的なプロセス：要件 → 設計 → タスク → 実装

3. 実装サポート

• get-spec-contextを使用して詳細な実装コンテキストを取得します。
• manage-tasksを使用してタスクの完了を追跡します。
• ウェブダッシュボードを通じて進捗状況を監視します。

📁 ファイル構造

your-project/
  .spec-workflow/
    steering/
      product.md        # 製品ビジョンと目標
      tech.md          # 技術的決定
      structure.md     # プロジェクト構造ガイド
    specs/
      {spec-name}/
        requirements.md # 構築する必要があるもの
        design.md      # 構築方法
        tasks.md       # 実装の細分化
    approval/
      {spec-name}/
        {document-id}.json # 承認ステータス追跡

🔨 開発

# 依存関係をインストールする
npm install

# プロジェクトをビルドする
npm run build

# 開発モードで実行する（自動リロード付き）
npm run dev

# 本番サーバーを起動する
npm start

# ビルドアーティファクトをクリーンアップする
npm run clean

🐞 トラブルシューティング

一般的な問題

1. ダッシュボードが起動しない

   • ダッシュボードサービスを起動する際に--dashboardフラグを使用していることを確認してください。
   • ダッシュボードはMCPサーバーとは別に起動する必要があります。
   • ダッシュボードのURLとエラーメッセージをコンソール出力で確認してください。
   • --portを使用する場合は、ポート番号が有効（1024 - 65535）で、他のアプリケーションによって使用されていないことを確認してください。

2. 承認が機能しない

   • ダッシュボードがMCPサーバーと一緒に実行されていることを確認してください。
   • ダッシュボードはドキュメントの承認とタスク追跡に必要です。
   • 両方のサービスが同じプロジェクトディレクトリを指していることを確認してください。

3. MCPサーバーが接続しない

   • 設定内のファイルパスが正しいことを確認してください。
   • プロジェクトがnpm run buildでビルドされていることを確認してください。
   • Node.jsがシステムのPATHに含まれていることを確認してください。

4. ポートの競合

   • 「ポートがすでに使用されています」というエラーが表示された場合は、--port <異なる番号>を使用して別のポートを試してください。
   • Windowsの場合はnetstat -an | find ":3000"、macOS/Linuxの場合はlsof -i :3000を使用して、ポートを使用しているものを確認してください。
   • --portパラメーターを省略すると、利用可能なエフェメラルポートが自動的に使用されます。

5. ダッシュボードが更新されない

   • ダッシュボードはリアルタイム更新にWebSocketを使用しています。
   • 接続が失われた場合は、ブラウザをリフレッシュしてください。
   • コンソールでJavaScriptエラーがないことを確認してください。

ヘルプを得る

• 既知の問題についてはIssuesページを確認してください。
• 提供されているテンプレートを使用して新しい問題を作成してください。
• ツール内のワークフローガイドを使用して、ステップバイステップの指示を得てください。

📄 ライセンス

GPL - 3.0

⭐ スター履歴