Mcpql

🚀 MCPQL - SQL Server MCP

MCPQLは、SQL Serverデータベース操作のための包括的なModel Context Protocol (MCP) サーバーです。このサーバーは、MCPプロトコルを通じて、データベース分析、オブジェクト探索、およびデータ操作のための10の強力なツールを提供します。

🚀 クイックスタート

前提条件

• Node.js 18+ と npm
• 適切な接続資格情報を持つSQL Serverデータベース
• MCP互換クライアント（Claude Desktop、Cursor IDE、または任意のMCPクライアントなど）

インストールと設定

オプション1: GitHubからnpxを使用する（推奨）

インストールは必要ありません！MCPクライアントを設定するだけです。

Claude Desktop (claude_desktop_config.json) の場合:

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "sql",
        "DB_SERVER": "your_server",
        "DB_NAME": "your_database",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "false",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

Cursor IDEの場合:

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "sql",
        "DB_SERVER": "your_server",
        "DB_NAME": "your_database",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "false",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

オプション2: ローカル開発用のインストール

1. クローンとセットアップ:

git clone https://github.com/hendrickcastro/MCPQL.git
cd MCPQL
npm install
npm run build

2. データベース接続の設定: データベースの資格情報を含む .env ファイルを作成します。

# 基本的なSQL Server接続
DB_AUTHENTICATION_TYPE=sql
DB_SERVER=localhost
DB_NAME=MyDatabase
DB_USER=sa
DB_PASSWORD=YourPassword123!
DB_PORT=1433
DB_ENCRYPT=false
DB_TRUST_SERVER_CERTIFICATE=true

3. ローカルパスでMCPクライアントを設定する:

{
  "mcpServers": {
    "mcpql": {
      "command": "node",
      "args": ["path/to/MCPQL/dist/server.js"]
    }
  }
}

✨ 主な機能

MCPQLは、SQL Serverデータベース操作のための10の包括的なツールを提供します。

1. 🏗️ テーブル分析 - mcp_table_analysis

列、キー、インデックス、および制約を含む完全なテーブル構造分析。

2. 📋 ストアドプロシージャ分析 - mcp_sp_structure

パラメーター、依存関係、およびソースコードを含むストアドプロシージャ構造の分析。

3. 👀 データプレビュー - mcp_preview_data

オプションのフィルタリングと行制限を伴うテーブルデータのプレビュー。

4. 📊 列統計情報 - mcp_get_column_stats

特定の列の包括的な統計情報を取得。

5. ⚙️ ストアドプロシージャの実行 - mcp_execute_procedure

パラメーターを指定してストアドプロシージャを実行し、結果を返す。

6. 🔍 SQLクエリの実行 - mcp_execute_query

完全なエラーハンドリングを伴うカスタムSQLクエリの実行。

7. ⚡ クイックデータ分析 - mcp_quick_data_analysis

行カウント、列分布、およびトップ値を含むクイック統計分析。

8. 🔎 包括的検索 - mcp_search_comprehensive

名前と定義によるデータベースオブジェクトの検索で、条件を設定可能。

9. 🔗 オブジェクト依存関係 - mcp_get_dependencies

データベースオブジェクト（テーブル、ビュー、ストアドプロシージャなど）の依存関係を取得。

10. 🎯 サンプル値 - mcp_get_sample_values

テーブル内の特定の列からサンプル値を取得。

💻 使用例

テーブルの分析

// 完全なテーブル構造を取得
const analysis = await mcp_table_analysis({ 
  table_name: "dbo.Users" 
});

// クイックデータ概要を取得
const overview = await mcp_quick_data_analysis({ 
  table_name: "dbo.Users",
  sample_size: 500
});

// フィルターを使用してテーブルデータをプレビュー
const data = await mcp_preview_data({
  table_name: "dbo.Users",
  filters: { "Status": "Active", "Department": "IT" },
  limit: 25
});

データベースオブジェクトの検索

// "User" を含むすべてのオブジェクトを検索
const objects = await mcp_search_comprehensive({ 
  pattern: "User",
  search_in_names: true,
  search_in_definitions: false
});

