Doris MCP Server

Doris MCP Server

Doris MCP（Model Context Protocol）Server は、Python と FastAPI で構築されたバックエンドサービスです。MCP を実装しており、定義済みの「ツール」を通じてクライアントが対話できます。主に Apache Doris データベースへの接続を目的としており、自然言語クエリから SQL への変換（NL2SQL）、クエリの実行、メタデータの管理と分析などのタスクで、大規模言語モデル（LLM）を活用できる場合があります。

🚀 v0.6.0 の新機能

• 🔐 エンタープライズ認証システム：トークンに紐づくデータベース設定を革新的に導入し、トークン、JWT、OAuth 認証を包括的にサポートします。きめ細かな制御スイッチとエンタープライズグレードのセキュリティ設定により、安全なマルチテナントアクセスを実現します。
• ⚡ データベースの即時検証：接続時にデータベース設定をリアルタイムで検証します。クエリ時のブロックをなくし、無効な設定に対する即時フィードバックを提供することで、後段で発生する接続失敗を100％排除します。
• 🔄 ホットリロードによる設定管理：tokens.json のインテリジェントなホットリロード、自動トークン再検証、ロールバック機構を備えた包括的なエラー処理により、ダウンタイムなしで設定を更新できます。
• 🏗️ 高度な接続アーキテクチャ：セッションキャッシュと接続プールの最適化により、接続のオーバーヘッドを60％削減します。インテリジェントなプール再作成とリソースの自動管理にも対応しています。
• 🌐 マルチワーカーのスケーラビリティ：ステートレスなマルチワーカーアーキテクチャ、効率的な負荷分散、エンタープライズグレードの並行処理機能により、真の水平スケーリングを実現します。
• 🔒 強化されたセキュリティフレームワーク：即時検証、ロールベースの権限、強化されたインジェクション検出パターンを備え、包括的なアクセス制御と SQL セキュリティ検証を提供します。
• 🛠️ 統合設定システム：コマンドラインの優先順位を適切に処理し、Docker との互換性を向上させ、クロスプラットフォームのデプロイをサポートする、合理化された設定管理を実現します。
• 📊 トークン管理ダッシュボード：作成、取り消し、統計、包括的な監査証跡を備え、エンタープライズのトークンガバナンスに必要なトークンのライフサイクル全体を管理できます。
• 🌐 Web ベースの管理インターフェース：直感的なダッシュボード、データベース紐付け設定、リアルタイム操作、エンタープライズグレードのアクセス制御を備え、localhost のみで安全にトークンを管理できます。

🚀 大きな節目：v0.6.0 により、このプラットフォームは、ダウンタイムのない運用（ホットリロード＋即時検証＋マルチワーカースケーリング）、高度なセキュリティ制御、トークンに紐づく包括的なデータベース設定を備えた、本番環境に対応したエンタープライズ認証・データベース管理システムとして確立されます。これは、エンタープライズデータプラットフォームの機能を根本から前進させるものです。

v0.5.1 の機能も含まれています

• 🔥 重大な at_eof 接続問題の修正：インテリジェントなヘルスモニタリングと自己修復による復旧により、接続プールのエラーを完全に排除します。
• 🔧 エンタープライズロギングシステム：レベル別のファイル分離、自動クリーンアップ、ミリ秒精度のタイムスタンプに対応します。
• 📊 高度なデータ分析スイート：品質分析、リネージ追跡、パフォーマンス監視など、エンタープライズグレードのデータガバナンスツールを7種類備えています。
• 🏃‍♂️ 高性能 ADBC 統合：Apache Arrow Flight SQL をサポートし、大規模データセットで3～10倍のパフォーマンス向上を実現します。
• ⚙️ 強化された設定管理：インテリジェントなパラメーター検証を備えた、ADBC の包括的な設定システムを提供します。

主な機能

• MCP プロトコルの実装：標準の MCP インターフェースを提供し、ツール呼び出し、リソース管理、プロンプトとのやり取りをサポートします。
• ストリーム可能な HTTP 通信：リクエスト／レスポンスとストリーミング通信の両方をサポートする統一 HTTP エンドポイントにより、最適なパフォーマンスと信頼性を実現します。
• Stdio 通信：Cursor などの MCP クライアントと直接連携するための標準入出力モードです。
• エンタープライズグレードのアーキテクチャ：包括的な機能を備えたモジュール設計です。
  • ツールマネージャー：統一インターフェースによる一元的なツール登録とルーティング（doris_mcp_server/tools/tools_manager.py）
  • 拡張監視ツールモジュール：モジュール式で拡張可能な設計による、高度なメモリ追跡、メトリクス収集、柔軟な BE ノード検出
  • クエリ情報ツール：設定可能なコンテンツの切り詰め、LLM 添付用のファイルエクスポート、高度なクエリ分析による SQL の explain とプロファイリングの強化
  • リソースマネージャー：リソース管理とメタデータの公開（doris_mcp_server/tools/resources_manager.py）
  • プロンプトマネージャー：データ分析用のインテリジェントなプロンプトテンプレート（doris_mcp_server/tools/prompts_manager.py）
• 高度なデータベース機能：
  • クエリ実行：高度なキャッシュと最適化、強化された接続の安定性、自動再試行メカニズムを備えた高性能 SQL 実行（doris_mcp_server/utils/query_executor.py）
  • セキュリティ管理：ブロックするキーワードの設定、SQL インジェクション対策、データマスキング、統一されたセキュリティ設定管理に対応する包括的な SQL セキュリティ検証（doris_mcp_server/utils/security.py）
  • メタデータ抽出：カタログ連携をサポートする包括的なデータベースメタデータ（doris_mcp_server/utils/schema_extractor.py）
  • パフォーマンス分析：高度な列分析、パフォーマンス監視、データ分析ツール（doris_mcp_server/utils/analysis_tools.py）
• カタログ連携のサポート：複数のカタログ環境（内部の Doris テーブルや Hive、MySQL などの外部データソース）を完全にサポートします。
• エンタープライズセキュリティ：環境変数による設定に対応した、認証、認可、SQL インジェクション対策、データマスキング機能を備える包括的なセキュリティフレームワークです。
• ウェブベースのトークン管理：データベースへの紐付け、リアルタイム統計、エンタープライズグレードのアクセス制御を備えた、トークンのライフサイクル全体を管理する安全な localhost 専用インターフェース（doris_mcp_server/auth/token_handlers.py）
• 統一設定フレームワーク：config.py による一元的な設定管理。包括的な検証、標準化されたパラメーター命名、自動的に information_schema にフォールバックするスマートなデフォルトデータベース処理に対応します。

システム要件

• Python：3.12+
• データベース：Apache Doris の接続情報（ホスト、ポート、ユーザー、パスワード、データベース）

🚀 クイックスタート

PyPI からインストール

# Install the latest version
pip install doris-mcp-server

# Install specific version
pip install doris-mcp-server==0.6.0

💡 コマンドの互換性：インストール後、後方互換性のため doris-mcp-server コマンドを両方とも利用できます。どちらのコマンドも同じように使用できます。

ストリーム可能な HTTP モードを起動（ウェブサービス）

最適なパフォーマンスと信頼性を提供する、主要な通信モードです。

# Full configuration with database connection
doris-mcp-server \
    --transport http \
    --host 0.0.0.0 \
    --port 3000 \
    --db-host 127.0.0.1 \
    --db-port 9030 \
    --db-user root \
    --db-password your_password 

Stdio モードを起動（Cursor およびその他の MCP クライアント向け）

MCP クライアントと直接連携するための標準入出力モードです。

# For direct integration with MCP clients like Cursor
doris-mcp-server --transport stdio

🌐 トークン管理インターフェース（v0.6.0 の新機能）

エンタープライズグレードのトークン管理を行う ウェブベースのトークン管理ダッシュボード にアクセスします。

安全なアクセスに必要な要件

• localhost のみアクセス可能：セキュリティを最大限に高めるため、インターフェースは 127.0.0.1 と ::1 のみに制限されています。
• 管理者認証：アクセスには TOKEN_MANAGEMENT_ADMIN_TOKEN が必要です。
• 設定の前提条件：

  # Required environment variables
  ENABLE_HTTP_TOKEN_MANAGEMENT=true
  ENABLE_TOKEN_AUTH=true
  TOKEN_MANAGEMENT_ADMIN_TOKEN=your_secure_admin_token
  TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1
  

