KWDB MCP Server

KWDB MCP サーバー

中文版

概要

KWDB MCP サーバーは、MCP（Model Context Protocol）プロトコルに基づくサーバー実装です。KWDB データベースを操作するためのツールとリソースを提供し、MCP プロトコルを通じてビジネスインテリジェンス機能を提供します。KWDB MCP サーバーは、データの読み取り、書き込み、クエリ、変更、および DDL 操作に対応しています。

アーキテクチャ

KWDB MCP サーバーの中核となるプロセスは、次のコンポーネントで構成されています。

• MCP プロトコルの解析：MCP StdIO または HTTP SSE リクエストを処理します。
• MCP ツールのスケジュール：MCP ツールの種類に基づいて API リクエストを振り分けます。
• クエリの準備：LIMIT 句のない SQL クエリに LIMIT 20 句を自動的に追加します。
• クエリ結果の整形：すべての API レスポンスに一貫性のある JSON 形式を採用します。

機能

• 読み取り操作：SELECT、SHOW、EXPLAIN などの読み取り専用クエリを実行します。
• 書き込み操作：INSERT、UPDATE、DELETE、および CREATE、DROP、ALTER の DDL 操作を実行します。
• データベース情報：テーブルやそのスキーマなど、データベースに関する情報を取得します。
• 検査ツール：query-metrics（管理用 /restapi/ts/query エンドポイントに対する、固定カタログの 32 個の実行時メトリクス）と query-slow-sql（kwdb_internal.node_statement_statistics に対する SELECT による、実行時間が長い SQL 文の上位 N 件）は、どちらも既存の DB URL から認証情報を取得し、TLS と安全でない KaiwuDB デプロイの両方に対応します。
• 構文ガイド：プロンプトを通じて、KWDB の包括的な構文ガイドを参照できます。
• 標準 API レスポンス：一貫性のあるエラー処理の仕組みを提供します。
  • ツールのエラー：エラー情報は isError フラグを含む結果オブジェクトに格納されます。

  {
    "content": [{"type": "text", "text": "Query error: error details"}],
    "isError": true
  }
  

  • リソースのエラー：標準の JSON-RPC エラーレスポンスを直接返します。

  {
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
      "code": -32002,  // RESOURCE_NOT_FOUND: リソースが存在しません
      "message": "handler not found for resource URI 'kwdb://table/nonexistent': resource not found"
    }
  }
  

  または、内部処理エラーの場合：

  {
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
      "code": -32603,  // INTERNAL_ERROR: 内部リソース処理エラー
      "message": "failed to get table schema for 'tablename': database connection error"
    }
  }
  

  • 成功レスポンス：ツールは結果オブジェクトを返し、リソースはコンテンツ配列を返します。
• LIMIT の自動追加：LIMIT 句のない SELECT クエリに LIMIT 20 句を自動的に追加し、大きな結果セットを防ぎます。

セキュリティ

KWDB MCP サーバーは、次のセキュリティ対策を提供します。

• 読み取り操作と書き込み操作に、それぞれ別のツールを用意します。
• クエリを検証し、想定される操作の種類と一致することを確認します。
• 許可されていない操作について、明確なエラーメッセージを出力します。

MCP リソース

MCP リソースを使用すると、KWDB MCP サーバーが、MCP クライアントから読み取ることができ、LLM とのやり取りのコンテキストとして使用できるデータやコンテンツを公開できます。KWDB MCP サーバーでは、次の MCP リソースを利用できます。

リソース	URI 形式	説明	例
製品情報	kwdb://product_info	バージョンやサポートされている機能などの製品情報	kwdb://product_info/
データベースメタデータ	kwdb://db_info/{database_name}	エンジンの種類、コメント、テーブルなど、特定のデータベースに関する情報	kwdb://db_info/db_shig
テーブルスキーマ	kwdb://table/{table_name}	列やクエリの例など、特定のテーブルのスキーマ	kwdb://table/user_profile

MCP ツール

MCP ツールを使用すると、KWDB MCP サーバーが実行可能な機能を MCP クライアントに公開できます。MCP ツールを通じて、LLM は外部システムとやり取りできます。KWDB MCP サーバーでは、次の MCP ツールを利用できます。

read-query

KWDB MCP サーバーは、データベースからデータを読み取るために、SELECT、SHOW、EXPLAIN 文およびその他の読み取り専用クエリを実行します。read_query 関数は、SQL 文のクエリ結果を配列形式で返します。また、大きな結果セットを防ぐため、KWDB MCP サーバーは LIMIT 句のない SELECT クエリに LIMIT 20 句を自動的に追加します。