// 特定のテーブルをクエリするプロシージャを検索
const procedures = await mcp_search_comprehensive({ 
  pattern: "FROM Users",
  object_types: ["PROCEDURE"],
  search_in_definitions: true
});

ストアドプロシージャの分析

// 完全なストアドプロシージャ分析を取得
const spAnalysis = await mcp_sp_structure({ 
  sp_name: "dbo.usp_GetUserData" 
});

// ストアドプロシージャを実行
const result = await mcp_execute_procedure({
  sp_name: "dbo.usp_GetUserById",
  params: { "UserId": 123, "IncludeDetails": true }
});

データ分析

// 列統計情報を取得
const stats = await mcp_get_column_stats({
  table_name: "dbo.Users",
  column_name: "Age"
});

// 列からサンプル値を取得
const samples = await mcp_get_sample_values({
  table_name: "dbo.Users",
  column_name: "Department",
  limit: 15
});

🔧 技術詳細

環境変数と接続タイプ

MCPQLは、包括的な構成オプションを持つ複数のSQL Server接続タイプをサポートしています。

🔐 認証タイプ

DB_AUTHENTICATION_TYPE を以下のいずれかに設定します。

• sql - SQL Server認証（デフォルト）
• windows - Windows認証
• azure-ad - Azure Active Directory認証

📋 完全な環境変数

接続構成の例

1. 🏠 SQL Serverローカル（SQL認証）

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "sql",
        "DB_SERVER": "localhost",
        "DB_NAME": "MyDatabase",
        "DB_USER": "sa",
        "DB_PASSWORD": "YourPassword123!",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "false",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

2. 🏢 SQL Server Express（名前付きインスタンス）

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "sql",
        "DB_SERVER": "localhost",
        "DB_INSTANCE_NAME": "SQLEXPRESS",
        "DB_NAME": "MyDatabase",
        "DB_USER": "sa",
        "DB_PASSWORD": "YourPassword123!",
        "DB_ENCRYPT": "false",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

3. 🪟 Windows認証

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "windows",
        "DB_SERVER": "MYSERVER",
        "DB_NAME": "MyDatabase",
        "DB_DOMAIN": "MYDOMAIN",
        "DB_USER": "myuser",
        "DB_PASSWORD": "mypassword",
        "DB_ENCRYPT": "false",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

4. ☁️ Azure SQL Database（Azure ADパスワード）

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "azure-ad",
        "DB_SERVER": "myserver.database.windows.net",
        "DB_NAME": "MyDatabase",
        "DB_USER": "user@domain.com",
        "DB_PASSWORD": "userpassword",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "true",
        "DB_TRUST_SERVER_CERTIFICATE": "false"
      }
    }
  }
}

5. 🔐 Azure SQL Database（サービスプリンシパル）

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_AUTHENTICATION_TYPE": "azure-ad",
        "DB_SERVER": "myserver.database.windows.net",
        "DB_NAME": "MyDatabase",
        "DB_AZURE_CLIENT_ID": "your-client-id",
        "DB_AZURE_CLIENT_SECRET": "your-client-secret",
        "DB_AZURE_TENANT_ID": "your-tenant-id",
        "DB_PORT": "1433",
        "DB_ENCRYPT": "true",
        "DB_TRUST_SERVER_CERTIFICATE": "false"
      }
    }
  }
}

6. 🔗 接続文字列を使用する

{
  "mcpServers": {
    "mcpql": {
      "command": "npx",
      "args": ["-y", "hendrickcastro/mcpql"],
      "env": {
        "DB_CONNECTION_STRING": "Server=localhost;Database=MyDatabase;User Id=sa;Password=YourPassword123!;Encrypt=false;TrustServerCertificate=true;"
      }
    }
  }
}

🚨 一般的な問題のトラブルシューティング

接続問題

• "ログインに失敗しました": ユーザー名とパスワードを確認してください。Windows認証の場合は、DB_AUTHENTICATION_TYPE=windows を確認してください。
• "サーバーが見つかりません": サーバー名とポートを確認してください。SQL Expressの場合は、DB_INSTANCE_NAME を追加してください。
• "証明書" エラー: ローカル開発の場合は、DB_TRUST_SERVER_CERTIFICATE=true を設定してください。
• タイムアウトエラー: DB_TIMEOUT を増やすか、ネットワーク接続を確認してください。

