SQL Server Table Assistant - Modal Context Protocol

SQL Server テーブルアシスタント - Modal Context Protocol

このアプリケーションでは、LLM とデータソース間の通信レイヤーとして Modal Context Protocol を利用し、自然言語で特定の SQL Server テーブルを操作できます。

このプロジェクトは、Aman Pachori によるリポジトリ mcp-sql-server-natural-lang をベースに、単一テーブルへのアクセスに重点を置いて変更を加えたものです。

主な機能：

• テーブルと会話：平易な英語で特定の SQL Server テーブルとやり取りできます
• SQL クエリの反復調整：SQL クエリが要件を満たすまで、フィードバックを与えて調整できます
• 見やすい表形式の結果：クエリ結果を整形された表で表示し、読みやすくします
• クエリ履歴の記録：クエリ、反復調整、結果を今後参照できるよう自動的に保存します
• ノーコードでのテーブル操作：自然な会話を通じて、データのクエリ、挿入、更新、削除ができます
• 安全で制限されたアクセス：セキュリティを強化するため、制限付きの認証情報で1つのテーブルのみに接続します
• MCP による精度向上：Modal Context Protocol により、正確なテーブル操作を実現します
• コンテキストを維持した会話：複数のクエリにわたってコンテキストを維持します
• 自然言語による説明：クエリ結果について平易な英語で説明を得られます
• トークンの最適化：スマートキャッシュとコンテキスト管理により、API の使用量を最小限に抑えます

MCP とは？

MCP（Modal Context Protocol）は、コンテキストを LLM に結び付ける方法を標準化する仕組みであり、AI モデルをさまざまなデータソースやツールに接続する標準的な方法を提供します。

単一テーブルモード

このアプリケーションは「単一テーブルモード」で動作し、次のような利点があります。

1. セキュリティの強化：データベース全体ではなく、1つのテーブルのみにアクセスを制限します
2. シンプルな権限設定：ユーザーに必要な権限は最小限です（対象のテーブルに対する権限のみ）
3. 特化した操作体験：アシスタントは1つのテーブルの操作に特化しています
4. リスクの軽減：他のテーブルにある機密データへの誤ったアクセスを防ぎます

トークンの最適化

このアプリケーションでは、トークンの使用量を最小限に抑え、レート制限を回避するために、いくつかの戦略を実装しています。

1. スマートなスキーマ要約：テーブルスキーマ全体をモデルに送る代わりに、簡潔な要約を作成します
2. レスポンスのキャッシュ：類似するクエリや説明をキャッシュし、重複した API 呼び出しを避けます
3. 簡潔なプロンプト設計：システムプロンプトとユーザー指示を簡潔になるよう最適化します
4. 会話の管理：コンテキストには最近の関連メッセージのみを含めます
5. タスク別のシステムプロンプト：スキーマ、クエリ生成、説明など、タスクごとに異なるプロンプトを使用します
6. 結果の選択的な送信：大きな結果セットはモデルに送信する前に縮小します
7. トークンパラメーターの調整：max_tokens などのリクエストパラメーターを控えめに設定します

これらの最適化により、大きなテーブルや複雑なクエリを扱う場合でも、API のレート制限内でアプリケーションをスムーズに動作させられます。

前提条件

始める前に、次のものが揃っていることを確認してください。

• Python 3.12+ がマシンにインストールされていること
• API にアクセスできる有効な Azure OpenAI デプロイ
• 操作対象のテーブルがある SQL Server
• 対象のテーブルのみにアクセスできる 制限付きユーザー認証情報

はじめに

次の手順に従って、プロジェクトを実行できる状態にします。

1. リポジトリをクローンする

git clone https://github.com/yourusername/sql-server-table-assistant.git
cd sql-server-table-assistant

2. 依存関係をインストールする

pip install -r requirements.txt

3. 環境変数を設定する

プロジェクトのルートに .env ファイルを作成し、次の内容を追加します。

