Db Whisper

🛡️ DB-Whisper (Production-Hardened MCP Server)

[中文] | [English]

DB-Whisper 是一个基于 Anthropic Model Context Protocol (MCP) 的生产级数据库只读访问工具。它专为 AI 助手（如 Cursor, Claude Desktop）设计，提供严苛的安全边界和深度 AST 校验，确保 AI 只能在受控环境下安全地查询并理解你的数据库。

A production-grade, AST-hardened database inspection tool based on the Model Context Protocol (MCP). Designed for AI assistants (Cursor, Claude Desktop), providing strict security boundaries to ensure AI can safely query and understand your database in a read-only, controlled environment.

---

🌟 核心安全性 / Core Security (Production-Ready)

1. 深度 AST 防火墙 (Deep AST Firewall)

• 🛡️ 严格白名单 (Strict Whitelist): 采用 Default Deny 策略，仅允许必要的 SELECT 节点类型。
• 🚫 系统表隔离 (System Metadata Isolation): 彻底封堵对 information_schema, pg_catalog 以及 SQLite 3.33.0+ 别名（如 sqlite_schema, sqlite_temp_schema）的访问。
• 🧩 复杂度限制 (Complexity Limits): 限制 AST 节点数 (≤150) 与嵌套深度 (≤8)，防止通过超大规模 SQL 进行资源耗尽攻击。

2. 驱动级只读保障 (Driver-Level Read-Only)

• 🗄️ SQLite 强制只读: 启用 readonly: true 模式并强制 PRAGMA query_only = ON。
• 🐘 PostgreSQL 事务保障: 每一条查询均在 BEGIN READ ONLY 事务中执行，确保数据库层面无法写入。
• 🔒 SSL 安全加固: 默认启用 rejectUnauthorized: true，防止中间人攻击。

3. 运行限流与脱敏 (Rate Limiting & Masking)

• ⏱️ 令牌桶限流 (Rate Limiting): 默认限制为 10 次查询/分钟，防止 AI 滥用导致数据库负载过高。
• 🤫 零信息泄露 (Zero Leakage): 安全拦截均返回通用错误信息，不泄露表名、列名等具体元数据。
• 🕵️ 审计脱敏 (Audit Masking): 自动识别并脱敏日志中的密码、API Key、邮箱及信用卡号。

---

🚀 快速上手 / Quick Start

1. 配置建议 / Mandatory Setup (Least Privilege)

重要安全提示：请务必为 MCP 创建专用的 只读数据库用户，并配合环境变量进行权限细化。 Critical: Always use a dedicated Read-Only DB User.

2. 环境变量配置 / Environment Variables

变量	说明	默认值
DATABASE_URL	数据库连接串 (Postgres URI 或 SQLite 绝对路径)	(必填)
ALLOWED_TABLES	表名白名单，用逗号分隔 (如 users,orders)	* (仅黑名单模式)
DB_SSL	是否强制启用 SSL 验证	false
QUERY_TIMEOUT_MS	单次查询硬超时时间	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"
      }
    }
  }
}

---

🛠️ 工程化支持 / Engineering & QA

• 自动化测试: 已通过 vitest 实现 100% 对抗性安全测试，覆盖 SQLite 别名绕过、嵌套 DML 拦截及限流逻辑。
• 依赖安全: 所有关键依赖已升级至最新版，并通过 npm audit 验证。

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

---

🔗 相关资源 / Resources

• SECURITY.md: 详细的安全政策与加固指南。
• CONTEXT.md: 项目演进记录与重要约定。

---

Note: All logs are directed to stderr; stdout is reserved strictly for MCP protocol data.