インターフェースへのアクセス

# Access the token management interface
http://localhost:3000/token/management?admin_token=your_secure_admin_token

利用可能な操作

• 📊 トークン統計：アクティブ、期限切れ、合計トークンのリアルタイム概要
• ➕ トークンの作成：
  • 基本情報（ID、説明、有効期限）
  • データベースの紐付け（ホスト、ポート、ユーザー、パスワード、データベース）
  • カスタムトークン値、または自動生成される安全なトークン
• 📋 トークン管理：
  • データベースの紐付け状況を含む、すべてのトークンの一覧表示
  • ワンクリックでトークンを失効
  • 期限切れトークンの自動クリーンアップ
• 🔒 エンタープライズセキュリティ：
  • すべての操作に管理者認証が必要
  • IP のリアルタイム検証
  • 完全な監査ログ
  • tokens.json への自動永続化

🔐 セキュリティに関する注意：このインターフェースはローカルホストでの管理専用に設計されています。リモートからアクセスできないため、トークン管理操作のセキュリティを最大限に確保できます。

インストールの確認

# Check installation
doris-mcp-server --help

# Test HTTP mode (in another terminal)
curl http://localhost:3000/health

環境変数（任意）

コマンドライン引数の代わりに、環境変数を使用できます：

# Basic Database Configuration
export DORIS_HOST="127.0.0.1"
export DORIS_PORT="9030"
export DORIS_USER="root"
export DORIS_PASSWORD="your_password"

# Token Management Interface (Security-Critical)
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export ENABLE_TOKEN_AUTH=true
export TOKEN_MANAGEMENT_ADMIN_TOKEN="your_secure_admin_token"
export TOKEN_MANAGEMENT_ALLOWED_IPS="127.0.0.1,::1"

# Then start with simplified command
doris-mcp-server --transport http --host 0.0.0.0 --port 3000

コマンドライン引数

doris-mcp-server コマンドでは、次の引数を使用できます：

引数	説明	デフォルト	必須
--transport	トランスポートモード：http または stdio	http	いいえ
--host	HTTP サーバーのホスト（HTTP モードのみ）	0.0.0.0	いいえ
--port	HTTP サーバーのポート（HTTP モードのみ）	3000	いいえ
--db-host	Doris データベースのホスト	localhost	いいえ
--db-port	Doris データベースのポート	9030	いいえ
--db-user	Doris データベースのユーザー名	root	いいえ
--db-password	Doris データベースのパスワード	-	はい（環境変数で指定されていない場合）

開発環境のセットアップ

ソースからビルドする開発者向けの手順です：

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

# Replace with the actual repository URL if different
git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server

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

pip install -r requirements.txt

3. 環境変数を設定する

.env.example ファイルを .env にコピーし、環境に合わせて設定を変更します：

cp .env.example .env

主な環境変数：

• データベース接続：
  • DORIS_HOST：データベースのホスト名（デフォルト：localhost）
  • DORIS_PORT：データベースのポート（デフォルト：9030）
  • DORIS_USER：データベースのユーザー名（デフォルト：root）
  • DORIS_PASSWORD：データベースのパスワード
  • DORIS_DATABASE：デフォルトのデータベース名（デフォルト：information_schema）
  • DORIS_MIN_CONNECTIONS：接続プールの最小サイズ（デフォルト：5）
  • DORIS_MAX_CONNECTIONS：接続プールの最大サイズ（デフォルト：20）
  • DORIS_BE_HOSTS：監視対象のBEノード（カンマ区切り、任意。空の場合はSHOW BACKENDSによる自動検出）
  • DORIS_BE_WEBSERVER_PORT：監視ツール用のBEウェブサーバーポート（デフォルト：8040）
  • FE_ARROW_FLIGHT_SQL_PORT：ADBC用のフロントエンドArrow Flight SQLポート（v0.5.0で追加）
  • BE_ARROW_FLIGHT_SQL_PORT：ADBC用のバックエンドArrow Flight SQLポート（v0.5.0で追加）
• 認証設定（v0.6.0で強化）：
  • ENABLE_TOKEN_AUTH：トークンベース認証を有効にします（デフォルト：false）
  • ENABLE_JWT_AUTH：JWT認証を有効にします（デフォルト：false）
  • ENABLE_OAUTH_AUTH：OAuth認証を有効にします（デフォルト：false）
  • TOKEN_FILE_PATH：トークン管理用のtokens.jsonファイルへのパス（デフォルト：tokens.json）
  • TOKEN_HOT_RELOAD：トークン設定のホットリロードを有効にします（デフォルト：true）
  • DEFAULT_ADMIN_TOKEN：デフォルトの管理者トークン（環境変数でカスタマイズ可能）
  • DEFAULT_ANALYST_TOKEN：デフォルトのアナリストトークン（環境変数でカスタマイズ可能）
  • DEFAULT_READONLY_TOKEN：デフォルトの読み取り専用トークン（環境変数でカスタマイズ可能）
• 従来のセキュリティ設定：
  • AUTH_TYPE：従来の認証タイプ（token/basic/oauth、非推奨。個別のスイッチを使用してください）
  • TOKEN_SECRET：従来のトークン秘密鍵（トークンベース認証を使用してください）
  • ENABLE_SECURITY_CHECK：SQLセキュリティ検証を有効または無効にします（デフォルト：true）
  • BLOCKED_KEYWORDS：ブロックするSQLキーワードのカンマ区切りリスト
  • ENABLE_MASKING：データマスキングを有効にします（デフォルト：true）
  • MAX_RESULT_ROWS：結果行数の上限（デフォルト：10000）
• ADBC設定（v0.5.0で追加）：
  • ADBC_DEFAULT_MAX_ROWS：ADBCクエリのデフォルト最大行数（デフォルト：100000）
  • ADBC_DEFAULT_TIMEOUT：ADBCクエリのデフォルトタイムアウト（秒）（デフォルト：60）
  • ADBC_DEFAULT_RETURN_FORMAT：デフォルトの戻り値形式（arrow/pandas/dict）（デフォルト：arrow）
  • ADBC_CONNECTION_TIMEOUT：ADBC接続のタイムアウト（秒）（デフォルト：30）
  • ADBC_ENABLED：ADBCツールを有効または無効にします（デフォルト：true）
• パフォーマンス設定：
  • ENABLE_QUERY_CACHE：クエリキャッシュを有効にします（デフォルト：true）
  • CACHE_TTL：キャッシュの有効期間（秒）（デフォルト：300）
  • MAX_CONCURRENT_QUERIES：同時クエリ数の上限（デフォルト：50）
  • MAX_RESPONSE_CONTENT_SIZE：LLMとの互換性を確保するための応答コンテンツサイズの上限（デフォルト：4096、v0.4.0で追加）
• 拡張ログ設定（v0.5.0で改善）：
  • LOG_LEVEL：ログレベル（DEBUG/INFO/WARNING/ERROR、デフォルト：INFO）
  • LOG_FILE_PATH：ログファイルのパス（レベル別に自動整理）
  • ENABLE_AUDIT：監査ログを有効にします（デフォルト：true）
  • ENABLE_LOG_CLEANUP：ログの自動クリーンアップを有効にします（デフォルト：true、v0.5.0で強化）
  • LOG_MAX_AGE_DAYS：ログファイルの最大保存期間（日）（デフォルト：30、v0.5.0で強化）
  • LOG_CLEANUP_INTERVAL_HOURS：ログクリーンアップの確認間隔（時間）（デフォルト：24、v0.5.0で強化）
  • v0.5.0の新機能：
    • レベル別ファイル分割：debug.log、info.log、warning.log、error.log、critical.logに自動で分割します
    • タイムスタンプ形式：ミリ秒単位の精度と適切な配置による、改善されたフォーマット
    • バックグラウンドクリーンアップスケジューラー：設定可能な保持ポリシーに基づく自動クリーンアップ
    • 監査証跡：保持期間を個別に管理する専用のaudit.log
    • パフォーマンス最適化：ローテーションに対応した、オーバーヘッドを最小限に抑える非同期ロギング

利用可能な MCP ツール

以下の表に、MCP クライアントから現在呼び出し可能な主なツールを示します。

