npm package: @firejeff01/dbcli-server
Description: MCP Server for executing read-only database queries via CLI tools
Latest version: 2.0.0

# DB CLI MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)

> **[English README](./README.md)**

一個 **Model Context Protocol (MCP) 伺服器**，提供統一、安全、AI 友善的介面，透過 CLI 工具跨多種資料庫執行**唯讀查詢**。

---

## 目錄

- [功能特色](#功能特色)
- [支援的資料庫](#支援的資料庫)
- [安裝方式](#安裝方式)
- [快速開始](#快速開始)
- [AI IDE 與 CLI 工具整合](#ai-ide-與-cli-工具整合)
  - [Claude Code](#claude-code)
  - [Codex CLI](#codex-cli)
  - [Cursor](#cursor)
  - [VS Code (Copilot)](#vs-code-copilot)
  - [GitHub Copilot CLI](#github-copilot-cli)
  - [Visual Studio 2026](#visual-studio-2026)
- [MCP Tools 參考](#mcp-tools-參考)
- [連線模式](#連線模式)
- [安全性](#安全性)
- [設定檔](#設定檔)
- [開發指南](#開發指南)
- [系統架構](#系統架構)
- [授權條款](#授權條款)

---

## 功能特色

- **多資料庫支援** — SQL Server、MySQL、MariaDB、PostgreSQL、Oracle
- **唯讀強制執行** — 嚴格的 SELECT-only 查詢驗證，採用 fail-closed 原則
- **零設定啟動** — 即使沒有設定檔或 CLI 工具，伺服器也能正常啟動
- **自動偵測** — 掃描專案檔案（.env、appsettings.json、docker-compose.yml 等）自動發現資料庫設定
- **暫時連線** — 僅存於記憶體中的臨時連線，不會寫入磁碟
- **CLI 工具指引** — 偵測缺失的 CLI 工具並提供安裝教學
- **AI 原生設計** — 透過 MCP 協定與各種 AI IDE 和 CLI 工具無縫整合

---

## 支援的資料庫

| 資料庫       | CLI 工具   | 預設連接埠 |
|-------------|-----------|-----------|
| SQL Server  | `sqlcmd`  | 1433      |
| MySQL       | `mysql`   | 3306      |
| MariaDB     | `mariadb` | 3306      |
| PostgreSQL  | `psql`    | 5432      |
| Oracle      | `sqlplus` | 1521      |

---

## 安裝方式

### 前置需求

- **Node.js** 18 或更新版本
- 至少一個資料庫 CLI 工具已安裝（選用 — 伺服器在沒有 CLI 工具時也能運作）

### 透過 npm 安裝

```bash
npm install -g @firejeff01/dbcli-server
```

### 從原始碼安裝

```bash
git clone https://github.com/your-org/dbcli-mcp-server.git
cd dbcli-mcp-server
npm install
npm run build
```

---

## 快速開始

### 1. 啟動伺服器

```bash
# 透過 npx（無需安裝）
npx @firejeff01/dbcli-server --stdio

# 或者已全域安裝的情況
dbcli-mcp-server --stdio
```

### 2. 檢查系統狀態

使用 `doctor` 工具檢視 CLI 工具及設定狀態：

```json
{
  "serverVersion": "2.0",
  "cliStatus": [
    { "dbType": "mssql", "cli": "sqlcmd", "installed": true, "version": "17.10" },
    { "dbType": "mysql", "cli": "mysql", "installed": false }
  ],
  "issues": ["mysql not installed"]
}
```

### 3. 執行查詢

```json
// 輸入
{ "sql": "SELECT * FROM users LIMIT 10" }

// 輸出
{
  "success": true,
  "columns": ["id", "name", "email"],
  "rows": [
    { "id": "1", "name": "Alice", "email": "alice@example.com" }
  ],
  "rowCount": 1,
  "truncated": false
}
```

---

## AI IDE 與 CLI 工具整合

### Claude Code

[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 原生支援 MCP 伺服器。

#### 設定方式

將伺服器加入 Claude Code 的 MCP 設定：

```bash
claude mcp add dbcli -- npx @firejeff01/dbcli-server --stdio
```

或手動編輯 `~/.claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}
```

#### 使用方式

設定完成後，直接在 Claude Code 中詢問：

```
> 查詢 users 資料表，顯示前 10 筆資料
> 檢查系統上安裝了哪些資料庫 CLI 工具
> 建立一個連接到本地 MySQL 資料庫的暫時連線
> 掃描這個專案中的資料庫設定
```

---

### Codex CLI

[Codex CLI](https://github.com/openai/codex) 支援 MCP 協定整合。

#### 設定方式

編輯 Codex CLI 設定檔 `~/.codex/config.json`：

```json
{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}
```

#### 使用方式

```bash
codex "查詢本地 SQL Server 資料庫的 users 資料表"
codex "這個專案有哪些資料庫設定？"
```

---

### Cursor

[Cursor](https://cursor.com) 支援 MCP 伺服器，用於 AI 輔助開發。

#### 設定方式

1. 開啟 Cursor 設定：`Ctrl+Shift+J`（Windows/Linux）或 `Cmd+Shift+J`（macOS）
2. 導航到 **MCP** 區段
3. 點擊 **「Add new MCP server」**
4. 填入設定：

```json
{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}
```

或手動編輯專案根目錄下的 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}
```

#### 使用方式

在 Cursor 的 AI 聊天或 Composer 中：

```
@dbcli 執行 SELECT * FROM products WHERE price > 100
@dbcli 顯示 orders 資料表的結構
@dbcli 建立暫時連線到 postgres://localhost:5432/mydb
```

---

### VS Code (Copilot)

[VS Code](https://code.visualstudio.com/) 搭配 GitHub Copilot 支援 MCP 伺服器（需安裝 Copilot Chat）。

#### 設定方式

1. 安裝 **GitHub Copilot** 和 **GitHub Copilot Chat** 擴充套件
2. 開啟 VS Code 設定（`Ctrl+,`）
3. 在設定中搜尋 `mcp`
4. 編輯 `settings.json` 並加入：

```json
{
  "github.copilot.chat.mcp.servers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}
```

或在專案中建立 `.vscode/mcp.json`：

```json
{
  "servers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}
```

#### 使用方式

在 Copilot Chat 面板中：

```
@dbcli 這個專案設定了哪些資料庫連線？
@dbcli 對我的資料庫設定進行健康檢查
@dbcli SELECT COUNT(*) FROM orders WHERE status = 'pending'
```

---

### GitHub Copilot CLI

[GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) 可以利用 MCP 伺服器。

#### 設定方式

透過 `~/.config/github-copilot/config.json` 設定：

```json
{
  "mcpServers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}
```

#### 使用方式

```bash
gh copilot explain "如何使用 dbcli MCP 伺服器查詢資料庫"
```

---

### Visual Studio 2026

[Visual Studio 2026](https://visualstudio.microsoft.com/) 透過 AI 整合功能支援 MCP 伺服器。

#### 設定方式

1. 開啟 **工具** → **選項** → **GitHub Copilot** → **MCP Servers**
2. 點擊 **「新增伺服器」**
3. 設定：
   - **名稱**: `dbcli`
   - **命令**: `npx`
   - **參數**: `@firejeff01/dbcli-server --stdio`

或在方案根目錄建立 `.vs/mcp.json`：

```json
{
  "servers": {
    "dbcli": {
      "command": "npx",
      "args": ["@firejeff01/dbcli-server", "--stdio"]
    }
  }
}
```

#### 使用方式

在 Copilot Chat 視窗中：

```
@dbcli 查詢本月的客戶資料
@dbcli 檢查 sqlcmd 是否已安裝，如果沒有請顯示安裝指引
```

---

## MCP Tools 參考

### `doctor()`

回傳系統診斷資訊，包含伺服器版本、CLI 工具安裝狀態及偵測到的問題。

**參數**: 無

**回應範例**:
```json
{
  "serverVersion": "2.0",
  "cliStatus": [
    { "dbType": "mssql", "cli": "sqlcmd", "installed": true, "version": "17.10", "path": "/usr/bin/sqlcmd" }
  ],
  "issues": []
}
```

---

### `scanProjectDbConfigs()`

掃描當前專案目錄中常見設定檔的資料庫設定。

**掃描檔案**: `.env`、`.env.*`、`appsettings.json`、`application.yml`、`application.properties`、`docker-compose.yml`

**參數**: 無

**回應範例**:
```json
[
  {
    "dbType": "mssql",
    "host": "localhost",
    "port": 1433,
    "database": "ExampleDB",
    "source": "appsettings.json"
  }
]
```

---

### `initConfig()`

在 `.mcp/dbcli.config.json` 中建立或更新持久化設定 Profile。

**參數**:

| 參數名稱         | 型別   | 必填 | 說明                          |
|-----------------|--------|------|-------------------------------|
| profileName     | string | 是   | Profile 名稱（如 "dev"）       |
| dbType          | string | 是   | 資料庫類型                     |
| host            | string | 是   | 資料庫主機                     |
| database        | string | 是   | 資料庫名稱                     |
| port            | number | 否   | 連接埠                         |
| username        | string | 否   | 使用者名稱                     |
| password        | string | 否   | 密碼                           |
| timeoutSeconds  | number | 否   | 查詢逾時秒數（預設：30）        |
| maxRows         | number | 否   | 最大回傳筆數（預設：500）       |

---

### `setActiveProfile()`

切換作用中的設定 Profile。

**參數**:

| 參數名稱      | 型別   | 必填 | 說明               |
|-------------- |--------|------|--------------------|
| profileName   | string | 是   | 要啟用的 Profile 名稱 |

---

### `getInstallInstructions()`

回傳特定資料庫 CLI 工具的安裝指引（依作業系統區分）。

**參數**:

| 參數名稱 | 型別   | 必填 | 說明       |
|---------|--------|------|-----------|
| dbType  | string | 是   | 資料庫類型 |

**回應範例**:
```json
{
  "dbType": "mssql",
  "cli": "sqlcmd",
  "installed": false,
  "instructions": {
    "windows": "winget install Microsoft.SQLCMD",
    "linux": "sudo apt install mssql-tools",
    "macos": "brew install mssql-tools"
  }
}
```

---

### `createTemporaryConnection()`

建立僅存於記憶體中的暫時資料庫連線，永遠不會寫入磁碟。

**參數**:

| 參數名稱   | 型別   | 必填 | 說明         |
|-----------|--------|------|-------------|
| dbType    | string | 是   | 資料庫類型   |
| host      | string | 是   | 資料庫主機   |
| database  | string | 是   | 資料庫名稱   |
| port      | number | 否   | 連接埠       |
| username  | string | 否   | 使用者名稱   |
| password  | string | 否   | 密碼         |

**回應範例**:
```json
{
  "id": "uuid-string",
  "type": "temporary",
  "dbType": "mssql",
  "cli": "sqlcmd",
  "connection": {
    "host": "localhost",
    "database": "TestDB",
    "password": "***"
  }
}
```

---

### `runSelectQuery()`

透過對應的資料庫 CLI 工具執行唯讀 SQL 查詢。

**參數**:

| 參數名稱       | 型別   | 必填 | 說明                                      |
|---------------|--------|------|------------------------------------------|
| sql           | string | 是   | SELECT SQL 查詢語句                       |
| connectionId  | string | 否   | 暫時連線 ID（未指定時使用作用中的 Profile）   |

**允許的 SQL 類型**:
- `SELECT ...`
- `WITH ... SELECT ...`（CTE 通用資料表運算式）
- `EXPLAIN SELECT ...`

**回應範例**:
```json
{
  "success": true,
  "columns": ["id", "name"],
  "rows": [{ "id": "1", "name": "Alice" }],
  "rowCount": 1,
  "truncated": false
}
```

---

## 連線模式

| 模式           | 說明                                    | 持久性   |
|---------------|----------------------------------------|---------|
| **專案偵測**   | 自動從專案檔案偵測連線資訊                | 無       |
| **設定 Profile** | 儲存於 `.mcp/dbcli.config.json`       | 磁碟     |
| **暫時連線**   | 僅存於執行期間，透過 `createTemporaryConnection()` 建立 | 僅記憶體 |

### 設定檔結構

```json
{
  "version": 1,
  "activeProfile": "dev",
  "profiles": {
    "dev": {
      "dbType": "mssql",
      "cli": "sqlcmd",
      "connection": {
        "host": "localhost",
        "port": 1433,
        "database": "ExampleDb",
        "username": "app",
        "password": "${DB_PASSWORD}"
      },
      "limits": {
        "timeoutSeconds": 30,
        "maxRows": 500
      }
    }
  }
}
```

---

## 安全性

### 核心安全規則

1. **SELECT-only 查詢** — 所有 DML/DDL 操作嚴格禁止
2. **Fail-closed 驗證** — SQL 解析器無法判斷查詢類型時，一律拒絕
3. **認證資訊不暴露** — 所有 API 回應中的密碼皆被遮蔽
4. **結果筆數限制** — `maxRows` 防止過量資料擷取
5. **查詢逾時控制** — `timeoutSeconds` 自動終止長時間執行的查詢
6. **防止 Shell 注入** — CLI 執行使用 `execFile`（而非 `exec`），防止 Shell 注入攻擊
7. **多語句拒絕** — 分號分隔的多語句查詢一律阻擋
8. **暫時連線隔離** — 臨時連線永遠不會寫入磁碟

### 禁止的 SQL 操作

`INSERT`、`UPDATE`、`DELETE`、`MERGE`、`CREATE`、`ALTER`、`DROP`、`TRUNCATE`、`EXEC`、`EXECUTE`、`CALL`、`GRANT`、`REVOKE`、`SELECT INTO`

---

## 開發指南

```bash
# 安裝相依套件
npm install

# 編譯
npm run build

# 執行測試
npm test

# 以監看模式執行測試
npm run test:watch
```

### 專案結構

```
src/
├── index.ts                  # MCP Server 進入點 + Tool 定義
├── types.ts                  # 核心 TypeScript 型別
├── server/
│   └── ConnectionStore.ts    # 暫時連線記憶體儲存
├── validator/
│   └── SqlValidator.ts       # SQL 安全驗證
├── cli/
│   ├── CliManager.ts         # CLI 偵測 + 安裝指引
│   └── CliExecutor.ts        # 安全 CLI 執行
├── config/
│   └── ConfigManager.ts      # 設定檔管理
├── scanner/
│   └── ProjectScanner.ts     # 專案資料庫設定掃描
└── formatter/
    └── ResultFormatter.ts    # 查詢結果格式化
```

---

## 系統架構

```
AI 用戶端（Claude Code / Cursor / VS Code / Codex CLI / ...）
    │
    │  MCP 協定（JSON-RPC over stdio）
    ▼
┌──────────────────────────────┐
│       MCP Server Core        │
│  （Tool 路由 & 生命週期管理）  │
└──────────┬───────────────────┘
           │
     ┌─────┼─────┬──────────┬──────────┬──────────┐
     ▼     ▼     ▼          ▼          ▼          ▼
  專案     CLI   設定檔      SQL       CLI       結果
  掃描器   管理器 管理器    驗證器     執行器    格式化器
```

---

## 授權條款

MIT License。詳見 [LICENSE](./LICENSE)。