SqlAugur

SqlAugur

AI アシスタントに SQL Server データベースへの安全な読み取り専用アクセスを提供する MCP サーバーです。すべてのクエリは正規表現ではなく、Microsoft 公式の T-SQL パーサーを使って完全な AST に解析されるため、コメントインジェクション、文字列リテラルを悪用した細工、エンコーディングによる回避を構文レベルで阻止します。

┌──────────────┐          ┌───────────────────────────────────────────┐        ┌──────────────┐
│              │  stdio   │  SqlAugur                                 │        │              │
│  AI Client   │◄────────►│                                           │───────►│  SQL Server  │
│              │          │  ┌────────────┐  ┌──────────────────────┐ │        │              │
└──────────────┘          │  │  Query     │  │  Schema / Diagram /  │ │        └──────────────┘
                          │  │  Validator │  │  DBA Services        │ │
                          │  └────────────┘  └──────────────────────┘ │
                          │  ┌────────────────────────────────────┐   │
                          │  │  Rate Limiter                      │   │
                          │  └────────────────────────────────────┘   │
                          └───────────────────────────────────────────┘

クイックスタート

すべてのインストール方法で、次の順序に従ってください。

1. SqlAugur をインストールする
2. appsettings.json を正しい場所に保存する
3. MCP クライアントの設定に SqlAugur を追加する
4. アシスタントに list_servers を呼び出すよう依頼して確認する

具体的なコマンドとファイルパスについては、インストールから始めてください。

このアプローチを採用する理由

• AST レベルのクエリ検証 — 多くの MCP データベースサーバーは、キーワードのブロックのみを行うか、まったく検証を行いません。このプロジェクトでは、Microsoft 公式の TSql180Parser を使ってすべてのクエリを完全な構文木に解析します。コメントインジェクション、文字列リテラルを悪用した細工、エンコーディングによる回避を、脆弱な正規表現パターンではなく構文レベルで阻止します。

• レート制限 — トークンバケット方式のスループット制限と同時実行制御により、AI のクエリループが暴走して本番環境の SQL Server に過剰な負荷をかけるのを防ぎます。この機能を提供する MCP データベースサーバーは他にありません。

• DBA 診断ツール — First Responder Kit、DarlingData、sp_WhoIsActive の統合サポートと、書き込み操作を防ぐパラメーターのブロック機能を備えています。これはまったく新しい MCP 機能カテゴリです。

• レスポンスサイズの最適化 — DBA ツールは冗長な列（XML クエリプラン、デッドロックグラフ、メトリクスの内訳）を除外し、既定で長い文字列を切り詰めるため、レスポンスサイズを 90～99% 削減できます。必要に応じて verbose と includeQueryPlans パラメーターを使うと、切り詰められていない完全な出力を取得できます。

• 段階的な検出 — 最大 31 個のツールをツールセットに整理し、必要に応じて読み込みます。最初に公開されるのはコアツール 6 個のみで、AI のコンテキストウィンドウを小さく保ち、トークン使用量を削減します。必要に応じて追加のツールセットを検出して有効化できます。

機能

セキュリティ

• 設計上読み取り専用 — SELECT クエリと CTE クエリのみ許可
• ScriptDom を使った AST ベースのクエリ検証（正規表現ではありません）
• 書き込みを防ぐため、すべての診断用ストアドプロシージャのパラメーターをブロック
• 同時実行数とスループットのレート制限

データベースツール

• 複数サーバー対応 — 複数の SQL Server インスタンスへの名前付き接続
• スキーマ概要 — PK、FK、制約、既定値を含む簡潔な Markdown スキーママップ
• テーブルのドキュメント — 列、インデックス、外部キー、制約の Markdown 説明
• ER 図の生成 — スマートなカーディナリティ検出による PlantUML および Mermaid の図
• スキーマの探索 — プログラム可能なオブジェクト、ビュー定義、拡張プロパティ、依存関係グラフの一覧表示
• クエリプランの分析 — 推定または実際の XML 実行プラン
• DBA 診断 — First Responder Kit、DarlingData、sp_WhoIsActive とのオプションの統合と、自動レスポンスサイズ最適化
• 段階的な検出 — 動的ツールセットモードでは、ツールを必要に応じて公開することで、初期コンテキストウィンドウの使用量を削減