ツール名	説明	パラメーター
exec_query	SQL クエリを実行して結果を返します。	sql (string, Required), db_name (string, Optional), catalog_name (string, Optional), max_rows (integer, Optional), timeout (integer, Optional)
get_table_schema	テーブルの詳細な構造情報を取得します。	table_name (string, Required), db_name (string, Optional), catalog_name (string, Optional)
get_db_table_list	指定したデータベース内のすべてのテーブル名の一覧を取得します。	db_name (string, Optional), catalog_name (string, Optional)
get_db_list	すべてのデータベース名の一覧を取得します。	catalog_name (string, Optional)
get_table_comment	テーブルのコメント情報を取得します。	table_name (string, Required), db_name (string, Optional), catalog_name (string, Optional)
get_table_column_comments	テーブル内のすべての列のコメント情報を取得します。	table_name (string, Required), db_name (string, Optional), catalog_name (string, Optional)
get_table_indexes	指定したテーブルのインデックス情報を取得します。	table_name (string, Required), db_name (string, Optional), catalog_name (string, Optional)
get_recent_audit_logs	直近の期間の監査ログレコードを取得します。	days (integer, Optional), limit (integer, Optional)
get_catalog_list	すべてのカタログ名の一覧を取得します。	random_string (string, Required)
get_sql_explain	LLM による分析用に、内容の切り詰め設定とファイルへのエクスポートに対応した SQL 実行計画を取得します。	sql (string, Required), verbose (boolean, Optional), db_name (string, Optional), catalog_name (string, Optional)
get_sql_profile	LLM による最適化ワークフロー用に、内容管理とファイルへのエクスポートに対応した SQL 実行プロファイルを取得します。	sql (string, Required), db_name (string, Optional), catalog_name (string, Optional), timeout (integer, Optional)
get_table_data_size	FE HTTP API 経由でテーブルデータサイズ情報を取得します。	db_name (string, Optional), table_name (string, Optional), single_replica (boolean, Optional)
get_monitoring_metrics_info	Doris のモニタリングメトリクスの定義と説明を取得します。	role (string, Optional), monitor_type (string, Optional), priority (string, Optional)
get_monitoring_metrics_data	柔軟な BE 検出を使用して、ノードから Doris の実際のモニタリングメトリクスデータを取得します。	role (string, Optional), monitor_type (string, Optional), priority (string, Optional)
get_realtime_memory_stats	自動または手動の BE 検出を使用して、BE Memory Tracker 経由でリアルタイムのメモリ統計情報を取得します。	tracker_type (string, Optional), include_details (boolean, Optional)
get_historical_memory_stats	柔軟な BE 設定を使用して、BE Bvar インターフェース経由で過去のメモリ統計情報を取得します。	tracker_names (array, Optional), time_range (string, Optional)
analyze_data_quality	完全性分析と分布分析を組み合わせて、包括的なデータ品質分析を行います。	table_name (string, Required), analysis_scope (string, Optional), sample_size (integer, Optional), business_rules (array, Optional)
trace_column_lineage	SQL 分析と依存関係のマッピングを通じて、列のリネージをエンドツーエンドで追跡します。	target_columns (array, Required), analysis_depth (integer, Optional), include_transformations (boolean, Optional)
monitor_data_freshness	設定可能な鮮度しきい値を使用して、データの陳腐化をリアルタイムで監視します。	table_names (array, Optional), freshness_threshold_hours (integer, Optional), include_update_patterns (boolean, Optional)
analyze_data_access_patterns	アクセスパターンを監視し、ユーザー行動の分析とセキュリティ異常の検出を行います。	days (integer, Optional), include_system_users (boolean, Optional), min_query_threshold (integer, Optional)
analyze_data_flow_dependencies	テーブルとビュー間のデータフローの影響分析と依存関係のマッピングを行います。	target_table (string, Optional), analysis_depth (integer, Optional), include_views (boolean, Optional)
analyze_slow_queries_topn	上位 N 件の低速クエリ分析とパターン分析により、パフォーマンスのボトルネックを特定します。	days (integer, Optional), top_n (integer, Optional), min_execution_time_ms (integer, Optional), include_patterns (boolean, Optional)
analyze_resource_growth_curves	リソースの増加分析と傾向予測により、キャパシティプランニングを行います。	days (integer, Optional), resource_types (array, Optional), include_predictions (boolean, Optional)
exec_adbc_query	ADBC（Arrow Flight SQL）プロトコルを使用して、高パフォーマンスで SQL を実行します。	sql (string, Required), max_rows (integer, Optional), timeout (integer, Optional), return_format (string, Optional)
get_adbc_connection_info	Arrow Flight SQL の ADBC 接続診断とステータス監視を行います。	パラメーターは不要です
注： すべてのメタデータツールは、複数カタログ環境向けのカタログフェデレーションをサポートしています。拡張監視ツールでは、包括的なメモリ追跡とメトリクス収集機能を利用できます。v0.5.0 の新機能：エンタープライズデータガバナンス向けの高度な分析ツール 7 種類と、大規模データセットで 3～10 倍のパフォーマンス向上を実現する高性能データ転送向け ADBC ツール 2 種類を追加しました。

4. サービスの実行

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

./start_server.sh

このコマンドにより、Streamable HTTP MCP サービスを備えた FastAPI アプリケーションが起動します。

5. docker へのデプロイ

Doris MCP Server のみを docker で実行する場合は、次のコマンドを使用します。

cd doris-mcp-server
docker build -t doris-mcp-server .
docker run -d -p <port>:<port> -v /*your-host*/doris-mcp-server/.env:/app/.env --name <your-mcp-server-name> -it doris-mcp-server:latest

サービスエンドポイント：

• Streamable HTTP：http://<host>:<port>/mcp（主要な MCP エンドポイント。GET、POST、DELETE、OPTIONS をサポートします）
• ヘルスチェック：http://<host>:<port>/health

注： サーバーは Web ベースの通信に Streamable HTTP を使用し、統一されたリクエスト／レスポンスとストリーミング機能を提供します。

使用方法

Doris MCP Server を利用するには、MCP クライアントが必要です。クライアントはサーバーの Streamable HTTP エンドポイントに接続し、MCP 仕様に従ってリクエストを送信して、サーバーのツールを呼び出します。

主なやり取りの流れ：

1. クライアントの初期化：initialize メソッド呼び出しを /mcp（Streamable HTTP）に送信します。
2. （任意）ツールの検出：クライアントは tools/list を呼び出し、サポートされているツールの一覧、説明、パラメーターのスキーマを取得できます。
3. ツールの呼び出し：クライアントは name と arguments を指定して tools/call リクエストを送信します。
   • 例：テーブルスキーマの取得
     • name：get_table_schema
     • arguments：table_name、db_name、catalog_name を含めます。
4. レスポンスの処理：
   • 非ストリーミング：クライアントは content または isError を含むレスポンスを受け取ります。
   • ストリーミング：クライアントは一連の進捗通知を受け取り、その後に最終レスポンスを受け取ります。

カタログフェデレーションのサポート

Doris MCP Server はカタログフェデレーションをサポートしており、統一されたインターフェースから複数のデータカタログ（内部の Doris テーブルや、Hive、MySQL などの外部データソース）を操作できます。

主な機能：

• 複数カタログのメタデータアクセス：すべてのメタデータツール（get_db_list、get_db_table_list、get_table_schema など）では、特定のカタログに問い合わせるための省略可能な catalog_name パラメーターをサポートしています。
• カタログ間の SQL クエリ：3 部構成のテーブル名を使用して、複数カタログにまたがる SQL クエリを実行できます。
• カタログの検出：get_catalog_list を使用して、利用可能なカタログとその種類を確認できます。

3 部構成の名前指定要件：

すべての SQL クエリでは、テーブル参照に必ず 3 部構成の名前を使用してください。

• 内部テーブル：internal.database_name.table_name
• 外部テーブル：catalog_name.database_name.table_name

例：

1. 利用可能なカタログの取得：

   {
     "tool_name": "get_catalog_list",
     "arguments": {"random_string": "unique_id"}
   }
   

2. 特定のカタログにあるデータベースの取得：

   {
     "tool_name": "get_db_list", 
     "arguments": {"random_string": "unique_id", "catalog_name": "mysql"}
   }
   

