Servidor de Consultas MySQL

MySQL クエリサーバー

これは、SSE（Server-Sent Events）を通じて MySQL データベース操作機能を提供する、MCP（Model-Controller-Provider）フレームワークベースの MySQL クエリサーバーです。

機能

• FastMCP フレームワークで構築
• SSE（Server-Sent Events）によるリアルタイムデータストリーミングに対応
• MySQL データベースのクエリインターフェース
• 包括的なログ記録システム
• トランザクションの自動管理（commit/rollback）
• 環境変数による設定に対応
• SQL セキュリティメカニズム
  • リスクレベルの制御
  • SQL インジェクション対策
  • 危険な操作のインターセプト
  • WHERE 句の必須チェック
  • 影響を受けた行数の自動返却
• 機密情報保護メカニズム
• メタデータクエリ結果の自動フォーマットと拡張

API 機能

システムでは、主に次の 4 種類のツールを提供します。

基本クエリツール

• mysql_query：パラメーター化クエリに対応した、任意の SQL クエリを実行します

メタデータクエリツール

• mysql_show_tables：パターンマッチングと結果数の制限に対応した、データベースのテーブル一覧を取得します
• mysql_show_columns：テーブルのカラム情報を取得します
• mysql_describe_table：テーブルの構造を説明します
• mysql_show_create_table：テーブルの作成ステートメントを取得します

データベース情報クエリツール

• mysql_show_databases：システムデータベースのフィルタリングに対応した、すべてのデータベースの一覧を取得します
• mysql_show_variables：MySQL サーバーの変数を取得します
• mysql_show_status：MySQL サーバーのステータス情報を取得します

高度なテーブル構造クエリツール

• mysql_show_indexes：テーブルのインデックス情報を取得します
• mysql_show_table_status：テーブルのステータス情報を取得します
• mysql_show_foreign_keys：テーブルの外部キー情報を取得します
• mysql_paginate_results：結果のページネーション機能を提供します

システム要件

• Python 3.6+
• MySQL サーバー
• 依存関係：
  • mysql-connector-python
  • python-dotenv
  • mcp（FastMCP フレームワーク）

インストール手順

1. プロジェクトをローカルにクローンします：

git clone [URL do projeto]
cd mysql-query-server

2. 依存関係をインストールします：

pip install -r requirements.txt

3. 環境変数を設定します：
   • .env.example ファイルをコピーし、名前を .env に変更します
   • 必要に応じて .env ファイルの設定を変更します

環境変数の設定

.env ファイルで次のパラメーターを設定します：

基本設定

• HOST：サーバーのリッスンアドレス（デフォルト：127.0.0.1）
• PORT：サーバーのリッスンポート（デフォルト：3000）
• MYSQL_HOST：MySQL サーバーのアドレス
• MYSQL_PORT：MySQL サーバーのポート
• MYSQL_USER：MySQL のユーザー名
• MYSQL_PASSWORD：MySQL のパスワード
• MYSQL_DATABASE：MySQL データベース名

SQL セキュリティ設定

• ENV_TYPE：環境の種類（development/production）
• ALLOWED_RISK_LEVELS：許可するリスクレベル（LOW/MEDIUM/HIGH/CRITICAL）
• BLOCKED_PATTERNS：ブロックする SQL パターン（正規表現、カンマ区切り）
• ENABLE_QUERY_CHECK：SQL セキュリティチェックを有効にするかどうか（true/false）
• ALLOW_SENSITIVE_INFO：機密情報のクエリを許可するかどうか（true/false）
• SENSITIVE_INFO_FIELDS：カスタムの機密フィールドパターン一覧（カンマ区切り）

セキュリティメカニズムの詳細

リスクレベルの制御

• LOW：クエリ操作（SELECT）およびメタデータ操作（SHOW、DESCRIBE など）
• MEDIUM：基本的なデータ変更（INSERT、WHERE 句を含む UPDATE/DELETE）
• HIGH：構造変更（CREATE/ALTER）および WHERE 句のない UPDATE
• CRITICAL：危険な操作（DROP/TRUNCATE）および WHERE 句のない DELETE

環境の違い

• 開発環境：
  • より高リスクの操作が可能です
  • 機密情報を非表示にしません
  • 詳細なエラーメッセージを表示します
• 本番環境：
  • デフォルトではリスクレベルが LOW の操作のみ可能です
  • データの変更を厳しく制限します
  • 機密情報を自動的に非表示にします
  • エラーメッセージに実装の詳細は含まれません

機密情報の保護

システムは、次のキーワードを含む変数やステータス値を自動的に検出し、非表示にします。

• password、auth、credential、key、secret、private
• ssl、tls、cipher、certificate
• host、path、directory などのシステムパス情報

トランザクション管理

• 変更操作（INSERT/UPDATE/DELETE）ではトランザクションが自動的にコミットされます
• エラー発生時はトランザクションが自動的にロールバックされます
• 操作によって影響を受けた行数を返します

