本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS Labs Aurora DSQL MCP 伺服器
適用於 Aurora DSQL 的 AWS 實驗室模型內容通訊協定 (MCP) 伺服器
## 功能
+ 將人類可讀的問題和命令轉換為結構化 Postgres 相容 SQL 查詢，並根據設定的 Aurora DSQL 資料庫執行它們。
+ 根據預設為唯讀，使用 啟用的交易 `--allow-writes`
+ 請求之間的連線重複使用以提升效能
+ 內建存取 Aurora DSQL 文件、搜尋和最佳實務建議
## 可用的工具
### 資料庫操作
+ **readonly\$1query** - 針對 DSQL 叢集執行唯讀 SQL 查詢
+ **交易** - 在交易中執行寫入操作 （需要 `--allow-writes`)
+ **get\$1schema** - 擷取資料表結構描述資訊
### 文件和建議
+ **dsql\$1search\$1documentation** - 搜尋 Aurora DSQL 文件
+ 參數： `search_phrase` （必要）、 `limit`（選用）
+ **dsql\$1read\$1documentation** - 讀取特定 DSQL 文件頁面
+ 參數： `url` （必要）、 `start_index`（選用）、 `max_length`（選用）
+ **dsql\$1recommend** - 取得 DSQL 最佳實務的建議
+ 參數：`url`（必要）
## 先決條件
1. 具有 [Aurora DSQL 叢集的 AWS](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) 帳戶
1. 此 MCP 伺服器只能在與 LLM 用戶端相同的主機上本機執行。
1. 設定可存取 AWS 服務的 AWS 登入資料
+ 您需要具有包含這些許可之角色的 AWS 帳戶：
+ `dsql:DbConnectAdmin` - 以管理員使用者身分連線至 DSQL 叢集
+ `dsql:DbConnect` - 使用自訂資料庫角色連線至 DSQL 叢集 （只有在使用非管理員使用者時才需要）
+ 使用 `aws configure`或 環境變數設定 AWS 登入資料
## 安裝
對於大多數工具，遵循[預設安裝](#default-installation)指示更新組態應該已足夠。
已針對 [Claude Code](#claude-code) 和 [Codex](#codex) 概述個別指示。
### 預設安裝：更新相關的 MCP Config 檔案
#### 使用 `uv`
1. `uv` 從 [Astral](https://docs.astral.sh/uv/getting-started/installation/) 或 [GitHub README](https://github.com/astral-sh/uv#installation) 安裝
1. 使用 安裝 Python `uv python install 3.10`
在 MCP 用戶端組態中設定 MCP 伺服器 [（尋找 MCP Config 檔案](#finding-mcp-config-file))
```
{
"mcpServers": {
"awslabs.aurora-dsql-mcp-server": {
"command": "uvx",
"args": [
"awslabs.aurora-dsql-mcp-server@latest",
"--cluster_endpoint",
"[your dsql cluster endpoint, e.g. abcdefghijklmnopqrst234567.dsql.us-east-1.on.aws]",
"--region",
"[your dsql cluster region, e.g. us-east-1]",
"--database_user",
"[your dsql username, e.g. admin]",
"--profile",
"[your aws profile, e.g. default]"
],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR"
},
"disabled": false,
"autoApprove": []
}
}
}
```
#### Windows 安裝
對於 Windows 使用者，MCP 伺服器組態格式略有不同：
```
{
"mcpServers": {
"awslabs.aurora-dsql-mcp-server": {
"disabled": false,
"timeout": 60,
"type": "stdio",
"command": "uv",
"args": [
"tool",
"run",
"--from",
"awslabs.aurora-dsql-mcp-server@latest",
"awslabs.aurora-dsql-mcp-server.exe"
],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR",
"AWS_PROFILE": "your-aws-profile",
"AWS_REGION": "us-east-1"
}
}
}
}
```
#### 尋找 MCP 用戶端組態檔案
對於一些最常見的代理程式開發工具，您可以在下列檔案路徑找到 MCP 用戶端組態：
+ Kiro：
+ 使用者組態： `~/.kiro/settings/mcp.json`
+ 工作區組態： `/path/to/workspace/.kiro/settings/mcp.json`
+ Claude Code：請參閱 [Claude Code Installation](#claude-code) 以取得詳細的設定說明
+ 使用者組態： `~/.claude.json` 中的 `"mcpServers"`
+ 專案組態： `/path/to/project/.mcp.json`
+ 本機組態： `~/.claude.json` 中的 `"projects" -> "path/to/project" -> "mcpServers"`
+ 游標：
+ 全域：`~/.cursor/mcp.json`
+ 專案： `/path/to/project/.cursor/mcp.json`
+ Codex： `~/.codex/config.toml`
+ 每個 MCP 伺服器都會在組態檔案中設定`[mcp_servers.]`資料表。請參閱[自訂 Codex 安裝說明](#codex)
+ 扭曲：
+ 檔案編輯： `~/.warp/mcp_settings.json`
+ 應用程式編輯器：`Settings > AI > Manage MCP Servers`並貼上 json
+ Amazon Q 開發人員 CLI： `~/.aws/amazonq/mcp.json`
+ Cline：通常是巢狀 VS 程式碼路徑 - `~/.vscode-server/path/to/cline_mcp_settings.json`
### Claude 程式碼
#### 先決條件
**重要：**MCP 伺服器管理只能透過 Claude Code CLI 終端機體驗使用，而非 VS Code 原生面板模式。
遵循 Claude 的[原生安裝建議程序](https://code.claude.com/docs/en/setup#native-install-recommended)，先安裝 Claude Code CLI。
#### 選擇正確的範圍
Claude Code 提供 3 種不同的範圍：本機 （預設）、專案和使用者和詳細資訊，以及根據憑證敏感度選擇範圍，且需要共用的詳細資訊。如需詳細資訊，請參閱 [MCP 安裝範圍](https://code.claude.com/docs/en/mcp#mcp-installation-scopes)上的 Claude Code 文件。
1. **本機範圍**伺服器代表預設組態層級，並存放在專案路徑`~/.claude.json`下的 中。它們**都是**私有的，並且只能在目前的專案目錄中存取。這是建立 MCP 伺服器`scope`時的預設值。
1. **專案範圍**伺服器**可啟用團隊協同合作**，同時仍可在專案目錄中存取。專案範圍伺服器會在專案的根目錄中新增`.mcp.json`檔案。此檔案旨在檢查版本控制，確保所有團隊成員都能存取相同的 MCP 工具和服務。當您新增專案範圍的伺服器時，Claude Code 會自動以適當的組態結構建立或更新此檔案。
1. **使用者範圍**伺服器存放在 中`~/.claude.json`，**並提供跨專案存取性**，讓它們可在機器上的所有專案中使用，同時保持**使用者帳戶的私有性。**
#### 使用 Claude CLI （建議）
使用互動式 `claude` CLI 工作階段可改善故障診斷體驗，因此這是建議的路徑。
```
claude mcp add amazon-aurora-dsql \
--scope [one of local, project, or user] \
--env FASTMCP_LOG_LEVEL="ERROR" \
-- uvx "awslabs.aurora-dsql-mcp-server@latest" \
--cluster_endpoint "[dsql-cluster-id].dsql.[region].on.aws" \
--region "[dsql cluster region, eg. us-east-1]" \
--database_user "[your-username]"
```
##### 故障診斷：在不同 AWS 帳戶上使用 Claude Code 搭配 Bedrock
如果您已使用與連線至 dsql 叢集所需的設定檔不同的 Bedrock AWS 帳戶或設定檔來設定 Claude Code，則需要提供額外的環境引數：
```
--env AWS_PROFILE="[dsql profile, eg. default]" \
--env AWS_REGION="[dsql cluster region, eg. us-east-1]" \
```
#### 組態檔案中的直接修改
Claude Code 需要英數字元命名，因此我們建議您為伺服器命名：`aurora-dsql-mcp-server`。
##### Local-Scope
`~/.claude.json` 在專案特定`mcpServers`欄位中更新：
```
{
"projects": {
"/path/to/project": {
"mcpServers": {}
}
}
}
```
##### 專案範圍
`/path/to/project/root/.mcp.json` 在 `mcpServers` 欄位中更新：
```
{
"mcpServers": {}
}
```
##### 使用者範圍
`~/.claude.json` 在專案特定`mcpServers`欄位中更新：
```
{
"mcpServers": {}
}
```
### Codex
#### 選項 1：Codex CLI
如果您已安裝 Codex CLI，您可以使用 codex mcp 命令來設定 MCP 伺服器。
```
codex mcp add amazon-aurora-dsql \
--env FASTMCP_LOG_LEVEL="ERROR" \
-- uvx "awslabs.aurora-dsql-mcp-server@latest" \
--cluster_endpoint "[dsql-cluster-id].dsql.[region].on.aws" \
--region "[dsql cluster region, eg. us-east-1]" \
--database_user "[your-username]"
```
#### 選項 2：config.toml
如需更精細地控制 MCP 伺服器選項，您可以手動編輯`~/.codex/config.toml`組態檔案。每個 MCP 伺服器都會在組態檔案中設定`[mcp_servers.]`資料表。
```
[mcp_servers.amazon-aurora-dsql]
command = "uvx"
args = [
"awslabs.aurora-dsql-mcp-server@latest",
"--cluster_endpoint", ".dsql..on.aws",
"--region", "",
"--database_user", ""
]
[mcp_servers.amazon-aurora-dsql.env]
FASTMCP_LOG_LEVEL = "ERROR"
```
### 驗證安裝
對於 Amazon Q Developer CLI、Kiro CLI、Claude CLI/TUI 或 Codex CLI/TUI，請執行 `/mcp`以查看 MCP 伺服器的狀態。
對於 Kiro IDE，您也可以導覽至 Kiro 面板的`MCP SERVERS`索引標籤，其中顯示所有設定的 MCP 伺服器及其連線狀態指示燈。
## 伺服器組態選項
### `--allow-writes`
根據預設，dsql mcp 伺服器不允許寫入操作 (「唯讀模式」)。任何交易工具的調用都會在此模式下失敗。若要使用交易工具，請傳遞 `--allow-writes` 參數以允許寫入。
我們建議您在連線至 DSQL 時使用最低權限存取。例如，使用者應盡可能使用唯讀的角色。唯讀模式具有最佳用戶端強制執行來拒絕變動。
### `--cluster_endpoint`
這是指定要連線之叢集的強制性參數。這應該是您叢集的完整端點，例如， `01abc2ldefg3hijklmnopqurstu.dsql.us-east-1.on.aws`
### `--database_user`
這是強制性參數，用於指定要連線的使用者。例如 `admin` 或 `my_user`。請注意，您使用的 AWS 登入資料必須具有以該使用者身分登入的許可。如需在 DSQL 中設定和使用資料庫角色的詳細資訊，請參閱[搭配 IAM 角色使用資料庫角色](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html)。
### `--profile`
您可以指定要用於登入資料的 aws 設定檔。請注意，Docker 安裝不支援此功能。
也支援在 MCP 組態中使用 `AWS_PROFILE`環境變數：
```
"env": {
"AWS_PROFILE": "your-aws-profile"
}
```
如果兩者皆未提供，則 MCP 伺服器會預設為使用 AWS 組態檔案中的「預設」設定檔。
### `--region`
這是強制性參數，用於指定 DSQL 資料庫的區域。
### `--knowledge-server`
為 DSQL 知識工具指定遠端 MCP 伺服器端點的選用參數 （文件搜尋、讀取和建議）。預設會預先設定。
範例：
```
--knowledge-server https://custom-knowledge-server.example.com
```
**注意：**為了安全起見，請僅使用信任的知識伺服器端點。伺服器應該是 HTTPS 端點。
### `--knowledge-timeout`
選用參數，以秒為單位指定對知識伺服器的請求逾時。
預設：`30.0`
範例：
```
--knowledge-timeout 60.0
```
如果您在存取慢速網路上的文件時遇到逾時，請提高此值。