3. 内部カタログへのクエリ：

   {
     "tool_name": "exec_query",
     "arguments": {
       "random_string": "unique_id",
       "sql": "SELECT COUNT(*) FROM internal.ssb.customer"
     }
   }
   

4. 外部カタログへのクエリ：

   {
     "tool_name": "exec_query", 
     "arguments": {
       "random_string": "unique_id",
       "sql": "SELECT COUNT(*) FROM mysql.ssb.customer"
     }
   }
   

5. カタログ間のクエリ：

   {
     "tool_name": "exec_query",
     "arguments": {
       "random_string": "unique_id", 
       "sql": "SELECT i.c_name, m.external_data FROM internal.ssb.customer i JOIN mysql.test.user_info m ON i.c_custkey = m.customer_id"
     }
   }
   

セキュリティ設定

Doris MCP Server には、v0.6.0 で強化された高度な認証、認可、SQL セキュリティ検証、データマスキング機能を備えた、エンタープライズグレードの包括的なセキュリティフレームワークが含まれています。

セキュリティ機能（v0.6.0 で強化）

• 🔐 マルチ認証システム：独立した制御スイッチを備えた、トークン、JWT、OAuth の完全な認証
• 🔗 トークンに紐づくデータベース設定：トークンに独自のデータベース接続パラメーターを持たせる革新的な方法
• 🔄 ホットリロードセキュリティ：インテリジェントなトークン再検証による、ダウンタイムのないセキュリティ設定の更新
• ⚡ 即時検証：接続時のリアルタイムなデータベースおよび認証の検証
• 🛡️ ロールベース認可：4 段階のセキュリティ分類を備えた高度な RBAC
• 🚫 強化された SQL セキュリティ：パターン検出を改善した、高度な SQL インジェクション対策
• 🎭 インテリジェントなデータマスキング：ユーザーベースの権限による、機密データの自動マスキング
• 📊 セキュリティ分析：包括的な監査証跡とセキュリティ監視

認証設定（v0.6.0）

きめ細かな制御が可能な新しい認証システムを設定します。

# Individual Authentication Control (New in v0.6.0)
ENABLE_TOKEN_AUTH=true          # Enable token-based authentication
ENABLE_JWT_AUTH=false           # Enable JWT authentication  
ENABLE_OAUTH_AUTH=false         # Enable OAuth authentication

# Token Management (New in v0.6.0)
TOKEN_FILE_PATH=tokens.json     # Token configuration file
TOKEN_HOT_RELOAD=true          # Enable hot reloading

# Default Tokens (Customizable via environment)
DEFAULT_ADMIN_TOKEN=doris_admin_token_123456
DEFAULT_ANALYST_TOKEN=doris_analyst_token_123456
DEFAULT_READONLY_TOKEN=doris_readonly_token_123456

# Legacy Configuration (Deprecated)
# AUTH_TYPE=token               # Use individual switches instead
# TOKEN_SECRET=your_secret_key  # Use token-based auth instead

トークンに紐づくデータベース設定（v0.6.0 で新登場）

高度なトークン管理とデータベースの紐付けを行うため、tokens.json ファイルを作成します。

{
  "version": "1.0",
  "tokens": [
    {
      "token_id": "customer-a-token",
      "token": "customer_a_secure_token_12345",
      "description": "Customer A dedicated database access",
      "expires_hours": null,
      "is_active": true,
      "database_config": {
        "host": "customer-a-db.example.com",
        "port": 9030,
        "user": "customer_a_user",
        "password": "secure_password",
        "database": "customer_a_data",
        "charset": "UTF8",
        "fe_http_port": 8030
      }
    },
    {
      "token_id": "customer-b-token", 
      "token": "customer_b_secure_token_67890",
      "description": "Customer B dedicated database access",
      "expires_hours": 720,
      "is_active": true,
      "database_config": {
        "host": "customer-b-db.example.com",
        "port": 9030,
        "user": "customer_b_user", 
        "password": "secure_password",
        "database": "customer_b_data",
        "charset": "UTF8",
        "fe_http_port": 8030
      }
    }
  ]
}

ホットリロードによる設定の更新（v0.6.0 で新登場）

システムは設定の変更を自動的に検出して適用します。

• 自動検出：10 秒ごとにファイルの変更を監視します
• 即時検証：新しいトークンのデータベース設定を直ちに検証します
• ダウンタイムなし：サービスを中断せずに設定を更新します
• ロールバック保護：設定エラーが発生した場合、自動的にロールバックします
• 監査証跡：設定変更をすべて記録します

トークン認証の例

# Client authentication with token
auth_info = {
    "type": "token",
    "token": "your_jwt_token",
    "session_id": "unique_session_id"
}

基本認証の例

# Client authentication with username/password
auth_info = {
    "type": "basic",
    "username": "analyst",
    "password": "secure_password",
    "session_id": "unique_session_id"
}

認可とセキュリティレベル

システムは、階層型アクセス制御を備えた 4 つのセキュリティレベルをサポートしています。

セキュリティレベル	アクセス範囲	一般的な用途
Public	制限なしのアクセス	公開レポート、一般的な統計
Internal	社員	社内ダッシュボード、業務指標
Confidential	許可された担当者	顧客データ、財務レポート
Secret	上級管理職	戦略データ、機密性の高い分析

ロール設定

ユーザーロールと権限を設定します。

# Example role configuration
role_permissions = {
    "data_analyst": {
        "security_level": "internal",
        "permissions": ["read_data", "execute_query"],
        "allowed_tables": ["sales", "products", "orders"]
    },
    "data_admin": {
        "security_level": "confidential", 
        "permissions": ["read_data", "execute_query", "admin"],
        "allowed_tables": ["*"]
    },
    "executive": {
        "security_level": "secret",
        "permissions": ["read_data", "execute_query", "admin"],
        "allowed_tables": ["*"]
    }
}

SQL セキュリティ検証

システムは、SQL クエリのセキュリティリスクを自動的に検証します。

ブロック対象の操作

環境変数を使用して、ブロック対象の SQL 操作を設定します（v0.4.2 で新登場）。

# Enable/disable SQL security check (New in v0.4.2)
ENABLE_SECURITY_CHECK=true

# Customize blocked keywords via environment variable (New in v0.4.2)
BLOCKED_KEYWORDS="DROP,DELETE,TRUNCATE,ALTER,CREATE,INSERT,UPDATE,GRANT,REVOKE,EXEC,EXECUTE,SHUTDOWN,KILL"

# Maximum query complexity score
MAX_QUERY_COMPLEXITY=100

デフォルトのブロック対象キーワード（v0.4.2 で統一）：

• DDL 操作：DROP、CREATE、ALTER、TRUNCATE
• DML 操作：DELETE、INSERT、UPDATE
• DCL 操作：GRANT、REVOKE
• システム操作：EXEC、EXECUTE、SHUTDOWN、KILL

SQL インジェクション対策

システムは、以下を自動的に検出してブロックします。

• UNION ベースのインジェクション：UNION SELECT 攻撃
• ブール値ベースのインジェクション：OR 1=1 パターン
• 時間ベースのインジェクション：SLEEP()、WAITFOR 関数
• コメントインジェクション：--、/**/ パターン
• スタッククエリ：; で区切られた複数のステートメント

セキュリティ検証の例

# This query would be blocked
dangerous_sql = "SELECT * FROM users WHERE id = 1; DROP TABLE users;"

# This query would be allowed
safe_sql = "SELECT name, email FROM users WHERE department = 'sales'"

データマスキングの設定

機密情報の自動データマスキングを設定します。

組み込みのマスキングルール

# Default masking rules
masking_rules = [
    {
        "column_pattern": r".*phone.*|.*mobile.*",
        "algorithm": "phone_mask",
        "parameters": {
            "mask_char": "*",
            "keep_prefix": 3,
            "keep_suffix": 4
        },
        "security_level": "internal"
    },
    {
        "column_pattern": r".*email.*", 
        "algorithm": "email_mask",
        "parameters": {"mask_char": "*"},
        "security_level": "internal"
    },
    {
        "column_pattern": r".*id_card.*|.*identity.*",
        "algorithm": "id_mask", 
        "parameters": {
            "mask_char": "*",
            "keep_prefix": 6,
            "keep_suffix": 4
        },
        "security_level": "confidential"
    }
]

