MCP Orchestro

🚀 🎭 Orchestro

Orchestro是一款智能編排系統，它如同一位專業的指揮家，能夠將產品經理、開發者和AI緊密連接起來，助力你將產品理念轉化為實際代碼，高效推動項目從構想到落地。

🚀 快速開始

你可以根據自己的需求，選擇以下任意一種方式來安裝和使用Orchestro：

選項1：從MCP註冊表安裝 ⭐（推薦）

Orchestro現已加入 官方MCP註冊表！

# 通過NPX安裝（無需全局安裝）
npx @khaoss85/orchestro@latest

或者添加到Claude Code配置中：

{
  "mcpServers": {
    "orchestro": {
      "command": "npx",
      "args": ["-y", "@khaoss85/orchestro@latest"],
      "env": {
        "DATABASE_URL": "your-supabase-connection-string"
      }
    }
  }
}

選項2：一鍵安裝 ⚡

npx @orchestro/init

安裝程序將完成以下操作：

• ✅ 下載並設置Orchestro
• ✅ 對Supabase應用數據庫遷移
• ✅ 自動配置Claude Code
• ✅ 設置Supabase連接
• ✅ 啟動儀表盤
• ✅ 驗證一切正常

交互式提示：

🎭 Orchestro Setup Wizard

? Supabase connection string: ████████
? Project name: My Project
? Install location: ~/orchestro

⚙️  Setting up...
✓ Orchestro installed
✓ Claude Code configured
✓ Database ready

🎉 Done! Restart Claude Code and ask:
   "Show me orchestro tools"

選項3：手動安裝（5分鐘）

1. 前提條件

# Node.js 18+
node --version

# Supabase賬戶（免費套餐即可）
# 在https://supabase.com註冊

2. 在Supabase上設置數據庫

創建你的Supabase項目：

1. 訪問https://supabase.com並創建一個新項目
2. 等待數據庫配置完成（約2分鐘）
3. 進入 設置 → 數據庫，複製 連接字符串（事務模式）

應用數據庫架構：

# 首先克隆此倉庫
git clone https://github.com/khaoss85/mcp-orchestro.git
cd mcp-orchestro

# 安裝依賴項
npm install

# 設置你的Supabase連接字符串
export DATABASE_URL="your-supabase-connection-string"

# 應用所有遷移以創建架構
npm run migrate

驗證數據庫設置：

# 遷移腳本將顯示所有創建的表：
# 你應該看到：
# ✅ Running migration: code_entities
# ✅ Running migration: add_tasks_metadata
# ✅ Running migration: fix_status_transition_trigger
# ✅ Running migration: event_queue
# ✅ Running migration: auto_update_user_story_status
# ✅ Running migration: add_task_metadata_fields
# ✅ Running migration: add_pattern_frequency_tracking

# 或者通過Supabase儀表盤手動驗證：
# 進入數據庫 → 表，檢查所有表是否已創建

獲取你的憑證：

# 從Supabase儀表盤：

# 1. DATABASE_URL（用於遷移和MCP服務器）
#    設置 → 數據庫 → 連接字符串 → 事務模式
#    示例：postgresql://postgres:[password]@db.[project].supabase.co:5432/postgres

# 2. SUPABASE_URL（用於API調用）
#    設置 → API → 項目URL
#    示例：https://[project].supabase.co

# 3. SUPABASE_SERVICE_KEY（用於管理操作 - 請保密！）
#    設置 → API → service_role key
#    示例：eyJhbG...

3. 快速設置腳本

# 運行交互式設置
npm run setup

# 或者手動配置：
cat > .env << EOF
DATABASE_URL=your-supabase-connection-string
SUPABASE_URL=your-supabase-url
SUPABASE_SERVICE_KEY=your-service-key
EOF

4. 配置Claude Code

# 自動配置（推薦）
npm run configure-claude

# 或者手動編輯：
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 添加：
{
  "mcpServers": {
    "orchestro": {
      "command": "node",
      "args": ["/absolute/path/to/orchestro/dist/server.js"],
      "env": {
        "DATABASE_URL": "your-connection-string"
      }
    }
  }
}

5. 啟動儀表盤

npm run dashboard
# 🌐 打開 http://localhost:3000

6. 驗證安裝

# 重啟Claude Code，然後詢問：
"Show me all orchestro tools"

# 你應該看到60個工具！ 🎭