インストール

どの方法でも同じ MCP サーバーがインストールされます。インストール、設定の保存、クライアントへの接続、確認の順に進めてください。

NuGet グローバルツール（推奨）

1. インストール（前提条件：.NET 10.0 ランタイム）

dotnet tool install -g SqlAugur

2. 設定ファイルを保存

# Linux/macOS
mkdir -p ~/.config/sqlaugur
# Edit ~/.config/sqlaugur/appsettings.json with your server connections

# Windows (PowerShell)
mkdir "$env:APPDATA\sqlaugur" -Force
# Edit %APPDATA%\sqlaugur\appsettings.json with your server connections

その場所に保存する appsettings.json の例：

{
  "SqlAugur": {
    "Servers": {
      "production": {
        "ConnectionString": "Server=myserver;Database=master;Integrated Security=True;TrustServerCertificate=False;Encrypt=True;"
      }
    }
  }
}

3. MCP クライアントに追加

{
  "mcpServers": {
    "sqlaugur": {
      "command": "sqlaugur"
    }
  }
}

更新するには：dotnet tool update -g SqlAugur

Docker / Podman

1. SqlAugur コンテナーを実行

# Volume-mount a config file
docker run -i --rm \
  -v /path/to/appsettings.json:/app/appsettings.json:ro,Z \
  ghcr.io/mbentham/sqlaugur:latest

# Or use environment variables (no config file needed)
docker run -i --rm \
  -e SqlAugur__Servers__production__ConnectionString="Server=host.docker.internal;Database=master;..." \
  ghcr.io/mbentham/sqlaugur:latest

注： ホストマシン上の SQL Server に接続するには、host.docker.internal（Docker Desktop）または --network=host（Linux）を使用してください。docker を podman に置き換えてください。コマンドはすべて同じです。ボリュームマウントの :Z フラグは、SELinux が有効なシステム（Fedora、RHEL）で必要です。macOS／Windows の Docker Desktop ユーザーは省略できます。

設定ファイルをマウントする場合は、/path/to/appsettings.json として保存し、/app/appsettings.json にマウントしてください。

2. MCP クライアントに追加

{
  "mcpServers": {
    "sqlaugur": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-v", "/path/to/appsettings.json:/app/appsettings.json:ro,Z",
        "ghcr.io/mbentham/sqlaugur:latest"]
    }
  }
}

services:
  sqlaugur:
    image: ghcr.io/mbentham/sqlaugur:latest
    stdin_open: true
    volumes:
      - ./appsettings.json:/app/appsettings.json:ro,Z

{
  "mcpServers": {
    "sqlaugur": {
      "command": "docker",
      "args": ["compose", "run", "-i", "--rm", "sqlaugur"]
    }
  }
}

ソースからビルド

1. ビルド（前提条件：.NET 10.0 SDK）

git clone [email protected]:mbentham/SqlAugur.git
cd SqlAugur
dotnet publish SqlAugur -c Release -o SqlAugur/publish

2. 設定ファイルを保存

# Linux/macOS
cp SqlAugur/appsettings.example.json SqlAugur/publish/appsettings.json
# Edit SqlAugur/publish/appsettings.json with your server connections

# Windows (PowerShell)
Copy-Item SqlAugur\appsettings.example.json SqlAugur\publish\appsettings.json
# Edit SqlAugur\publish\appsettings.json with your server connections

3. MCP クライアントに追加

{
  "mcpServers": {
    "sqlaugur": {
      "command": "dotnet",
      "args": ["/absolute/path/to/SqlAugur/publish/SqlAugur.dll"]
    }
  }
}

MCP 接続を確認する（LLM 優先）

MCP クライアントを再起動した後、アシスタントに次のように依頼してください。

• Call list_servers
• Call list_databases for server "production"

期待される結果：

