Mcpcosmosdb

🚀 MCP CosmosDB - Azure CosmosDB MCP Server

MCP CosmosDBは、Azure CosmosDBのデータベース操作を行うための包括的な**Model Context Protocol (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は、Model Context Protocolを通じて包括的なAzure CosmosDBデータベース分析を提供します。CosmosDBを使用する開発者やデータアナリストに最適です！ 🚀