MCP Db Bridge

🚀 mcp-db-bridge

mcp-db-bridge 是一個支持 MySQL、PostgreSQL 和 SQLite 的 MCP（Model Context Protocol）服務器，具備細粒度權限控制、多數據庫支持以及雲就緒的 SSL/TLS 功能。它採用適配器模式構建，具有良好的可擴展性。

English | Português

🚀 快速開始

安裝

npm install mcp-db-bridge
# 或者
pnpm add mcp-db-bridge

配置示例

MySQL（本地）

# .env
DB_TYPE=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASS=password
DB_NAME=mydb

PostgreSQL（本地）

# .env
DB_TYPE=postgresql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASS=password
DB_NAME=mydb

SQLite（內存數據庫）

# .env
DB_TYPE=sqlite
SQLITE_DB=:memory:

運行

pnpm build
pnpm start
# 或者
node dist/index.js

✨ 主要特性

• 🔌 多數據庫支持：支持 MySQL、PostgreSQL 和 SQLite。
• 🏗️ 適配器模式：架構清晰，易於擴展。
• ☁️ 雲就緒：支持 AWS RDS、Google Cloud SQL 和 Azure Database 的 SSL/TLS 連接。
• 🔒 安全優先：具備只讀模式和細粒度的模式權限控制。
• 🌐 多數據庫模式：可同時訪問多個模式或數據庫。
• 🔄 事務處理：自動處理 BEGIN/COMMIT/ROLLBACK。
• 🚀 HTTP 模式：可選的遠程 HTTP 服務器（基於 Express）。

📦 安裝指南

安裝依賴

npm install mcp-db-bridge
# 或者
pnpm add mcp-db-bridge

💻 使用示例

MySQL 搭配 Unix 套接字

DB_TYPE=mysql
MYSQL_SOCKET_PATH=/tmp/mysql.sock
DB_USER=root
DB_PASS=password
DB_NAME=mydb

帶權限控制的 PostgreSQL 多數據庫模式

DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASS=password
DB_NAME=                                      # 多數據庫模式
SCHEMA_INSERT_PERMISSIONS=app_db:true         # app_db 可以插入數據
SCHEMA_UPDATE_PERMISSIONS=app_db:true         # app_db 可以更新數據
SCHEMA_DELETE_PERMISSIONS=app_db:false        # app_db 禁止刪除數據

只讀模式的 SQLite

DB_TYPE=sqlite
SQLITE_DB=/var/lib/data/production.db
DB_READ_ONLY_MODE=true

帶 SSL 的 AWS RDS MySQL

DB_TYPE=mysql
DB_HOST=prod.abc123.us-east-1.rds.amazonaws.com
DB_PORT=3306
DB_USER=admin
DB_PASS=secure_password
DB_NAME=production
DB_SSL=true
DB_SSL_REJECT_UNAUTHORIZED=true
ALLOW_INSERT_OPERATION=false
ALLOW_UPDATE_OPERATION=false
ALLOW_DELETE_OPERATION=false
ALLOW_DDL_OPERATION=false

📚 詳細文檔

配置

數據庫類型

DB_TYPE=mysql          # MySQL
DB_TYPE=postgresql     # PostgreSQL
DB_TYPE=sqlite         # SQLite

連接設置

通用設置（適用於所有數據庫）

DB_HOST=127.0.0.1
DB_PORT=3306           # MySQL: 3306, PostgreSQL: 5432
DB_USER=root
DB_PASS=password
DB_NAME=mydb           # 留空表示啟用多數據庫模式
DB_CONNECTION_LIMIT=10

MySQL 特定設置（向後兼容）

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASS=password
MYSQL_DB=mydb
MYSQL_SOCKET_PATH=/tmp/mysql.sock  # Unix 套接字（優先於 host/port）

PostgreSQL 特定設置

POSTGRESQL_HOST=127.0.0.1
POSTGRESQL_PORT=5432
POSTGRESQL_DB=mydb

SQLite 特定設置

SQLITE_DB=:memory:              # 內存數據庫
SQLITE_DB=/var/lib/app/data.db  # 文件數據庫

安全與權限

只讀模式

在應用層阻止所有寫操作：

DB_READ_ONLY_MODE=true

全局寫權限

按操作類型進行細粒度的全局控制：

ALLOW_INSERT_OPERATION=true   # 允許 INSERT 操作
ALLOW_UPDATE_OPERATION=true   # 允許 UPDATE 操作
ALLOW_DELETE_OPERATION=false  # 阻止 DELETE 操作
ALLOW_DDL_OPERATION=false     # 阻止 CREATE/ALTER/DROP/TRUNCATE 操作

模式特定權限

覆蓋特定模式的全局權限：

# 格式: "schema1:true,schema2:false,schema3:true"
SCHEMA_INSERT_PERMISSIONS=prod_db:false,test_db:true,staging_db:true
SCHEMA_UPDATE_PERMISSIONS=prod_db:false,test_db:true,staging_db:true
SCHEMA_DELETE_PERMISSIONS=prod_db:false,test_db:false,staging_db:false
SCHEMA_DDL_PERMISSIONS=prod_db:false,test_db:true,staging_db:false

