# MCP 整合 (/zh-Hant/docs/verdent-manager/configuration/mcp)
> 透過 Model Context Protocol 伺服器與外掛擴充 Verdent
## 什麼是 MCP（Model Context Protocol）？ [#什麼是-mcpmodel-context-protocol]
Model Context Protocol（MCP）是一套整合系統，透過連接外部工具、資料來源與服務來擴充 Verdent 的能力。
**核心概念：**
MCP 讓 Verdent 能與其內建工具集以外的系統互動，實現與下列項目的無縫整合：
* 外部 API 與網路服務
* 資料庫系統
* 雲端平台（AWS、Azure、GCP）
* 專案管理工具
* CI/CD 流程
* 自訂內部工具
**架構：**
MCP 伺服器作為 Verdent 與外部系統之間的橋樑。每個 MCP 伺服器會公開特定能力，讓 Verdent 在編碼工作階段中呼叫，類似 `file_read` 或 `bash` 等內建工具。
**設定儲存：**
MCP 伺服器設定儲存於 `~/.verdent/mcp.json`，並透過設定選單管理。
***
## MCP 整合的優點 [#mcp-整合的優點]
### 擴充能力 [#擴充能力]
**存取外部系統：**
將 Verdent 連接到內建功能無法使用的工具與服務。查詢資料庫、與雲端服務互動，或整合專案特定的 API，全程無需離開你的編碼工作流程。
**自訂工具開發：**
針對專案的獨特需求打造客製化的 MCP 伺服器。為內部工具、專有 API 或特定領域的系統建立專屬整合。
### 互通性 [#互通性]
**運用生態系：**
接入持續成長的 MCP 生態系。社群開發的 MCP 伺服器為熱門工具與服務提供現成的整合方案。
**標準化協定：**
MCP 提供一致的工具整合介面，確保新能力能順暢地融入 Verdent 既有的工具系統。
### 工作流程自動化 [#工作流程自動化]
**無縫整合：**
MCP 伺服器會成為 Verdent 工具集的一部分。代理會在適當時機自動使用 MCP 工具，你也可以針對特定任務明確呼叫它們。
**情境感知操作：**
MCP 整合能理解你的程式碼庫上下文，根據目前的開發狀態與外部系統進行智慧互動。
***
## 設定 MCP 伺服器 [#設定-mcp-伺服器]
### 設定流程 [#設定流程]
**存取 MCP 設定：**
1. 在 Verdent 中開啟設定選單
2. 前往 **MCP Servers** 區段
3. 檢視或修改 `~/.verdent/mcp.json` 設定
**設定檔：**
MCP 伺服器透過 `~/.verdent/mcp.json` 檔案設定，該檔案定義伺服器連線、驗證與整合參數。完整結構請參閱下方的 **MCP 設定** 區段。
### 設定管理 [#設定管理]
**新增伺服器：**
在 `mcp.json` 中加入包含連線細節與驗證憑證的項目，即可設定新的 MCP 伺服器。
**多個伺服器：**
Verdent 支援多個並行的 MCP 伺服器，可同時整合數個外部系統。
**測試連線：**
驗證 MCP 伺服器設定，以確保在開發工作流程中使用前能成功連線。
### 伺服器狀態 [#伺服器狀態]
在 MCP 設定面板中監控連線狀態：
| 狀態 | 說明 |
| ----------- | ------------- |
| **Success** | 伺服器已連線，工具可供使用 |
| **Failed** | 連線錯誤（點擊以檢視詳情） |
| **Loading** | 伺服器初始化中 |
**重新整理工具：**
在設定變更或連線發生問題後，點擊重新整理按鈕以重新探索伺服器提供的可用工具。
***
## MCP 設定 [#mcp-設定]
### 基本設定 [#基本設定]
**位置：** 專案根目錄中的 `.mcp.json` 或 `~/.verdent/mcp.json`（全域）
```json PostgreSQL Server
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://localhost:5432/myapp_dev"
]
}
}
}
```
```json GitHub Server
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
```
```json Multiple Servers
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://localhost:5432/myapp_dev"
]
},
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
```
**設定鍵：**
* `mcpServers` - MCP 設定的必要頂層鍵
* `command` - 要執行的可執行檔（Node.js 套件通常為 `npx`）
* `args` - 傳遞給命令的引數（套件名稱、連線字串等）
* `env` - 用於驗證／設定的環境變數
**深入了解 MCP：**
* [Model Context Protocol 規範](https://modelcontextprotocol.io/specification)
* [MCP Server Registry](https://mcp.so/servers) - 瀏覽可用的 MCP 伺服器
* [官方 MCP 伺服器](https://github.com/modelcontextprotocol) - PostgreSQL、GitHub、Filesystem 等
***
## MCP 外掛與擴充 [#mcp-外掛與擴充]
### 可用的外掛 [#可用的外掛]
MCP 外掛為常見工具與服務提供現成的整合。請至 [mcp.so/servers](https://mcp.so/servers) 的社群登錄處，或 [官方 MCP 伺服器儲存庫](https://github.com/modelcontextprotocol) 瀏覽目前可用的項目。
**常見外掛類別：**
* **資料庫整合：** PostgreSQL、MySQL、MongoDB 查詢工具
* **雲端服務：** AWS、Azure、GCP API 互動
* **開發者工具：** GitHub、GitLab、Jira、Linear 整合
* **CI/CD 平台：** Jenkins、GitHub Actions、CircleCI
* **監控服務：** Datadog、New Relic、Sentry
* **通訊：** Slack、Discord、Microsoft Teams 通知
### 外掛安裝 [#外掛安裝]
**安裝方式：**
外掛透過 MCP 設定介面安裝與設定，通常需要：
* 外掛識別碼或來源
* 設定參數
* 驗證憑證（如適用）
**相依性管理：**
MCP 外掛可能相依於外部服務或函式庫。安裝程序會在可能時自動處理相依性解析。
***
## 自訂 MCP 伺服器開發 [#自訂-mcp-伺服器開發]
### 建立自訂伺服器 [#建立自訂伺服器]
進階使用者可建立自訂 MCP 伺服器，以整合專有工具或特定領域的系統。
**開發方式：**
自訂 MCP 伺服器實作 MCP 協定規範，公開可供 Verdent 呼叫的工具能力。實作細節與 SDK 請參閱 [Model Context Protocol 規範](https://modelcontextprotocol.io/specification)。
**自訂伺服器的使用情境：**
* **內部 API 整合：** 連接到公司專屬的 API 與服務
* **舊系統橋接：** 讓 Verdent 能與舊有基礎架構互動
* **專屬資料來源：** 存取專有資料庫或資料倉儲
* **工作流程自動化：** 觸發自訂的建置、部署或測試流程
### 整合模式 [#整合模式]
**工作區層級設定：**
MCP 伺服器可在工作區層級設定以供專案專屬整合，讓團隊能透過版本控制共用 MCP 設定。
**工具互通性：**
MCP 提供的工具能與 Verdent 的內建工具（`file_read`、`bash`、`spawn_subagent`）無縫整合，實現結合多種工具類型的複雜工作流程。
***
## Desktop 專屬的 MCP 功能 [#desktop-專屬的-mcp-功能]
### 各專案個別設定 [#各專案個別設定]
| 設定層級 | 位置 | 範圍 |
| ------------ | --------------------- | ------ |
| **全域** | `~/.verdent/mcp.json` | 所有專案 |
| **專案** | 專案根目錄中的 `.mcp.json` | 單一專案 |
| **Worktree** | 繼承自專案 | 繼承專案設定 |
### 多 Worktree MCP [#多-worktree-mcp]
MCP 伺服器可跨 worktree 運作：
* **共用伺服器：** 基礎工作區的 MCP 設定由所有 worktree 共用
* **隔離操作：** 每個 worktree 維護各自獨立的 MCP 工作階段狀態
* **並行存取：** 多個 worktree 可同時使用相同的 MCP 伺服器
### 專案切換 [#專案切換]
切換專案時：
* 載入目前專案的 MCP 伺服器
* 全域 MCP 伺服器仍可使用
* 先前專案的 MCP 連線於背景中維持
***
## MCP 工作流程範例 [#mcp-工作流程範例]
### 資料庫查詢整合 [#資料庫查詢整合]
**情境：** 查詢正式環境資料庫以除錯資料問題。
**MCP 做法：**
```
User: "Check the orders table for customer ID 12345"
Verdent: [Uses MCP database server to execute safe read-only query]
Results: 3 orders found for customer 12345
[Displays formatted results]
```
MCP 資料庫伺服器會處理驗證、查詢驗證與結果格式化。
### 雲端服務互動 [#雲端服務互動]
**情境：** 檢查 AWS Lambda 函式日誌以找出錯誤。
**MCP 做法：**
```
User: "Show me recent errors from the payment-processor Lambda function"
Verdent: [Invokes MCP AWS integration]
[Retrieves CloudWatch logs for specified function]
[Filters for ERROR level entries]
[Presents formatted error summaries]
```
MCP AWS 伺服器負責管理驗證、API 呼叫與日誌解析。
### CI/CD 流程監控 [#cicd-流程監控]
**情境：** 在部署變更前檢查建置狀態。
**MCP 做法：**
```
User: "Is the master branch build passing?"
Verdent: [Queries MCP CI/CD integration]
Build #245: ✓ Passed (2 minutes ago)
All tests passed, ready for deployment
```
MCP CI/CD 伺服器會追蹤流程狀態並提供即時回饋。
***
## 安全考量 [#安全考量]
### 驗證與授權 [#驗證與授權]
**憑證管理：**
MCP 伺服器負責處理對外部服務的驗證。憑證會安全地儲存在 MCP 設定中，絕不會出現在對話記錄或程式碼裡。
**權限範圍控管：**
為 MCP 伺服器設定最低必要的權限。盡可能使用唯讀存取，並限制破壞性操作。
### 安全操作 [#安全操作]
**命令審查：**
涉及 MCP 工具的操作會顯示在對話記錄中，提供可見性與控制權。
**稽核記錄：**
MCP 伺服器操作會出現在 Verdent 的對話記錄中，建立外部系統互動的稽核軌跡。
***
## MCP 整合疑難排解 [#mcp-整合疑難排解]
### 常見問題 [#常見問題]
**連線失敗：**
* 確認與 MCP 伺服器的網路連線
* 檢查 `mcp.json` 中的驗證憑證
* 確保 MCP 伺服器正在執行且可存取
* 驗證設定檔語法
**權限錯誤：**
* 確認 API 金鑰或憑證具備所需權限
* 檢查服務配額或速率限制
* 確認防火牆規則允許 MCP 流量
**工具呼叫問題：**
* 確保 MCP 伺服器正確公開預期的工具
* 檢查工具參數格式是否符合伺服器預期
* 查看 MCP 伺服器日誌以了解錯誤細節
### 取得協助 [#取得協助]
**支援管道：**
* Verdent 支援：[support@verdent.ai](mailto:support@verdent.ai)
* [MCP 協定文件](https://modelcontextprotocol.io)
* [Verdent Discord 社群](https://discord.com/invite/NGjXEZcbJq)
**診斷資訊：**
回報 MCP 問題時，請提供：
* MCP 伺服器類型與版本
* 設定細節（移除憑證後）
* 對話記錄中的錯誤訊息
* MCP 伺服器日誌（如可取得）
***
## 常見問題 [#常見問題-1]
MCP 伺服器操作會根據處理結果的模型消耗點數。MCP 伺服器本身不會直接使用點數。
不是。MCP 伺服器是在使用者層級設定，而非各專案。所有已設定的伺服器都可在你的所有專案中使用。
mcp.json 中的憑證會儲存在你本機的電腦上，絕不會傳送到 Verdent 伺服器。敏感值請使用環境變數（`${VAR_NAME}`）。
MCP 伺服器會在需要時啟動，並在你的工作階段期間執行。Verdent 關閉時不會消耗資源。
MCP 伺服器擁有你所設定的權限。請盡可能使用唯讀存取，並限制破壞性操作。
請 Verdent 使用 MCP 伺服器提供的某個工具。若成功回應，即表示連線正常運作。若發生問題，請參閱疑難排解區段。