マスキングアルゴリズム

アルゴリズム	説明	例
phone_mask	電話番号をマスキングします	138****5678
email_mask	メールアドレスをマスキングします	j***[email protected]
id_mask	ID カード番号をマスキングします	110101****1234
name_mask	個人名をマスキングします	張*明
partial_mask	比率を指定して部分的にマスキングします	abc***xyz

カスタムマスキングルール

設定にカスタムマスキングルールを追加します。

# Custom masking rule
custom_rule = {
    "column_pattern": r".*salary.*|.*income.*",
    "algorithm": "partial_mask",
    "parameters": {
        "mask_char": "*",
        "mask_ratio": 0.6
    },
    "security_level": "confidential"
}

セキュリティ設定の例

環境変数

# .env file
AUTH_TYPE=token
TOKEN_SECRET=your_jwt_secret_key
ENABLE_MASKING=true
MAX_RESULT_ROWS=10000
BLOCKED_SQL_OPERATIONS=DROP,DELETE,TRUNCATE,ALTER
MAX_QUERY_COMPLEXITY=100
ENABLE_AUDIT=true

機密テーブルの設定

# Configure sensitive tables with security levels
sensitive_tables = {
    "user_profiles": "confidential",
    "payment_records": "secret", 
    "employee_salaries": "secret",
    "customer_data": "confidential",
    "public_reports": "public"
}

セキュリティのベストプラクティス

1. 🔑 強力な認証：適切な有効期限を設定した JWT トークンを使用します
2. 🎯 最小権限の原則：必要最小限の権限を付与します
3. 🔍 定期的な監査：セキュリティ監視のために監査ログを有効にします
4. 🛡️ 入力の検証：すべての SQL クエリは自動的に検証されます
5. 🎭 データの分類：セキュリティレベルに基づいてデータを適切に分類します
6. 🔄 定期的な更新：セキュリティルールと設定を最新の状態に保ちます

セキュリティ監視

システムは包括的なセキュリティ監視を提供します。

# Security audit log example
{
    "timestamp": "2024-01-15T10:30:00Z",
    "user_id": "analyst_user",
    "action": "query_execution", 
    "resource": "customer_data",
    "result": "blocked",
    "reason": "insufficient_permissions",
    "risk_level": "medium"
}

⚠️ 重要：本番環境にデプロイする前に、必ず開発環境でセキュリティ設定をテストしてください。組織の要件に基づき、セキュリティポリシーを定期的に確認して更新してください。

Cursor との接続

Cursor は、Stdio モード（推奨）または Streamable HTTP モードを使用して、この MCP サーバーに接続できます。

Stdio モード

Stdio モードでは、Cursor がサーバープロセスを直接管理できます。設定は Cursor の MCP サーバー設定ファイル（通常は ~/.cursor/mcp.json など）で行います。

方法 1：PyPI を使用したインストール（推奨）

PyPI からパッケージをインストールし、Cursor で使用するよう設定します。

pip install doris-mcp-server

Cursor の設定： Cursor の MCP 設定に、次のようなエントリを追加します。