サーバーの起動

以下のコマンドを実行して、サーバーを起動します。

python src/server.py

サーバーは設定されたアドレスとポートで起動します。デフォルトでは http://127.0.0.1:3000/sse です。

プロジェクト構成

.
├── src/                     # Diretório de código-fonte
│   ├── server.py           # Arquivo principal do servidor
│   ├── db/                 # Código relacionado ao banco de dados
│   │   └── mysql_operations.py # Implementação de operações MySQL
│   ├── security/           # Código relacionado à segurança SQL
│   │   ├── interceptor.py   # Interceptor SQL
│   │   ├── query_limiter.py # Verificador de segurança SQL
│   │   └── sql_analyzer.py  # Analisador SQL
│   └── tools/              # Código de ferramentas
│       ├── mysql_tool.py           # Ferramentas de consulta básica
│       ├── mysql_metadata_tool.py  # Ferramentas de consulta de metadados
│       ├── mysql_info_tool.py      # Ferramentas de consulta de informações do banco de dados
│       ├── mysql_schema_tool.py    # Ferramentas de consulta avançada de estrutura de tabela
│       └── metadata_base_tool.py   # Classe base para ferramentas de metadados
├── tests/                  # Diretório de código de testes
├── .env.example            # Arquivo de exemplo de variáveis de ambiente
└── requirements.txt        # Arquivo de dependências do projeto

よくある問題の解決方法

DELETE 操作が正常に実行されない

• DELETE 操作に WHERE 句が含まれているか確認します
• WHERE 句のない DELETE 操作は、リスクレベル CRITICAL として扱われます
• 操作を実行する必要がある場合は、ALLOWED_RISK_LEVELS に CRITICAL が含まれていることを確認します
• 操作が実際にデータベースに影響したか確認するため、返された影響行数を確認します

環境変数が機能しない

• server.py の load_dotenv() 呼び出しが、ほかのモジュールをインポートする前に行われていることを確認します
• 環境変数が正しく読み込まれるよう、アプリケーションを再起動します
• 「環境変数からリスクレベルの設定を読み込みました」というログ出力を確認します

セキュリティ機構によって操作が拒否された

• 操作のリスクレベルが許可されている範囲内か確認します
• 高リスクの操作を実行する必要がある場合は、ALLOWED_RISK_LEVELS を適宜調整します
• WHERE 句のない UPDATE または DELETE では、条件を追加してリスクレベルを下げます（WHERE 1=1 でも構いません）

機密情報を表示できない

• 開発環境では、ALLOW_SENSITIVE_INFO=true を設定します
• 本番環境では、機密情報はデフォルトで非表示になります。これはセキュリティ機能です

ログシステム

サーバーには、コンソールとログファイルの両方で実行状態とエラーメッセージを確認できる、包括的なログ記録システムが含まれています。ログレベルは server.py で設定できます。

エラー処理

サーバーには、包括的なエラー処理機構が含まれています。

• MySQL コネクターのインポート確認
• データベース設定の検証
• SQL のセキュリティ確認
• 実行時エラーの捕捉と記録
• トランザクションの自動ロールバック

テストクライアント

このプロジェクトには、サーバーへの接続と MySQL クエリの実行方法を示すテストクライアント（test_client.py）が含まれています。最近の改善点は次のとおりです。

• SSE セッション処理の改善：

  • セッションの ping を二重に確認
  • サーバーの初期化が完了するまで適切に待機
  • より堅牢なエラー処理
  • SSE イベントのログ記録を改善

• クエリ送信の改善：

  • クエリ間に適切な間隔を設定
  • クエリ送信前にセッションのステータスを確認
  • より堅牢な SSE レスポンス処理
  • すべてのレスポンスを受信できるようタイムアウトを調整

貢献ガイド

プロジェクトの改善に向けて、Issue や Pull Request をお気軽にお送りください。

ライセンス

MIT License

Copyright (c) 2024 MCP MySQL Query Server

本ソフトウェアおよび関連ドキュメントファイル（以下「ソフトウェア」）の複製を入手したすべての人に対し、ソフトウェアを無制限に取り扱う権利を無償で許可します。これには、ソフトウェアの複製を使用、複製、変更、結合、公開、配布、サブライセンス、および／または販売する権利、ならびにソフトウェアを提供された人に同様の権利を許可する権利が含まれます。ただし、以下の条件に従うものとします。 上記の著作権表示および本許諾表示を、ソフトウェアのすべての複製または重要な部分に含めるものとします。

本ソフトウェアは「現状のまま」提供され、明示または黙示を問わず、いかなる種類の保証もありません。これには、商品性、特定目的への適合性、および非侵害性に関する保証が含まれますが、これらに限定されません。いかなる場合も、作者または著作権者は、本ソフトウェアまたはその使用、その他の取引に起因または関連する、契約、不法行為、その他のいかなる訴訟においても、請求、損害、その他の責任について責任を負いません。