MCPサーバ - DBHubのソースを表示

== 概要 ==
DBHub (bytebase/dbhub) は、Model Context Protocol (MCP) を通じてAIアシスタントがデータベースと対話するための標準化されたインターフェースを提供するサーバである。<br>
Bytebaseが開発しており、MITライセンスの下でTypeScriptで実装されている。<br>
<br>
MCPとは、AIアシスタントが外部ツールやデータソースと通信するためのオープンプロトコルであり、DBHubはAIとデータベースをシームレスに統合する役割を担う。<br>
<br>
対応するデータベースは、PostgreSQL、MySQL、MariaDB、SQL Server、SQLiteである。<br>
Claude Desktop、Claude Code、OpenCode、Cursor、VS Code等の主要なMCPクライアント環境で動作する。<br>
<br>
主な特徴は以下の通りである。<br>
* ゼロ依存の設計で、Node.jsの <code>npx</code> またはDockerで即座に実行可能
* トークン効率的な設計により、AIとのやり取りを最適化
* <code>execute_sql</code> と <code>search_objects</code> の2つの組み込みMCPツールを提供
* SSHトンネリングによるリモートデータベースへのセキュアなアクセスに対応
* SSL/TLS接続に対応
* 読み取り専用モードによるデータ保護が可能
* TOML設定ファイルによるカスタムツールの定義が可能
* Windows、MacOS、Linuxの主要なOSで動作
<br><br>

== DBHubの機能 ==
DBHubは、SQLクエリ実行とスキーマ探索の2つの組み込みMCPツールに加え、カスタムツールの定義機能を提供する。<br>
<br>
==== execute_sql ====
<u>execute_sql</u> は、SQLクエリを実行するためのツールである。<br>
セミコロン区切りで複数のSQLステートメントを1度に実行することも可能である。<br>
<br>
<center>
{| class="wikitable"
|+ execute_sql ツールのパラメータ
! パラメータ !! 型 !! 説明
|-
| <code>sql</code> || 文字列 || 実行するSQLクエリ<br>セミコロン区切りで複数ステートメントの実行も可能
|-
| <code>source</code> || 文字列 || TOML設定ファイルで定義したデータベース接続のソースID
|}
</center>
<br>
==== search_objects ====
<u>search_objects</u> は、データベースのスキーマ情報を探索するためのツールである。<br>
テーブル、カラム、インデックス等のデータベースオブジェクトを検索・一覧表示することができる。<br>
<br>
<center>
{| class="wikitable"
|+ search_objects ツールのパラメータ
! パラメータ !! 型 !! 説明
|-
| <code>object_type</code> || 文字列 (必須) || 検索対象<br>指定可能な値は、<code>schema</code>、<code>table</code>、<code>column</code>、<code>procedure</code>、<code>index</code>
|-
| <code>pattern</code> || 文字列 || SQL LIKE構文でのフィルタパターン<br>デフォルト: <code>%</code>
|-
| <code>schema</code> || 文字列 || フィルタリングするスキーマ名
|-
| <code>detail_level</code> || 文字列 || 詳細度レベル<br>指定可能な値は、<code>names</code>、<code>summary</code>、<code>full</code>
|-
| <code>limit</code> || 数値 || 最大結果数<br>デフォルト: 100<br>最大: 1000
|}
</center>
<br>
==== カスタムツール ====
<u>dbhub.toml設定ファイル</u> を使用することにより、パラメータ付きのSQLテンプレートをカスタムツールとして定義できる。<br>
これにより、繰り返し使用するクエリをMCPツールとして登録し、AIアシスタントから呼び出すことが可能になる。<br>
<br>
カスタムツールの設定例を以下に示す。<br>
<br>
 <syntaxhighlight lang="toml">
 [[tools]]
 name = "search_users"
 source = "mydb"
 description = "Search for users by name or email"
 statement = "SELECT id, name, email FROM users WHERE name LIKE {{pattern}} LIMIT {{limit}}"
 
 [[tools.parameters]]
 name = "pattern"
 type = "string"
 description = "Search pattern (use % for wildcard)"
 required = true
 
 [[tools.parameters]]
 name = "limit"
 type = "integer"
 description = "Maximum number of results"
 required = false
 default = 100
 </syntaxhighlight>
