DB-Whisper MCP Server

[中文] | [English]

基于 Anthropic Model Context Protocol (MCP) 的生产级数据库透视工具。专为 AI 助手（Cursor, Claude Desktop 等）设计，提供安全、受控的数据库只读访问。

A production-grade database inspection tool based on the Anthropic Model Context Protocol (MCP). Designed for AI assistants (Cursor, Claude Desktop, etc.), providing secure and controlled read-only access to databases.

核心特性 / Core Features

• 安全拦截 (AST Firewall)：通过 SQL 抽象语法树深度校验，物理隔绝 DROP, UPDATE, DELETE 等写操作。
• Security Interception (AST Firewall): Deep validation via SQL Abstract Syntax Tree (AST) to physically isolate write operations like DROP, UPDATE, and DELETE.
• 结构感知 / Schema Awareness：AI 可自动读取数据库 Schema 并生成 Markdown 格式的表关系概览。
• Context Awareness: AI automatically reads the database schema and generates a Markdown-formatted overview of table relationships.
• 性能保护 / Performance Protection：自动结果截断（50 行）及字段长度限制（1000 字符），防止数据撑爆 LLM 上下文。
• Data Safety: Automatic truncation (50 rows) and field length limits (1000 chars) to prevent context window overflow.
• 多数据库支持 / Multi-DB Support：原生支持 PostgreSQL 与 SQLite。
• Compatibility: Native support for PostgreSQL and SQLite.

快速上手 / Quick Start

1. 环境准备 / Environment Setup

npm install
npm run build

2. 配置环境变量 / Configuration

创建 / Create .env:

# SQLite 示例 / SQLite Example
DATABASE_URL=./your_database.db
# PostgreSQL 示例 / PostgreSQL Example
# DATABASE_URL=postgresql://user:pass@localhost:5432/dbname

3. 在 IDE 中集成 / IDE Integration (Cursor)

1. 打开 / Open Cursor Settings -> MCP.
2. 点击 / Click + Add New MCP Server.
3. 填写 / Fill in:
   • Name: db-whisper
   • Type: command
   • Command: node /ABSOLUTE_PATH/db-whisper/dist/index.js
4. 保存 / Save. AI 助手即可获得 query_read_only 工具 / AI is now equipped with query_read_only.

开发调试 / Development & Debugging

# 使用 MCP Inspector / Use MCP Inspector
DATABASE_URL=./test.db npx @modelcontextprotocol/inspector node dist/index.js

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