workbench-mcp

Fedora/Linuxシステム上での対話的なPostgreSQLデータ探索、API統合、および自動化のためのローカルPython MCPサーバー。

概要

バージョン1には以下が含まれます：

• Fedora/Linuxシステム向けのPython仮想環境セットアップ

• .envファイル経由で設定されるPostgreSQL 18接続

• 以下のためのMCPツール：

  • テーブル、カラム、スキーマ構造の発見

  • 読み取り専用クエリプレビューの実行

  • 一時テーブルサポートを備えた保護されたSQLバッチの実行

  • PostgreSQLのストアド関数およびプロシージャの呼び出し

  • 完全なURLリクエストによる外部APIへのアクセス

  • PATH内で利用可能なbashスクリプトの実行

• 安全性の強制：永続的なスキーマおよびデータの変更はブロックされます

• SQLバッチ内でのセッションスコープの一時テーブルワークフローをサポート

Fedora / Linuxのセットアップ

まず、必要なシステムパッケージをインストールします：

sudo dnf install -y python3 python3-pip nodejs npm

Python 3.12以降が必要です。複数のバージョンを管理する場合はpyenvなどを使用してください。

仮想環境のセットアップ

プロジェクトのルートから、Python仮想環境を作成して有効化します：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .

環境変数

設定例をコピーし、PostgreSQLの接続詳細を入力します：

cp .env.example .env

必須：

• DB_HOST — PostgreSQLサーバーのホスト名

• DB_NAME — データベース名

• DB_USER — データベースユーザー名

• DB_PASSWORD — データベースパスワード

任意（チューニング）：

• DB_PORT — 接続ポート（デフォルト: 5432）

• DB_SSLMODE — SSLモード（デフォルト: prefer）

• DB_APPLICATION_NAME — アプリケーション識別子

• DB_QUERY_TIMEOUT_SECONDS — クエリタイムアウト（デフォルト: 30）

• DB_MAX_ROWS — 結果セットあたりの最大行数（デフォルト: 100）

• DB_MAX_RESULT_SETS — バッチあたりの最大結果セット数（デフォルト: 5）

• DB_OBJECT_PREVIEW_CHARS — 定義プレビューの最大長（デフォルト: 4000）

ローカル開発の例：

DB_HOST=localhost
DB_PORT=5432
DB_NAME=app_dev
DB_USER=app_user
DB_PASSWORD=your-secure-password
DB_SSLMODE=prefer

任意：HTTPリクエストのチューニング

HTTPツールは呼び出しごとに完全なURLを受け取り、APIプロファイルの設定は不要です。

サポートされている環境設定：

呼び出しの形状例：

url: https://localhost:44331/api/breakouts/filter/1871161/dd-table?ParameterSetId=231022
method: GET

認証が必要な呼び出しの場合、.env（またはプロセス環境変数）で API_BEARER_TOKEN を設定します。HTTPツールは、呼び出し元が独自の jwt_token を渡さない限り、自動的にこれを使用します。

認証の取り扱い

HTTPツールは2つの認証ソースをサポートしています：

1. ツール呼び出しで渡される jwt_token

2. .env またはプロセス環境からの API_BEARER_TOKEN

優先順位

• jwt_token が提供されている場合、そのトークンが Authorization: Bearer <jwt_token> として転送されます。

• jwt_token が省略されているか空の場合、サーバーは API_BEARER_TOKEN にフォールバックします。

• どちらの値も存在しない場合、リクエストは Authorization ヘッダーなしで送信されます。

エージェントに対する重要なルール

headers.Authorization の中にベアラートークンを配置してはいけません。 MCPサーバーは headers から Authorization を取り除き、専用の jwt_token フィールドを通じた認証のみを受け付けます。

これにより、意図しないヘッダーの衝突を防ぎ、トークンの優先順位を明確にします。

例：デフォルトのサーバートークンを使用する

{
  "url": "https://localhost:5001/api/v1/sales/my-sales"
}

例：呼び出し元自身のトークンを転送する

{
  "url": "https://localhost:5001/api/v1/sales/my-sales",
  "jwt_token": "eyJhbGciOi..."
}

例：追加ヘッダーと共に呼び出し元トークンを転送する

{
  "url": "https://localhost:5001/api/v1/sales/my-sales",
  "jwt_token": "eyJhbGciOi...",
  "headers": {
    "Accept": "application/json"
  }
}

同じ jwt_token フィールドが http_get、http_head、http_post、http_put、http_patch、および http_delete で利用可能です。

セッション認証

呼び出しごとに jwt_token を渡す代わりに、エージェントはセッションスコープのJWTを一度取得し、セッションの残りの期間、すべてのHTTPツール呼び出しで自動的にそれを使用させることができます。

仕組み

1. エージェントが対象ユーザーのメールアドレスを指定して auth_start_session を呼び出します。

2. MCPサーバーは、共有シークレット + メールアドレスをバックエンドブローカー (POST /api/v1/mcp/exchange) からのスコープ付きJWTと交換します。

3. トークンはプロセスメモリにキャッシュされます。

4. jwt_token を省略する以降のすべてのHTTPツール呼び出しは、自動的にセッショントークンを使用します。

5. エージェントは auth_status でセッションを検査し、auth_switch_user でユーザーを切り替え、auth_clear_session でセッションをクリアできます。

トークンの優先順位（高 → 低）

必要な環境変数

セッション認証ツール