選項4：添加到現有項目

如果你已經有一個Claude Code項目，可以添加Orchestro：

# 在你的項目目錄中
npx @orchestro/add

# 或者通過Claude Code配置：
claude mcp add orchestro

有關現有項目設置的詳細信息，請參閱 集成指南。

選項5：Claude Code插件 🎁（最簡單！）

全新功能！ 使用一個命令將Orchestro作為Claude Code插件安裝：

# 在Claude Code終端中
/plugin marketplace add khaoss85/mcp-orchestro

# 安裝Orchestro套件
/plugin install orchestro-suite@orchestro-marketplace

# 提示時重啟Claude Code

你將獲得：

• ✅ Orchestro MCP服務器 - 通過 npx @khaoss85/orchestro@latest 提供60個工具（無需全局安裝）
• ✅ 5個守護代理 - 數據庫、API、架構、測試維護者、生產就緒
• ✅ 自動配置 - MCP服務器和代理隨時可用
• ✅ 完整文檔 - 包含設置指南

前提條件：

• Supabase賬戶（有關設置，請參閱選項2）
• 設置環境變量：

  export SUPABASE_URL="https://your-project.supabase.co"
  export SUPABASE_SERVICE_KEY="your-service-key"
  export ANTHROPIC_API_KEY="your-key"
  

驗證安裝：

# 檢查代理
/agents
# 應該顯示：database-guardian, api-guardian, architecture-guardian,
#              test-maintainer, production-ready-code-reviewer

# 測試MCP工具
mcp__orchestro__get_project_info
mcp__orchestro__list_tasks

插件包括：

• MCP服務器配置 (.mcp.json)
• 5個專門的守護代理
• 包含使用示例的完整README
• 故障排除指南

有關插件的詳細文檔，請參閱 plugins/orchestro-suite/README.md。

✨ 主要特性

👔 面向產品經理和所有者

• 用戶故事分解 - 編寫一個用戶故事，AI將自動創建技術任務
• 可視化進度板 - 具有即時更新的看板視圖
• 無需技術知識 - 無需編碼即可管理開發過程
• 完全透明 - 確切瞭解正在構建的內容、時間和原因
• 風險感知 - 自動標記風險並提供通俗易懂的解釋

👨‍💻 面向開發者

• 智能任務分析 - AI分析代碼庫並建議實現方案
• 依賴跟蹤 - 可視化圖表顯示任務之間的依賴關係
• 模式學習 - 系統從成功和失敗中學習
• 衝突預防 - 檢測任務是否涉及相同的文件
• 上下文保留 - 不會在會話之間丟失上下文

🤖 面向Claude Code

• 60個MCP工具 - 用於編排開發的完整工具包
• 結構化工作流程 - 準備 → 分析 → 實施 → 學習
• 豐富的提示 - 上下文感知的實施指南
• 知識庫 - 模板、模式和學習成果永久保存

📊 面向所有人

• 即時儀表盤 - 通過Socket.io進行即時更新
• 完整歷史記錄 - 所有決策和更改的時間線
• 回滾功能 - 安全地撤銷錯誤操作
• 導出所有內容 - 為利益相關者提供Markdown報告

🎯 為什麼選擇Orchestro？

問題所在：

• 產品經理難以跟蹤開發進度
• 開發者在上下文切換和處理依賴關係時遇到困難
• Claude Code會話之間的知識容易丟失
• 缺乏一個關於正在構建內容的單一事實來源

解決方案：Orchestro編排整個開發生命週期：

• 👔 對於產品經理：可視化看板、用戶故事分解、進度跟蹤
• 👨‍💻 對於開發者：AI驅動的任務分析、依賴關係圖、模式學習
• 🤖 對於Claude Code：結構化工作流程、豐富的上下文、知識保留
• 📊 對於所有人：即時儀表盤、透明的進度、完整的審計跟蹤

可以將其想象為Trello × Jira × AI的結合，但專門為AI輔助開發而設計。

💻 使用示例

基礎用法

面向產品經理

1. 在儀表盤上編寫用戶故事：
   "用戶應該能夠使用電子郵件/密碼登錄"

2. 點擊 "使用AI分解"
   → Orchestro將自動創建具有依賴關係的技術任務

3. 監控看板：
   → 即時查看Claude實施的進度
   → 自動標記風險（例如，"PDF庫大小影響"）
   → 懸停在任務上查看技術細節

