🎭 DevParadeOrchestra MCP - MCP仕様完全準拠AI開発システム

DevParadeOrchestra MCP（DPO-MCP） は、MCP（Model Context Protocol）仕様に完全準拠した世界初のドクトリン駆動AI開発システムです。
AIが設計原則を忘れる・違反する問題を根本的に解決し、企業級の一貫した高品質開発を自動化します。

🎯 プロジェクト概要

コア機能

• 🧩 Master: AI駆動タスク分割 + ドクトリン統合管理
• 👷 Worker群: 専門分野別AI実装（DB・Frontend・Backend・Test・Security・DevOps）
• 🛡️ Validator Worker: ドクトリン準拠検証・違反検出・修正指示生成
• 💾 ContextOptimizer: 永続化・要約圧縮・検索・履歴管理
• 📐 DoctrineManager: JSON Schema準拠のドクトリン管理・バージョン管理

🚀 MCP仕様完全準拠

• ✅ インターフェース契約: JSON Schema、二段階実行、冪等性保証
• ✅ 成果物の扱い: diff/AST形式、Resource化、ハンドル返却
• ✅ 安全・ガバナンス: 危険操作宣言、権限スコープ、セキュリティ監査
• ✅ 品質保証: テスト駆動、静的検査、カバレッジ管理
• ✅ 並列・オーケストレーション: 並列ワーカー、合議戦略、競合回避
• ✅ コスト・レート・可観測性: 使用量可視化、レート制限、完全監査ログ
• ✅ 失敗時のふるまい: 原子性、エラー粒度、フォールバック
• ✅ Cursor連携: サーバー登録、ユーザー承認分割、出力サイズ制限

革新性

• 設計原則の永続化: AIがドクトリンを忘れる問題を解決
• 自動検証フロー: 全Worker出力のドクトリン準拠自動チェック
• フィードバックループ: 違反検出→修正指示→再作業の自動化
• 企業級品質: JSON Schema・エラーハンドリング・監査ログ

🚀 最新機能（MCP準拠版）

🔧 MCP準拠ツール

• master_development_request_plan: 詳細実行計画の作成（計画段階）
• master_development_request_execute: 承認された計画の実行（実行段階）
• get_resource: Resource取得（大容量ファイル対応）
• list_resources: Resource一覧表示

🛡️ セキュリティ・ガバナンス

• 危険操作宣言: policy_flagsで危険操作を明示
• 権限スコープ: ホワイトリスト制御、ディレクトリ制限
• セキュリティ監査: 全操作の監査ログ・追跡
• 承認システム: 危険操作の段階的承認

📊 品質保証

• テスト駆動: 自動テスト生成・実行・カバレッジ管理
• 静的検査: lint・typecheck・security scan
• エラー管理: 詳細エラー情報・再現性・修正提案
• 設計判断: 根拠・トレードオフ・代替案の明示

💰 コスト管理

• 使用量可視化: トークン数・APIコスト・実行時間
• レート制限: 同時実行制御・API呼び出し制限
• コスト予測: リアルタイムコスト計算・アラート
• 日次管理: 自動リセット・統計・推奨事項

🔄 冪等性保証

• 固定シード: 乱数生成の再現性保証
• 依存関係固定: バージョン固定・環境安定化
• API順序: 呼び出し順序の記録・安定化
• 環境固定: タイムゾーン・環境変数の固定

🚀 クイックスタート

1. インストール & 設定

# リポジトリのクローン
git clone https://github.com/your-org/dev-parade-orchestra-mcp.git
cd dev-parade-orchestra-mcp

# 依存関係のインストール
npm install

# 環境変数の設定
cp .env.example .env
# .envファイルを編集してAPIキーを設定

2. Cursor設定

// .cursor/config
{
  "mcp": {
    "servers": {
      "dev-parade-orchestra": {
        "command": "node",
        "args": ["server.js"],
        "env": {
          "OPENAI_API_KEY": "your-openai-api-key",
          "ANTHROPIC_API_KEY": "your-anthropic-api-key",
          "GOOGLE_AI_API_KEY": "your-google-ai-api-key"
        }
      }
    }
  }
}

3. サーバー起動

# 開発モード
npm run dev

# 本番モード
npm start

# PM2での管理
npm run start:pm2

🔧 使用方法

基本的な使用フロー

1. 計画段階: master_development_request_planで実行計画を作成
2. 承認: 計画をレビュー・承認
3. 実行段階: master_development_request_executeで実際の実行
4. 結果確認: Resource・テスト結果・使用量の確認

ツール使用例

// 計画段階
const planResult = await mcp.callTool('master_development_request_plan', {
  request: 'ユーザー認証システムの実装',
  context: {
    techStack: 'Node.js + PostgreSQL',
    requirements: 'セキュリティ重視'
  }
});

// 実行段階
const executeResult = await mcp.callTool('master_development_request_execute', {
  plan_id: planResult.metadata.task_id,
  approval_token: 'approved_token_here',
  context: {}
});