例：

-- Query table data.
SELECT * FROM users LIMIT 10;

-- List all created tables.
SHOW TABLES;

-- Execute a SQL query and generate details about the SQL query.
EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 1;

write-query

KWDB MCP サーバーは、DML および DDL 操作を含むデータ変更クエリを実行します。

例：

-- Insert data into the table.
INSERT INTO users (name, email) VALUES ('John Doe', '[email protected]');

-- Update data in the table.
UPDATE users SET email = '[email protected]' WHERE id = 1;

-- Remove data from the table.
DELETE FROM users WHERE id = 1;

-- Create a table.
CREATE TABLE products (id SERIAL PRIMARY KEY, name TEXT, price DECIMAL);

-- Add a column to a table.
ALTER TABLE products ADD COLUMN description TEXT;

-- Remove a table.
DROP TABLE products;

query-metrics

KWDB MCP サーバーは、データベース管理者用の /ts/query API を通じて、過去の実行時メトリクスをクエリできます。このツールは、docs/design-tls-inspection-tools.md で定義されている、固定カタログに含まれる32種類の検査メトリクス（QPS、CPU、メモリ、レイテンシ、ストレージ、クラスター、ネットワーク）を受け付けます。各呼び出しでは、metric_names、start_ms、end_ms、sample_ms が必要です。Basic Auth の認証情報は、接続文字列の user:password から取得されます。

32種類のメトリクスカタログは、次のカテゴリに分類されます（すべて derivative: "none"）。

カテゴリ	例
基本	cr.node.liveness.livenodes、cr.node.sys.uptime
システム	cr.node.sys.cpu.user.percent、cr.store.capacity、cr.node.sys.rss
SQL ワークロード	cr.node.sql.query.count、cr.node.exec.latency-p99
ストレージ	cr.store.totalbytes、cr.store.livebytes
クラスター	cr.store.replicas、cr.store.ranges.unavailable
ネットワーク	cr.node.clock-offset.meannanos

例：

{
  "metric_names": ["cr.node.sql.query.count", "cr.node.sys.cpu.user.percent"],
  "start_ms": 1775035140000,
  "end_ms": 1775035740000,
  "sample_ms": 60000
}

成功時のレスポンス（上流の /ts/query は成功時に code: 0 を返します）：

{
  "status": "success",
  "type": "metrics_inspection",
  "data": {
    "code": 0,
    "desc": ""
  },
  "error": null
}

query-slow-sql

KWDB MCP サーバーは、クラスター側のシステムテーブル kwdb_internal.node_statement_statistics に対して SELECT を実行することで、実行時間の長い SQL 文をクエリできます。このツールでは、オプションとして limit（デフォルトは10）、min_latency_ms（デフォルトは0）、sort_by（デフォルトは service_lat。run_lat、plan_lat、count に対応）を指定できます。結果には、クエリテキスト、4つのレイテンシ項目（ミリ秒単位）、実行回数が含まれます。

フィルタリングは、選択した sort_by にかかわらず、常に service_latency_ms に対して実行されます。デフォルトの呼び出しでは、平均サービスレイテンシの降順で、上位10件の文が返されます。

例：

{
  "limit": 10,
  "min_latency_ms": 100,
  "sort_by": "service_lat"
}

成功時のレスポンス（簡潔にするため一部省略）：

{
  "data": [
    {
      "id": "1",
      "fingerprint": "1",
      "query": "SELECT count(_), max(\"timestamp\") FROM [DELETE FROM system.rangelog WHERE ...]",
      "service_latency_ms": 3.805022,
      "run_latency_ms": 0.649384,
      "plan_latency_ms": 1.041746,
      "count": 1
    }
  ],
  "status": "success",
  "type": "slow_sql_inspection"
}

query-metrics と query-slow-sql はどちらも同じ X-Database-URI ヘッダー（またはデフォルトプール）を再利用し、保存済みの認証情報から Basic Auth を取得します。管理者用エンドポイントの URL は、DB URL のホストから自動的に導出されます。TLS エンドポイントでは、KaiwuDB の自己署名証明書の慣例に合わせ、証明書の検証をスキップします。

MCP プロンプト

MCP プロンプトを使用すると、KWDB MCP サーバーで再利用可能なプロンプトテンプレートとワークフローを定義し、MCP クライアントからユーザーや LLM に簡単に提示できます。一般的な LLM とのやり取りを標準化して共有する強力な方法です。KWDB MCP サーバーでは、次の MCP プロンプトを提供しています。