4. 審核並接受：
   → 以通俗易懂的方式查看代碼差異
   → 如有需要，進行回滾操作
   → 導出時間線以生成利益相關者報告

面向開發者

1. 從看板上選擇一個任務

2. 詢問Claude：
   "準備執行任務 [任務ID]"
   → Orchestro分析代碼庫
   → 顯示：需要修改的文件、依賴關係、風險

3. 獲取豐富的上下文：
   → 過去類似的實現
   → 相關模式（帶有成功率！）
   → 風險緩解策略

4. 自信地實施：
   → 如果其他任務涉及相同的文件，衝突檢測會發出警告
   → 模式學習建議最佳方法
   → 完整的歷史記錄確保安全回滾

面向團隊

產品經理編寫故事 → AI分解 → 開發者實施 → 所有人查看進度

• 產品經理：非技術看板視圖
• 開發者：技術依賴關係圖
• Claude：豐富的實施上下文
• 所有人：即時更新、完全透明

高級用法

電商結賬流程示例

// 1. 分解故事（自動分析任務）
decompose_story("Customer checkout with payment")
// → 創建6個任務
// → 自動為無依賴關係的任務生成分析提示
// → 返回準備使用的分析提示數組

// 2. Claude審查分析提示
// 提示包括：要檢查的文件、要查找的模式、要識別的風險

// 3. Claude使用提示分析代碼庫
// 找到：現有的支付表、類似的架構
// 風險：無（新表）

// 4. 保存分析結果
save_task_analysis({
  taskId: "task-1-id",
  filesToCreate: ["migrations/002_checkout.sql"],
  dependencies: [{type: "file", name: "001_orders.sql", action: "uses"}],
  risks: []
})

// 5. 獲取豐富的上下文
get_execution_prompt("task-1-id")
// → 返回：相關代碼、模式、指南

// 6. 實施！
// Claude編寫遷移腳本、運行測試

// 7. 記錄學習成果
add_feedback({
  pattern: "e-commerce checkout schema",
  type: "success",
  feedback: "Stripe integration smooth"
})

📚 詳細文檔

入門指南

• 快速開始指南 - 5分鐘設置指南
• 產品經理指南 - 即將推出
• 開發者指南 - 即將推出
• 示例 - 實際使用示例

深入探索

• 工作流程 - 完整的工作流程解釋
• 架構 - 技術架構
• API文檔 - MCP工具參考

🔧 技術細節

開發流程

┌─────────────────────────────────────────────────────┐
│  產品經理                                           │
│  "用戶應該能夠使用電子郵件/密碼登錄"               │
└─────────────────────────────────────────────────────┘
                        ↓
            ┌──────────────────────┐
            │  Orchestro AI        │
            │  分解用戶故事        │
            └──────────────────────┘
                        ↓
    ┌──────────────────────────────────────────┐
    │  創建7個技術任務                         │
    │  • 數據庫架構                            │
    │  • 認證服務                              │
    │  • API端點                               │
    │  • 前端組件                              │
    │  • 狀態管理                              │
    │  （自動處理依賴關係）                    │
    └──────────────────────────────────────────┘
                        ↓
            ┌──────────────────────┐
            │  開發者/Claude Code  │
            │  實施任務            │
            └──────────────────────┘
                        ↓
    ┌──────────────────────────────────────────┐
    │  產品經理查看進度                        │
    │  • 看板即時更新                          │
    │  • 自動標記風險                          │
    │  • 可視化依賴關係                        │
    └──────────────────────────────────────────┘

架構設計

┌─────────────────────────────────────────┐
│         產品經理                         │
│  • 編寫用戶故事                         │
│  • 監控看板                             │
│  • 審查進度                             │
└─────────────────────────────────────────┘
              ↓ (儀表盤)
┌─────────────────────────────────────────┐
│      Orchestro儀表盤 (Next.js)          │
│  • 具有即時更新的看板                   │
│  • 依賴關係圖                           │
│  • 進度可視化                           │
└─────────────────────────────────────────┘
              ↓ ↑ (Socket.io)
┌─────────────────────────────────────────┐
│         Supabase (數據層)               │
│  • 任務、依賴關係、資源                 │
│  • 事件隊列和即時同步                   │
│  • 知識庫和模式跟蹤                     │
└─────────────────────────────────────────┘
              ↓ ↑ (PostgreSQL)