📋 MCP仕様準拠チェックリスト

✅ インターフェース契約

• [x] ツール出力はSchemaに完全準拠（機械検証OK）
• [x] 変更はdiff/ASTで返却（丸投げしない）
• [x] 二段階実行（plan→execute）
• [x] 冪等性保証（同じ入力で同じ結果）

✅ 成果物の扱い

• [x] 大容量はResource（ファイル本体はResource、ハンドルのみ返却）
• [x] 一時領域の明確化（/tmp/work-）
• [x] diff/ASTパッチ優先

✅ 安全・ガバナンス

• [x] policy_flags宣言＆危険操作は分離＋UI承認
• [x] シークレット最小化（短命トークン・読み取り専用）
• [x] 権限スコープ（ホワイトリスト・ディレクトリ制限）

✅ 品質保証

• [x] tests/lint/typecheck/scanが緑（基準を数値で）
• [x] テスト駆動（基準未達は採用拒否）
• [x] 根拠提示（設計判断の要点）

✅ 並列・オーケストレーション

• [x] 並列ワーカー（Promise.all/asyncio）
• [x] 合議戦略（投票・ベスト案のdiff抽出）
• [x] 競合回避（リソースロック）
• [x] タイムアウト&再試行（指数バックオフ）

✅ コスト・レート・可観測性

• [x] usageにコスト・時間を明示
• [x] 同時実行制御（レート制限・キュー）
• [x] 完全監査ログ（入力/出力ハッシュ・依存バージョン）

✅ 失敗時のふるまい

• [x] 原子性（テスト失敗時は何も永続化しない）
• [x] エラー粒度（再現可能な情報）
• [x] フォールバック（部分成功・自動ロールバック）

✅ Cursor連携

• [x] サーバー登録（.cursor/config）
• [x] ユーザー承認の分割（小さなツールに分割）
• [x] 出力サイズ制限（構造化JSON＋Resource参照）
• [x] 対話単位の完結（1ツール呼び出し＝1つの意味のある成果物）

🧪 テスト

# 全テスト実行
npm test

# ユニットテストのみ
npm run test:unit

# 統合テストのみ
npm run test:integration

# カバレッジ付きテスト
npm run test:coverage

🎯 テスト結果

• 54個中54個が成功（100%の成功率）
• Masterテスト: 全15個が成功
• Workerテスト: 全18個が成功
• DoctrineManagerテスト: 全10個が成功
• WorkerValidatorテスト: 全11個が成功

📊 監視・ログ

# リアルタイムログ表示
tail -f logs/combined.log

# エラーログのみ
tail -f logs/error.log

# MCP監査ログ
grep "MCP Audit Trail" logs/combined.log

# コスト管理ログ
grep "Cost Manager" logs/combined.log

🔒 セキュリティ

危険操作の分類

• read_only: 読み取り専用（デフォルト）
• exec_shell: シェル実行
• network_write: ネットワーク書き込み
• secrets_access: シークレットアクセス
• file_write: ファイル書き込み
• git_push: Gitプッシュ
• deploy: デプロイ
• db_migrate: データベースマイグレーション
• system_config: システム設定

権限スコープ

• 許可ディレクトリ: ./src, ./test, ./docs, ./modules, ./utils
• 許可拡張子: .js, .ts, .json, .md, .yml, .yaml
• 最大ファイルサイズ: 10MB
• Git保護: 有効
• システム保護: 有効

💰 コスト管理

制限値（デフォルト）

• 最大同時実行: 10リクエスト
• レート制限: 60リクエスト/分
• 最大トークン: 10,000トークン/リクエスト
• 最大コスト: $100/日

コスト予測

• GPT-4o: $0.03/1K tokens
• GPT-4o-mini: $0.015/1K tokens
• Claude-3-Opus: $0.075/1K tokens
• Claude-3-Sonnet: $0.003/1K tokens
• Gemini-Pro: $0.0005/1K tokens

🔄 冪等性保証

固定要素

• 乱数シード: 固定値による再現性
• 依存関係: package.jsonから固定
• 環境変数: NODE_ENV, TZ固定
• API順序: 呼び出し順序の記録

ハッシュ生成

• 入力パラメータのハッシュ
• 固定シードの組み込み
• 依存関係バージョンの組み込み
• 環境情報の組み込み

📈 パフォーマンス

推奨設定

• テスト基準: branches >= 70%, lines >= 80%
• タイムアウト: 個別API 30-60s、全体 180s
• 再試行: max_retries = 2、指数バックオフ（上限 8s）
• 同時実行: モデルごとに concurrency = 2-4
• 出力制限: 単レスポンス本文 ≤ 1-2MB

🤝 コントリビューション

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 ライセンス

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 謝辞

• MCP（Model Context Protocol）仕様の策定者
• Cursor開発チーム
• オープンソースコミュニティ

📞 サポート

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

DevParadeOrchestra MCP - MCP仕様完全準拠のAI開発システム 🎭✨