🛡️ DB-Whisper (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)

• 🛡️ 严格 AST 白名单 (Strict AST Firewall): 采用 Default Deny 策略，仅允许 20+ 种基础 SELECT 节点类型和 15 种安全聚合函数。彻底封堵 DML/DDL 及其子查询绕过。
• ⏱️ 注入防御 (Injection Defense): 屏蔽 pg_sleep, BENCHMARK 等函数，从源头切断时间盲注 (Time-based Blind Injection) 路径。
• 🚫 模式隔离 (Metadata Isolation): 强制拦截对 information_schema, pg_catalog, sqlite_master 等系统表的访问，防止 AI 获取敏感元数据。
• ⚡ 稳定性加固 (Stability Hardening):
  • 强制 LIMIT 注入: 数据库层强制注入 LIMIT 101，防止大表扫描导致的内存溢出 (OOM)。
  • 硬性查询超时: 10 秒强制执行超时，保护本地 CPU。
• 🕵️ 审计与脱敏 (Audit & Masking):
  • 错误信息脱敏，不泄露数据库结构；查询实时记录至 [AUDIT] 日志流。
  • SSL 强制传输: PostgreSQL 默认启用 SSL 加密。

🚀 快速上手 / Quick Start

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

重要安全提示：请务必为 MCP 创建专用的 只读数据库用户，仅授予必要的 SELECT 权限。 Critical: Always use a dedicated Read-Only DB User with limited SELECT permissions.

2. 在 Claude Desktop / Cursor 中集成

推荐使用 npx 快速启动，无需全局安装：

{
  "mcpServers": {
    "db-whisper": {
      "command": "npx",
      "args": ["-y", "db-whisper-mcp"],
      "env": {
        "DATABASE_URL": "替换为你的绝对路径或连接串 (REPLACE_WITH_YOUR_PATH)",
        "NODE_ENV": "production"
      }
    }
  }
}

注：SQLite 必须使用绝对路径。

🛠️ 工程化支持 / Engineering & QA

• 自动化测试: 已通过 vitest 实现 100% 对抗性安全测试，覆盖常见的 SQL 注入与绕过场景。
• 依赖安全: 所有关键依赖（pg, sdk, zod）已升级至最新版，修复了已知的 RCE 和数据泄露漏洞。

npm install   # 安装依赖
npm test      # 运行安全测试
npm run audit # 运行依赖安全审计

🔗 相关资源 / Resources

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

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