{
  "mcpServers": {
    "doris-stdio": {
      "command": "doris-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

方法 2：uv を使用（開発用）

uv がインストールされており、ソースから実行する場合：

uv run --project /path/to/doris-mcp-server doris-mcp-server

注： /path/to/doris-mcp-server を、プロジェクトディレクトリの実際の絶対パスに置き換えてください。

Cursor の設定： Cursor の MCP 設定に、次のようなエントリを追加します。

{
  "mcpServers": {
    "doris-stdio": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/your/doris-mcp-server", "doris-mcp-server"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

Streamable HTTP モード

Streamable HTTP モードでは、まず MCP サーバーを独立して起動してから、Cursor が接続するよう設定する必要があります。

1. .env を設定： プロジェクトディレクトリ内の .env ファイルで、データベースの認証情報やその他必要な設定が正しく構成されていることを確認します。

2. サーバーを起動： プロジェクトのルートディレクトリで、ターミナルからサーバーを実行します。

   ./start_server.sh
   

   このスクリプトは .env ファイルを読み込み、Streamable HTTP に対応した FastAPI サーバーを起動します。サーバーがリッスンしているホストとポートを確認してください（デフォルトは 0.0.0.0:3000 です）。

3. Cursor の設定： 実行中のサーバーの Streamable HTTP エンドポイントを指定して、Cursor の MCP 設定に次のようなエントリを追加します。

   {
     "mcpServers": {
       "doris-http": {
          "url": "http://127.0.0.1:3000/mcp"
       }
     }
   }
   

   注： サーバーが別のアドレスで動作している場合は、ホストやポートを変更してください。/mcp エンドポイントは、統合された Streamable HTTP インターフェースです。

Cursor でいずれかのモードを設定すると、サーバー（例：doris-stdio または doris-http）を選択して、そのツールを使用できるようになります。

ディレクトリ構成

doris-mcp-server/
├── doris_mcp_server/           # Main server package
│   ├── main.py                 # Main entry point and FastAPI app
│   ├── multiworker_app.py      # Multi-worker application module (New in v0.6.0)
│   ├── auth/                   # Authentication modules (New in v0.6.0)
│   │   ├── token_manager.py    # Enterprise token management with hot reload
│   │   ├── jwt_manager.py      # JWT authentication provider
│   │   ├── oauth_provider.py   # OAuth authentication provider  
│   │   ├── oauth_handlers.py   # OAuth HTTP endpoint handlers
│   │   ├── token_handlers.py   # Token management HTTP endpoints
│   │   ├── auth_middleware.py  # Authentication middleware
│   │   └── __init__.py
│   ├── tools/                  # MCP tools implementation
│   │   ├── tools_manager.py    # Centralized tools management and registration
│   │   ├── resources_manager.py # Resource management and metadata exposure
│   │   ├── prompts_manager.py  # Intelligent prompt templates for data analysis
│   │   └── __init__.py
│   ├── utils/                  # Core utility modules
│   │   ├── config.py           # Configuration management with validation
│   │   ├── db.py               # Enhanced database connection management with token binding (Enhanced in v0.6.0)
│   │   ├── query_executor.py   # High-performance SQL execution with caching
│   │   ├── security.py         # Advanced security management and authentication (Enhanced in v0.6.0)
│   │   ├── schema_extractor.py # Metadata extraction with catalog federation
│   │   ├── analysis_tools.py   # Data analysis and performance monitoring
│   │   ├── data_governance_tools.py  # Data lineage and freshness monitoring (v0.5.0)
│   │   ├── data_quality_tools.py     # Comprehensive data quality analysis (v0.5.0)
│   │   ├── data_exploration_tools.py # Advanced statistical analysis (v0.5.0)
│   │   ├── security_analytics_tools.py # Access pattern analysis (v0.5.0)
│   │   ├── dependency_analysis_tools.py # Impact analysis and dependency mapping (v0.5.0)
│   │   ├── performance_analytics_tools.py # Query optimization and capacity planning (v0.5.0)
│   │   ├── adbc_query_tools.py       # High-performance Arrow Flight SQL operations (v0.5.0)
│   │   ├── logger.py           # Logging configuration
│   │   └── __init__.py
│   └── __init__.py
├── doris_mcp_client/           # MCP client implementation
│   ├── client.py               # Unified MCP client for testing and integration
│   ├── README.md               # Client documentation
│   └── __init__.py
├── logs/                       # Log files directory
├── tokens.json                 # Token configuration file (New in v0.6.0)
├── README.md                   # This documentation
├── RELEASE_NOTES_v0.6.0.md     # Release notes for v0.6.0
├── .env.example                # Environment variables template
├── requirements.txt            # Python dependencies
├── pyproject.toml              # Project configuration and entry points
├── uv.lock                     # UV package manager lock file
├── generate_requirements.py    # Requirements generation script
├── start_server.sh             # Server startup script
└── restart_server.sh           # Server restart script

新しいツールの開発

このセクションでは、ツールを一元管理する統合モジュールアーキテクチャに基づいて、Doris MCP Server に新しい MCP ツールを追加する手順を説明します。

1. 既存のユーティリティモジュールを活用する

サーバーには、一般的なデータベース操作に対応する包括的なユーティリティモジュールが用意されています。

• doris_mcp_server/utils/db.py：接続プーリングとヘルスモニタリングを備えたデータベース接続管理です。
• doris_mcp_server/utils/query_executor.py：高度なキャッシュ、最適化、パフォーマンスモニタリングを備えた高性能な SQL 実行機能です。
• doris_mcp_server/utils/schema_extractor.py：完全なカタログフェデレーションに対応したメタデータ抽出機能です。
• doris_mcp_server/utils/security.py：包括的なセキュリティ管理、SQL 検証、データマスキング機能です。
• doris_mcp_server/utils/analysis_tools.py：高度なデータ分析および統計ツールです。
• doris_mcp_server/utils/config.py：検証機能を備えた設定管理です。
• doris_mcp_server/utils/data_governance_tools.py：データリネージの追跡と鮮度のモニタリング機能です（v0.5.0 で追加）。
• doris_mcp_server/utils/data_quality_tools.py：包括的なデータ品質分析フレームワークです（v0.5.0 で追加）。
• doris_mcp_server/utils/adbc_query_tools.py：高性能な Arrow Flight SQL 操作機能です（v0.5.0 で追加）。

2. ツールのロジックを実装する

doris_mcp_server/tools/tools_manager.py の DorisToolsManager クラスに新しいツールを追加します。ツールマネージャーでは、統一されたインターフェースを使用してツールを一元的に登録・実行できます。

例： 新しい分析ツールを追加する：

# In doris_mcp_server/tools/tools_manager.py

async def your_new_analysis_tool(self, arguments: Dict[str, Any]) -> List[Dict[str, Any]]:
    """
    Your new analysis tool implementation
    
    Args:
        arguments: Tool arguments from MCP client
        
    Returns:
        List of MCP response messages
    """
    try:
        # Use existing utilities
        result = await self.query_executor.execute_sql_for_mcp(
            sql="SELECT COUNT(*) FROM your_table",
            max_rows=arguments.get("max_rows", 100)
        )
        
        return [{
            "type": "text",
            "text": json.dumps(result, ensure_ascii=False, indent=2)
        }]
        
    except Exception as e:
        logger.error(f"Tool execution failed: {str(e)}", exc_info=True)
        return [{
            "type": "text", 
            "text": f"Error: {str(e)}"
        }]

3. ツールを登録する

同じクラスの _register_tools メソッドにツールを追加します。

# In the _register_tools method of DorisToolsManager

@self.mcp.tool(
    name="your_new_analysis_tool",
    description="Description of your new analysis tool",
    inputSchema={
        "type": "object",
        "properties": {
            "parameter1": {
                "type": "string",
                "description": "Description of parameter1"
            },
            "parameter2": {
                "type": "integer", 
                "description": "Description of parameter2",
                "default": 100
            }
        },
        "required": ["parameter1"]
    }
)
async def your_new_analysis_tool_wrapper(arguments: Dict[str, Any]) -> List[Dict[str, Any]]:
    return await self.your_new_analysis_tool(arguments)

4. 高度な機能

より複雑なツールでは、包括的なフレームワークを活用できます。

• 高度なキャッシュ：クエリエグゼキューターに組み込まれたキャッシュを使用して、パフォーマンスを向上させます。
• エンタープライズセキュリティ：セキュリティマネージャーを通じて、包括的な SQL 検証とデータマスキングを適用します。
• インテリジェントなプロンプト：プロンプトマネージャーを使用して、高度なクエリ生成を行います。
• リソース管理：リソースマネージャーを通じてメタデータを公開します。
• パフォーマンスモニタリング：分析ツールと統合して、モニタリング機能を利用します。

5. テスト

付属の MCP クライアントを使用して、新しいツールをテストします。

# Using doris_mcp_client/client.py
from doris_mcp_client.client import DorisUnifiedMCPClient

async def test_new_tool():
    client = DorisUnifiedMCPClient()
    result = await client.call_tool("your_new_analysis_tool", {
        "parameter1": "test_value",
        "parameter2": 50
    })
    print(result)

MCP クライアント

このプロジェクトには、テストと統合を目的とした統合 MCP クライアント（doris_mcp_client/）が含まれています。このクライアントは複数の接続モードに対応し、MCP サーバーとやり取りするための便利なインターフェースを提供します。

クライアントの詳細なドキュメントについては、doris_mcp_client/README.md を参照してください。

コントリビューション

Issue または Pull Request によるコントリビューションを歓迎します。

ライセンス

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

FAQ

Q: Qwen3-32b などのパラメーター数の少ないモデルで、ツールの呼び出しがいつも失敗するのはなぜですか？

A: これはよくある問題です。主な原因は、これらのモデルが MCP ツールを正しく使用するために、より明確な指示を必要とすることです。モデルに次の指示プロンプトを追加することをおすすめします。

• 中国語版：

<instruction>
尽可能使用MCP工具完成任务，仔细阅读每个工具的注解、方法名、参数说明等内容。请按照以下步骤操作：

1. 仔细分析用户的问题，从已有的Tools列表中匹配最合适的工具。
2. 确保工具名称、方法名和参数完全按照工具注释中的定义使用，不要自行创造工具名称或参数。
3. 传入参数时，严格遵循工具注释中规定的参数格式和要求。
4. 调用工具时，根据需要直接调用工具，但参数请求参考以下请求格式：{"mcp_sse_call_tool": {"tool_name": "$tools_name", "arguments": "{}"}}
5. 输出结果时，不要包含任何XML标签，仅返回纯文本内容。

<input>
用户问题：user_query
</input>

<output>
返回工具调用结果或最终答案，以及对结果的分析。
</output>
</instruction>

• 英語版：

<instruction>
Use MCP tools to complete tasks as much as possible. Carefully read the annotations, method names, and parameter descriptions of each tool. Please follow these steps:

1. Carefully analyze the user's question and match the most appropriate tool from the existing Tools list.
2. Ensure tool names, method names, and parameters are used exactly as defined in the tool annotations. Do not create tool names or parameters on your own.
3. When passing parameters, strictly follow the parameter format and requirements specified in the tool annotations.
4. When calling tools, call them directly as needed, but refer to the following request format for parameters: {"mcp_sse_call_tool": {"tool_name": "$tools_name", "arguments": "{}"}}
5. When outputting results, do not include any XML tags, return plain text content only.

<input>
User question: user_query
</input>

<output>
Return tool call results or final answer, along with analysis of the results.
</output>
</instruction>

返される結果にさらに要件がある場合は、<output> タグ内に具体的な要件を記述できます。

Q: 異なるデータベース接続を設定するにはどうすればよいですか？

A: データベース接続は、いくつかの方法で設定できます。

1. 環境変数（推奨）：

   export DORIS_HOST="your_doris_host"
   export DORIS_PORT="9030"
   export DORIS_USER="root"
   export DORIS_PASSWORD="your_password"
   

2. コマンドライン引数：

   doris-mcp-server --db-host your_host --db-port 9030 --db-user root --db-password your_password
   

3. 設定ファイル： .env ファイル内の該当する設定項目を変更します。

Q: モニタリングツール用に BE ノードを設定するにはどうすればよいですか？

A: デプロイシナリオに応じて、適切な設定を選択してください。

外部ネットワーク（手動設定）：

# Manually specify BE node addresses
DORIS_BE_HOSTS=10.1.1.100,10.1.1.101,10.1.1.102
DORIS_BE_WEBSERVER_PORT=8040

内部ネットワーク（自動検出）：

# Leave BE_HOSTS empty for auto-discovery
# DORIS_BE_HOSTS=  # Not set or empty
# System will use 'SHOW BACKENDS' command to get internal IPs

Q：最適化のために、SQL Explain／Profile ファイルを LLM で使用するにはどうすればよいですか？

A： ツールでは、LLM による分析用に、内容を省略したファイルと完全なファイルの両方を提供します。

1. 分析結果を取得する：

   {
     "content": "Truncated plan for immediate review",
     "file_path": "/tmp/explain_12345.txt",
     "is_content_truncated": true
   }
   

2. LLM 分析のワークフロー：

   • 内容を省略したファイルを確認して、すばやく情報を把握します
   • 完全なファイルを添付ファイルとして LLM にアップロードします
   • 最適化の提案やパフォーマンス分析を依頼します
   • 推奨された改善策を実施します

3. コンテンツサイズを設定する：

   MAX_RESPONSE_CONTENT_SIZE=4096  # Adjust as needed
   

Q：データセキュリティとマスキング機能を有効にするにはどうすればよいですか？

A： .env ファイルに次の設定を追加します。

# Enable data masking
ENABLE_MASKING=true
# Set authentication type
AUTH_TYPE=token
# Configure token secret
TOKEN_SECRET=your_secret_key
# Set maximum result rows
MAX_RESULT_ROWS=10000

Q：Stdio モードと HTTP モードの違いは何ですか？

A：

• Stdio モード：クライアントがサーバープロセスを管理する、Cursor などの MCP クライアントとの直接統合に適しています
• HTTP モード：複数のクライアント接続に対応する独立したウェブサービスで、本番環境に適しています

推奨事項：

• 開発および個人利用：Stdio モード
• 本番環境およびマルチユーザー環境：HTTP モード

Q：接続タイムアウトの問題を解決するにはどうすればよいですか？

A： 次の解決策をお試しください。

1. タイムアウト設定を増やす：

   # Set in .env file
   QUERY_TIMEOUT=60
   CONNECTION_TIMEOUT=30
   

2. ネットワーク接続を確認する：

   # Test database connection
   curl http://localhost:3000/health
   

3. 接続プールの設定を最適化する：

   DORIS_MAX_CONNECTIONS=20
   

Q：at_eof 接続エラーを解決するにはどうすればよいですか？（v0.5.0 で完全に修正済み）

A： バージョン 0.5.0 では、接続プールの全面的な再設計により、重大な at_eof 接続エラーを完全に解決しました。

問題：

• 接続プールの事前作成と不適切な接続状態管理により、at_eof エラーが発生していました
• 接続のライフサイクル中に、MySQL aiomysql リーダーの状態に不整合が生じていました
• 同時負荷がかかると、接続プールが不安定になっていました

解決策（v0.5.0）：

1. 接続プール戦略の全面的な見直し：

   • 最小接続数をゼロに設定：事前作成に関する問題を防ぐため、min_connections のデフォルト値を 0 に変更しました
   • オンデマンドで接続を作成：必要なときにのみ接続を作成し、古い接続に関する問題を解消します
   • 新規接続戦略：プールから常に新しい接続を取得し、セッションレベルでのキャッシュは行いません

2. ヘルスモニタリングの強化：

   • タイムアウトベースのヘルスチェック：接続検証クエリに 3 秒のタイムアウトを設定します
   • バックグラウンドヘルスモニター：30 秒ごとにプールのヘルス状態を継続的に監視します
   • 古い接続の事前検出：問題のある接続を自動的に検出してクリーンアップします

3. インテリジェントな復旧システム：

   • プールの自動復旧：包括的なエラー処理を備えた自己修復型プールです
   • 指数バックオフによる再試行：最大 3 回まで試行するスマートな再試行メカニズムです
   • 接続固有のエラー検出：接続関連のエラーを正確に特定します

4. パフォーマンスの最適化：

   • プールのウォームアップ：最適なパフォーマンスを実現するため、接続プールをインテリジェントにウォームアップします
   • バックグラウンドクリーンアップ：アクティブな処理に影響を与えずに、古い接続を定期的にクリーンアップします
   • 接続診断：接続のヘルス状態をリアルタイムで監視し、報告します

接続のヘルス状態を監視する：

# Monitor connection pool health in real-time
tail -f logs/doris_mcp_server_info.log | grep -E "(pool|connection|at_eof)"

# Check detailed connection diagnostics
tail -f logs/doris_mcp_server_debug.log | grep "connection health"

# View connection pool metrics
curl http://localhost:8000/health  # If running in HTTP mode

最適な接続パフォーマンスのための設定：

# Recommended connection pool settings in .env
DORIS_MAX_CONNECTIONS=20          # Adjust based on workload
CONNECTION_TIMEOUT=30             # Connection establishment timeout
QUERY_TIMEOUT=60                  # Query execution timeout

# Health monitoring settings
HEALTH_CHECK_INTERVAL=60          # Pool health check frequency

結果：at_eof エラーを 99.9％解消し、接続の安定性とパフォーマンスを大幅に向上させました。

Q：MCP ライブラリのバージョン互換性の問題を解決するには？（v0.4.2 で修正）

A： バージョン 0.4.2 では、MCP 1.8.x と 1.9.x の両方をサポートする、インテリジェントな MCP 互換性レイヤーが導入されました。

問題：

• MCP 1.9.3 で RequestContext クラスに互換性を損なう変更が導入されました（ジェネリックパラメーターが 2 個から 3 個に変更）
• その結果、TypeError: Too few arguments for RequestContext エラーが発生しました

解決策（v0.4.2）：

• インテリジェントなバージョン検出：インストールされている MCP のバージョンを自動的に検出します
• 互換性レイヤー：バージョン間の API の違いを適切に処理します
• 柔軟なバージョンサポート：依存関係に mcp>=1.8.0,<2.0.0 を指定します

サポート対象の MCP バージョン：

# Both versions now work seamlessly
pip install mcp==1.8.0  # Stable version (recommended)
pip install mcp==1.9.3  # Latest version with new features

バージョン情報：

# Check which MCP version is being used
doris-mcp-server --transport stdio
# The server will log: "Using MCP version: x.x.x"

MCP 関連の起動エラーが発生した場合：

# Recommended: Use stable version
pip uninstall mcp
pip install mcp==1.8.0

# Or upgrade to latest compatible version
pip install --upgrade doris-mcp-server==0.5.0

Q：ADBC の高性能機能を有効にするには？（v0.5.0 で新規追加）

A： ADBC（Arrow Flight SQL）は、大規模なデータセットで 3～10 倍のパフォーマンス向上を実現します。

1. ADBC の依存関係（v0.5.0 以降では自動的に含まれます）：

   # ADBC dependencies are now included by default in doris-mcp-server>=0.5.0
   # No separate installation required
   

2. Arrow Flight SQL のポートを設定する：

   # Add to your .env file
   FE_ARROW_FLIGHT_SQL_PORT=8096
   BE_ARROW_FLIGHT_SQL_PORT=8097
   

3. ADBC のオプションのカスタマイズ：

   # Customize ADBC behavior (optional)
   ADBC_DEFAULT_MAX_ROWS=200000
   ADBC_DEFAULT_TIMEOUT=120
   ADBC_DEFAULT_RETURN_FORMAT=pandas  # arrow/pandas/dict
   

4. ADBC 接続をテストする：

   # Use get_adbc_connection_info tool to verify setup
   # Should show "status": "ready" and port connectivity
   

Q：新しいデータ分析ツールを使用するには？（v0.5.0 で新規追加）

A： 7 つの新しい分析ツールにより、包括的なデータガバナンス機能を利用できます。

データ品質分析：

{
  "tool_name": "analyze_data_quality",
  "arguments": {
    "table_name": "customer_data",
    "analysis_scope": "comprehensive",
    "sample_size": 100000
  }
}

カラムリネージの追跡：

{
  "tool_name": "trace_column_lineage", 
  "arguments": {
    "target_columns": ["users.email", "orders.customer_id"],
    "analysis_depth": 3
  }
}

データ鮮度の監視：

{
  "tool_name": "monitor_data_freshness",
  "arguments": {
    "freshness_threshold_hours": 24,
    "include_update_patterns": true
  }
}

パフォーマンス分析：

{
  "tool_name": "analyze_slow_queries_topn",
  "arguments": {
    "days": 7,
    "top_n": 20,
    "include_patterns": true
  }
}

Q：強化されたロギングシステムを使用するには？（v0.5.0 で改善）

A： バージョン 0.5.0 では、自動管理とレベル別の整理に対応した包括的なロギングシステムが導入されました。

ログファイルの構成（v0.5.0 で新規追加）：

logs/
├── doris_mcp_server_debug.log      # DEBUG level messages
├── doris_mcp_server_info.log       # INFO level messages  
├── doris_mcp_server_warning.log    # WARNING level messages
├── doris_mcp_server_error.log      # ERROR level messages
├── doris_mcp_server_critical.log   # CRITICAL level messages
├── doris_mcp_server_all.log        # Combined log (all levels)
└── doris_mcp_server_audit.log      # Audit trail (separate)

強化されたロギング機能：

1. レベル別のファイル分割：ログレベルごとに自動で整理するため、トラブルシューティングが容易になります
2. タイムスタンプ付きの書式設定：適切に整列されたミリ秒精度のタイムスタンプにより、プロフェッショナルなログを実現します
3. 自動ログローテーション：設定可能なファイルサイズ上限により、ディスク容量の問題を防ぎます
4. バックグラウンドクリーンアップ：設定可能な保持ポリシーを備えた、インテリジェントなクリーンアップスケジューラー
5. 監査証跡：コンプライアンスとセキュリティ監視のための個別の監査ログ

ログの表示：

# View real-time logs by level
tail -f logs/doris_mcp_server_info.log     # General operational info
tail -f logs/doris_mcp_server_error.log    # Error tracking
tail -f logs/doris_mcp_server_debug.log    # Detailed debugging

# View all activity in combined log
tail -f logs/doris_mcp_server_all.log

# Monitor specific operations
tail -f logs/doris_mcp_server_info.log | grep -E "(query|connection|tool)"

# View audit trail
tail -f logs/doris_mcp_server_audit.log

設定：

# Enhanced logging configuration in .env
LOG_LEVEL=INFO                         # Base log level
ENABLE_AUDIT=true                      # Enable audit logging
ENABLE_LOG_CLEANUP=true                # Enable automatic cleanup
LOG_MAX_AGE_DAYS=30                    # Keep logs for 30 days
LOG_CLEANUP_INTERVAL_HOURS=24          # Check for cleanup daily

# Advanced settings
LOG_FILE_PATH=logs                     # Log directory (auto-organized)

強化されたログを使用したトラブルシューティング：

# Debug connection issues
grep -E "(connection|pool|at_eof)" logs/doris_mcp_server_error.log

# Monitor tool performance
grep "execution_time" logs/doris_mcp_server_info.log

# Check system health
tail -20 logs/doris_mcp_server_warning.log

# View recent critical issues
cat logs/doris_mcp_server_critical.log

ログクリーンアップの管理：

• 自動：バックグラウンドスケジューラーが LOG_MAX_AGE_DAYS より古いファイルを削除します
• 手動：ログは 10MB に達すると自動的にローテーションされます
• バックアップ：各ログレベルにつき 5 個のバックアップファイルを保持します
• パフォーマンス：サーバーのパフォーマンスへの影響は最小限です

Q：新しいトークンバインド型データベース設定を使用するには？（v0.6.0 で新規追加）

A： 革新的なトークンバインド型データベース設定では、各トークンに独自のデータベース接続パラメーターを持たせ、安全なマルチテナントアクセスを実現できます。

1. トークン認証を有効にする：

   # In your .env file
   ENABLE_TOKEN_AUTH=true
   TOKEN_HOT_RELOAD=true
   TOKEN_FILE_PATH=tokens.json
   

2. tokens.json の設定を作成する：

   {
     "version": "1.0",
     "tokens": [
       {
         "token_id": "tenant-alpha",
         "token": "tenant_alpha_secure_token_123",
         "description": "Tenant Alpha database access",
         "expires_hours": null,
         "is_active": true,
         "database_config": {
           "host": "tenant-alpha-db.company.com",
           "port": 9030,
           "user": "alpha_user",
           "password": "secure_password",
           "database": "alpha_analytics",
           "charset": "UTF8"
         }
       }
     ]
   }
   

3. 設定の優先順位（v0.6.0 で新規追加）：

   • トークンバインド型 DB 設定（最優先）
   • 環境変数（.env）
   • どちらも利用できない場合はエラー

4. ホットリロードのメリット：

   • サービスを再起動せずに新しいテナントを追加できます
   • データベースの認証情報をリアルタイムで更新できます
   • エラー時に自動で検証とロールバックを行います
   • 変更の完全な監査証跡を記録します

5. マルチテナントでの使用方法：

   # Different tokens access different databases automatically
   curl -H "Authorization: Bearer tenant_alpha_secure_token_123" http://localhost:3000/mcp
   curl -H "Authorization: Bearer tenant_beta_secure_token_456" http://localhost:3000/mcp
   

Q: ホットリロードはどのように機能し、安全ですか？（v0.6.0で追加）

A: ホットリロードシステムは、包括的な安全対策を備え、エンタープライズの本番環境向けに設計されています。

仕組み：

• ファイル監視：10秒ごとにtokens.jsonを確認し、変更を検出します
• 即時検証：新しいトークンを検証し、データベース接続も確認します
• アトミックな更新：すべてを適用するか、何も適用しない構成更新を行います
• ロールバック保護：トークンの検証に失敗した場合、自動的にロールバックします

安全機能：

• バックアップと復元：変更前に現在の構成をバックアップします
• 接続テスト：変更の適用前にデータベース接続をテストします
• エラーの分離：無効なトークンが、既存の有効なトークンに影響しません
• 監査ログ：すべての構成変更を完全に記録します

ベストプラクティス：

# Monitor hot reload activity
tail -f logs/doris_mcp_server_info.log | grep "hot reload"

# Test configuration before applying
cp tokens.json tokens.json.backup
# Make changes to tokens.json
# System will automatically validate and apply or rollback

Q: トークンのライフサイクルとセキュリティを管理するには？（v0.6.0で追加）

A: トークン管理には、安全なファイルベースの方式を使用します。また、包括的なセキュリティ制御を備えた管理用エンドポイントを任意で利用できます。

主なトークン管理方法（推奨）：

# 1. Edit tokens.json file directly (safest method)
nano tokens.json

# 2. Hot reload will automatically detect changes
# No server restart required - changes applied within 10 seconds

# 3. Monitor hot reload in logs
tail -f logs/doris_mcp_server_info.log | grep "hot reload"

管理用エンドポイント（安全、ローカルアクセスのみ）：

🛡️ セキュリティ：これらのエンドポイントは包括的なセキュリティ制御で保護されており、デフォルトでは無効になっています。

# Security Requirements (ALL must be met):
# ✓ HTTP token management explicitly enabled in configuration
# ✓ Access only from localhost (127.0.0.1/::1) - IP restrictions enforced
# ✓ Valid admin authentication token required
# ✓ Admin authentication enabled in configuration

# Enable HTTP token management (disabled by default)
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export TOKEN_MANAGEMENT_ADMIN_TOKEN=your_secure_admin_token
export REQUIRE_ADMIN_AUTH=true
export TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1

# Access with proper authentication
curl -H "Authorization: Bearer your_secure_admin_token" http://127.0.0.1:3000/token/stats

# Demo page (local access only, with authentication)
# Access: http://127.0.0.1:3000/token/demo

推奨されるトークン管理ワークフロー：

1. 開発／テスト：

   // tokens.json
   {
     "version": "1.0",
     "tokens": [
       {
         "token_id": "dev-token",
         "token": "dev_secure_token_123",
         "description": "Development environment access",
         "expires_hours": 24,
         "is_active": true
       }
     ]
   }
   

2. 本番環境へのデプロイ：

   # Use secure token generation
   openssl rand -hex 32  # Generate secure token
   
   # Store in secure configuration management
   # Never commit tokens to version control
   # Use environment variables for sensitive tokens
   

セキュリティ機能：

• ファイルベースの管理：保護された構成ファイルを使用した管理が基本です
• ホットリロード：サービスを中断せずに構成を自動更新します
• トークンのハッシュ化：トークンは内部でSHA-256ハッシュとして保存されます
• 監査証跡：すべてのトークン操作と変更を完全に記録します
• 有効期限の管理：期限切れのトークンを自動的に削除します
• ローカル管理者のみ：管理用エンドポイントへのアクセスをlocalhostに制限します
• 構成の検証：トークンとデータベースの構成を即時に検証します

セキュリティのベストプラクティス：

• トークンは必ず安全な構成ファイルを通じて管理してください
• トークン管理エンドポイントを外部ネットワークに公開しないでください
• 本番環境では、強力なランダム生成トークンを使用してください
• tokens.jsonに適切なファイル権限（600または640）を設定してください
• 有効なトークンとその使用パターンを定期的に監査してください
• 不正な構成変更がないか、ホットリロードのログを監視してください

その他の問題については、GitHub Issuesをご確認いただくか、新しいイシューを作成してください。