SQL Server Expressのセットアップ

1. SQL Server構成マネージャーでTCP/IPプロトコルを有効にします。
2. 静的ポート（通常は1433）を設定するか、ブラウザーサービスを使用して動的ポートを使用します。
3. Windowsファイアウォールを構成して、SQL Serverのトラフィックを許可します。
4. デフォルトのExpressインストールでは、DB_INSTANCE_NAME=SQLEXPRESS を使用します。

Azure SQL Databaseのセットアップ

1. サーバーのファイアウォールルールを作成して、クライアントのIPを許可します。
2. サーバー名には server.database.windows.net の形式を使用します。
3. 常に DB_ENCRYPT=true と DB_TRUST_SERVER_CERTIFICATE=false を設定します。
4. サービスプリンシパル認証の場合は、Azure ADにアプリを登録し、権限を割り当てます。

🧪 テスト

包括的なテストスイートを実行します。

npm test

テストスイートには、すべての10のツールの包括的なテストが含まれており、実際のデータベースでのテストと完全なカバレッジがあります。

🏗️ アーキテクチャ

プロジェクト構造

MCPQL/
├── src/
│   ├── __tests__/          # 包括的なテストスイート
│   ├── tools/              # モジュール化されたツールの実装
│   │   ├── tableAnalysis.ts      # テーブル分析ツール
│   │   ├── storedProcedureAnalysis.ts  # ストアドプロシージャ分析ツール
│   │   ├── dataOperations.ts     # データ操作ツール
│   │   ├── objectSearch.ts       # 検索と発見ツール
│   │   ├── types.ts              # 型定義
│   │   └── index.ts              # ツールのエクスポート
│   ├── db.ts               # データベース接続管理
│   ├── server.ts           # MCPサーバーのセットアップとハンドラー
│   ├── tools.ts            # ツールの定義とスキーマ
│   └── mcp-server.ts       # ツールの再エクスポート
├── dist/                   # コンパイルされたJavaScript出力
└── package.json           # 依存関係とスクリプト

主要な機能

• ⚡ 接続プーリング: 効率的なデータベース接続管理
• 🛡️ 堅牢なエラーハンドリング: 包括的なエラーハンドリングと検証
• 📋 豊富なメタデータ: 詳細な結果と包括的なデータベース情報
• 🔧 柔軟な構成: 環境に基づく構成
• 📊 最適化されたクエリ: すべての操作に対する効率的なSQLクエリ

📝 重要な注意事項

• オブジェクト名: 常にスキーマ付きの名前（例: dbo.Users, api.Idiomas）を使用してください。
• エラーハンドリング: すべてのツールは成功/エラーの指標を含む構造化されたレスポンスを返します。
• 型安全性: 適切な型定義を持つ完全なTypeScriptサポート。
• 接続管理: 自動接続プーリングとリトライロジック。
• セキュリティ: SQLインジェクションを防止するためのパラメータ化クエリ。

🤝 コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します (git checkout -b feature/amazing-feature)。
3. 変更を加え、テストを追加します。
4. すべてのテストが通過することを確認します (npm test)。
5. 変更をコミットします (git commit -m 'Add amazing feature')。
6. ブランチにプッシュします (git push origin feature/amazing-feature)。
7. プルリクエストを開きます。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

🙏 謝辞

• Model Context Protocol SDK を使用して構築されています。
• SQL Server接続に mssql を使用しています。
• Jest を使用した包括的なテスト。

🏷️ タグとキーワード

データベース

sql-server azure-sql database-analysis database-tools mssql t-sql database-management database-administration 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 sql-client database-sdk rest-api json-api database-connector

機能

table-analysis stored-procedures data-preview column-statistics query-execution database-search object-dependencies schema-analysis data-exploration database-insights

デプロイメント

docker azure-deployment cloud-ready enterprise-ready production-ready scalable secure authenticated encrypted configurable

ユースケース

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

🎯 MCPQLは、Model Context Protocolを通じて包括的なSQL Serverデータベース分析と操作機能を提供します。データベース管理者、開発者、およびSQL Serverデータベースを扱うすべての人に最適です！ 🚀