AI导哈

意图路由与流程执行服务

MCP Orchestrator是Model Context Protocol（MCP）平台的核心协调层，负责意图分类、流程路由、会话跟踪及跨服务追踪。

  • by wbernardo-star
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 wbernardo-star/blinksbuy_mcp_orchestrator

使用说明

MCP编排器

模型上下文协议——意图路由和流执行
版本1.1

概述

MCP编排器是模型上下文协议（MCP）平台的中央协调层。它从MCP适配器接收精简规范化请求，并执行以下操作：

  1. 意图分类（基于OpenAI或存根）
  2. 通过流服务进行域流路由
  3. 轻量级会话跟踪（回合数、last_route）
  4. Loki+Grafana的结构化可观测性
  5. 跨适配器的端到端trace_id传播→ 编排器→ 意图→ flow → 菜单服务

编排器故意不返回规范的JSON。MCP适配器将其输出封装到规范响应v1.1中。

在建筑中的作用

客户端→ 频道→ MCP适配器→ MCP编排器→ 意向服务→ 流量服务→ 菜单服务→ MCP适配器→ 客户端

MCP适配器职责

  • 规范JSON v1.1（输入+输出）
  • 多模态归一化
  • 信封生成错误
  • trace_id创建
  • 设备、区域设置、租户、频道上下文

MCP协调人职责

  • 意图分类
  • 流路由
  • 精简会话状态
  • 日志记录+跟踪传播

环境变量

变量 描述
GRAFANA_LOKI_URL GRAFANA Cloud洛基推送URL
GRAFANA_LOKI_USER名称 洛基租户ID
GRAFANA_LOKI_API_TOKEN neneneba API令牌（日志：写入）
MCP_APP_LABEL 洛基应用标签
OPENAI_API_KEY 用于OPENAI意图分类的密钥
OPENAI_MODEL OPENAI模型名称
MENU_SERVICE_URL 外部菜单微服务URL

API终点

GET/健康

示例响应：

{
  "status": "ok",
  "service": "mcp_orchestrator_thin"
}

POST/编排

请求（精简格式）

{
  "text": "Can you read me the menu?",
  "user_id": "user-123",
  "channel": "web",
  "session_id": "user-123:web",
  "trace_id": "trace-123abc"
}

编排器响应（精简格式）

{
  "decision": "reply",
  "reply_text": "Here is the menu.",
  "session_id": "user-123:web",
  "route": "menu",
  "intent": "menu",
  "intent_confidence": 0.98,
  "trace_id": "trace-123abc"
}

规范响应v1.1（成功）

{
  "version": "1.1",
  "timestamp": "2025-11-21T21:28:56.146Z",
  "context": {
    "channel": "web",
    "device": "browser",
    "locale": "en-US",
    "tenant": "blinksbuy",
    "client_app": "elevenlabs"
  },
  "session": {
    "session_id": "user-123:web",
    "conversation_id": "conv-001",
    "user_id": "user-123",
    "turn": 4,
    "route": "menu"
  },
  "response": {
    "status": "success",
    "code": 200,
    "type": "text",
    "text": "Here is the menu:\n1. Garlic Chicken – 500\n2. Sizzling Pata – 650",
    "metadata": {
      "source": "mcp_orchestrator",
      "duration_ms": 16250.315
    }
  },
  "error": null,
  "observability": {
    "trace_id": "trace-123abc",
    "span_id": "span-out-1",
    "message_id": "msg-0003"
  }
}

规范响应v1.1（错误）

{
  "version": "1.1",
  "timestamp": "2025-11-21T21:28:56.146Z",
  "context": {
    "channel": "web",
    "device": "browser",
    "locale": "en-US",
    "tenant": "blinksbuy",
    "client_app": "elevenlabs"
  },
  "session": {
    "session_id": "user-123:web",
    "conversation_id": "conv-001",
    "user_id": "user-123",
    "turn": 4,
    "route": null
  },
  "response": {
    "status": "error",
    "code": 502,
    "type": "text",
    "text": null,
    "metadata": {
      "source": "mcp_adapter",
      "duration_ms": 112.529
    }
  },
  "error": {
    "type": "MCP_ORCHESTRATOR_ERROR",
    "code": 502,
    "message": "MCP orchestrator error: 500 Internal error in orchestrator",
    "retryable": false,
    "details": {
      "mcp_url": "https://your-mcp-service.railway.app/orchestrate"
    }
  },
  "observability": {
    "trace_id": "trace-123abc",
    "span_id": "span-error-1",
    "message_id": "msg-err-001"
  }
}

测井和观测

所有服务都使用以下方式将结构化JSON日志记录到Grafana Loki中：

  • trace_id
  • 会话id
  • service_type
  • 同步模式
  • 输入
  • 事件类型
  • latency_ms
  • 意图+信心

这实现了全面的跨服务可追溯性。

项目结构

app/
  main.py
  flow_service.py
  intent_service.py
  menu_service.py
  logging_loki.py
grafana/
  mcp_orchestrator_loki_dashboard.json
Procfile
requirements.txt
README.md

铁路部署

程序文件：

web: uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8000}

设置环境变量：

  • GRAFANA_LOKI_网址
  • GRAFANA_LOKI_用户名
  • GRAFANA_LOKI_API_TOKEN公司
  • OPENAI_API密钥
  • MENU_SERVICE_URL
  • MCP_APP_LABEL

总结

编排器现在完全与以下内容对齐：

  • MCP规范JSON v1.1
  • trace_id传播
  • 升级了意图、流程、菜单服务
  • 更新了带有跟踪标签的logging_log
  • 铁路部署要求
  • Grafana仪表板可追溯性

相关 MCP