Mcpcosmosdb

🚀 MCP CosmosDB - Azure CosmosDB MCP 服務器

MCP CosmosDB 是一款用於 Azure CosmosDB 數據庫操作的全面 模型上下文協議 (MCP) 服務器。該服務器通過 MCP 協議提供了 8 種強大的工具，可用於文檔數據庫分析、容器發現和數據查詢。

🚀 快速開始

前提條件

• Node.js 18 及以上版本和 npm
• 帶有連接字符串的 Azure CosmosDB 數據庫
• 兼容 MCP 的客戶端（Claude Desktop、Cursor IDE 等）

⚙️ 配置

必需的環境變量

安裝選項

選項 1：NPX（推薦）

無需安裝！配置您的 MCP 客戶端：

{
  "mcpServers": {
    "mcp-cosmosdb": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/MCPCosmosDB"],
      "env": {
        "OCONNSTRING": "AccountEndpoint=https://your-cosmos-account.documents.azure.com:443/;AccountKey=your-account-key-here;",
        "COSMOS_DATABASE_ID": "your-database-name"
      }
    }
  }
}

選項 2：本地開發

git clone <your-repo-url>
cd MCPCosmosDB
npm install && npm run build

然後使用本地路徑進行配置：

{
  "mcpServers": {
    "mcp-cosmosdb": {
      "command": "node",
      "args": ["path/to/MCPCosmosDB/dist/server.js"],
      "env": {
        "OCONNSTRING": "your-connection-string",
        "COSMOS_DATABASE_ID": "your-database-name"
      }
    }
  }
}

🛠️ 可用工具

MCP CosmosDB 為 Azure CosmosDB 操作提供了 8 種全面的工具：

1. 🗄️ 列出數據庫 - mcp_list_databases

列出 CosmosDB 賬戶中的所有數據庫。

2. 📦 列出容器 - mcp_list_containers

列出當前數據庫中的所有容器。

3. 📋 容器信息 - mcp_container_info

獲取特定容器的詳細信息，包括分區鍵、索引策略和吞吐量設置。

4. 📊 容器統計信息 - mcp_container_stats

獲取容器的統計信息，包括文檔計數、大小估計和分區鍵分佈。

5. 🔍 執行 SQL 查詢 - mcp_execute_query

使用參數和性能指標對 CosmosDB 容器執行 SQL 查詢。

6. 📄 獲取文檔 - mcp_get_documents

從容器中檢索文檔，可選擇進行過濾和指定分區鍵。

7. 🎯 按 ID 獲取文檔 - mcp_get_document_by_id

通過文檔 ID 和分區鍵檢索特定文檔。

8. 🏗️ 模式分析 - mcp_analyze_schema

分析容器中的文檔模式結構，以瞭解數據模式。

💻 使用示例

容器分析

// 列出所有容器
const containers = await mcp_list_containers();

// 獲取容器信息
const containerInfo = await mcp_container_info({ 
  container_id: "users" 
});

// 獲取容器統計信息
const stats = await mcp_container_stats({ 
  container_id: "users",
  sample_size: 1000
});

查詢數據

// 執行 SQL 查詢
const result = await mcp_execute_query({
  container_id: "products",
  query: "SELECT * FROM c WHERE c.category = @category AND c.price > @minPrice",
  parameters: { "category": "electronics", "minPrice": 100 },
  max_items: 50
});

// 獲取過濾後的文檔
const documents = await mcp_get_documents({
  container_id: "orders",
  filter_conditions: { "status": "completed", "year": 2024 },
  limit: 100
});

文檔操作

// 獲取特定文檔
const document = await mcp_get_document_by_id({
  container_id: "users",
  document_id: "user-123",
  partition_key: "user-123"
});

// 分析模式
const schema = await mcp_analyze_schema({
  container_id: "products",
  sample_size: 500
});

可選配置

配置示例

生產環境：

