---
title: 整合工作流程
description: 將 Verdent 與外部工具及服務整合的實用模式
---



### 你將學到什麼

結合自訂子代理、規則與 MCP 伺服器，因應真實開發情境的實用整合工作流程。

---

## 整合方法

| 方法 | 最適用於 | 設定 |
|--------|----------|---------------|
| **自訂子代理** | AI 驅動的專門任務 | `~/.verdent/subagents/*.md` |
| **規則（AGENTS.md）** | 團隊標準與行為 | 專案根目錄 `AGENTS.md` |
| **MCP 伺服器** | 符合協定的外部工具 | `.mcp.json`（專案根目錄） |

**理念：** 結合多種方法，打造符合你需求的完整工作流程。

---

## 常見整合模式

### 資料庫開發工作流程

**技術組合：** Migration Reviewer 子代理 + AGENTS.md 標準 + PostgreSQL MCP 伺服器

**子代理：**
```markdown
---
name: migration-reviewer
description: Reviews database migrations for safety
---
Checks: Destructive operations, reversibility, indexing, blocking operations
```

**AGENTS.md：**
```markdown
## Database Standards
- All migrations reviewed by @migration-reviewer
- Test on staging before production
- Include rollback procedures
```

**MCP：** PostgreSQL 伺服器，用於執行查詢、檢查結構描述、驗證遷移

**工作流程：** 撰寫遷移 → @migration-reviewer 驗證 → MCP 在 staging 環境測試 → PR 文件

---

### 帶安全性的 API 開發

**技術組合：** Security Auditor + AGENTS.md 規則 + 自訂 API 測試工具

**組成元件：**
- **子代理：** `@api-security-auditor` - 輸入驗證、SQL 注入、認證、速率限制
- **規則：** 所有端點都需要安全性審查、公開 API 需有速率限制
- **外部工具：** 透過自訂整合進行自動化端點測試與安全性掃描

**結果：** 在 PR 核准前自動進行安全性審查。

<Note>
API 測試與安全性掃描工具可透過自訂 MCP 伺服器實作或其他整合方法進行整合，視你的工具鏈而定。
</Note>

---

### 前端無障礙性

**技術組合：** Accessibility Auditor + WCAG 規則 + Lighthouse 整合

**工作流程：**
```
Create component → @a11y-auditor reviews → Lighthouse tests accessibility → Rules enforce >90 score
```

<Note>
Lighthouse 及其他無障礙性工具可透過自訂 MCP 伺服器或 CI/CD 管線整合，視你的工作流程而定。
</Note>

---

## MCP 設定範例

### 認識 MCP

**Model Context Protocol（MCP）** 是一種開放協定，標準化應用程式向 LLM 提供上下文的方式。MCP 伺服器是實作該協定的可執行檔。它們不是資料庫連線或 API 端點，而是執行並透過 JSON-RPC 2.0 通訊的程式。

**關鍵概念：**
- **MCP 伺服器**：實作 MCP 協定的可執行檔（Node.js 套件、Python 指令稿等）
- **設定**：告訴 Verdent 如何啟動伺服器（`command` + `args`）
- **通訊**：伺服器自行處理其業務邏輯（查詢、API 呼叫等）

### 基本設定

**位置：** 專案根目錄下的 `.mcp.json`

<CodeGroup>
```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}"
      }
    }
  }
}
```
</CodeGroup>

**說明：**
- `mcpServers` - MCP 設定所需的最上層鍵
- `command` - 要執行的可執行檔（Node.js 套件通常為 `npx`）
- `args` - 傳遞給指令的引數（套件名稱、連線字串等）
- `env` - 用於認證／設定的環境變數

### 多環境

```json
{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DEV_DATABASE_URL}"
      ]
    },
    "postgres-staging": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${STAGING_DATABASE_URL}"
      ]
    },
    "postgres-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${PROD_DATABASE_URL}"
      ]
    }
  }
}
```

**最佳實務：** 使用環境變數存放連線字串，以確保憑證安全。MCP 伺服器會依其實作在內部處理唯讀行為。存取控制選項請參閱各伺服器的特定文件。