<br><br>

== 動作要件 ==
==== 共通の要件 ====
OS問わず共通して必要な要件を以下に示す。<br>
<br>
* Node.js環境 (npxコマンドの実行に必要) または Docker
*: npxを使用する場合は、Node.js LTS版のインストールが必要
* 対応するデータベースサーバへのネットワークアクセス
*: ローカルまたはリモートのデータベースサーバに接続可能な環境が必要
<br>
==== 対応データベース ====
DBHubが対応するデータベースとDSN形式を以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ 対応データベースとDSN形式
! データベース !! DSN形式 !! デフォルトポート
|-
| PostgreSQL || <u>postgres://user:password@host:port/dbname?sslmode=disable</u> || 5432
|-
| MySQL || <u>mysql://user:password@host:port/dbname</u> || 3306
|-
| MariaDB || <u>mysql://user:password@host:port/dbname</u> || 3306
|-
| SQL Server || <u>sqlserver://user:password@host:port;database=dbname</u> || 1433
|-
| SQLite || <u>sqlite:///path/to/database.db</u> || -
|}
</center>
<br><br>

== インストール ==
==== npxによる実行 ====
<code>npx</code> コマンドを使用することにより、インストール不要で直接DBHubを実行できる。<br>
<br>
PostgreSQLへの接続例を以下に示す。<br>
<br>
 npx @bytebase/dbhub@latest --dsn "postgres://<ユーザ名>:<パスワード>@<ホスト名 または IPアドレス  例: localhost>:5432/mydb?sslmode=disable"
<br>
==== Dockerによる実行 ====
Dockerコンテナを使用してDBHubを実行することも可能である。<br>
<br>
Dockerコンテナからホストマシンのデータベースにアクセスするには、<u>localhost</u> の代わりに <u>host.docker.internal</u> を使用する。<br>
<br>
 docker run --rm --init --name dbhub                       \
                        --publish 8080:8080 bytebase/dbhub \
                        --transport http                   \
                        --port 8080                        \
                        --dsn "postgres://<ユーザ名>:<パスワード>@host.docker.internal:5432/mydb?sslmode=disable"
<br>
==== デモモード ====
<code>--demo</code> オプションを使用することで、サンプルの従業員データベースを自動起動してDBHubの機能を試すことができる。<br>
<br>
 npx @bytebase/dbhub@latest --demo
<br><br>

== 設定 ==
==== 設定ファイルの場所 ====
各MCPクライアントの設定ファイルの場所は以下の通りである。<br>
<br>
Claude Desktopの設定ファイルを以下に示す。<br>
* Linux
*: <u>~/.config/Claude/claude_desktop_config.json</u>
* MacOS
*: <u>~/Library/Application Support/Claude/claude_desktop_config.json</u>
* Windows
*: <u>%APPDATA%\Claude\claude_desktop_config.json</u>
<br>
Claude Codeの設定ファイルを以下に示す。<br>
* Linux
*: <u>~/.config/claude/settings.json</u>
* MacOS
*: <u>~/Library/Application Support/claude/settings.json</u>
* Windows
*: <u>%APPDATA%\claude\settings.json</u>
<br>
OpenCodeの設定ファイルを以下に示す。<br>
* Linux / MacOS / Windows (共通)
*: <u>$HOME/.opencode.json</u>
<br>
==== Claude Desktopでの設定 ====
Claude Desktopの設定ファイルに以下の内容を追記する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "mcpServers": {
     "dbhub": {
       "command": "npx",
       "args": [
         "-y",
         "@bytebase/dbhub@latest",
         "--transport",
         "stdio",
         "--dsn",
         "postgres://user:password@localhost:5432/mydb?sslmode=disable"
       ]
     }
   }
 }
 </syntaxhighlight>