# Azure OpenAI Configuration (required)
AZURE_OPENAI_API_KEY=your_azure_openai_api_key
AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com
AZURE_OPENAI_API_VERSION=2023-05-15
AZURE_OPENAI_DEPLOYMENT_ID=your-deployment-name

# SQL Server Configuration
MSSQL_SERVER=localhost
MSSQL_DATABASE=your_database_name
MSSQL_USERNAME=your_username
MSSQL_PASSWORD=your_password
MSSQL_DRIVER={ODBC Driver 18 for SQL Server}

# Table Configuration
MSSQL_TABLE_SCHEMA=dbo
MSSQL_TABLE_NAME=your_table_name

テーブルアシスタントを実行する

環境と依存関係の設定が完了したら、テーブルアシスタントを操作する準備ができています。

クライアントスクリプトを実行する

次のコマンドを実行して、アシスタントを起動します。

python mcp-ssms-client.py

スクリプトが起動すると、テーブル名と利用可能なコマンドが表示されます。その後、リクエストを平易な英語で入力できます。例：

Table Assistant is ready. You are working with table: dbo.Employees
Type your questions about the table in natural language, and I'll translate them to SQL.
Special commands: 
  /diagnose - Run diagnostics
  /refresh_schema - Refresh table schema
  /history - View query history

Enter your Query: Show me all employees with a salary over $50,000

対話型クエリのワークフロー

アシスタントは、次の対話型ワークフローに従います。

1. 自然言語で質問します
2. アシスタントが SQL クエリを生成します
3. 次の操作を選択できます。
   • クエリを実行する（e）
   • フィードバックを提供して調整する（f）
   • キャンセルする（c）
4. フィードバックを提供すると、アシスタントが改善されたクエリを生成します
5. 実行すると、結果が整形されたテーブルに表示されます
6. アシスタントが結果を平易な英語で説明します
7. クエリ、反復処理、結果の完全なログが自動的に保存されます

会話の例

Enter your Query: Show me the highest paid employee in each department

===== GENERATED SQL QUERY =====
SELECT 
    Department,
    EmployeeName,
    Salary
FROM (
    SELECT 
        Department,
        EmployeeName,
        Salary,
        ROW_NUMBER() OVER (PARTITION BY Department ORDER BY Salary DESC) as RankBySalary
    FROM dbo.Employees
) RankedEmployees
WHERE RankBySalary = 1
ORDER BY Department
===============================

Do you want to (e)xecute this query, provide (f)eedback to refine it, or (c)ancel? (e/f/c): f
Enter your feedback for improving the SQL query: Include the employee's hire date as well

SQL query generated (iteration 2).

===== GENERATED SQL QUERY =====
SELECT 
    Department,
    EmployeeName,
    Salary,
    HireDate
FROM (
    SELECT 
        Department,
        EmployeeName,
        Salary,
        HireDate,
        ROW_NUMBER() OVER (PARTITION BY Department ORDER BY Salary DESC) as RankBySalary
    FROM dbo.Employees
) RankedEmployees
WHERE RankBySalary = 1
ORDER BY Department
===============================

Do you want to (e)xecute this query, provide (f)eedback to refine it, or (c)ancel? (e/f/c): e

===== QUERY RESULTS =====
Query executed successfully. 5 rows returned.

+------------+---------------+----------+------------+
| Department | EmployeeName  |   Salary | HireDate   |
+============+===============+==========+============+
| Finance    | Jane Smith    | 95000.00 | 2018-03-15 |
| HR         | Tim Johnson   | 75000.00 | 2020-01-10 |
| IT         | Mary Williams | 98000.00 | 2017-05-22 |
| Marketing  | Bob Miller    | 82000.00 | 2019-07-08 |
| Sales      | John Davis    | 92000.00 | 2016-11-14 |
+------------+---------------+----------+------------+
==========================

Query log saved successfully to logs/queries/query_20230901_152412.json