┌─────────────────────────────────────────┐
│    Orchestro MCP服務器 (指揮者)         │
│  • 27個用於任務編排的工具               │
│  • 模式學習和風險檢測                   │
│  • AI用戶故事分解                       │
└─────────────────────────────────────────┘
              ↓ ↑ (MCP協議)
┌─────────────────────────────────────────┐
│      Claude Code (開發者 + AI)          │
│  • 分析代碼庫                           │
│  • 實現功能                             │
│  • 記錄決策                             │
└─────────────────────────────────────────┘

技術棧

性能與擴展性

• ⚡ 查詢速度：使用GIN索引，查詢速度小於10ms
• 🔄 即時性：輪詢間隔為1秒
• 🗄️ 存儲：自動清理已處理的事件（24小時）
• 📊 可擴展性：已在100多個任務上進行測試
• 🚀 分析：非阻塞（委託給Claude）
• 👥 用戶：支持多個產品經理和開發者

安全與合規性

• ✅ 環境變量 - 不使用硬編碼的秘密信息
• ✅ Supabase RLS - 行級安全策略
• ✅ 完整審計跟蹤 - 記錄每一個決策
• ✅ 事件處理 - 防止重複操作
• ✅ 本地優先 - 所有數據存儲在你的Supabase實例中
• ✅ 符合GDPR - 支持導出和刪除數據

📄 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE 文件。

📈 版本更新日誌

v2.1.0 (2025-10-10) - 當前版本 🎉

• ✅ 發佈到MCP註冊表 - 現已加入 官方MCP註冊表
• ✅ NPM包 - 以 @khaoss85/orchestro 名稱發佈到npm
• ✅ 60個MCP工具 - 從27個擴展到60個生產就緒工具
• ✅ 自動任務分析 - decompose_story 現在默認自動準備分析提示（autoAnalyze=true）
• ✅ 項目配置系統 - 完整的技術棧、代理和工具管理
• ✅ Claude Code代理同步 - 與 .claude/agents/ 目錄自動同步
• ✅ AI代理/工具建議 - 為任務提供智能推薦
• ✅ 任務歷史記錄和事件 - 包含13個歷史工具的完整審計跟蹤
• ✅ 用戶故事健康狀態 - 監控完成情況和狀態一致性
• ✅ 修復漏洞 - 解決了 get_project_configuration 中的SQL錯誤
• ✅ 全面測試覆蓋 - 所有60個工具均經過測試和驗證（成功率96.7%）

v2.0.0 (2025-10-03)

• ✅ 更名為Orchestro - "你的AI開發指揮家"
• ✅ 模式分析工具 - 新增5個用於故障檢測的MCP工具
• ✅ 模式頻率跟蹤 - 通過數據庫觸發器自動跟蹤
• ✅ 風險評估 - detect_failure_patterns 和 check_pattern_risk
• ✅ 任務元數據 - 增加了分配人、優先級、標籤字段
• ✅ 面向產品經理的文檔 - 為產品所有者更新

v1.5.0 (2025-10-02)

• ✅ 新工作流程：MCP編排，Claude Code分析
• ✅ 3個執行工具：prepare、save_analysis、get_execution_prompt
• ✅ tasks.metadata JSONB列
• ✅ 事件隊列更新（8種事件類型）
• ✅ 守護驗證通過

v1.0.0

• 初始MCP實現
• 基本任務管理
• AI用戶故事分解
• 知識庫集成

🌟 成功案例

“作為一名產品經理，我終於能夠即時瞭解開發者正在構建的內容。Orchestro彌合了產品願景和技術實現之間的差距。” — 你的推薦語

“模式學習為我們節省了大量時間。系統在我們浪費時間之前就警告了一個有風險的方法。” — 你的推薦語

📞 支持與社區

• 📧 問題反饋：GitHub Issues
• 💬 討論交流：GitHub Discussions
• 📖 文檔資料：倉庫中提供了全面的指南
• 🌐 儀表盤：http://localhost:3000
• 🐦 Twitter：@orchestro_ai（即將推出）

🙏 致謝

• Claude Code - MCP平臺和AI開發
• Supabase - 數據庫和即時基礎設施
• Next.js - 用於儀表盤的React框架
• React Flow - 漂亮的依賴關係圖
• shadcn/ui - 精美的UI組件