# 🛡️ 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 中集成
```json
{
  "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` 验证。

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

---

## 🔗 相关资源 / Resources
- **[SECURITY.md](./SECURITY.md)**: 详细的安全政策与加固指南。
- **[CONTEXT.md](./CONTEXT.md)**: 项目演进记录与重要约定。

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