关键词

Cosmos DBAzure云数据库管理数据查询Go语言

项目简介

本项目是一个基于 Model Context Protocol (MCP) 的服务器实现，专门为 Azure Cosmos DB 构建。它允许LLM客户端通过标准化的MCP协议与Azure Cosmos DB数据库进行交互，实现数据资源的访问和管理。该服务器使用 Go 语言和 Azure Cosmos DB Go SDK 开发，并基于 mcp-go 库作为MCP协议的Go语言实现基础。

主要功能点

  • 数据库管理:
    • 列出 Cosmos DB 账号下的所有数据库。
    • 列出指定数据库下的所有容器。
    • 读取指定容器的元数据信息（配置）。
    • 创建新的容器。
  • 数据操作:
    • 向指定容器添加新的数据项。
    • 读取指定容器中的特定数据项。
    • 执行SQL查询以检索容器中的数据。

所有功能均通过 MCP 协议以 Tool (工具) 的形式暴露给 LLM 客户端，客户端可以调用这些工具来完成与 Cosmos DB 的交互。

安装步骤

  1. 克隆仓库:

    git clone https://github.com/abhirockzz/mcp_cosmosdb_go
cd mcp_cosmosdb_go

  2. 编译服务器程序:

    go build -o mcp_azure_cosmosdb main.go

    这将在当前目录下生成可执行文件 'mcp_azure_cosmosdb'。

服务器配置

MCP服务器需要通过配置文件 '.vscode/mcp.json' 告知 MCP 客户端如何启动和连接。以下是一个示例配置，你需要根据实际情况进行调整。

在项目根目录下创建 '.vscode' 文件夹，并在其中创建 'mcp.json' 文件，文件内容如下：

{
  "servers": {
    "CosmosDB Golang MCP": {  // 服务器名称，可以自定义
      "type": "stdio",       // 连接类型，本项目使用标准输入输出 (stdio)
      "command": "$(pwd)/mcp_azure_cosmosdb", // MCP 服务器可执行文件的绝对路径。$(pwd) 代表当前项目根目录。请确保 mcp_azure_cosmosdb 可执行文件在此路径下。
      "env": {               // 环境变量配置 (可选)
        // "COSMOSDB_ACCOUNT_KEY": "your_cosmosdb_account_key"  // 如果使用密钥认证，请取消注释并替换为你的 Cosmos DB 账号密钥
      }
    }
  }
}

配置说明:

  • 'servers': 定义可用的 MCP 服务器列表。
  • 'CosmosDB Golang MCP': 服务器的名称，将在 MCP 客户端中显示。可以自定义。
  • 'type: "stdio"': 指定 MCP 服务器使用标准输入输出 (stdio) 进行通信。这是本项目实现的连接方式。
  • 'command': 重要。指定启动 MCP 服务器的命令。
    • '$(pwd)/mcp_azure_cosmosdb' 表示服务器可执行文件 'mcp_azure_cosmosdb' 位于当前项目根目录下。你需要根据 'mcp_azure_cosmosdb' 实际的存放路径进行调整。
    • 注意: 某些 MCP 客户端可能不支持 '$(pwd)' 这种路径展开，如果遇到问题，请将 'command' 配置为 'mcp_azure_cosmosdb' 的绝对路径。例如： '"command": "/path/to/your/project/mcp_azure_cosmosdb"'
  • 'env': 可选。配置 MCP 服务器运行时的环境变量。
    • 'COSMOSDB_ACCOUNT_KEY': 认证方式。
      • 方式一：Azure CLI 认证 (推荐) - 如果你的 Azure 账号已经通过 Azure CLI ('az login') 登录，则无需配置 'COSMOSDB_ACCOUNT_KEY'。服务器将自动使用默认的 Azure 凭据进行认证。
      • 方式二：密钥认证 - 如果你想使用 Cosmos DB 账号密钥进行认证，请取消注释 'COSMOSDB_ACCOUNT_KEY' 行，并将 'your_cosmosdb_account_key' 替换为你的 Cosmos DB 账号密钥。安全性提示: 建议使用 Azure CLI 认证或托管身份等更安全的方式，避免将密钥硬编码在配置文件中。

关于 Azure Cosmos DB 权限:

确保你使用的 Azure 账号或密钥拥有足够的权限来操作 Cosmos DB 资源（数据库、容器、数据项）。你需要为该账号配置 Cosmos DB 的控制平面和数据平面的 RBAC 权限，以便执行 CRUD 操作。

基本使用方法

  1. 启动 MCP 客户端: 你需要使用支持 MCP 协议的客户端工具，例如：

    • VS Code Insiders (Agent Mode): Visual Studio Code 的预览版本，集成了 MCP 客户端功能。
    • MCP Inspector: 一个通用的 MCP 客户端工具，用于测试和调试 MCP 服务器。可以使用命令 'npx @modelcontextprotocol/inspector ./mcp_azure_cosmosdb' 启动 (需要安装 Node.js 和 npm)。
    • Claude Desktop 等其他 MCP 客户端。

  2. 配置 MCP 客户端连接: 在 MCP 客户端中，配置连接到 "CosmosDB Golang MCP" 服务器。客户端会读取 '.vscode/mcp.json' 配置文件，并根据配置信息启动和连接到你的 MCP 服务器。

  3. 使用 Tool (工具): 连接成功后，MCP 客户端会显示 "CosmosDB Golang MCP" 服务器提供的工具列表 (例如： 'list_databases', 'list_containers', 'execute_query' 等)。你可以根据需要选择并调用相应的工具，并提供工具所需的参数 (例如 Cosmos DB 账号名、数据库名、容器名、查询语句等)。

  4. 查看结果: 工具执行完成后，MCP 客户端会显示工具返回的结果。对于数据查询类工具，结果通常以 JSON 格式返回。

示例使用场景:

  • 在 LLM 应用中，使用 'list_databases' 工具获取 Cosmos DB 账号下的数据库列表，让 LLM 了解可用的数据库资源。
  • 使用 'execute_query' 工具执行 SQL 查询，从 Cosmos DB 中检索所需的数据，并将数据作为上下文信息提供给 LLM。
  • 使用 'add_item_to_container' 工具向 Cosmos DB 中写入数据，实现 LLM 应用的数据持久化。

请参考仓库 README 文件和示例视频，了解更详细的使用方法和演示。

信息

分类

数据库与文件

访问项目