MCPCosmosDB

数据库 TypeScript

🚀 MCP CosmosDB - Azure CosmosDB MCP 服务器

MCP CosmosDB 是一个用于 Azure CosmosDB 数据库操作的综合 模型上下文协议 (MCP) 服务器。该服务器通过 MCP 协议提供了 8 种强大的工具，可用于文档数据库分析、容器发现和数据查询。

🚀 快速开始

前提条件

Node.js 18 及以上版本和 npm
具备连接字符串的 Azure CosmosDB 数据库
兼容 MCP 的客户端（Claude Desktop、Cursor IDE 等）

⚙️ 配置

必需的环境变量

变量	描述	示例
`OCONNSTRING`	从 Azure 门户获取的 CosmosDB 连接字符串	`AccountEndpoint=https://...;AccountKey=...;`
`COSMOS_DATABASE_ID`	要连接的数据库 ID	`MyDatabase`

安装选项

选项 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 
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
});

可选配置

变量	描述	默认值
`COSMOS_ENABLE_ENDPOINT_DISCOVERY`	启用自动端点发现	`true`
`COSMOS_MAX_RETRY_ATTEMPTS`	请求的最大重试次数	`9`
`COSMOS_MAX_RETRY_WAIT_TIME`	最大重试等待时间（毫秒）	`30000`
`COSMOS_ENABLE_CROSS_PARTITION_QUERY`	启用跨分区查询	`true`

配置示例

生产环境：

{
"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 模拟器

安装 Azure CosmosDB 模拟器
在端口 8081 上启动模拟器
使用默认的模拟器连接字符串
创建用于测试的数据库和容器

🧪 开发

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 消耗

安全性：安全存储连接字符串

🤝 贡献

分叉仓库
创建功能分支 (git checkout -b feature/name)
进行更改并添加测试
确保测试通过 (npm test)
提交更改 (git commit -m 'Add feature')
推送并打开拉取请求

📄 许可证

本项目采用 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

🙏 致谢

🎯 MCP CosmosDB 通过模型上下文协议提供全面的 Azure CosmosDB 数据库分析。非常适合使用 CosmosDB 的开发人员和数据分析师！ 🚀

0 条评论
分类：数据库