• list_servers が設定済みのサーバー名（例：production）を返す
• list_databases が接続エラーや認証エラーではなく、データベースの JSON 配列を返す

確認に失敗した場合：

1. MCP 設定で想定されるコマンド（sqlaugur、docker run ...、または dotnet /path/to/SqlAugur.dll）が実行されていることを確認してください
2. appsettings.json が、インストール方法に応じた場所に保存されていることを確認してください：
   • ローカルツール：~/.config/sqlaugur/appsettings.json（Linux/macOS）または %APPDATA%\sqlaugur\appsettings.json（Windows）
   • コンテナー：/app/appsettings.json にマウント
   • ソースからのビルド：公開済み DLL の隣（SqlAugur/publish/appsettings.json）
3. ツール呼び出しで、設定済みのサーバーキー（例：production）を使用していることを確認してください
4. 接続文字列の SQL 接続と認証を確認してください

構成

サーバーは複数のソースから構成を読み込みます。優先順位の高いソースが、低いソースの設定を上書きします。

1. コマンドライン引数
2. 環境変数 — セクションの区切り文字として __ を使用します（例：SqlAugur__Servers__production__ConnectionString=...）
3. 現在の作業ディレクトリ — コマンドを実行したディレクトリ内の appsettings.json
4. ユーザー構成ディレクトリ — Linux では ~/.config/sqlaugur/appsettings.json、Windows では %APPDATA%\sqlaugur\appsettings.json
5. Azure Key Vault — AzureKeyVaultUri が設定されている場合（下記参照）
6. アプリケーションディレクトリ — DLL と同じ場所にある appsettings.json

構成例（Windows 認証 — 推奨）：

{
  "SqlAugur": {
    "Servers": {
      "production": {
        "ConnectionString": "Server=myserver;Database=master;Integrated Security=True;TrustServerCertificate=False;Encrypt=True;"
      }
    },
    "MaxRows": 1000,
    "CommandTimeoutSeconds": 30,
    "MaxConcurrentQueries": 5,
    "MaxQueriesPerMinute": 60,
    "EnableFirstResponderKit": false,
    "EnableDarlingData": false,
    "EnableWhoIsActive": false,
    "EnableDynamicToolsets": false
  }
}

セキュリティに関する注意： 認証情報を誤ってコミットしないよう、appsettings.json は gitignore の対象です。Windows 認証、Azure Managed Identity、安全な認証情報の保存方法など、推奨される認証方法については SECURITY.md を参照してください。

ツール

サーバーには、ツールセットに分類された 31 個のツールがあります。6 個のコアツールは常に利用できます。追加のツールセットは、起動時（静的モード）または必要に応じて（動的モード）読み込まれます。

コアツール

各ツールキットは設定フラグで個別に有効化され、対象の SQL Server に対応するストアドプロシージャがインストールされている必要があります。

すべての DBA ツールでは、デフォルトで応答サイズが最適化されます。AI のコンテキストウィンドウ内に応答を収めるため、XML クエリプランの列は除外され、長い文字列値は切り詰められます。すべてのツールで、次のオプションのパラメーターを使用できます。

一部のツールには追加のパラメーターがあります：includeXmlReports（BlitzLock、HealthParser、HumanEventsBlockViewer）、compact（sp_WhoIsActive）、verboseMetrics（QuickieStore）。

EnableDynamicToolsets が true の場合、起動時に読み込まれるのはコアツールのみです。3 つのメタツールを使うと、AI は必要に応じて追加のツールセットを検出して有効にできるため、初期コンテキストウィンドウの使用量を削減できます。

使用例：

1. AI が list_toolsets を呼び出す — first_responder_kit が「利用可能」（設定済みだが未有効）であることを確認します
2. AI が get_toolset_tools("first_responder_kit") を呼び出す — 7 つのツールとそのパラメーターを確認します
3. AI が enable_toolset("first_responder_kit") を呼び出す — 7 つのツールが登録され、使用可能になります
4. AI が sp_blitz を呼び出す — 通常どおりヘルスチェックを実行します