<Tip>
**深入了解 MCP：**
- [Model Context Protocol 規格](https://modelcontextprotocol.io/specification)
- [MCP 伺服器登錄](https://mcp.so/servers) - 瀏覽可用的 MCP 伺服器
- [官方 MCP 伺服器](https://github.com/modelcontextprotocol) - PostgreSQL、GitHub、Filesystem 等
</Tip>

---

## 工作區整合

### 專案專屬設定

**設定步驟：**
1. 儲存在專案根目錄：`.mcp.json`
2. 提交至版本控制以供團隊共用
3. 團隊成員自動使用專案的 MCP 伺服器

**微服務範例：**
```json
{
  "mcpServers": {
    "users-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/users"
      ]
    },
    "orders-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5433/orders"
      ]
    }
  }
}
```

<Note>
對於 Kafka 等其他服務，你會需要相容的 MCP 伺服器實作。官方 MCP 伺服器登錄 [mcp.so/servers](https://mcp.so/servers) 列出了可用的社群伺服器。
</Note>

---

## 團隊協作

### 共用的 AGENTS.md 標準

提交至版本控制以達成全團隊一致性：

```markdown
# AGENTS.md

## Code Review Process
- Run @code-reviewer before PR
- Address all security warnings
- Minimum 80% test coverage

## Integration Requirements
- @migration-reviewer for database changes
- @api-security-auditor for new endpoints
- @a11y-auditor for UI components

## MCP Servers
- Use postgres-staging MCP server for queries
- Never use postgres-prod MCP server for exploratory queries
```

**好處：** 一致的行為、強制執行的標準、自動化的品質關卡。

---

## 多代理協調

### 複雜功能工作流程

**範例：** 新的付款端點

```
1. Developer request → 2. Main agent generates code →
3. @api-security-auditor reviews security →
4. @migration-reviewer validates schema →
5. MCP tests on staging →
6. Main agent generates tests and PR
```

**結果：** 套用了安全性與資料庫最佳實務、經完整審查的端點。

---

## 整合最佳實務

### 漸進式採用

**第一階段：** 基本規則
```markdown
## Code Standards
- Use TypeScript strict mode
- Run tests before commit
```

**第二階段：** 加入專門子代理
```markdown
## Code Review
- Run @security-reviewer before PR
```

**第三階段：** 整合 MCP
```markdown
## Database Access
- Use MCP postgres-staging for queries
```

### 策略性組合

| 組合 | 用途 | 範例 |
|-------------|---------|---------|
| 規則 + 子代理 | 規則定義*何時*，子代理*分析* | AGENTS.md：「以 @security-reviewer 審查」 |
| 規則 + MCP | 規則指定*哪些*伺服器，MCP *存取* | AGENTS.md：「只使用 db-staging」 |
| 子代理 + MCP | 子代理使用 MCP 取得*外部資料* | Security auditor 查詢 API 端點 |

### 團隊文件最佳實務

為團隊撰寫整合文件時，應包含：

- **自訂子代理**：列出每個子代理的名稱、用途，以及何時呼叫它
- **AGENTS.md 規則**：記錄規則並附上理由，說明每項標準背後的「為什麼」
- **MCP 伺服器**：描述每個伺服器的用途、存取層級（唯讀／可寫），以及何時使用
- **整合工作流程**：提供範例工作流程，展示各元件如何協同運作
- **疑難排解**：記錄你特定設定中的常見問題及其解決方案

<Tip>
將整合文件與你的 `.mcp.json` 及 `AGENTS.md` 檔案一起提交，讓新團隊成員能快速理解你的設定。
</Tip>

---

## 疑難排解

<Tabs>
  <Tab title="子代理問題">
    **問題：** 子代理未在預期時呼叫

    **檢查：**

    **位置**：檔案存在於 `~/.verdent/subagents/[name].md`

    **YAML Frontmatter**：語法有效，且包含必要的 `name` 與 `description` 欄位

    **呼叫政策**：與使用方式相符（strict 需要明確的 @ 提及）

    **描述**：代理的 `description` 準確描述了應於何時使用該子代理

    **重新啟動**：嘗試重新啟動 Verdent 以重新載入子代理定義

    ---

    **常見原因：**
    - 子代理檔案名稱或 @ 提及有錯字
    - frontmatter 中的 YAML 語法無效
    - 子代理的 `description` 與任務上下文不符
  </Tab>

  <Tab title="AGENTS.md 問題">
    **問題：** AGENTS.md 規則未套用

    **檢查：**

    **位置**：檔案位於專案根目錄

    **語法**：有效的 Markdown，沒有解析錯誤

    **指令風格**：使用明確的命令（用「永遠使用…」而非「試著…」）

    **工作階段**：開啟新對話以測試規則是否重新套用

    **衝突**：檢查使用者規則是否無意間覆蓋了專案規則

    ---

    **常見原因：**
    - AGENTS.md 放在錯誤的目錄（必須在專案根目錄）
    - 模糊的指示讓 AI 有不同的解讀
    - 規則已套用但結果不如預期（請調整措辭）
  </Tab>

  <Tab title="MCP 伺服器問題">
    **問題：** MCP 伺服器無法啟動或連線

    **檢查：**

    **語法**：`.mcp.json` 含有效的 JSON（使用 `jq` 驗證）

    **結構**：最上層存在必要的 `mcpServers` 鍵

    **伺服器設定**：每個伺服器都正確指定了 `command` 與 `args`

    **套件**：MCP 伺服器套件可存取（`npx` 會自動下載套件；`-y` 旗標可略過確認提示）

    **環境**：`env` 物件中的變數已在你的 shell 中正確設定

    **權限**：伺服器可執行檔具有適當的執行權限

    ---

    **常見原因：**
    - JSON 中有錯字（缺少逗號、括號未閉合）
    - args 陣列中的套件名稱錯誤
    - 缺少或不正確的環境變數
    - 網路／防火牆阻擋了 npx 套件安裝

    ---

    **除錯步驟：**
    1. 驗證 JSON：`cat .mcp.json | jq .`
    2. 手動測試指令：`npx -y @modelcontextprotocol/server-postgres "postgresql://..."`
    3. 檢查環境：`echo $GITHUB_TOKEN`
    4. 查看 Verdent 記錄以取得具體的錯誤訊息
  </Tab>
</Tabs>

---

## 另請參閱

<CardGroup cols={2}>
  <Card title="擴充性指南" icon="puzzle-piece" href="/docs/verdent-for-vscode/advanced-features/extensibility">
    完整的擴充方法總覽
  </Card>
  <Card title="MCP 整合" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp">
    Model Context Protocol 詳細資訊
  </Card>
</CardGroup>