===== RESULT EXPLANATION =====
The results show the highest paid employee in each department along with their hire date. There are 5 departments in total:

- In Finance, Jane Smith has the highest salary at $95,000 and was hired on March 15, 2018.
- In HR, Tim Johnson earns the most at $75,000 and joined on January 10, 2020.
- In IT, Mary Williams is the top earner with $98,000 and has been with the company since May 22, 2017.
- In Marketing, Bob Miller makes $82,000 and started on July 8, 2019.
- In Sales, John Davis has the highest salary at $92,000 and was hired on November 14, 2016.

Mary Williams from IT has the highest overall salary among all the top-earning employees across departments.
==============================

診断と特別なコマンド

アプリケーションには、次の特別なコマンドが含まれています。

• /diagnose - テーブルへのアクセスを包括的に診断します
• /refresh_schema - テーブルスキーマを更新します
• /history - 現在のセッションで実行したすべてのクエリの一覧を表示します

クエリ履歴

クエリ履歴機能を使うと、セッション中に実行したすべてのクエリを確認できます。

===== QUERY HISTORY =====
1. [2023-09-01 15:24:12] Show me all employees with a salary over $50,000
   SQL: SELECT EmployeeName, Department, Salary FROM dbo.Employees WHERE Salary > 50000 ORDER...
   Iterations: 1, Success: True

2. [2023-09-01 15:32:45] Show me the highest paid employee in each department
   SQL: SELECT Department, EmployeeName, Salary, HireDate FROM (SELECT Department, EmployeeName...
   Iterations: 2, Success: True
=======================

クエリのログ記録

すべてのクエリと結果は、今後参照できるように JSON ファイルとして logs/queries/ に自動的に保存されます。各ログには次の内容が含まれます。

• 元の自然言語クエリ
• すべての SQL の反復処理とフィードバック
• 実行された最終的な SQL クエリ
• クエリの結果
• タイムスタンプ

これにより、クエリが時間とともにどのように変化するかを追跡し、すべてのデータベース操作の記録を維持できます。

セキュリティに関する考慮事項

このアプリケーションには、次のセキュリティ機能が実装されています。

1. 単一テーブルへのアクセス：クエリは設定されたテーブルに制限されます
2. クエリの検証：すべての SQL クエリは、実行前にユーザーの承認を得るために表示されます
3. トランザクションの安全性：INSERT／UPDATE／DELETE のテストでは、ロールバックを伴うトランザクションを使用します
4. エラーの追跡：詳細なエラーログにより、機密情報を漏らさずに問題を診断できます
5. SQL インジェクションの防止：構造化されたクエリ生成により、SQL インジェクションのリスクを軽減します

接続の問題

接続の問題が発生した場合は、次の点を確認してください。

1. サーバー名または IP アドレスが正しいことを確認します
2. SQL Server が稼働しており、リモート接続を受け入れることを確認します
3. SQL Server の通信が許可されるように、ファイアウォールの設定を確認します
4. .env ファイルで指定されている ODBC ドライバーがインストールされていることを確認します
5. SSMS や sqlcmd などの他のツールを使って接続をテストします

トークン使用量のトラブルシューティング

Azure OpenAI でレート制限エラーが発生した場合は、次の方法を試してください。

1. 再試行する前に待機する：レート制限は通常、時間の経過で解除されるため、60 秒待つと問題が解決する場合があります
2. クォータを増やす：より高いレート制限を申請するには、https://aka.ms/oai/quotaincrease にアクセスします
3. プランをアップグレードする：無料アカウントでは、従量課金制へのアップグレードが必要になる場合があります
4. /refresh_schema コマンドを使用する：トークン使用量を減らせる可能性があるスキーマの要約を再生成します
5. プロンプトの長さを確認する：非常に複雑な質問では、トークン使用量が増える場合があります

ライセンス

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

謝辞

• Aman Pachori によるオリジナルの MCP SQL Server Natural Language 実装：Aman Pachori
• Modal Context Protocol (MCP) を使用して構築