種類	プロンプト名	説明
データベースの説明	db_description	KWDB データベースの包括的な説明です。主な機能、サポートされる機能、ユースケースが含まれます。
構文ガイド	syntax_guide	KWDB の包括的な構文ガイドです。一般的なクエリの例とベストプラクティスが含まれます。
クラスター管理	cluster_management	KWDB クラスター管理の包括的なガイドです。ノード管理、負荷分散、監視が含まれます。
データ移行	data_migration	KWDB との間でデータを移行するためのガイドです。インポート／エクスポートの方法とベストプラクティスが含まれます。
インストール	installation	さまざまな環境で KWDB をインストールし、デプロイするための手順を追ったガイドです。
パフォーマンス調整	performance_tuning	KWDB のパフォーマンスを最適化するためのガイドです。クエリの最適化、インデックス戦略、システムレベルのチューニングが含まれます。
トラブルシューティング	troubleshooting	KWDB でよく発生する問題やエラーを診断し、解決するためのガイドです。
バックアップと復元	backup_restore	KWDB データベースのバックアップと復元に関する包括的なガイドです。戦略、ツール、ベストプラクティスが含まれます。
DBA テンプレート	dba_template	MCP プロンプトの作成に使用するテンプレートとガイドラインです。

MCP プロンプトの追加

MCP プロンプトは、pkg/prompts/docs/ ディレクトリに保存された Markdown ファイルです。これらのファイルは、Go の embed パッケージを使用して KWDB MCP サーバーをコンパイルするときにバイナリに埋め込まれます。現在、KWDB MCP サーバーでは次のプロンプトファイルを提供しています。

• pkg/prompts/docs/ReadExamples.md：読み取りクエリの例（SELECT 文を使用）を含みます。
• pkg/prompts/docs/WriteExamples.md：書き込みクエリの例（INSERT、UPDATE、DELETE、CREATE、ALTER 文を使用）を含みます。
• pkg/prompts/docs/DBDescription.md：データベースの説明を含みます。
• pkg/prompts/docs/SyntaxGuide.md：SQL 構文ガイドを含みます。
• pkg/prompts/docs/ClusterManagementGuide.md：クラスター管理ガイドを含みます。
• pkg/prompts/docs/DataMigrationGuide.md：データ移行ガイドを含みます。
• pkg/prompts/docs/InstallationGuide.md：インストールガイドを含みます。
• pkg/prompts/docs/PerformanceTuningGuide.md：パフォーマンス調整ガイドを含みます。
• pkg/prompts/docs/TroubleShootingGuide.md：トラブルシューティングガイドを含みます。
• pkg/prompts/docs/BackupRestoreGuide.md：バックアップと復元のガイドを含みます。
• pkg/prompts/docs/DBATemplate.md：データベース管理テンプレートを含みます。

MCP プロンプトを追加するには、次の手順に従います。

1. pkg/prompts/docs/ ディレクトリに new_usecase.md などの Markdown ファイルを作成します。
2. pkg/prompts/prompts.go ファイルに変数と読み込みコードを追加します。
3. 新しい MCP プロンプトの登録関数を作成します。
4. pkg/prompts/prompts.go ファイルの registerUseCasePrompts() に登録関数の呼び出しを追加します。
5. README ファイルを更新します。

MCP プロンプトの追加方法について詳しくは、pkg/prompts/prompts.go ファイル内のコメントを参照してください。

MCP プロンプトを変更する

MCP プロンプトを変更するには、次の手順に従ってください。

1. pkg/prompts/docs/ ディレクトリ内の該当する Markdown ファイルを編集します。
2. make build コマンドを実行して、アプリケーションを再ビルドします。更新された MCP プロンプトはバイナリに埋め込まれます。

ソースコードからビルドする

前提条件

• Go 1.23 以降をインストールします。
• PostgreSQL ドライバー lib/pq をダウンロードしてインストールします。
• KWDB をインストールして起動し、認証方式を設定してデータベースを作成します。詳細については、KWDB Documentation Website を参照してください。
• テーブルとデータベースに対する適切な権限を持つユーザーを作成します。詳細については、Create Users を参照してください。

手順

1. リポジトリをクローンします。

   git clone https://gitee.com/kwdb/kwdb-mcp-server
   cd kwdb-mcp-server
   

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

   make deps
   

3. アプリケーションをビルドします。

   make build
   

成功すると、アプリケーションは次の構成になります。

