Structured Workflow MCP

🚀 構造化ワークフローMCPサーバー

このMCPサーバーは、開発の各フェーズにおいて、AIアシスタントに作業の監査を行い、検証済みの出力を生成することを要求することで、規律あるプログラミング手法を強制します。

🚀 クイックスタート

このMCPサーバーを使用することで、AIに規律あるプログラミング手法を強制し、システマティックに作業させることができます。以下に、サーバーの導入方法や使用方法を説明します。

✨ 主な機能

• 強制的なワークフローフェーズ：AIは、特定のフェーズ（セットアップ、監査、分析、計画、実装、テストなど）を順番に完了する必要があります。
• 必須の出力成果物：各フェーズでは、次のフェーズに進む前に、構造化されたドキュメントまたは検証済みの出力が必要です。
• 複数のワークフロータイプ：コードのリファクタリング、機能開発、テストカバレッジの向上、テスト駆動開発（TDD）サイクル、特殊なニーズに対応するカスタムワークフローなど、さまざまなワークフロータイプがあります。
• 出力検証：サーバーは、出力が意味のある内容と適切な構造を持っていることを検証します。
• セッション状態管理：進捗状況を追跡し、フェーズをスキップすることを防止します。

📦 インストール

クイックスタート（推奨） - ゼロインストール

AIアシスタントの設定に追加 - 自動的にnpxを使用します。

⚠️ 重要提示

@latestを使用することをおすすめします。これにより、常に最新の機能と修正を取得できます。@latestを使用しない場合、npxは古いバージョンをキャッシュする可能性があります。

VS Code / Cursor / Windsurf - MCP設定に追加：

{
  "mcp": {
    "servers": {
      "structured-workflow": {
        "command": "npx",
        "args": ["structured-workflow-mcp@latest"],
        "env": {}
      }
    }
  }
}

Claude Desktop - claude_desktop_config.jsonに追加：

{
  "mcpServers": {
    "structured-workflow": {
      "command": "npx",
      "args": ["structured-workflow-mcp@latest"],
      "env": {}
    }
  }
}

グローバルインストール（オプション）

NPMを使用してマシンにグローバルにインストールすることができます。

npm install -g structured-workflow-mcp

その後、AIアシスタントの設定で使用します。

{
  "mcp": {
    "servers": {
      "structured-workflow": {
        "command": "structured-workflow-mcp",
        "args": [],
        "env": {}
      }
    }
  }
}

カスタム出力ディレクトリを指定する場合：

{
  "mcp": {
    "servers": {
      "structured-workflow": {
        "command": "structured-workflow-mcp",
        "args": ["--output-dir", "/home/user/workflow-outputs"],
        "env": {}
      }
    }
  }
}

Smitheryを介した自動インストール

Smitheryは、Claude Desktopなどのアプリに直接インストールするためのいくつかの方法を提供します。

npx -y @smithery/cli install structured-workflow-mcp --client claude

手動インストール

開発者は、リポジトリをクローンし、ローカルでビルドすることができます。

git clone https://github.com/kingdomseed/structured-workflow-mcp
cd structured-workflow-mcp
npm install && npm run build

💻 使用例

基本的な使用法

AIアシスタントに設定した後、以下のワークフローツールを使用して始めましょう。

• mcp__structured-workflow__build_custom_workflow - カスタムワークフローを作成します。
• mcp__structured-workflow__refactor_workflow - 構造化されたリファクタリングを行います。
• mcp__structured-workflow__create_feature_workflow - 機能開発を行います。
• mcp__structured-workflow__test_workflow - テストカバレッジのワークフローを行います。

高度な使用法

サーバーは、AIが次のような構造化された出力を生成することを強制します。

AUDIT_INVENTORYフェーズの出力例：

{
  "filesAnalyzed": ["lib/auth/user_service.dart", "lib/auth/auth_middleware.dart"],
  "dependencies": {
    "providers": ["userProvider", "authStateProvider"],
    "models": ["User", "AuthToken"]
  },
  "issues": [
    "Single Responsibility Principle violation - handles too many concerns",
    "File approaching 366 lines - recommended to keep widgets smaller"
  ],
  "changesList": [
    {
      "action": "CREATE",
      "file": "lib/auth/components/auth_form.dart",
      "description": "Extract authentication form logic",
      "justification": "Component focused on form validation only"
    }
  ]
}

COMPARE_ANALYZEフェーズの出力例：

{
  "approaches": [
    {
      "name": "Incremental Component Extraction",
      "complexity": "Medium",
      "risk": "Low", 
      "timeEstimate": "30-45 minutes"
    }
  ],
  "recommendation": "Incremental Component Extraction",
  "justification": "Provides best balance of benefits vs. risk",
  "selectedImplementationOrder": [
    "1. Extract form component (lowest risk)",
    "2. Create validation service",
    "3. Refactor main view"
  ]
}