<br>
設定ファイルを保存した後、Claude Desktopを再起動して設定を反映する。<br>
<br>
==== Claude Codeでの設定 ====
Claude Codeでは、<code>claude mcp add</code> コマンドを使用してMCPサーバを追加できる。<br>
<br>
 claude mcp add dbhub -- npx -y @bytebase/dbhub@latest \
                      --transport stdio                \
                      --dsn "postgres://<ユーザ名>:<パスワード>@localhost:5432/mydb?sslmode=disable"
<br>
設定ファイルを使用する場合は、以下の内容を <code>settings.jsonファイル</code> に追記する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "mcpServers": {
     "dbhub": {
       "command": "npx",
       "args": [
         "-y",
         "@bytebase/dbhub@latest",
         "--transport",
         "stdio",
         "--dsn",
         "postgres://user:password@localhost:5432/mydb?sslmode=disable"
       ]
     }
   }
 }
 </syntaxhighlight>
<br>
==== OpenCodeでの設定 ====
OpenCodeの設定ファイル (<u>~/.opencode.jsonファイル</u>) に以下の内容を追記する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "mcpServers": {
     "dbhub": {
       "type": "stdio",
       "command": "npx",
       "args": [
         "-y",
         "@bytebase/dbhub@latest",
         "--transport",
         "stdio",
         "--dsn",
         "postgres://user:password@localhost:5432/mydb?sslmode=disable"
       ]
     }
   }
 }
 </syntaxhighlight>
<br>
==== コマンドラインオプション ====
下表に、DBHubで使用可能なコマンドラインオプションの一覧を示す。<br>
<br>
<center>
{| class="wikitable"
|+ コマンドラインオプション一覧
! オプション !! 説明
|-
| <code>--transport</code> || 通信プロトコル<br><code>stdio</code> または <code>http</code> を指定する<br><br>デフォルト: <code>stdio</code>
|-
| <code>--port</code> || HTTPサーバのポート番号 (httpトランスポート使用時)<br><br>デフォルト: 8080
|-
| <code>--dsn</code> || データベース接続文字列
|-
| <code>--config</code> || TOML設定ファイルのパス<br><br>デフォルト: <code>./dbhub.toml</code>
|-
| <code>--id</code> || インスタンスID (複数インスタンス実行時の識別子)<br><br>デフォルト: <code>default</code>
|-
| <code>--demo</code> || デモモードの有効化 (サンプルデータベースを自動起動)
|-
| <code>--ssh-host</code> || SSHトンネル先ホスト名
|-
| <code>--ssh-user</code> || SSHユーザ名
|-
| <code>--ssh-key</code> || SSHキーファイルパス<br><br>デフォルト: <code>~/.ssh/id_rsa</code>
|-
| <code>--ssh-passphrase</code> || SSHキーのパスフレーズ
|-
| <code>--ssh-proxy-jump</code> || SSHプロキシジャンプ設定 (踏み台経由接続)
|}
</center>
<br>
<code>--config</code> を使用する場合、<code>--dsn</code> と <code>--id</code> オプションの同時指定はできない。<br>
<br>
==== dbhub.toml設定ファイル ====
TOML形式の設定ファイルを使用することで、複数のデータベース接続やカスタムツールを定義できる。<br>
<br>
* 単一データベースに対する基本的な設定例 (読み取り専用)
*: <syntaxhighlight lang="toml">
 [[sources]]
 id = "mydb"
 dsn = "postgres://user:password@localhost:5432/mydb"
 
 [[tools]]
 name = "execute_sql"
 source = "mydb"
 readonly = true
 max_rows = 1000
 
 [[tools]]
 name = "search_objects"
 source = "mydb"
 </syntaxhighlight>
*: <br>
* 複数データベースを使用する場合の設定例
*: <syntaxhighlight lang="toml">
 [[sources]]
 id = "postgres_db"
 dsn = "postgres://user:password@db.example.com:5432/production"
 connection_timeout = 30
 query_timeout = 60
 sslmode = "require"
 
 [[sources]]
 id = "mysql_db"
 dsn = "mysql://user:password@analytics.example.com:3306/analytics"
 
 [[tools]]
 name = "execute_sql"
 source = "postgres_db"
 readonly = true
 max_rows = 5000
 
 [[tools]]
 name = "search_objects"
 source = "mysql_db"
 </syntaxhighlight>