エージェント向けの完全なリファレンスについては、docs/SESSION_AUTH.md を参照してください。

ローカルでの実行

仮想環境を有効化し、依存関係をインストールした後、以下のいずれかのコマンドでMCPサーバーを起動します：

workbench-mcp

python -m workbench_mcp.server

MCPインスペクター

ローカルでのMCP開発およびデバッグのために、MCPインスペクターが迅速な手動テストループを提供します：

npx @modelcontextprotocol/inspector .venv/bin/python -m workbench_mcp.server

インスペクターでブレークポイントデバッグを行うために debugpy の下でMCPサーバーを起動するには：

npx @modelcontextprotocol/inspector .venv/bin/python -m debugpy --listen 127.0.0.1:5678 -m workbench_mcp.server

起動後、インスペクターUIを開き、STDIO 経由で接続し、health、describe_object、exec_proc_preview などのツールをテストします。

ブレークポイント (debugpy): デバッガーにはポート 5678 を使用してください。6274ではありません（6274はインスペクターのWeb UI専用です）。ステップバイステップのワークフローと「以前何が問題だったか」については docs/DEBUG_MCP.md に記載されています。

VS Codeのセットアップ

VS CodeにローカルMCPサーバーを登録するには、ワークスペースのMCP設定ファイルにエントリを追加します：

• ワークスペースファイル: .vscode/mcp.json

設定例：

{
  "servers": {
    "workbench-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/workbench-mcp/.venv/bin/python",
      "args": ["-m", "workbench_mcp.server"]
    }
  }
}

コマンドパスを、仮想環境のPythonへのローカルリポジトリパスに置き換えてください。

シークレットと環境値

環境値は以下のいずれかの場所に指定できます：

1. workbench-mcp/.env

2. .vscode/mcp.json 内の env — VS CodeはこれらをMCPサーバープロセスに注入します。

優先順位: プロセス環境（.vscode/mcp.json → env を含む）は、同じキーに対して .env からの値を上書きします。

VS CodeでのHTTPチューニングの例：

{
  "servers": {
    "workbench-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/workbench-mcp/.venv/bin/python",
      "args": ["-m", "workbench_mcp.server"],
      "env": {
        "API_TIMEOUT_SECONDS": "30",
        "API_MAX_RESPONSE_BYTES": "2097152",
        "API_VERIFY_SSL": "false"
      }
    }
  }
}

本物のトークンをコミットしてはいけません。ローカル専用のワークスペース設定を優先するか、env を省略して .env を使用してください（.env はgitから除外する必要があります）。

他のMCPサーバーが既に設定されている場合は、ファイル全体を置き換えるのではなく、既存の servers オブジェクト内に workbench-mcp を追加してください。

.vscode/mcp.json を保存した後、VS CodeをリロードするかMCPサーバーを更新して、新しいサーバーが検出されるようにします。サーバーが読み込まれたら、データベースプロシージャをテストする前に health ツールを実行してください。

初期ツール

• health

• describe_object

• list_tables_and_columns

• preview_query

• execute_readonly_sql

• exec_proc_preview

• exec_function_preview

• insert_row

• insert_rows

• http_get

• http_head

• http_post

• http_put

• http_patch

• http_delete

• auth_start_session

• auth_switch_user

• auth_status

• auth_clear_session

• execute_path_bash_script (スクリプト名は PATH 経由で解決)

安全性モデル

• 永続的なDDLおよびDMLは、アドホックなPostgreSQLバッチではブロックされます

• 一時テーブルへの書き込みのみが許可されており、現在のバッチで作成された一時テーブルに対してのみ可能です

• preview_query は SELECT 文とCTEベースの読み取りのみを許可します

• exec_proc_preview はPostgreSQLのプロシージャと関数を実行できます。オーバーロードされたルーチンは public.my_func(integer, text) のようなシグネチャで渡す必要があります

• execute_path_bash_script はスクリプト名のみを受け付け（パスは不可）、PATH 経由で解決し、bash を通じて実行します

推奨される最初のチェック

.env が設定された後の典型的な検証フローは以下の通りです：

1. 検査対象の関数、プロシージャ、テーブル、またはビューを記述（describe）します。

2. そのオブジェクトを理解するために必要な設定や参照データをプレビューします。

3. 既知の入力を使用して exec_proc_preview、preview_query、または execute_readonly_sql を実行します。

4. 返された形状を、評価中の機能、調査、またはデバッグシナリオと比較します。

関数実行の例

位置指定のPostgreSQL関数呼び出しには exec_function_preview を使用します。 PostgreSQLの配列は通常のJSONリストとして渡します。

SQLターゲットの例：

select * from sales."Fn_GetSalesChamps"(2, 2025, array[1,2,5,6,7,8,9,10,11,12,15,16,18,19], 5);

同等のMCPツール入力：

{
  "function_name": "sales.\"Fn_GetSalesChamps\"",
  "parameters": [2, 2025, [1, 2, 5, 6, 7, 8, 9, 10, 11, 12, 15, 16, 18, 19], 5]
}

挿入の例

単一行の挿入：

{
  "table_name": "sales.orders",
  "row": {
    "customer_id": 10,
    "status": "new"
  },
  "returning_columns": ["order_id"]
}

バッチ挿入：

{
  "table_name": "sales.orders",
  "rows": [
    {"customer_id": 10, "status": "new"},
    {"customer_id": 11, "status": "pending"}
  ]
}