kwdb-mcp-server/
├── bin/
│   └── kwdb-mcp-server      # Binary executable file
├── cmd/
│   └── kwdb-mcp-server/
│       └── main.go           # The main application
├── pkg/
│   ├── db/
│   │   └── db.go             # Database operations
│   ├── prompts/
│   │   ├── prompts.go        # MCP Prompts
│   │   └── docs/             # MCP Prompts files
│   │       ├── ReadExamples.md     # Read query examples
│   │       ├── WriteExamples.md    # Write query examples
│   │       ├── DBDescription.md    # Database descriptions
│   │       ├── SyntaxGuide.md      # SQL Syntax guide
│   │       ├── ClusterManagementGuide.md # Cluster management guide
│   │       ├── DataMigrationGuide.md    # Data migration guide
│   │       ├── InstallationGuide.md      # Installation guide
│   │       ├── PerformanceTuningGuide.md # Performance tunning
│   │       ├── TroubleShootingGuide.md   # Troubleshooting guide
│   │       ├── BackupRestoreGuide.md     # Backup and restore guide
│   │       └── DBATemplate.md            # DBA templates
│   ├── resources/
│   │   └── resources.go      # MCP Resources
│   ├── server/
│   │   └── server.go         # KWDB MCP Server configurations
│   ├── tools/
│   │   └── tools.go          # MCP Tools
│   └── version/
│       └── version.go        # Version information
├── Makefile                  # Commands for building and running the KWDB MCP Server
└── README.md                 # README file

KWDB MCP サーバーを起動する

KWDB MCP Server は、次の 3 つのトランスポートモードをサポートしています。

• StdIO（標準入出力）モード：標準入出力を使って通信します。これがデフォルトのモードです。
• HTTP モード（推奨）：HTTP を使って通信します。本番環境で推奨されるモードです。
• SSE（Server-Sent Events）モード（非推奨）：HTTP POST と SSE を使って通信します。このモードは近日中に非推奨となる予定です。

動作モード

• 単一データベース（互換モード）：オプションの PostgreSQL 接続文字列を最初の引数として（または Makefile の CONNECTION_STRING を通じて）指定してサーバーを起動します。サーバーはデフォルトの接続プールを初期化します。ツール read-query と write-query は、X-Database-URI ヘッダーを指定せずに呼び出すことができ、このデフォルトのプールを使用します。
• ステートレスなマルチテナント：接続文字列を指定せずにサーバーを起動します（例：./bin/kwdb-mcp-server または ./bin/kwdb-mcp-server -t http -p 8080）。サーバーはツールが呼び出されるまで、どのデータベースにも接続しません。すべての read-query と write-query の呼び出しでは、完全な PostgreSQL 接続文字列を含むリクエストヘッダー X-Database-URI を送信する必要があります。送信しない場合、ツールはエラー missing X-Database-URI header を返します。
• 管理エンドポイントの自動導出：検査ツール（query-metrics、query-slow-sql）は、接続文字列のホストから管理エンドポイントの URL（デフォルトポート 8080）を導出し、同じ接続文字列から Basic 認証の認証情報を導出します。個別の管理設定は不要です。接続文字列の sslmode と証明書のパスによって、管理エンドポイントへの接続に http と https のどちらを使用するかが決まります。リクエストごとに導出された管理 URL を上書きするには、X-Admin-Base-URL を送信します。

---

StdIO モード

• KWDB MCP Server を実行します（シングル DB モードでは、接続文字列を任意で指定できます）。

  ./bin/kwdb-mcp-server "postgresql://<username>:<password>@<hostname>:<port>/<database_name>?sslmode=disable"
  

• または、接続文字列を指定せずにステートレスモードで実行します。この場合、各 read-query / write-query 呼び出しで X-Database-URI ヘッダーを送信する必要があります。検査ツール（query-metrics、query-slow-sql）は、この同じ接続文字列から管理エンドポイント URL と Basic Auth を自動的に導出します。導出された URL を上書きするには、X-Admin-Base-URL を送信してください。

  ./bin/kwdb-mcp-server
  

• Makefile を使って KWDB MCP Server を実行します。

  CONNECTION_STRING="postgresql://<username>:<password>@<hostname>:<port>/<database_name>?sslmode=disable" make run
  

パラメーター：

• username：KWDB データベースへの接続に使用するユーザー名です。
• password：認証用のパスワードです。
• hostname：KWDB データベースの IP アドレスです。
• port：KWDB データベースへの接続に使用するポートです。
• database_name：アクセスする KWDB データベースの名前です。
• sslmode：SSL モードです。サポートされている値：disable、allow、prefer、require、verify-ca、verify-full。詳細については、SSL Mode Parametersを参照してください。

---

HTTP モード（推奨）

