内容
# MCPBridge
生产级[模型上下文协议](https://modelcontextprotocol.io)服务器，连接AI助手（Claude Desktop，Cursor，Windsurf，Claude Code等）到**PostgreSQL** — 拥有真正数据库应有的防护措施。
大多数数据库MCP服务器只是`pool.query()`的薄封装。MCPBridge添加了缺失的生产环境层：
- **查询安全验证** — DDL和多语句有效载荷被阻止；注释、字符串字面量和美元引号字符串在关键字分析之前被剥离，以便没有任何内容可以偷运过验证器；读取额外地在`READ ONLY`事务中运行，作为深度防御。
- **两阶段受控写入** — `write_db`从不执行任何操作。它分阶段执行语句，通过规划器估计受影响的行，分配风险级别，并返回`confirmation_id`。执行仅通过`confirm_write`发生；高风险操作（批量删除，`UPDATE`无`WHERE`）需要明确的`acknowledge_risk=true`。未确认的写入在10分钟后过期。
- **结果限制** — 无`LIMIT`的`SELECT`自动限制（默认为100行），并带有警告，以便`SELECT * FROM events`不会淹没上下文窗口。
- **审计日志** — 每个操作（成功，错误，阻止，速率限制）都被追加到JSONL审计跟踪中，包含时间，行数和客户端身份。凭证从每行日志和错误消息中被删除。日志每10 MB旋转一次。
- **速率限制** — 滑动窗口限制器（默认为每客户端每分钟100个请求），在数据库连接被消耗之前拒绝请求。
- **模式智能** — 行估计来自规划器统计（从不`COUNT(*)`），外键关系映射与基数，索引库存，列统计，样本行 — 所有这些都位于5分钟TTL缓存之后。
## 架构
**基于功能的架构与领域驱动设计（DDD）相结合**。每个核心功能都是一个有界上下文，位于`src/`下的独立文件夹中，包含其Gherkin规范（`.feature`），测试和DDD分层（`domain` → `application` → `infrastructure` / `presentation`）。依赖关系在功能内指向内部；功能仅依赖于`shared/`，`platform/`和其他功能的公共模块 — 从不依赖于组合根。
```bash
features/ # Gherkin规范（Cucumber约定） — 每个功能一个.feature文件
src/
├── querying/ # 功能：安全的只读查询
│ ├── domain/ # SQL词法分析，分类，验证，结果限制
│ ├── application/ # ExecuteQuery，ExplainQuery用例
│ ├── presentation/ # query_db / explain_query工具，优化查询提示
│ └── tests/
├── schema-exploration/ # 功能：模式智能
│ ├── domain/ # 表/列/关系/统计类型
│ ├── application/ # SchemaService（TTL缓存），ListTables，DescribeTable
│ ├── infrastructure/ # PostgreSQL目录内省器
│ └── presentation/ # list_tables / describe_table工具 + schema:// table:// stats:// relations:// 资源
├── guarded-writes/ # 功能：两阶段确认写入
│ ├── domain/ # PendingWrite聚合，RiskAssessor
│ ├── application/ # RequestWrite，ConfirmWrite，RejectWrite
│ ├── infrastructure/ # 内存中待处理写入存储
│ ├── presentation/ # write_db / confirm_write / reject_write工具
│ └── tests/
├── search/ # 功能：自然语言搜索
│ ├── application/ # SearchData用例，SqlGenerator端口
│ ├── infrastructure/ # MCP采样SQL生成器
│ └── presentation/ # search_data工具
├── audit/ # 功能：审计跟踪（JSONL日志，旋转，删除）
├── throttling/ # 功能：速率限制（滑动窗口 + OperationGate）
├── shared/ # 共享内核：Clock，错误，结果信封，TTL缓存，格式化，测试伪造
├── platform/ # 跨功能管道：zod配置，pg池 + 网关，MCP程序集，HTTP传输，组合根
└── main.ts # 入口点
docker/ # Dockerfile，Dockerfile.dockerignore，docker-compose.yml
docs/ # 架构，文件夹结构，设置，开发指南
```
完整文档位于[docs/](docs/)： [架构](docs/architecture.md) · [文件夹结构](docs/folder-structure.md) · [设置](docs/setup.md) · [开发指南](docs/development.md)。
## 工具
| 工具 | 描述 |
|------|-------------|
| `query_db` | 执行只读SQL。无限制的查询会被限制并带有警告。 |
| `explain_query` | 显示执行计划（可选`EXPLAIN ANALYZE`）并带有性能警告。 |
| `list_tables` | 表/视图，带有估计的行数和注释。 |
| `describe_table` | 列，PK/FKs，索引，关系，样本行，列统计。 |
| `search_data` | 自然语言问题 → SQL（通过MCP采样）→ 验证 → 执行。 |
| `write_db` | 分阶段执行INSERT/UPDATE/DELETE；返回影响预览 + `confirmation_id`。 |
| `confirm_write` | 执行分阶段写入（高风险需要`acknowledge_risk=true`）。 |
| `reject_write` | 取消分阶段写入。 |
## 资源和提示
- `schema://{schemaName}` — 完整的模式快照（5分钟TTL缓存）
- `table://{name}` / `stats://{table}` / `relations://{table}` — 每张表的结构，统计数据，关系映射
- 提示：`analyze-table`，`optimize-query`
## 快速开始
```bash
npm install
npm run build
```
### Claude Desktop / Claude Code
添加到`claude_desktop_config.json`（或Claude Code的`.mcp.json`）：
```json
{
"mcpServers": {
"mcpbridge": {
"command": "node",
"args": ["/absolute/path/to/mcpbridge/dist/main.js"],
"env": {
"DATABASE_URL": "postgresql://user:password@localhost:5432/mydb",
"MCPBRIDGE_MODE": "read-only"
}
}
}
}
```
重启客户端 — MCPBridge及其8个工具立即出现。设置`MCPBRIDGE_MODE=read-write`以启用受控写入流程。
### 远程（可流式HTTP）
```bash
MCPBRIDGE_TRANSPORT=http MCPBRIDGE_HTTP_PORT=3920 node dist/main.js
# MCP端点：http://localhost:3920/mcp
```
### Docker
所有Docker资产位于[docker/](docker/)：
```bash
docker compose -f docker/docker-compose.yml up # PostgreSQL，带有样本数据 + MCPBridge on :3920
docker build -f docker/Dockerfile -t mcpbridge . # 镜像仅（仓库根目录作为上下文）
```
## 配置
所有配置均基于环境（参见`.env.example`）：
| 变量 | 默认值 | 目的 |
|----------|---------|---------|
| `DATABASE_URL` | — | PostgreSQL连接字符串（或使用`PGHOST`/`PGDATABASE`/`PGUSER`/`PGPASSWORD`/`PGPORT`） |
| `MCPBRIDGE_MODE` | `read-only` | `read-only`完全禁用`write_db`；`read-write`启用受控写入 |
| `MCPBRIDGE_DEFAULT_SCHEMA` | `public` | 默认情况下，工具和资源使用的模式 |
| `MCPBRIDGE_MAX_ROWS` | `100` | 应用于无`LIMIT`的`SELECT`的限制 |
| `MCPBRIDGE_RATE_LIMIT` | `100` | 每个窗口每个客户端允许的请求数 |
| `MCPBRIDGE_RATE_WINDOW_SECONDS` | `60` | 速率限制窗口 |
| `MCPBRIDGE_QUERY_TIMEOUT_MS` | `30000` | 每个查询的`statement_timeout` |
| `MCPBRIDGE_CONFIRMATION_TTL_SECONDS` | `600` | 分阶段写入等待确认的时间 |
| `MCPBRIDGE_SCHEMA_CACHE_TTL_SECONDS` | `300` | 模式缓存TTL |
| `MCPBRIDGE_HIGH_RISK_ROW_THRESHOLD` | `100` | 写入成为高风险操作时估计的影响行数 |
| `MCPBRIDGE_MAX_CONNECTIONS` | `10` | 连接池大小 |
| `MCPBRIDGE_AUDIT_LOG` | `mcpbridge-audit.jsonl` | 审计跟踪路径（每10 MB旋转） |
| `MCPBRIDGE_BLOCKED_TABLES` | — | 额外阻止的表的逗号分隔列表（系统凭证目录始终被阻止） |
| `MCPBRIDGE_TRANSPORT` | `stdio` | `stdio`或`http` |
| `MCPBRIDGE_HTTP_PORT` | `3920` | HTTP传输端口 |
## 安全模型
1. **领域验证（关闭失败）**。语句被词法分析（注释/字符串被清空），按类型分类，并检查禁止关键字（`DROP`，`TRUNCATE`，`ALTER`，`CREATE`，`GRANT`，`COPY`，...），凭证目录（`pg_shadow`，`pg_authid`，...），多语句有效载荷和CTE偷运写入（`WITH x AS (DELETE ...) SELECT ...`）。无法分类的任何内容都被拒绝。
2. **事务强制执行**。读取在`BEGIN TRANSACTION READ ONLY`中运行 — PostgreSQL本身拒绝任何写入。写入在它们自己的事务中运行，并在失败时回滚。
3. **人工确认**。写入被分阶段，预览（操作，目标表，规划器行估计，风险级别）并且仅在明确确认时执行 — 对于高风险操作执行两次。
4. **无处不在的删除**。已知机密，连接字符串密码和`password=`对从每个错误消息和审计行中被清除。
## 开发
```bash
npm run dev # 从源代码运行（tsx）
npm test # 65个单元测试（vitest），每个功能在<feature>/tests/中
npm run typecheck
node scripts/smoke.mjs # 标准输入上的端到端MCP协议烟雾测试
```
行为规范位于[features/](features/)中作为Gherkin文件 — 每个功能一个文件（`features/safe-querying.feature`，`features/guarded-writes.feature`，...），遵循标准的Cucumber布局。它们按场景记录预期行为，是单元测试的参考。有关完整工作流程和指南，请参见[docs/development.md](docs/development.md)。
## 许可证
MIT
## 致谢
MCPBridge的灵感来自[Claude Desktop](https://claude.ai/desktop)和[Cursor](https://cursor.so/)及其受控数据库访问流程。它与这两个产品无关。PostgreSQL是PostgreSQL全球开发组注册的商标。MCPBridge与PostgreSQL项目无关。项目由[@manulthanura](https://manulthanura.com)开发。
