关键词

Cosmos DBAzure产品搜索订单查询上下文服务

使用说明

项目简介

该项目是一个基于Model Context Protocol (MCP) 的服务器实现，旨在演示如何使用 MCP 协议连接 Azure Cosmos DB 数据库，并为 LLM 客户端提供商品目录和订单数据访问能力。该 MCP 服务器作为应用后端，可以与前端应用（如示例中的 NextJS 应用）或直接与 LLM 客户端配合使用，为 AI 应用提供结构化的数据访问和工具调用能力。

主要功能点

  • 资源访问: 通过 MCP 协议向客户端提供访问 Azure Cosmos DB 中商品目录和订单数据的能力。
  • 工具注册与执行: 注册了 'searchProducts' 和 'getOrders' 工具，允许 LLM 客户端调用以搜索商品和查询订单。
  • 基于 Azure Cosmos DB: 后端数据存储基于 Azure Cosmos DB NoSQL 数据库，利用 Cosmos DB 的向量搜索能力实现商品语义搜索。
  • SSE 传输协议: 使用 SSE (Server-Sent Events) 作为 MCP 服务器的传输协议，实现与客户端的实时通信。
  • 可扩展性: 项目结构清晰，易于扩展新的数据资源和工具，满足更复杂的 LLM 应用场景需求。

安装步骤

  1. Azure 云资源配置:

    • 确保已创建 Azure Cosmos DB for NoSQL 账号，并启用向量搜索功能。
    • 在 Cosmos DB 中创建 'eshop' 数据库，以及 'products'、'carts' 和 'orders' 容器。'products' 容器需要配置向量索引。
    • 创建 Azure Storage 账号用于存储商品图片（可选，示例项目使用）。
    • 创建 Azure OpenAI 服务，并部署 Embedding 模型和 Chat 模型（用于向量 embedding 和 LLM 交互，非 MCP 服务器核心功能，但 populate 脚本和 Nextjs 前端用到）。

  2. 软件环境准备:

    • 安装 Node.js (v22.13.1 或更高版本)。
    • 安装 .NET SDK (v9.0 或更高版本，用于 populate 脚本)。
    • 安装 Git。
    • 克隆 GitHub 仓库 'https://github.com/patrice-truong/cosmosdb-mcp.git' 到本地。

  3. 配置环境变量:

    • 在 'cosmosdb-mcp/mcp-server' 目录下，复制 '.env.template' 文件并重命名为 '.env'。
    • 修改 '.env' 文件，填入 Azure Cosmos DB, Azure Storage 和 Azure OpenAI 的连接信息，例如 Endpoint, Database Name, Container Name, Account Name, API Key 等。
    • 在 'cosmosdb-mcp/populate' 目录下，复制 'appsettings.json' 文件并根据实际 Azure Cosmos DB 账号信息进行配置。
    • 在 'cosmosdb-mcp/nextjs' 目录下，复制 '.env.template' 文件并重命名为 '.env'，根据实际 Azure 服务信息进行配置 (Nextjs 前端使用)。

  4. 填充商品数据 (可选，用于演示):

    • 进入 'cosmosdb-mcp/populate' 目录。
    • 运行命令 'dotnet run'，将 'catalog.json' 中的商品数据填充到 Azure Cosmos DB 的 'products' 容器中。（此步骤需要配置正确的 Azure OpenAI 服务信息，因为会调用 OpenAI 服务生成商品描述的 embedding 向量）。

  5. 构建 MCP 服务器:

    • 进入 'cosmosdb-mcp/mcp-server' 目录。
    • 运行命令 'npm install' 安装依赖。
    • 运行命令 'npm run build' 或 'npm run dev' 构建和启动 MCP 服务器。

服务器配置 (MCP 客户端配置)

以下 JSON 配置信息用于 MCP 客户端连接和使用该 Cosmos DB MCP 服务器。客户端需要配置 'command' 和 'args' 来启动服务器进程 (本例中服务器已经启动，客户端只需配置连接信息)。

{
  "serverName": "cosmosdb-mcp-server",
  "command": "npx",
  "args": ["ts-node", "src/server.ts"],
  "transport": {
    "type": "sse",
    "url": "http://localhost:3001/sse"
  },
  "capabilities": {
    "tools": [
      {
        "name": "searchProducts",
        "description": "Given a user query, search for matching products in the Azure Cosmos DB database",
        "parameters": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "The query to search for products"
            }
          },
          "required": ["query"]
        }
      },
      {
        "name": "getOrders",
        "description": "Get all orders in the Azure Cosmos DB database for the selected email",
        "parameters": {
          "type": "object",
          "properties": {
            "email": {
              "type": "string",
              "description": "The email address to get orders for"
            }
          },
          "required": ["email"]
        }
      }
    ]
  }
}

配置参数说明:

  • 'serverName': MCP 服务器的名称，客户端用于标识连接的服务器。
  • 'command': 启动 MCP 服务器的命令，这里使用 'npx' 来执行 'ts-node'。
  • 'args': 启动命令的参数，'ts-node src/server.ts' 指定运行 'src/server.ts' 文件。
  • 'transport.type': 传输协议类型，这里配置为 'sse' (Server-Sent Events)。
  • 'transport.url': SSE 协议的连接 URL，指向 MCP 服务器的 '/sse' 端点。客户端通过此 URL 建立 SSE 连接。
  • 'capabilities.tools': 声明服务器提供的工具列表。客户端可以根据这些工具信息，调用服务器提供的功能。
    • 'tools[].name': 工具名称，例如 'searchProducts' 或 'getOrders'。
    • 'tools[].description': 工具描述，用于帮助 LLM 理解工具的功能。
    • 'tools[].parameters': 工具参数定义，描述了调用工具时需要提供的参数及其类型和描述。

注意: 实际 MCP 客户端可能需要根据自身实现方式来配置连接信息和能力声明，以上配置为通用参考。

基本使用方法

  1. 启动 MCP 服务器: 在 'cosmosdb-mcp/mcp-server' 目录下运行 'npm run dev' 或 'npm start' 启动服务器。
  2. 配置 MCP 客户端: 在 MCP 客户端中，根据上述 "服务器配置" 部分的信息，配置连接到 'http://localhost:3001/sse' 的 MCP 服务器。
  3. 客户端调用工具: 客户端可以使用 MCP 协议发送 JSON-RPC 请求，调用服务器注册的 'searchProducts' 或 'getOrders' 工具，并传递相应的参数 (例如，商品搜索关键词或用户邮箱)。
  4. 服务器响应: MCP 服务器接收到客户端请求后，会执行相应的工具函数，访问 Azure Cosmos DB 数据，并将结果通过 SSE 连接返回给客户端。

示例场景:

LLM 客户端可以调用 'searchProducts' 工具，让用户输入商品关键词，然后将关键词作为参数传递给工具。MCP 服务器会查询 Cosmos DB 数据库，搜索相关的商品信息，并将结果返回给 LLM 客户端，最终呈现给用户。同样，可以调用 'getOrders' 工具查询用户的订单信息。

信息

分类

数据库与文件

访问项目