各フェーズでは、AIが実装に進む前に、文書化された分析と計画が必要です。

📚 ドキュメント

ワークフローエントリポイント

• refactor_workflow - 必要な分析と計画フェーズを含む構造化されたリファクタリングプロセスを開始します。
• create_feature_workflow - 統合されたテストとドキュメント要件を持つ新しい機能を開発します。
• test_workflow - テストが必要なものを必須の分析とともにテストカバレッジを追加します。
• tdd_workflow - 強制されたRed-Green-Refactorサイクルでテスト駆動開発を実装します。
• build_custom_workflow - カスタムフェーズと検証要件を持つワークフローを作成します。

フェーズガイダンスツール

• audit_inventory_guidance - 徹底的なコード分析と変更のカタログ化を強制します。
• compare_analyze_guidance - 複数のアプローチの評価とその長所と短所を要求します。
• question_determine_guidance - 明確化と最終的な計画を必須とします。
• phase_output - 各フェーズからの構造化された出力を検証し、記録します。
• workflow_status - 現在の進捗状況と検証状態を確認します。

入力検証

サーバーは、以下の入力を要求します。

• task (文字列)：達成したいことの説明
• outputArtifacts (配列)：各完了フェーズの構造化されたドキュメント

出力検証

各フェーズの完了は、以下の条件で検証されます。

• 意味のあるコンテンツの長さ（最小10文字）
• 構造化された出力の有効なJSON形式
• フェーズ固有のコンテンツ要件
• 決定と分析の適切なドキュメント化

セーフティルール

ファイルは変更前に読み取る必要があります。これにより、誤ったデータの損失を防ぎ、適切な変更を確保します。

🔧 技術詳細

ワークフローの仕組み

graph TD
    A[🚀 Start Workflow] --> B[AI Gets Phase Guidance]
    B --> C{Create Phase Output}
    C --> D[Auto-Save with Numbered Naming<br/>00-setup-confirmation-2025-01-07.md]
    D --> E[Phase Validation]
    E --> F{All Phases Done?}
    F -->|No| G[Move to Next Phase]
    G --> B
    F -->|Yes| H[Workflow Complete!]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style D fill:#e8f5e8
    style E fill:#fff9c4
    style H fill:#e8f5e8

各ステップでの処理：

1. ワークフローの開始 - AIはワークフローツール（refactor_workflow、create_feature_workflowなど）を呼び出します。
2. AIがフェーズガイダンスを取得 - サーバーは現在のフェーズ（監査、分析、実装など）に関する具体的な指示を提供します。
3. フェーズ出力の作成 - AIはフェーズを進め、ドキュメント/成果物を作成します。
4. 自動保存 - ファイルはタスクディレクトリに番号付きの名前で自動的に保存されます。
5. フェーズ検証 - サーバーは出力が要件を満たしていることを検証し、次のフェーズに進むことを許可します。
6. 次のフェーズ - ワークフローが完了するまでプロセスが繰り返されます。

この分解の利点の1つは、AIエージェントが現在のフェーズに関連する指示セットを受け取り、全体のワークフローで迷子になることを防ぎ、現在のフェーズに集中できることです。これに関する興味深い記事はこちらで読むことができます：LLMs Get Lost In Multi-Turn Conversation

ワークフロー出力

AI生成ドキュメント

サーバーは、フェーズを進めるにつれて番号付きのワークフローファイルを提案します。AIアシスタントは、独自のツールを使用して実際のファイルを作成します。

workflows/
├── your-task-name/
│   ├── 01-audit-inventory-2025-01-04.md
│   ├── 02-compare-analyze-2025-01-04.json
│   ├── 03-question-determine-2025-01-04.md
│   ├── 04-write-or-refactor-2025-01-04.md
│   ├── 05-test-2025-01-04.json
│   ├── 06-lint-2025-01-04.json
│   ├── 07-iterate-2025-01-04.md
│   └── 08-present-2025-01-04.md

ワークフローアーキテクチャ

• ファイル処理：サーバーは提案されたパスと形式を提供しますが、直接ファイルを書き込むことはありません。代わりに、AIアシスタントに独自のファイルシステムアクセスを使用してこれらのファイルを作成するように指示します。
• 一貫した命名：ファイルは、フェーズ番号、名前、タイムスタンプを含む標準化された命名規則に従います。
• 環境独立性：アーキテクチャは、AIが適切なファイルシステムアクセス許可を持っている任意の環境で動作します。
• グレースフルデグレーデーション：AIがファイルを作成できない場合、ワークフローはメモリのみのモードで続行され、進捗状況が中断されることはありません。

📄 ライセンス

このMCPサーバーはMITライセンスの下でライセンスされています。これは、MITライセンスの条件に従い、ソフトウェアを自由に使用、変更、配布できることを意味します。