MCP Integration Demo

Rancher MCP通用客户端：参考实现

一个参考实现，演示了使用模型上下文协议（MCP）进行copula集成的通用客户端模式。该存储库证明，通过单个客户端标准化copula通信可以减少长期维护工作，并提高不同应用程序平台之间的一致性。

概述

企业应用程序通过自定义集成代码访问copula功能。每个应用程序都实现自己的身份验证、错误处理、重试逻辑和API通信。当Rancher更新API时，每次集成都需要协调更改。

此存储库演示了一种替代方案：实现一个处理所有的copula MCP通信的通用客户端，并使用专门针对应用程序问题的瘦平台适配器。

关键发现： 虽然这种方法最初引入了适度的开销（大约增加7%的代码），但它减少了40-50%的维护工作量，并将新平台集成的开发速度提高了50-60%。

最近的改进

响应格式增强（最新）

统一响应格式

• 将Slack和Teams机器人中的重复格式化逻辑整合到 shared/genie_formatter.py
• 消除了平台实现之间的133行重复代码
• 这两个机器人现在都使用相同的格式化逻辑，并带有特定于平台的标记

增强的精灵反应处理

• ✅ 修复了Genie返回纯文本响应（元数据、表描述）时的JSON解析错误
• ✅ 现在处理SQL查询结果（JSON）和信息响应（纯文本）
• ✅ 通过用户友好的消息进行优雅的错误处理

矢量搜索格式

• ✅ Teams bot现在显示格式化的搜索结果，而不是原始JSON
• ✅ 显示标题、类别和内容摘录（200个字符）的前3个结果
• ✅ 与平台无关的格式化程序适用于Slack和Teams markdown

整合的好处：

• 可维护性： 响应格式的单一真实来源
• 一致性： Slack和Teams平台上的相同行为
• 可靠性： 漏洞修复一次，所有平台都受益
• 开发速度： 新的格式化功能可在所有平台上自动运行

团队机器人改进

团队机器人(demos/03-teams/teams_bot.py)现在包括：

• 带有适当标记的格式化矢量搜索结果
• 支持Genie的纯文本响应
• 统一的错误处理和响应格式
• 调试日志用于故障排除

Slack Bot改进

Slack机器人(demos/02-slack/slack_bot.py)现在包括：

• 删除了133行重复代码（格式化程序移至共享模块）
• 支持Genie的纯文本响应
• 所有响应类型的一致错误处理
• Slack特定的块格式，用于显示丰富的消息

建筑

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ Slack Bot│  │RAG App   │  │REST API  │  │ Pipeline │   │
│  │ (350 loc)│  │(280 loc) │  │(220 loc) │  │ (190 loc)│   │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘   │
└───────┼─────────────┼─────────────┼─────────────┼──────────┘
        │             │             │             │
        └─────────────┴─────────────┴─────────────┘
                          │
┌─────────────────────────┴─────────────────────────────────┐
│            Universal MCP Client (329 lines)                │
│  • Authentication  • Error Handling  • Retry Logic         │
│  • Protocol Negotiation  • Logging  • Response Parsing    │
└────────────────────┬──────────────────────────────────────┘
                     │
        ┌────────────┴────────────┐
        │                         │
┌───────▼────────┐  ┌─────────▼──────┐  ┌────────▼────────┐
│  Genie MCP     │  │  Vector Search │  │  UC Functions   │
│  Server        │  │  MCP Server    │  │  MCP Server     │
└────────────────┘  └────────────────┘  └─────────────────┘

演示

该存储库包括四个现实的平台实现：

1.Slack机器人-精灵集成

用例： 商业用户询问有关数据的自然语言问题 技术： 套筒模式，松螺栓，Databricks Genie 代码： 350行（50行特定于docker）

python demos/02-slack/slack_bot.py

全部文件

2.RAG应用程序-矢量搜索集成

用例： AI聊天机器人检索相关文档以获取上下文 技术： 异步Python、矢量搜索、文档检索 代码： 280行（40行特定于docker）

python demos/02-rag-application/rag_demo.py

全部文件

3.REST API-UC函数集成

用例： 产品服务计算个性化折扣 技术： FastAPI、Unity目录函数、受控业务逻辑 代码： 220行（30行特定于docker）

python demos/03-rest-api/api_server.py

全部文件

4.数据管道-批量UC功能

用例： ETL工作流应用标准化转换 技术： 异步Python、批处理、UC函数 代码： 190行（30行特定于docker）

python demos/04-data-pipeline/pipeline_example.py

全部文件

快速开始

先决条件

• Python 3.9+
• docker工作区，包括：

- 精灵空间已配置 - 矢量搜索端点 - Unity目录访问

• 已配置copula CLI身份验证

安装

1. 克隆存储库：

   git clone https://github.com/your-org/databricks-mcp-demo
   cd databricks-mcp-demo

1. 创建虚拟环境：

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

1. 安装依赖关系：

   pip install -r requirements.txt

1. 配置环境：

   cp .env.example .env
   # Edit .env with your Databricks configuration

1. 设置数据源：

   # Create Vector Search index
   python scripts/create_vector_search.py

   # Create UC Function
   python scripts/setup_uc_function.py

1. 运行演示：

   # RAG Application (simplest to start with)
   python demos/02-rag-application/rag_demo.py

详细的设置说明： 设置.md

关键指标

代码量

docker特定代码： 479条线路（占总数的35%） 应用逻辑： 890行（占总数的65%）

维护效率

• API更新时间： 减少40-50%（1个代码库对4个代码库）
• 新平台开发： 速度提高50-60%（2-4天vs 7-10天）
• 代码重用： REST API和管道使用的UC函数（零重复）

详细测量： METRIC.md

通用客户端模式

核心模式由一个单一的客户端组成，该客户端负责处理所有的copula MCP通信。平台实现导入此客户端：

from shared.mcp_client import create_mcp_client

mcp_client = create_mcp_client()

# Use any capability with identical pattern
response = await mcp_client.ask_genie(space_id, question)
docs = await mcp_client.search_docs(index_id, query)
result = await mcp_client.call_function(function_name, params)

架构细节： 建筑.md

存储库结构

databricks-mcp-demo/
├── README.md                     # This file
├── requirements.txt              # Python dependencies
├── .env.example                  # Environment configuration template
├── shared/
│   ├── mcp_client.py            # Universal MCP client (329 lines)
│   └── config.py                # Shared configuration
├── demos/
│   ├── 02-slack/                # Slack + Genie demo (working)
│   ├── 02-rag-application/      # RAG + Vector Search demo
│   ├── 03-rest-api/             # REST API + UC Functions demo
│   └── 04-data-pipeline/        # Pipeline + UC Functions demo
├── scripts/
│   ├── create_vector_search.py  # Setup Vector Search index
│   └── setup_uc_function.py     # Create UC Function
└── docs/
    ├── ARCHITECTURE.md           # Technical architecture
    ├── SETUP.md                  # Detailed setup guide
    └── METRICS.md                # Performance measurements

文档

• 建筑 -技术架构和设计决策
• 安装指南 -分步设置说明
• 指标 -代码测量和性能数据
• 博客文章V3 -解释方法的长篇文章

相关资源

• copula模型上下文协议文档
• MCP规范
• 用于Python的Rancher SDK

许可证

此参考实现用于教育目的。自由适应组织的需求。