• KWDB MCP Server を HTTP モードで実行します。

  CONNECTION_STRING="postgresql://<username>:<password>@<hostname>:<port>/<database_name>?sslmode=disable" PORT=8080 make run-http
  

• HTTP サービスはデフォルトで 0.0.0.0:<port> でリッスンし、MCP エンドポイントは http://<host>:<port>/mcp です。接続文字列を指定せずに起動した場合（ステートレスモード）、クライアントは各 read-query / write-query 呼び出しで X-Database-URI リクエストヘッダーを送信する必要があります。

• 検査ツール（query-metrics、query-slow-sql）は、X-Database-URI 接続文字列から Basic Auth と管理エンドポイント URL を導出します。導出された URL を上書きするには、X-Admin-Base-URL を送信してください。

• HTTPS（TLS） は任意です。PEM ファイルのパスを指定して、--tls-cert と --tls-key の両方を渡してください。サーバーは TLS を使用してリッスンし、MCP エンドポイントは https://<host>:<port>/mcp になります。2 つのフラグのうち一方のみを設定すると、プロセスはエラーで終了します。TLS は mcp-go の WithTLSCert で実装されています（mcp-go v0.39+ が必要です）。

  ./bin/kwdb-mcp-server -t http -p 8443 --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem "postgresql://..."
  

パラメーター：

• -t または --transport：トランスポートの種類です。stdio、sse、http をサポートしています。
  • stdio：標準入出力モード
  • sse：SSE モード（非推奨）
  • http：HTTP モード（推奨）
• -p または --port：KWDB MCP Server の待ち受けポートです。デフォルトは 8080 です。
• --tls-cert / --tls-key：任意です。HTTP モードの HTTPS 用 PEM 証明書と秘密鍵です。両方を一緒に設定する必要があります。-t http の場合のみ適用されます。
• username：KWDB データベースへの接続に使用するユーザー名です。
• password：認証用のパスワードです。
• hostname：KWDB データベースの IP アドレスです。
• port：KWDB データベースへの接続に使用するポートです。
• database_name：アクセスする KWDB データベースの名前です。
• sslmode：SSL モードです。サポートされている値：disable、allow、prefer、require、verify-ca、verify-full。詳細については、SSL Mode Parametersを参照してください。

---

SSE モード（非推奨）

注

SSE モードは非推奨であり、今後のリリースで削除される予定です。可能な場合は HTTP モードを使用してください。

• KWDB MCP サーバーを SSE モードで実行します（ステートレスモードの場合は CONNECTION_STRING を省略してください。その場合、クライアントはツールを呼び出すたびに X-Database-URI を送信する必要があります）。

  CONNECTION_STRING="postgresql://<username>:<password>@<hostname>:<port>/<database_name>?sslmode=disable" PORT=8080 make run-sse
  

パラメーター：

• -t または --transport：トランスポートの種類です。stdio、sse、http に対応しています。
  • stdio：標準入出力モード
  • sse：SSE モード（非推奨）
  • http：HTTP モード（推奨）
• -p または --port：KWDB MCP サーバーのリッスンポートです。デフォルトは 8080 です。
• username：KWDB データベースへの接続に使用するユーザー名です。
• password：認証用のパスワードです。
• hostname：KWDB データベースの IP アドレスです。
• port：KWDB データベースへの接続に使用するポートです。
• database_name：アクセスする KWDB データベースの名前です。
• sslmode：SSL モードです。サポートされている値は disable、allow、prefer、require、verify-ca、verify-full です。詳細は、SSL モードのパラメーターを参照してください。

LLM エージェントとの統合

KWDB MCP サーバーと LLM エージェントの統合方法については、LLM エージェントとの統合を参照してください。

トラブルシューティング

KWDB MCP サーバーのトラブルシューティングについては、トラブルシューティングを参照してください。

ドキュメント

KWDB MCP サーバーのドキュメントについては、KWDB ドキュメントサイトを参照してください。

今後の機能強化

• クエリ履歴：クエリ履歴機能を実装します。
• リモートモード：リモート KWDB MCP サーバーへの接続をサポートします。
• 最適化提案の改善：クエリの最適化に関する推奨事項を強化します。
• メトリクスリソース：データベースのメトリクスを追加します。

貢献

貢献を歓迎します！お気軽にイシューやプルリクエストを送信してください。

ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。

謝辞

• mark3labs/mcp-go - MCP Go サーバーフレームワーク
• lib/pq - PostgreSQL Go ドライバー

その他

kwdb-mcp-server は MCP Review に登録され、認定されています。