静的モード（EnableDynamicToolsets: false）では、有効なすべてのツールセットが起動時に読み込まれ、検出ツールは登録されません。Schema Exploration と Diagrams のツールセットは、モードにかかわらず常に読み込まれます。

既知の制限事項： 段階的な検出は、新しいツールが登録されたことをクライアントに通知する MCP の notifications/tools/list_changed 通知に依存しています。Claude Code は現在この通知を処理しないため（anthropics/claude-code#4118）、動的に有効化されたツールセットは表示されません。Claude Code を使用する場合は、静的モード（EnableDynamicToolsets: false）を使用してください。

セキュリティ

クエリの検証

すべてのクエリは、Microsoft の公式 TSql180Parser を使用して抽象構文木（AST）に解析され、以下のルールを満たす必要があります。

• 単一のステートメントのみ — 複数のステートメントは拒否されます
• SELECT のみ — INSERT、UPDATE、DELETE、DROP、EXEC、CREATE、ALTER、およびその他すべてのステートメントタイプはブロックされます
• SELECT INTO は不可 — SELECT によるテーブル作成を防ぎます
• 外部データへのアクセスは不可 — OPENROWSET（BULK、Cosmos DB、内部用を含むすべてのバリエーション）、OPENQUERY、OPENDATASOURCE、OPENXML はブロックされます
• リンクサーバーは不可 — 4 部構成の名前参照は拒否されます
• MAXRECURSION ヒントは不可 — デフォルトの再帰制限が上書きされるのを防ぎます
• データベースをまたぐクエリは許可されます — 3 部構成の名前は設計上使用できます。セキュリティ境界はデータベースではなくサーバーです。単一のデータベースに制限するには、ログインの権限を制限してください。

検証は解析済みの AST に対して行われるため、コメント内のキーワード、文字列リテラル、入れ子になったブロックコメント、エンコードのトリックなど、文字列ベースの方法では対処できないエッジケースも正しく処理できます。

パラメーターのブロック

診断用ストアドプロシージャは、書き込みを防ぐブロック対象パラメーターと、許可リストに登録されたプロシージャ名を使用して実行されます。

• First Responder Kit — すべての @Output* パラメーターをブロックします（サーバーテーブルへの結果の書き込みを防ぎます）
• DarlingData — ログおよび出力パラメーターをブロックします（テーブルの作成とデータの保持を防ぎます）
• sp_WhoIsActive — @destination_table、@return_schema、@schema、@help をブロックします

レート制限

すべてのツール実行には、同時実行数制限（MaxConcurrentQueries、デフォルトは 5）とスループット制限（MaxQueriesPerMinute、デフォルトは 60）が適用されます。上限を超えたリクエストは、再試行を促すメッセージとともに拒否されます。

接続のセキュリティ

構成ファイルへの認証情報の保存を避けるため、可能な場合は Windows 認証または Azure Managed Identity を使用してください。SQL 認証が必要な場合は、環境変数によるオーバーライドを使って実行時に認証情報を渡してください。認証情報ストアや接続文字列の暗号化など、詳しいガイダンスについては SECURITY.md を参照してください。

既知のリスク

• このプロジェクトは、公式の Microsoft MCP C# SDK（ModelContextProtocol NuGet パッケージ、バージョン 1.3.0）に依存しています。MCP フレームワークがすべてのプロトコル I/O を処理するため、フレームワークに脆弱性があると、このアプリケーションのセキュリティ境界に直接影響します。パッケージの更新を監視し、新しいバージョンがリリースされたらアップグレードしてください。
• SQL Server クエリから返されるデータには、AI を標的とする悪意のあるプロンプトインジェクションが含まれる可能性があります。これはすべての AI 利用に伴うリスクであり、このプロジェクトで軽減することはできません。AI セキュリティのベストプラクティスに従い、信頼できるデータソースにのみ接続してください。

貢献

貢献を歓迎します。アーキテクチャの詳細、開発環境のセットアップ、テスト手順、新しいツールの追加に関するガイドラインについては、CONTRIBUTING.md をご覧ください。

ライセンス

MIT