内容
db-tool-mcp
[](examples/db-tool-mcp.png)
> **执行 SQL 查询并使用沙盒 Perl 代码过滤 — 唯一一个带有内置 Safe 沙盒的 MCP 服务器，用于行级数据处理。**
[](https://www.perl.org/)
[](https://modelcontextprotocol.io)
[](LICENSE)
## 功能特点
- **SQL 查询** — SELECT、INSERT、UPDATE、DELETE、CREATE TABLE、PRAGMA 等
- **沙盒 Perl 代码（`code` 参数）** — 使用 Perl 内置的 `Safe` 模块，在服务器端过滤和转换行数据
- **列出表格** — 显示数据库中的所有表格
- **检查表格** — 显示列名、类型和元数据
- **事务** — `begin_work`、`commit`、`rollback`
- **绑定参数** — 安全的参数化查询
- **多种数据库引擎** — SQLite、MySQL、PostgreSQL 以及任何 DBI 支持的驱动
- **延迟连接** — 连接一次，在多个请求中重用
- **零外部依赖** — 只需要 `perl`、`JSON`、`DBI` 和 `DBD::*`
## 为什么选择 Perl？
| 特性 | Perl | Python | JavaScript | Lua |
|---------|------|--------|------------|-----|
| 内置沙盒 | ✅ `Safe` 模块 | ❌ 无内置沙盒 | ❌ `vm` 模块不安全 | ❌ 无内置沙盒 |
| 行级过滤 | ✅ `code` 参数 | ❌ 需要额外库 | ❌ 需要自己编写沙盒 | ❌ 需要自己编写沙盒 |
| 可执行性 | 一个文件，无需构建 | 需要虚拟环境 | 需要 npm 安装 | 需要 luarocks |
| DBI 支持 | ✅ SQLite、MySQL、Pg 等 | ✅（独立驱动） | ✅（独立库） | ✅（独立库） |
**Perl 的 `Safe` 模块是所有主要动态语言中唯一一个内置、生产环境下经过测试的沙盒。** 它自 1994 年以来一直是 Perl 的一部分，并经过安全审计。
## 安装
### 前置条件
```bash
# Perl 模块
sudo cpan JSON DBI
# 或在 Arch Linux 上：
sudo pacman -S perl-json perl-dbi perl-dbd-sqlite
# 其他数据库驱动（MySQL、PostgreSQL）：
sudo cpan DBD::mysql DBD::Pg
```
### 设置
1. 克隆仓库：
```bash
git clone https://github.com/kirill-scherba/db-tool-mcp.git
cd db-tool-mcp
chmod +x db-tool-mcp.pl
```
2. 将以下内容添加到您的 MCP 设置文件（通常是 `cline_mcp_settings.json` 或 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"db-tool": {
"command": "perl",
"args": ["/path/to/db-tool-mcp/db-tool-mcp.pl"],
"env": {},
"disabled": false,
"autoApprove": []
}
}
}
```
## 使用
### 基本 SQL 查询
```json
{
"query": "SELECT * FROM users LIMIT 10",
"db_name": "/path/to/database.db"
}
```
### 列出表格
```json
{
"list_tables": true,
"db_name": "/path/to/database.db"
}
```
### 检查表格架构
```json
{
"inspect_table": { "table": "users" },
"db_name": "/path/to/database.db"
}
```
### 沙盒 Perl 代码过滤（`code` — 杀手锏）
`code` 参数允许 AI 助手传递 Perl 代码，在沙盒环境中**逐行**运行。这将过滤工作负载转移到数据库服务器，减少数据传输。
```json
{
"query": "SELECT * FROM users",
"db_name": "/path/to/database.db",
"code": "length($row->{name}) > 5 && $row->{id} % 2 == 1"
}
```
**工作原理：**
```
客户端（AI） MCP 服务器（Perl）
│ │
│ 工具/调用 │
│ { 查询, 代码 } │
│──────────────────────────────────> │
│ │
│ 执行 SQL
│ 逐行获取数据
│ 对于每一行：
│ 在 Safe 沙盒中评估 $code
│ 如果为真 → 保留
│ 如果为假 → 跳过
│ │
│ { 计数: 3, 数据: [...] } │
│<────────────────────────────────── │
```
**更多 `code` 示例：**
```perl
# 按字符串长度过滤
length($row->{name}) > 5
# 不区分大小写的正则表达式匹配
lc($row->{email}) =~ /\@company\.com$/
# 数值比较
$row->{price} < 500 && $row->{rating} > 4.0
# 数组/列表大小（如果列是分隔字符串）
scalar(split(',', $row->{tags})) >= 3
# 日期比较
$row->{created_at} gt '2026-01-01'
# 字符串转换
ucfirst(lc($row->{name}))
```
### 事务
```json
{
"begin_work": true,
"db_name": "/path/to/database.db"
}
{
"query": "INSERT INTO users (name) VALUES (?)",
"bind": ["Alice"],
"db_name": "/path/to/database.db"
}
{
"commit": true,
"db_name": "/path/to/database.db"
}
```
### 使用不同的数据库引擎
```json
{
"query": "SELECT * FROM products",
"db_driver": "mysql",
"db_host": "localhost",
"db_port": 3306,
"db_name": "shop",
"db_user": "root",
"db_password": "secret"
}
```
## 快速测试
```bash
cd /path/to/db-tool-mcp
# 创建测试数据库
sqlite3 test.db "CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY, name TEXT); INSERT INTO test VALUES (1, 'Alice'), (2, 'Bob'), (3, 'Charlie');"
# 使用单个请求测试服务器
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}' | perl db-tool-mcp.pl 2>/dev/null
# 或运行完整测试序列
printf '{"jsonrpc":"2.0","id":1,"method":"initialize"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"db_execute","arguments":{"query":"SELECT * FROM test","db_name":"test.db"}}}
' | perl db-tool-mcp.pl 2>/dev/null
```
## 架构
```
┌──────────────────────────────────────────────────────────┐
│ MCP 客户端（AI） │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │初始化 │ │工具/列表│ │工具/调用│ │工具/调用│ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ JSON-RPC 2.0 超过 stdin/stdout │
└──────────────────────────┬───────────────────────────────┘
│
┌──────────────────────────▼───────────────────────────────┐
│ db-tool-mcp（Perl） │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ MCP 主循环 │──>│ 请求 │──>│ 数据库 │ │
│ │ │ │ 调度器 │ │ （DBI -> SQLite） │ │
│ │ │ │ │ │ │ │
│ │ 循环 │ │ • 列出表格 │ │ + Safe 沙盒 │ │
│ │ <STDIN> │ │ • 检查 │ │ 用于代码参数 │ │
│ │ │ │ • 查询 + 代码│ │ │ │
│ │ │ │ • 事务 │ │ │ │
│ └──────────┘ └──────────────┘ └──────────────────┘ │
└──────────────────────────────────────────────────────────┘
```
## 协议
该服务器使用 **JSON-RPC 2.0** 超过 stdin/stdout 实现 **模型上下文协议（MCP）**。
| 方法 | 描述 |
|--------|-------------|
| `initialize` | 协议版本和功能握手 |
| `ping` | 健康检查 |
| `tools/list` | 返回具有完整 JSON 模式的 `db_execute` 工具定义 |
| `tools/call` | 使用提供的参数执行 `db_execute` |
所有日志记录都输出到 **stderr**，使 **stdout** 保持干净以进行 JSON-RPC 消息传递。
## 安全
- `code` 参数在 Perl 的 `Safe` 隔离区中运行，限制了文件操作、系统调用和其他危险操作
- 只允许使用白名单 Perl 模块（`MIME::Base64`、`Digest::MD5`、`URI::Escape`）
- `code` 参数仅设计用于 **AI 助手** — AI 生成 Perl 代码，而不是最终用户
## 贡献
欢迎贡献！请随意提出问题或提交拉取请求。
## 许可证
MIT Kirill Scherba
---
*使用 🐪 构建 — 因为只有 Perl 在其核心中具有 `Safe`。*
