# 連携ワークフロー (/ja/docs/verdent-for-vscode/advanced-features/integrations)

> 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 がステージングでテスト → PR ドキュメント化

***

### セキュリティを考慮した API 開発 [#セキュリティを考慮した-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-の設定例]

### 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 Specification](https://modelcontextprotocol.io/specification)
  * [MCP Server Registry](https://mcp.so/servers) - 利用可能な MCP サーバーを閲覧
  * [Official MCP Servers](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.so/servers](https://mcp.so/servers) にある公式の MCP サーバーレジストリには、利用可能なコミュニティサーバーが一覧表示されています。
</Note>

***

## チームコラボレーション [#チームコラボレーション]

### 共有 AGENTS.md 標準 [#共有-agentsmd-標準]

チーム全体での一貫性を保つためにバージョン管理にコミットします:

```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
```

**結果:** セキュリティとデータベースのベストプラクティスが適用された、十分にレビュー済みのエンドポイント。

***

## 連携のベストプラクティス [#連携のベストプラクティス]

### 段階的な導入 [#段階的な導入]

**フェーズ 1:** 基本的なルール

```markdown
## Code Standards
- Use TypeScript strict mode
- Run tests before commit
```

**フェーズ 2:** 専門的なサブエージェントを追加

```markdown
## Code Review
- Run @security-reviewer before PR
```

**フェーズ 3:** MCP を統合

```markdown
## Database Access
- Use MCP postgres-staging for queries
```

### 戦略的な組み合わせ [#戦略的な組み合わせ]

| 組み合わせ          | 目的                                  | 例                                       |
| -------------- | ----------------------------------- | --------------------------------------- |
| ルール + サブエージェント | ルールが *タイミング* を定義し、サブエージェントが *分析* する | AGENTS.md: 「@security-reviewer でレビューする」 |
| ルール + MCP      | ルールが *どの* サーバーかを指定し、MCP が *アクセス* する | AGENTS.md: 「db-staging のみを使用する」         |
| サブエージェント + MCP | サブエージェントが *外部データ* のために MCP を使用する    | セキュリティ監査が API エンドポイントを照会する              |

### チームドキュメントのベストプラクティス [#チームドキュメントのベストプラクティス]

チーム向けに連携をドキュメント化する際は、次の内容を含めます:

* **カスタムサブエージェント**: 各サブエージェントの名前、目的、呼び出すタイミングを記載
* **AGENTS.md ルール**: 各標準の「なぜ」を説明する根拠とともにルールを記載
* **MCP サーバー**: 各サーバーの目的、アクセスレベル (読み取り専用 / 書き込み)、使用するタイミングを記載
* **連携ワークフロー**: コンポーネントがどのように連携するかを示すワークフローの例を提供
* **トラブルシューティング**: 自分のセットアップ固有のよくある問題とその解決策を記載

<Tip>
  連携ドキュメントは `.mcp.json` や `AGENTS.md` ファイルと一緒にコミットしておくと、新しいチームメンバーがセットアップをすばやく理解できます。
</Tip>

***

## トラブルシューティング [#トラブルシューティング]

<Tabs>
  <Tab title="サブエージェントの問題">
    **問題:** 期待したタイミングでサブエージェントが呼び出されない

    **確認:**

    **場所**: ファイルが `~/.verdent/subagents/[name].md` に存在するか

    **YAML フロントマター**: 必須の `name` および `description` フィールドを含む有効な構文か

    **呼び出しポリシー**: 使い方に一致しているか (strict は明示的な @メンションが必要)

    **説明**: エージェントの `description` が、サブエージェントを使うべきタイミングを正確に記述しているか

    **再起動**: Verdent を再起動してサブエージェント定義を再読み込みしてみる

    ***

    **よくある原因:**

    * サブエージェントのファイル名や @メンションのタイプミス
    * フロントマターの 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` オブジェクト内の変数がシェルで正しく設定されているか

    **権限**: サーバー実行可能ファイルに適切な実行権限があるか

    ***

    **よくある原因:**

    * 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>