Db Whisper

🛡️ DB-Whisper（本番環境向けに強化された MCP サーバー）

[中国語] | [英語]

DB-Whisper は、Anthropic の Model Context Protocol (MCP) に基づく、本番環境向けのデータベース読み取り専用アクセスツールです。Cursor や Claude Desktop などの AI アシスタント向けに設計されており、厳格なセキュリティ境界と詳細な AST 検証を備えています。これにより、AI は制御された環境でのみデータベースを安全に検索し、その内容を理解できます。

Model Context Protocol (MCP) に基づく、本番環境向けの AST 強化データベース検査ツールです。Cursor や Claude Desktop などの AI アシスタント向けに設計されており、厳格なセキュリティ境界を提供することで、読み取り専用の制御された環境で AI がデータベースを安全に検索し、その内容を理解できるようにします。

---

🌟 主なセキュリティ機能 / 本番環境対応

1. 詳細な AST ファイアウォール

• 🛡️ 厳格なホワイトリスト：Default Deny ポリシーを採用し、必要な SELECT ノードタイプのみを許可します。
• 🚫 システムメタデータの隔離：information_schema、pg_catalog および SQLite 3.33.0+ の別名（sqlite_schema、sqlite_temp_schema など）へのアクセスを完全に遮断します。
• 🧩 複雑さの制限：AST ノード数（≤150）とネストの深さ（≤8）を制限し、極端に大きな SQL によるリソース枯渇攻撃を防ぎます。

2. ドライバーレベルの読み取り専用保護

• 🗄️ SQLite の読み取り専用を強制：readonly: true モードを有効にし、PRAGMA query_only = ON を強制します。
• 🐘 PostgreSQL のトランザクション保護：各クエリを BEGIN READ ONLY トランザクション内で実行し、データベースレベルで書き込みを防ぎます。
• 🔒 SSL セキュリティの強化：デフォルトで rejectUnauthorized: true を有効にし、中間者攻撃を防ぎます。

3. 実行時のレート制限とマスキング

• ⏱️ トークンバケット方式のレート制限：デフォルトで 1 分あたり 10 回のクエリに制限し、AI の過剰利用によるデータベース負荷の増大を防ぎます。
• 🤫 情報漏えいゼロ：セキュリティによるブロック時には汎用エラーメッセージを返し、テーブル名や列名などの具体的なメタデータを漏らしません。
• 🕵️ 監査ログのマスキング：ログ内のパスワード、API Key、メールアドレス、クレジットカード番号を自動的に識別してマスキングします。

---

🚀 クイックスタート

1. 設定の推奨事項（必須）／最小権限

重要なセキュリティ上の注意：MCP 用に専用の読み取り専用データベースユーザーを必ず作成し、環境変数と組み合わせて権限を細かく設定してください。 重要：専用の読み取り専用データベースユーザーを必ず使用してください。

2. 環境変数の設定

変数	説明	デフォルト値
DATABASE_URL	データベース接続文字列（Postgres URI または SQLite の絶対パス）	（必須）
ALLOWED_TABLES	テーブル名のホワイトリスト。カンマ区切りで指定します（例：users,orders）	*（ブラックリストモードのみ）
DB_SSL	SSL 検証を強制的に有効にするかどうか	false
QUERY_TIMEOUT_MS	1 回のクエリに設定するハードタイムアウト	10000

3. Claude Desktop / Cursor への統合

{
  "mcpServers": {
    "db-whisper": {
      "command": "npx",
      "args": ["-y", "db-whisper-mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/db",
        "ALLOWED_TABLES": "public_users,products",
        "NODE_ENV": "production"
      }
    }
  }
}

---

🛠️ エンジニアリングサポート / 品質保証

• 自動テスト：vitest による 100% の敵対的セキュリティテストに合格済みです。SQLite の別名による回避、ネストされた DML のブロック、レート制限のロジックを網羅しています。
• 依存関係のセキュリティ：すべての重要な依存関係を最新バージョンにアップグレードし、npm audit で検証済みです。

npm install   # 安装依赖
npm test      # 运行安全与限流测试 (需 DATABASE_URL 环境)
npm run build # 编译项目

---

🔗 関連リソース

• SECURITY.md：詳細なセキュリティポリシーと強化ガイドです。
• CONTEXT.md：プロジェクトの変遷と重要な取り決めを記録しています。

---

注：すべてのログは stderr に出力されます。stdout は MCP プロトコルデータ専用です。