{
  "env": {
    "OCONNSTRING": "AccountEndpoint=https://mycompany-prod.documents.azure.com:443/;AccountKey=your-production-key;",
    "COSMOS_DATABASE_ID": "ProductionDB"
  }
}

CosmosDB 模擬器（本地）：

{
  "env": {
    "OCONNSTRING": "AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;",
    "COSMOS_DATABASE_ID": "TestDB"
  }
}

高級配置：

{
  "env": {
    "OCONNSTRING": "AccountEndpoint=https://mycompany.documents.azure.com:443/;AccountKey=your-key;",
    "COSMOS_DATABASE_ID": "MyDatabase",
    "COSMOS_MAX_RETRY_ATTEMPTS": "15",
    "COSMOS_MAX_RETRY_WAIT_TIME": "60000"
  }
}

🚨 故障排除

連接問題

• 連接字符串無效：驗證 OCONNSTRING 格式是否包含 AccountEndpoint 和 AccountKey
• 未找到數據庫：檢查 COSMOS_DATABASE_ID 是否與現有數據庫匹配
• 請求超時：增加 COSMOS_MAX_RETRY_WAIT_TIME 或檢查網絡

查詢問題

• 需要跨分區查詢：在查詢參數中設置 enable_cross_partition: true
• 查詢超時：減小樣本大小或添加特定過濾器
• 需要分區鍵：為單分區操作指定 partition_key

CosmosDB 模擬器

1. 安裝 Azure CosmosDB 模擬器
2. 在端口 8081 上啟動模擬器
3. 使用默認的模擬器連接字符串
4. 創建用於測試的數據庫和容器

🧪 開發

npm test          # 運行測試
npm run build     # 構建項目
npm start         # 開發模式

🏗️ 架構

項目結構

src/
├── tools/                    # 工具實現
│   ├── containerAnalysis.ts  # 容器操作
│   ├── dataOperations.ts     # 數據查詢
│   └── types.ts              # 類型定義
├── db.ts                     # CosmosDB 連接
├── server.ts                 # MCP 服務器設置
└── tools.ts                  # 工具定義

關鍵特性

• ⚡ 帶有重試邏輯的連接管理
• 🛡️ 全面的錯誤處理
• 📊 性能指標和請求費用
• 🔧 基於環境的配置
• 📋 智能模式分析

📝 重要提示

⚠️ 重要提示

• 容器 ID：使用與 CosmosDB 中完全一致的名稱
• 分區鍵：為獲得最佳性能，請務必指定
• 跨分區查詢：可能會產生較高費用，請使用過濾器
• 請求費用：監控 RU 消耗
• 安全性：安全存儲連接字符串

🤝 貢獻

1. 分叉倉庫
2. 創建功能分支 (git checkout -b feature/name)
3. 進行更改並添加測試
4. 確保測試通過 (npm test)
5. 提交更改 (git commit -m 'Add feature')
6. 推送並打開拉取請求

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。

🏷️ 標籤與關鍵字

數據庫相關

cosmosdb azure-cosmosdb nosql document-database database-analysis database-tools azure database-management database-operations data-analysis

MCP 與 AI 相關

model-context-protocol mcp-server mcp-tools ai-tools claude-desktop cursor-ide anthropic llm-integration ai-database intelligent-database

技術相關

typescript nodejs npm-package cli-tool database-client nosql-client database-sdk rest-api json-api database-connector

特性相關

container-analysis document-operations sql-queries schema-analysis query-execution database-search data-exploration database-insights partition-management throughput-analysis

使用場景相關

database-development data-science business-intelligence database-migration schema-documentation performance-analysis data-governance database-monitoring troubleshooting automation

🙏 致謝

• Model Context Protocol SDK
• @azure/cosmos
• 靈感來源於 MCPQL

🎯 MCP CosmosDB 通過模型上下文協議提供全面的 Azure CosmosDB 數據庫分析。非常適合使用 CosmosDB 的開發人員和數據分析師！ 🚀