工作原理：

• 如果模式有特定權限，則使用該權限。
• 否則，使用全局標誌。

示例：

# 全局設置：禁止 INSERT 操作
ALLOW_INSERT_OPERATION=false

# test_db 可以插入數據，prod_db 禁止插入數據
SCHEMA_INSERT_PERMISSIONS=test_db:true,prod_db:false

# 結果：
# - 在 test_db 上執行 INSERT 操作：✅ 允許（使用模式權限）
# - 在 prod_db 上執行 INSERT 操作：❌ 禁止（使用模式權限）
# - 在 other_db 上執行 INSERT 操作：❌ 禁止（使用全局權限）

多數據庫模式

通過單個連接訪問多個數據庫或模式。

激活

將 DB_NAME 留空（僅適用於 MySQL/PostgreSQL）：

DB_TYPE=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASS=password
DB_NAME=                # 留空表示啟用多數據庫模式

寫保護

默認情況下，為了安全起見，多數據庫模式為只讀模式。若要允許寫操作：

MULTI_DB_WRITE_MODE=true  # ⚠️ 謹慎使用！

建議：使用 SCHEMA_*_PERMISSIONS 進行細粒度控制，而不是直接設置 MULTI_DB_WRITE_MODE=true。

完整示例

# 帶細粒度權限的多數據庫模式
DB_TYPE=mysql
DB_NAME=                                    # 多數據庫模式
ALLOW_INSERT_OPERATION=false                # 全局設置：禁止插入
SCHEMA_INSERT_PERMISSIONS=test_db:true      # 例外：test_db 可以插入數據
SCHEMA_UPDATE_PERMISSIONS=test_db:true      # 例外：test_db 可以更新數據
SCHEMA_DELETE_PERMISSIONS=test_db:false     # test_db 禁止刪除數據
SCHEMA_DDL_PERMISSIONS=test_db:true         # test_db 允許 DDL 操作

雲數據庫的 SSL/TLS 配置

AWS RDS（MySQL/PostgreSQL）

DB_TYPE=mysql
DB_HOST=myinstance.123456789012.us-east-1.rds.amazonaws.com
DB_PORT=3306
DB_SSL=true
DB_SSL_REJECT_UNAUTHORIZED=true
# 可選：DB_SSL_CA=/path/to/aws-rds-ca-cert.pem

Google Cloud SQL（PostgreSQL）

DB_TYPE=postgresql
DB_HOST=34.123.45.67
DB_PORT=5432
DB_SSL=true
DB_SSL_CA=/path/to/server-ca.pem
DB_SSL_CERT=/path/to/client-cert.pem
DB_SSL_KEY=/path/to/client-key.pem

Azure Database for MySQL

DB_TYPE=mysql
DB_HOST=myserver.mysql.database.azure.com
DB_PORT=3306
DB_SSL=true
DB_SSL_REJECT_UNAUTHORIZED=true

遠程 MCP（HTTP 服務器）

通過 HTTP 運行 MCP 服務器並進行身份驗證：

# .env
IS_REMOTE_MCP=true
REMOTE_SECRET_KEY=your-secret-key-here
PORT=3000

端點：POST http://localhost:3000/mcp

請求頭：Authorization: Bearer your-secret-key-here

🔧 技術細節

架構

src/
├── db/
│   ├── adapters/
│   │   ├── types.ts              # 接口和類型定義
│   │   ├── factory.ts            # 工廠模式
│   │   ├── mysql.adapter.ts      # 通過 mysql2 實現的 MySQL 適配器
│   │   ├── postgresql.adapter.ts # 通過 pg 實現的 PostgreSQL 適配器
│   │   └── sqlite.adapter.ts     # 通過 better-sqlite3 實現的 SQLite 適配器
│   ├── index.ts                  # 核心查詢處理程序
│   ├── utils.ts                  # SQL 解析（使用 node-sql-parser）
│   └── permissions.ts            # 模式權限檢查
├── config/
│   └── index.ts                  # 環境配置
├── utils/
│   └── index.ts                  # 日誌記錄和工具函數
└── types/
    └── index.ts                  # 類型定義

適配器模式

每個適配器都實現了 DatabaseAdapter 接口：

export interface DatabaseAdapter {
  readonly type: DatabaseType;
  createPool(config: ConnectionConfig): Promise<DatabasePool>;
  executeQuery<T>(pool: DatabasePool, sql: string, params?: any[]): Promise<T>;
  setReadOnly(connection: DatabaseConnection): Promise<void>;
  unsetReadOnly(connection: DatabaseConnection): Promise<void>;
  normalizeResult(result: any): NormalizedResult;
  supportsReadOnlyMode(): boolean;
}

事務流程

讀操作：

BEGIN → SET TRANSACTION READ ONLY → QUERY → ROLLBACK → RESET TO READ WRITE

寫操作：

BEGIN → QUERY → COMMIT (或在出錯時 ROLLBACK)

📄 許可證

本項目採用 MIT 許可證。

致謝

• mcp-server-mysql：@benborla