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)          │
│  • 分析代码库                           │
│  • 实现功能                             │
│  • 记录决策                             │
└─────────────────────────────────────────┘

技术栈

| 属性 | 详情 | |------|------| | 后端（MCP服务器） | TypeScript 5.0、@modelcontextprotocol/sdk、Supabase (PostgreSQL)、Socket.io用于实时通信 | | 前端（仪表盘） | Next.js 14 (App Router)、React 18 + TypeScript、TailwindCSS + shadcn/ui、React Flow (图表)、react-markdown (渲染) | | 数据库（Supabase/PostgreSQL） | 核心：项目、任务、任务依赖关系；知识：学习成果、模式、模板、模式频率；资源：资源节点、资源边、代码实体、代码依赖关系；系统：事件队列、文件历史记录、代码库分析；技术：JSONB元数据、GIN索引、行级安全 (RLS) | | AI集成 | Claude Code (MCP协议)、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组件