# 機能設計書 47-コンポーネント一覧取得

## 概要

本ドキュメントは、MCPサーバーによるUIパッケージのコンポーネントディレクトリ一覧取得機能の設計について記載する。この機能は、Model Context Protocol（MCP）を使用した開発支援ツールとして、UIコンポーネントの一覧を取得するAPIを提供する。

### 本機能の処理概要

**業務上の目的・背景**：Liamアプリケーションは、`@liam-hq/ui`パッケージに多数のUIコンポーネントを持つ。開発者やAIアシスタントがこれらのコンポーネントを効率的に参照・利用するために、コンポーネントの一覧を取得する機能が必要である。MCPサーバーを通じてこの情報を提供することで、開発支援ツールやAIコード生成の精度向上に貢献する。

**機能の利用シーン**：
- AIアシスタントが利用可能なUIコンポーネントを把握する際
- 開発者がコンポーネント一覧を確認する際
- コード生成ツールが適切なコンポーネントを選択する際

**主要な処理内容**：
1. MCPサーバーがツールリクエストを受信
2. UIパッケージのcomponentsディレクトリを読み取り
3. ディレクトリエントリをフィルタリング（ディレクトリのみ）
4. コンポーネント名のリストを改行区切りで返却

**関連システム・外部連携**：
- Model Context Protocol（MCP）
- @modelcontextprotocol/sdk
- Node.js fs/promises モジュール
- stdio トランスポート

**権限による制御**：MCPサーバーはローカル環境で実行され、ファイルシステムへの読み取りアクセス権限を持つ。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能は画面に直接関連しない開発支援ツール |

## 機能種別

開発支援ツール / API提供

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | 入力パラメータなし | - |

### 入力データソース

MCPクライアントからのツールリクエスト（stdioトランスポート経由）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| content | { type: 'text'; text: string }[] | コンポーネント名の改行区切りリスト |

### 出力先

MCPクライアントへのレスポンス

## 処理フロー

### 処理シーケンス

```
1. MCPクライアントからlist_componentsツールが呼び出される
2. uiComponentsPathを解決
   └─ frontend/packages/ui/src/components
3. fs.readdir でディレクトリ内容を取得
   └─ withFileTypes: true でDirentオブジェクトを取得
4. isDirectory() でフィルタリング
   └─ ディレクトリのみを抽出
5. ディレクトリ名を抽出
6. 改行区切りで結合して返却
```

### フローチャート

```mermaid
flowchart TD
    A[list_components呼び出し] --> B[uiComponentsPath解決]
    B --> C[fs.readdir実行]
    C --> D{成功?}
    D -->|No| E[エラーレスポンス返却]
    D -->|Yes| F[ディレクトリのみフィルタ]
    F --> G[名前を抽出]
    G --> H[改行区切りで結合]
    H --> I[成功レスポンス返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-47-01 | ディレクトリのみ | ファイルは除外し、ディレクトリのみを返却 | 常時 |
| BR-47-02 | 改行区切り | コンポーネント名は改行で区切って返却 | 常時 |
| BR-47-03 | 相対パス固定 | UIパッケージのcomponentsディレクトリを固定参照 | 常時 |

### 計算ロジック

**コンポーネントパス解決**：
```typescript
const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)
const uiComponentsPath = path.resolve(
  __dirname,
  '../../../packages/ui/src/components',
)
```

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本機能はデータベースを操作しない |

### テーブル別操作詳細

本機能はファイルシステムからの読み取りのみを行い、データベースは使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイルシステムエラー | ディレクトリ読み取り失敗 | エラーメッセージを返却 |

### リトライ仕様

ファイルシステム操作は通常即座に完了するため、リトライは不要。

## トランザクション仕様

本機能はファイルシステム読み取りのみであり、トランザクション管理は不要。

## パフォーマンス要件

- ディレクトリ読み取り: 即時（ミリ秒単位）
- コンポーネント数が数十個程度のため、性能影響は軽微

## セキュリティ考慮事項

- ローカル環境でのみ実行
- 読み取り専用操作
- 固定パスへのアクセスのみ（パストラバーサル不可）

## 備考

- MCPサーバー名: liam-development-mcp-server
- バージョン: 0.1.0
- ツール名: list_components
- stdioトランスポートを使用

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: MCPサーバーの構造を理解する

まず、MCPサーバーの基本構造と設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `frontend/internal-packages/mcp-server/src/index.ts` | サーバー定義とパス設定 |

**読解のコツ**:
- McpServerクラスのインスタンス化（17-20行目）
- uiComponentsPathの相対パス解決（12-15行目）

#### Step 2: list_componentsツールを理解する

コンポーネント一覧取得の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `frontend/internal-packages/mcp-server/src/index.ts` | list_componentsツールの実装 |

**主要処理フロー**:
1. **35行目**: `server.tool(...)` でツールを定義
2. **36行目**: ツール名 `'list_components'`
3. **37行目**: 説明文 `'Lists all component directories in the UI package'`
4. **38行目**: パラメータなし（空オブジェクト相当）
5. **39行目**: 非同期ハンドラ関数
6. **40-42行目**: `fs.readdir` でディレクトリ読み取り
7. **43-45行目**: `filter(entry.isDirectory())` でディレクトリのみ抽出
8. **46行目**: ディレクトリ名を抽出
9. **47行目**: 成功レスポンス返却

#### Step 3: エラーハンドリングを理解する

エラー発生時の処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `frontend/internal-packages/mcp-server/src/index.ts` | エラーハンドリング |

**主要処理フロー**:
- **48-55行目**: catch ブロック
- **49-50行目**: エラーメッセージの抽出
- **51-55行目**: McpToolErrorResult形式で返却

#### Step 4: サーバー起動を理解する

MCPサーバーの起動フローを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.ts | `frontend/internal-packages/mcp-server/src/index.ts` | main関数とサーバー接続 |

**主要処理フロー**:
- **138-147行目**: main関数
- **140行目**: 起動ログ出力
- **141行目**: `server.connect(new StdioServerTransport())` でstdio接続
- **142行目**: 接続完了ログ

### プログラム呼び出し階層図

```
MCPクライアント
    │
    └─ stdio トランスポート
           │
           └─ McpServer
                  │
                  └─ server.tool('list_components', ...)
                         │
                         ├─ fs.readdir(uiComponentsPath, { withFileTypes: true })
                         │
                         ├─ entries.filter(e => e.isDirectory())
                         │
                         └─ componentDirs.join('\n')
```

### データフロー図

```
[入力]                      [処理]                          [出力]

                     ┌─────────────────────────┐
MCPリクエスト ────────▶│   list_components      │
(パラメータなし)        │   ツールハンドラ        │
                     └──────────┬──────────────┘
                                │
                     ┌──────────▼──────────────┐
                     │   fs.readdir            │
                     │   (withFileTypes: true) │
                     └──────────┬──────────────┘
                                │
                     ┌──────────▼──────────────┐
                     │   filter(isDirectory)   │
                     └──────────┬──────────────┘
                                │
                     ┌──────────▼──────────────┐
                     │   map(dir.name)         │──────────▶ McpToolResult
                     │   join('\n')            │            { content: [{ type: 'text',
                     └─────────────────────────┘              text: 'Button\nInput\n...' }] }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `frontend/internal-packages/mcp-server/src/index.ts` | ソース | MCPサーバーのメイン実装 |
| components/ | `frontend/packages/ui/src/components/` | 対象ディレクトリ | コンポーネント格納ディレクトリ |