<br>
==== SSHトンネリング ====
SSHトンネリングを使用することで、踏み台サーバ経由でリモートデータベースにセキュアに接続できる。<br>
<br>
* コマンドラインでのSSH接続設定例
*: <syntaxhighlight lang="text">
 npx @bytebase/dbhub@latest --transport stdio \
    --dsn "postgres://user:password@localhost:5432/mydb" \
    --ssh-host "jump.example.com" \
    --ssh-user "sshuser" \
    --ssh-key "/home/user/.ssh/id_rsa"
 </syntaxhighlight>
*: <br>
* TOML設定ファイルでSSHトンネリングを設定する場合
*: <syntaxhighlight lang="toml">
 [[sources]]
 id = "remote_db"
 dsn = "postgres://user:password@localhost:5432/mydb"
 ssh_host = "jump.example.com"
 ssh_user = "sshuser"
 ssh_key = "/home/user/.ssh/id_rsa"
 </syntaxhighlight>
<br><br>

== 使用方法 ==
DBHubの各ツールは、AIアシスタントが自然言語の指示を受けて自動的に呼び出す。<br>
<br>
==== SQLクエリの実行例 ====
SQLクエリの実行に関する操作例を以下に示す。<br>
<br>
* データベースのテーブル一覧を取得する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 データベース内のテーブル一覧を表示してください。
 </syntaxhighlight>
*: <br>
* 特定のテーブルからデータを取得する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 usersテーブルの全データを取得してください。
 </syntaxhighlight>
*: <br>
* 条件を指定してクエリを実行する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 ordersテーブルからステータスが「completed」のレコードを取得してください。
 </syntaxhighlight>
<br>
==== スキーマ探索の例 ====
スキーマ情報の取得に関する操作例を以下に示す。<br>
<br>
* テーブル構造を確認する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 usersテーブルのカラム定義を教えてください。
 </syntaxhighlight>
*: <br>
* データベース内のテーブルを検索する場合
*: <syntaxhighlight lang="text">
 # プロンプト例 :
 
 名前に「user」を含むテーブルを検索してください。
 </syntaxhighlight>
<br><br>

== トラブルシューティング ==
==== 共通の問題 ====
OS問わず発生する可能性がある問題と対処法を以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ 共通トラブルシューティング
! 問題 !! 対処法
|-
| npxコマンドが動作しない || Node.js LTS版がインストールされているか確認する。<br><code>npm cache clean --force</code> を実行してキャッシュをクリアする。
|-
| データベース接続エラー || DSN文字列が正しいか確認する。<br>データベースサーバが起動しているか確認する。<br>ファイアウォール設定を確認する。
|-
| ポート競合 (httpトランスポート使用時) || <code>--port</code> オプションで別のポート番号を指定する。<br>使用中のポートを <code>lsof -i :8080</code> 等で確認する。
|-
| SSHトンネリングの接続エラー || SSHキーのパスと権限を確認する。<br>SSHホストへのアクセスが可能か確認する。
|-
| Permission deniedエラー || データベースユーザの権限を確認する。<br>SSHキーファイルの権限 (600) を確認する。
|}
</center>
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,Electric Circuit,Electric,pcb,Mathematics,AVR,TI,STMicro,AVR,ATmega,MSP430,STM,Arduino,Xilinx,FPGA,Verilog,HDL,PinePhone,Pine Phone,Raspberry,Raspberry Pi,C,C++,C#,Qt,Qml,MFC,Shell,Bash,Zsh,Fish,SUSE,SLE,Suse Enterprise,Suse Linux,openSUSE,open SUSE,Leap,Linux,uCLnux,電気回路,電子回路,基板,プリント基板,DBHub,Bytebase,MCP,Model Context Protocol,MCPサーバ,Claude,AI,データベース,SQL,PostgreSQL,MySQL,MariaDB,SQLite,SQL Server,Node.js
|description={{PAGENAME}} - 電子回路とSUSE Linuxに関する情報 | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:設定]]