Kiro と Claude Opus 4 が直接会話するための MCPサーバーを Specモード で作った

# 要件定義書

## 概要

この仕様書は、Kiro IDE ユーザーが Model Context Protocol (MCP) を通じて AWS Bedrock の Amazon Nova + Claude の 3 つの AI モデルと用途別に対話できる Claude MCP サーバーの要件を定義します。このサーバーは、コスト効率を考慮した適切なモデル選択、エラーハンドリング、セキュリティ対策を維持しながら、テキストベースの会話のためのシンプルで信頼性の高いインターフェースを提供します。

## システム概要図

```mermaid
flowchart TD
    A[Kiro IDE ユーザー] --> B[MCP クライアント
Kiro IDE 内蔵]
    B --> C[MCP サーバー
claude_opus_mcp]
    C --> D[AWS Bedrock API]

    D --> E[Amazon Nova Micro
超低コスト]
    D --> F[Claude Sonnet 4
バランス型]
    D --> G[Claude Opus 4
最高性能]

    E --> D
    F --> D
    G --> D
    D --> C
    C --> B
    B --> A

    H[AWS プロファイル
認証情報] --> C
    I[mcp.json
設定ファイル] --> B

    style A fill:#64b5f6,stroke:#1976d2,color:#000
    style B fill:#4caf50,stroke:#2e7d32,color:#000
    style C fill:#ff9800,stroke:#f57c00,color:#000
    style D fill:#9c27b0,stroke:#7b1fa2,color:#fff
    style E fill:#00bcd4,stroke:#0097a7,color:#000
    style F fill:#4caf50,stroke:#2e7d32,color:#000
    style G fill:#4caf50,stroke:#2e7d32,color:#000
```

## 技術前提知識

本仕様書は以下の技術知識を前提とします：

- **AWS Bedrock**: Foundation Model サービスの基本概念
- **IAM**: ロールとポリシーの設定経験
- **Python**: 中級レベルのプログラミング経験
- **JSON**: 設定ファイルの読み書き
- **CLI**: コマンドライン操作の基本
- **API**: REST API の基本概念

## データフロー図

```mermaid
sequenceDiagram
    participant U as Kiro ユーザー
    participant K as Kiro IDE
    participant M as MCP サーバー
    participant B as AWS Bedrock
    participant C as AIモデル
(Nova/Sonnet/Opus)

    U->>K: "Claude に質問して"
    K->>M: chat_with_claude_opus(message, temperature)
    M->>M: AWS 認証情報取得
    M->>B: invoke_model() API 呼び出し
    B->>C: メッセージ送信
    C->>B: 応答生成
    B->>M: API レスポンス
    M->>M: レスポンス処理
    M->>K: MCP レスポンス
    K->>U: Claude の回答表示

    Note over M,B: IAM 権限: bedrock:InvokeModel
    Note over B,C: モデル ID: anthropic.claude-opus-4-20250514-v1:0
```

## 要件

### 要件 1: 用途別 AI モデルとの会話機能

**ユーザーストーリー:** Kiro IDE ユーザーとして、MCP ツールを通じて用途に応じて最適な AI モデル（Amazon Nova Micro, Claude Sonnet 4, Claude Opus 4）にメッセージを送信したい。これにより、コスト効率を考慮しながら開発環境内で直接各モデルの特性を活用できるようになる。

#### 技術仕様フロー

```mermaid
flowchart TD
    A[ユーザー入力
メッセージ + temperature] --> B{入力検証}
    B -->|有効| C[AWS Bedrock API 呼び出し]
    B -->|無効| D[エラーレスポンス]
    C --> E{API 成功?}
    E -->|成功| F[Claude レスポンス取得]
    E -->|失敗| G[API エラー処理]
    F --> H[5秒以内レスポンス]
    G --> I[エラーメッセージ返却]
    H --> J[ユーザーに結果表示]
    I --> J

    style A fill:#64b5f6,stroke:#1976d2,color:#000
    style C fill:#9c27b0,stroke:#7b1fa2,color:#fff
    style F fill:#4caf50,stroke:#2e7d32,color:#000
    style H fill:#00bcd4,stroke:#0097a7,color:#000
```

#### 受け入れ基準

1. ユーザーが chat_casual ツールを呼び出した時、システムは Amazon Nova Micro モデルにメッセージを送信すること
2. ユーザーが chat_professional ツールを呼び出した時、システムは Claude Sonnet 4 モデルにメッセージを送信すること
3. ユーザーが chat_expert ツールを呼び出した時、システムは Claude Opus 4 モデルにメッセージを送信すること
4. 各モデルが応答した時、システムは 5 秒以内にユーザーに応答テキストを返すこと
5. メッセージが 4000 トークンを超えた時、システムはトークン制限超過を示すエラーメッセージを返すこと
6. ユーザーが temperature パラメータ（0.0-1.0）を提供した時、システムは応答生成にその値を使用すること
7. temperature が提供されない場合、システムはデフォルト値として 0.7 を使用すること

### 要件 2: エラーハンドリングとトラブルシューティング

**ユーザーストーリー:** Kiro IDE ユーザーとして、何か問題が発生した時に明確なエラーメッセージが欲しい。これにより、MCP サーバーの問題を迅速に理解し解決できるようになる。

#### エラー処理フロー

```mermaid
flowchart TD
    A[エラー発生] --> B{エラー種別判定}
    B -->|認証エラー| C[AWS 認証失敗
IAM/プロファイル確認]
    B -->|API エラー| D[Bedrock API エラー
権限/モデルアクセス確認]
    B -->|ネットワークエラー| E[接続エラー
ネットワーク確認]
    B -->|その他| F[予期しないエラー
ログ記録]

    C --> G[ユーザー向けメッセージ]
    D --> G
    E --> G
    F --> G

    G --> H[デバッグログ出力]
    H --> I[エラーレスポンス返却]

    style A fill:#ff5722,stroke:#d32f2f,color:#fff
    style C fill:#ff9800,stroke:#f57c00,color:#000
    style D fill:#ff9800,stroke:#f57c00,color:#000
    style E fill:#ff9800,stroke:#f57c00,color:#000
    style F fill:#ff9800,stroke:#f57c00,color:#000
    style I fill:#64b5f6,stroke:#1976d2,color:#000
```

#### 受け入れ基準

1. AWS 認証が失敗した時、システムは「AWS 認証に失敗しました。認証情報と AWS プロファイル設定を確認してください。」を返すこと
2. Bedrock API がエラーを返した時、システムは「Bedrock API エラー: [具体的なエラー]。Bedrock アクセス権限を確認してください。」を返すこと
3. ネットワーク接続が失敗した時、システムは「ネットワーク接続に失敗しました。インターネット接続を確認してください。」を返すこと
4. AI モデルアクセスが拒否された時、システムは「AI モデルアクセスが拒否されました。AWS Bedrock コンソールでモデルアクセス（Amazon Nova Micro, Claude Sonnet 4, Claude Opus 4）を有効にしてください。」を返すこと
5. 任意のエラーが発生した時、システムはデバッグ目的で詳細なエラーをログに記録すること

### 要件 3: Kiro IDE 統合とセットアップ

**ユーザーストーリー:** Kiro IDE ユーザーとして、MCP サーバーが Kiro の設定とシームレスに統合されることを望む。これにより、複雑なセットアップ手順なしに使用できるようになる。

#### 統合アーキテクチャ

```mermaid
flowchart TD
    A[mcp.json 設定ファイル] --> B[Kiro IDE MCP クライアント]
    B --> C[MCP サーバー起動
python -m claude_opus_mcp]

    D[AWS プロファイル
~/.aws/credentials] --> E[環境変数
MCP_AWS_PROFILE]
    E --> C

    C --> F[MCP プロトコル
ハンドシェイク]
    F --> G[ツール登録
chat_with_claude_opus]
    G --> H[Kiro でツール利用可能]

    I[autoApprove 設定] --> B

    style A fill:#4caf50,stroke:#2e7d32,color:#000
    style B fill:#64b5f6,stroke:#1976d2,color:#000
    style C fill:#ff9800,stroke:#f57c00,color:#000
    style D fill:#9c27b0,stroke:#7b1fa2,color:#fff
    style H fill:#00bcd4,stroke:#0097a7,color:#000
```

#### 受け入れ基準

1. MCP サーバーが mcp.json で設定された時、Kiro は利用可能な MCP サーバーとして認識すること
2. サーバーが開始された時、適切な JSON スキーマで chat_with_claude_opus ツールを登録すること
3. ユーザーが autoApprove を設定している時、ツールは手動承認プロンプトなしで実行されること
4. サーバーが MCP_AWS_PROFILE 環境変数を使用する時、指定された AWS プロファイルを使用して認証すること
5. MCP_AWS_PROFILE が設定されていない場合、システムはデフォルトの AWS プロファイルを使用すること

### 要件 4

**ユーザーストーリー:** 開発者として、MCP サーバーが Python のベストプラクティスと MCP プロトコル標準に従うことを望む。これにより、保守可能で信頼性の高いものになる。

#### 受け入れ基準

1. サーバーがインストールされた時、`python -m claude_opus_mcp` で実行可能であること
2. サーバーが開始された時、適切な MCP プロトコルハンドシェイクを実装すること
3. サーバーがツール呼び出しを受信した時、JSON スキーマに従って入力パラメータを検証すること
4. サーバーが例外に遭遇した時、クラッシュすることなく適切に処理すること
5. サーバーがリクエストを処理する時、通常の条件下で 95% の成功率を維持すること

### 要件 5

**ユーザーストーリー:** システム管理者として、MCP サーバーが AWS 認証情報を安全に処理することを望む。これにより、機密情報が露出したり悪用されたりしないようになる。

#### 受け入れ基準

1. AWS 認証情報が必要な時、システムは AWS プロファイルまたは環境変数のみを使用すること
2. 認証情報が読み込まれた時、システムは平文でログに記録したり露出したりしないこと
3. AWS プロファイルを使用する時、システムは AWS CLI 認証情報の優先順位を尊重すること
4. IAM 権限が不十分な時、システムは必要な権限について明確なガイダンスを提供すること
5. サーバーが実行される時、3 つの AI モデル（Amazon Nova Micro, Claude Sonnet 4, Claude Opus 4）に対する bedrock:InvokeModel 権限のみを必要とすること

### 要件 6: テスト要件とコスト最適化

**ユーザーストーリー:** 開発者として、コスト効率的にテストを実行したい。これにより、開発コストを抑制しながら品質を確保できるようになる。

#### テスト用モデル設定フロー

```mermaid
flowchart TD
    A[テスト実行] --> B{テスト種別}
    B -->|単体テスト| C[モック使用
コスト: $0]
    B -->|統合テスト| D[Claude Sonnet 4
コスト効率重視]
    B -->|本番確認| E[Claude Opus 4
最終検証のみ]

    D --> F[基本機能確認
anthropic.claude-sonnet-4-20250514-v1:0]
    E --> G[高度推論確認
anthropic.claude-opus-4-20250514-v1:0]

    style C fill:#4caf50,stroke:#2e7d32,color:#000
    style D fill:#ff9800,stroke:#f57c00,color:#000
    style E fill:#9c27b0,stroke:#7b1fa2,color:#fff
```

#### 受け入れ基準

1. システムは設定可能なモデル ID をサポートし、テスト時は Claude Sonnet 4 (anthropic.claude-sonnet-4-20250514-v1:0) を使用できること
2. 単体テストでは AWS API 呼び出しをモック化し、実際のコストを発生させないこと
3. 統合テストでは Claude Sonnet 4 を使用して基本的な会話機能を検証すること
4. 本番リリース前の最終確認でのみ Claude Opus 4 を使用し、日常的なテストでは Amazon Nova Micro や Claude Sonnet 4 を使用すること
5. テスト設定は環境変数 MCP_TEST_MODEL_ID で切り替え可能であること

## AWS 技術要件

### 必要な AWS サービス知識

#### AWS Bedrock

- **Foundation Models**: Amazon Nova Micro, Claude Sonnet 4, Claude Opus 4 モデルの特性理解
- **API 呼び出し**: invoke_model() メソッドの使用方法
- **モデル ID**:
  - Amazon Nova Micro: amazon.nova-micro-v1:0
  - Claude Sonnet 4: us.anthropic.claude-sonnet-4-20250514-v1:0
  - Claude Opus 4: us.anthropic.claude-opus-4-20250514-v1:0
- **リージョン**: us-east-1, us-east-2, us-west-2 での利用可能性

#### IAM 権限設定

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["bedrock:InvokeModel"],
      "Resource": "arn:aws:bedrock:*::foundation-model/anthropic.claude-opus-4-20250514-v1:0"
    }
  ]
}
```

#### AWS CLI プロファイル設定

```ini
# ~/.aws/credentials
[your-profile]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY

# ~/.aws/config
[profile your-profile]
region = us-east-1
```

### パフォーマンス要件

#### レスポンス時間

- **目標**: 5 秒以内
- **測定方法**: API 呼び出し開始から MCP レスポンス返却まで
- **タイムアウト**: 30 秒でタイムアウト処理

#### スループット

- **同時接続**: 1 接続（Kiro IDE からの単一セッション）
- **リクエスト頻度**: 制限なし（AWS Bedrock の制限に従う）

### セキュリティ要件

#### 認証情報管理

- AWS プロファイルまたは環境変数のみ使用
- 認証情報の平文ログ出力禁止
- IAM 最小権限の原則に従う

#### ネットワークセキュリティ

- HTTPS 通信のみ（AWS Bedrock API）
- ローカル実行（外部からのアクセス不要）

## 参考ドキュメント

### AWS 公式ドキュメント

- [Amazon Nova Models in Amazon Bedrock](https://aws.amazon.com/bedrock/nova/)
  - Amazon Nova Micro モデル ID と利用可能リージョンの確認
- [Introducing Claude 4 in Amazon Bedrock - AWS News Blog](https://aws.amazon.com/blogs/aws/claude-opus-4-anthropics-most-powerful-model-for-coding-is-now-in-amazon-bedrock/)
  - Claude Sonnet 4 / Opus 4 モデル ID と利用可能リージョンの確認
- [InvokeModel - Amazon Bedrock API Reference](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)
  - Bedrock API の基本仕様
- [Bedrock Converse API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html)
  - 推奨される統一 API インターフェース

### MCP プロトコル仕様

- [MCP Release Notes - Speakeasy](https://www.speakeasy.com/mcp/release-notes)
  - 2025 年最新仕様（Streamable HTTP、OAuth 2.1 対応）
- [Model Context Protocol (MCP) - GeeksforGeeks](https://www.geeksforgeeks.org/artificial-intelligence/model-context-protocol-mcp/)
  - MCP の基本概念と標準化フレームワーク

### 技術実装参考

- [Model context protocol (MCP) - OpenAI Agents SDK](https://openai.github.io/openai-agents-python/mcp/)
  - Python SDK の実装例とベストプラクティス

# 設計文書

## 概要

Claude MCP サーバーは、Kiro IDE と AWS Bedrock の Amazon Nova + Claude の 3 つの AI モデルを橋渡しする軽量なプロキシサーバーです。MCP プロトコルに準拠し、用途別モデル選択によるコスト効率化を実現しながら、シンプルで信頼性の高い会話インターフェースを提供します。

## アーキテクチャ

### パッケージ構造とコンポーネント関係

```mermaid
graph TB
    subgraph "プロジェクトルート"
        A[setup.py
パッケージ設定・依存関係]
        B[requirements.txt
Python依存関係定義]
    end

    subgraph "claude_opus_mcp パッケージ"
        D[__init__.py
パッケージ初期化・エクスポート]
        E[__main__.py
エントリーポイント・起動制御]
        F[server.py
MCPプロトコル実装]
        G[bedrock_client.py
AWS Bedrock API クライアント]
        H[config.py
設定管理・環境変数処理]
        I[tool_handlers.py
ツール実行ロジック]
        J[exceptions.py
カスタム例外定義]
    end

    A --> D
    A -.-> B
    E --> F
    F --> I
    I --> G
    G --> H
    F --> H
    G --> J
    I --> J

    style D fill:#64b5f6,stroke:#1976d2,color:#000
    style E fill:#4caf50,stroke:#2e7d32,color:#000
    style F fill:#ff9800,stroke:#f57c00,color:#000
    style G fill:#9c27b0,stroke:#7b1fa2,color:#fff
    style H fill:#00bcd4,stroke:#0097a7,color:#000
```

### 実装レベルでのデータフロー

```mermaid
sequenceDiagram
    participant U as Kiro ユーザー
    participant K as Kiro MCP クライアント
    participant S as server.py
    participant T as tool_handlers.py
    participant B as bedrock_client.py
    participant C as config.py
    participant A as AWS Bedrock API

    U->>K: チャット入力
    K->>S: MCP call_tool(name, arguments)
    S->>S: ツール名検証
    S->>T: handle_chat_xxx(arguments)
    T->>C: get_model_by_purpose(purpose)
    C-->>T: model_id
    T->>B: chat_with_model(message, model_id, temperature)
    B->>C: get_aws_session()
    C-->>B: boto3.Session
    B->>B: _build_request_body_for_model()
    B->>A: invoke_model(modelId, body)
    A-->>B: API Response
    B->>B: _parse_response_for_model()
    B-->>T: response_text
    T-->>S: TextContent(text=response_text)
    S-->>K: MCP Response
    K-->>U: AI応答表示
```

### システム全体アーキテクチャ

```mermaid
graph TB
    subgraph "Kiro IDE 環境"
        A[Kiro IDE ユーザー]
        B[MCP クライアント]
        C[mcp.json 設定]
    end

    subgraph "ローカル MCP サーバー"
        D[chat_mcp]
        E[MCP プロトコル ハンドラー]
        F[Bedrock クライアント]
        G[設定管理]
        H[エラーハンドラー]
    end

    subgraph "AWS クラウド"
        I[AWS Bedrock API]
        J[Amazon Nova Micro
超低コスト]
        K[Claude Sonnet 4
バランス型]
        L[Claude Opus 4
最高性能]
    end

    subgraph "認証・設定"
        M[AWS プロファイル]
        N[環境変数]
    end

    A --> B
    B --> D
    C --> B
    D --> E
    E --> F
    F --> I
    I --> J
    I --> K
    I --> L
    J --> I
    K --> I
    L --> I
    I --> F
    F --> E
    E --> D
    D --> B
    B --> A

    M --> D
    N --> D

    J --> G
    K --> G
    L --> G
    G --> F

    D --> H

    style D fill:#ff9800,stroke:#f57c00,color:#000
    style F fill:#9c27b0,stroke:#7b1fa2,color:#fff
    style I fill:#00bcd4,stroke:#0097a7,color:#000
    style J fill:#4caf50,stroke:#2e7d32,color:#000
```

### コンポーネント設計

#### 1. MCP サーバーコア (server.py)

**責務:**

- MCP プロトコルの実装
- ツール登録とリクエスト処理
- エラーハンドリングとレスポンス管理

**主要メソッド:**

```python
async def main() -> None:
    """MCP サーバーのメインエントリーポイント"""

async def list_tools() -> List[Tool]:
    """利用可能なツールのリストを返す"""

async def call_tool(name: str, arguments: dict) -> ToolResult:
    """指定されたツールを実行する"""
```

#### 2. Bedrock クライアント (bedrock_client.py)

**責務:**

- AWS Bedrock API との通信
- 3 つの AI モデル（Amazon Nova Micro, Claude Sonnet 4, Claude Opus 4）の呼び出し
- 用途別モデル選択ロジック
- レスポンスの解析と変換

**主要メソッド:**

```python
async def chat_with_model(message: str, model_id: str, temperature: float = 0.7) -> str:
    """指定されたAIモデルとの会話を実行"""

def _build_request_body(message: str, temperature: float) -> dict:
    """Bedrock API リクエストボディを構築"""

def _parse_response(response: dict) -> str:
    """Bedrock API レスポンスを解析"""
```

#### 3. 設定管理 (config.py)

**責務:**

- 環境変数と AWS プロファイルの管理
- 設定値の検証とデフォルト値の提供
- 認証情報の安全な取得

**設定項目:**

```python
@dataclass
class Config:
    aws_region: str = "us-east-1"
    aws_profile: Optional[str] = None
    nova_micro_model_id: str = "amazon.nova-micro-v1:0"
    claude_sonnet_model_id: str = "us.anthropic.claude-sonnet-4-20250514-v1:0"
    claude_opus_model_id: str = "us.anthropic.claude-opus-4-20250514-v1:0"
    max_tokens: int = 4000
    timeout_seconds: int = 30

    def get_model_by_purpose(self, purpose: str) -> str:
        """用途に応じたモデル ID を取得"""
        model_mapping = {
            'casual': self.nova_micro_model_id,      # 軽量会話
            'professional': self.claude_sonnet_model_id,  # 技術的会話
            'expert': self.claude_opus_model_id      # 高度な設計
        }
        return model_mapping.get(purpose, self.claude_sonnet_model_id)
```

## データモデル

### MCP ツール定義

```json
{
  "name": "chat_casual",
  "description": "日常会話や簡単な質問に答える（Amazon Nova Micro使用・超低コスト）",
  "inputSchema": {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "Claude に送信するメッセージ",
        "minLength": 1,
        "maxLength": 10000
      },
      "temperature": {
        "type": "number",
        "description": "応答の創造性を制御 (0.0-1.0)",
        "minimum": 0.0,
        "maximum": 1.0,
        "default": 0.7
      }
    },
    "required": ["message"]
  }
}
```

### Bedrock API リクエスト形式

```json
{
  "anthropic_version": "bedrock-2023-05-31",
  "max_tokens": 4000,
  "temperature": 0.7,
  "messages": [
    {
      "role": "user",
      "content": "ユーザーメッセージ"
    }
  ]
}
```

### MCP レスポンス形式

```json
{
  "content": [
    {
      "type": "text",
      "text": "Claude からの応答テキスト"
    }
  ],
  "isError": false
}
```

## インターフェース設計

### 1. MCP プロトコル インターフェース

#### ツール登録

```python
@app.list_tools()
async def list_tools():
    return [
        {
            "name": "chat_casual",
            "description": "日常会話や簡単な質問に答える（Amazon Nova Micro使用・超低コスト）",
            "inputSchema": TOOL_SCHEMA_CASUAL
        },
        {
            "name": "chat_professional",
            "description": "技術的な質問や詳細な説明が必要な会話（Claude Sonnet 4使用・バランス型）",
            "inputSchema": TOOL_SCHEMA_PROFESSIONAL
        },
        {
            "name": "chat_expert",
            "description": "複雑な設計、アーキテクチャ、実装に関する高度な相談（Claude Opus 4使用・最高性能）",
            "inputSchema": TOOL_SCHEMA_EXPERT
        }
    ]
```

#### ツール実行

```python
@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "chat_with_claude_opus":
        return await handle_chat_request(arguments)
    else:
        raise ValueError(f"Unknown tool: {name}")
```

### 2. AWS Bedrock インターフェース

#### API 呼び出し

```python
async def invoke_bedrock_model(
    client: BedrockRuntimeClient,
    model_id: str,
    request_body: dict
) -> dict:
    """Bedrock モデルを呼び出す"""
    response = await client.invoke_model(
        modelId=model_id,
        body=json.dumps(request_body)
    )
    return json.loads(response['body'].read())
```

## エラーハンドリング設計

### エラー分類と処理戦略

```mermaid
flowchart TD
    A[エラー発生] --> B{エラー種別}

    B -->|ClientError| C[AWS API エラー]
    B -->|ValidationError| D[入力検証エラー]
    B -->|TimeoutError| E[タイムアウトエラー]
    B -->|Exception| F[予期しないエラー]

    C --> G{エラーコード判定}
    G -->|AccessDenied| H[認証・権限エラー]
    G -->|ModelNotFound| I[モデルアクセスエラー]
    G -->|ThrottlingException| J[レート制限エラー]
    G -->|その他| K[一般的な API エラー]

    D --> L[入力値エラーメッセージ]
    E --> M[タイムアウトエラーメッセージ]
    F --> N[システムエラーメッセージ]

    H --> O[ユーザー向けエラーレスポンス]
    I --> O
    J --> O
    K --> O
    L --> O
    M --> O
    N --> O

    O --> P[ログ出力]
    P --> Q[MCP エラーレスポンス返却]

    style A fill:#ff5722,stroke:#d32f2f,color:#fff
    style O fill:#ff9800,stroke:#f57c00,color:#000
    style Q fill:#64b5f6,stroke:#1976d2,color:#000
```

### エラーメッセージマッピング

```python
ERROR_MESSAGES = {
    "AccessDenied": "AWS 認証に失敗しました。認証情報と AWS プロファイル設定を確認してください。",
    "ModelNotFound": "AIモデルアクセスが拒否されました。AWS Bedrock コンソールでモデルアクセス（Amazon Nova Micro, Claude Sonnet 4, Claude Opus 4）を有効にしてください。",
    "ThrottlingException": "リクエスト制限に達しました。しばらく待ってから再試行してください。",
    "ValidationException": "入力パラメータが無効です。メッセージ内容を確認してください。",
    "TimeoutError": "リクエストがタイムアウトしました。ネットワーク接続を確認してください。",
    "NetworkError": "ネットワーク接続に失敗しました。インターネット接続を確認してください。"
}
```

## セキュリティ設計

### 認証情報管理

#### AWS 認証フロー

```mermaid
sequenceDiagram
    participant S as MCP サーバー
    participant C as Config
    participant A as AWS SDK
    participant P as AWS プロファイル
    participant E as 環境変数

    S->>C: 設定初期化
    C->>C: MCP_AWS_PROFILE 確認

    alt プロファイル指定あり
        C->>P: プロファイル読み込み
        P->>A: 認証情報設定
    else プロファイル指定なし
        C->>E: 環境変数確認
        E->>A: デフォルト認証情報
    end

    A->>S: 認証済み Bedrock クライアント
```

#### セキュリティ原則

1. **最小権限の原則**

   - `bedrock:InvokeModel` 権限のみ要求
   - 特定モデルへのアクセスに限定

2. **認証情報の保護**

   - 平文での認証情報ログ出力禁止
   - メモリ内での認証情報の適切な管理

3. **入力検証**
   - JSON スキーマによる厳密な入力検証
   - SQL インジェクション等の攻撃対策

## パフォーマンス設計

### レスポンス時間最適化

#### 目標値

- **通常応答**: 3 秒以内
- **最大応答**: 5 秒以内
- **タイムアウト**: 30 秒

#### 最適化戦略

1. **非同期処理**

   ```python
   async def chat_with_claude(self, message: str, temperature: float) -> str:
       """非同期での Bedrock API 呼び出し"""
       async with self.session.post(url, json=body, timeout=30) as response:
           return await self._parse_response(response)
   ```

2. **接続プール**

   ```python
   # HTTP セッションの再利用
   self.session = aiohttp.ClientSession(
       timeout=aiohttp.ClientTimeout(total=30),
       connector=aiohttp.TCPConnector(limit=10)
   )
   ```

3. **エラー時の早期リターン**
   ```python
   # 入力検証での早期エラー検出
   if len(message) > MAX_MESSAGE_LENGTH:
       raise ValidationError("メッセージが長すぎます")
   ```

## 監視・ログ設計

### ログレベル定義

```python
import logging

# 本番環境: INFO レベル
# 開発環境: DEBUG レベル
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
```

### ログ出力項目

1. **リクエストログ**

   - タイムスタンプ
   - ツール名
   - メッセージ長
   - temperature 値

2. **レスポンスログ**

   - 処理時間
   - レスポンス長
   - 成功/失敗ステータス

3. **エラーログ**
   - エラー種別
   - エラーメッセージ
   - スタックトレース（DEBUG 時のみ）

## テスト戦略

### テストレベル

#### 1. 単体テスト

- 各コンポーネントの独立テスト
- モック使用による外部依存の排除

#### 2. 統合テスト

- MCP プロトコルの動作確認
- AWS Bedrock API との実際の通信テスト

#### 3. エンドツーエンドテスト

- Kiro IDE での実際の動作確認
- エラーシナリオの検証

### テスト環境

```python
# テスト用の設定
TEST_CONFIG = {
    "aws_region": "us-east-1",
    "claude_model_id": "anthropic.claude-sonnet-4-20250514-v1:0",  # コスト効率重視
    "max_tokens": 100,  # テスト用に短縮
    "timeout_seconds": 10
}

# 本番確認用の設定
PRODUCTION_TEST_CONFIG = {
    "aws_region": "us-east-1",
    "claude_model_id": "anthropic.claude-opus-4-20250514-v1:0",  # 最終確認のみ
    "max_tokens": 4000,
    "timeout_seconds": 30
}
```

## デプロイメント設計

### パッケージ構造

```
claude_opus_mcp/
├── __init__.py
├── __main__.py          # python -m エントリーポイント
├── server.py            # MCP サーバー実装
├── bedrock_client.py    # AWS Bedrock クライアント
├── config.py            # 設定管理
├── tool_handlers.py     # ツールハンドラー実装
└── exceptions.py        # カスタム例外
```

### インストール要件

```txt
# requirements.txt
mcp>=1.0.0
boto3>=1.34.0
aiohttp>=3.8.0
pydantic>=2.0.0
python-dotenv>=1.0.0
```

### Kiro 統合設定

```json
{
  "mcpServers": {
    "chat-mcp": {
      "command": "python",
      "args": ["-m", "chat_mcp"],
      "env": {
        "MCP_AWS_PROFILE": "sts",
        "MCP_AWS_REGION": "us-east-1",
        "MCP_USE_TEST_MODEL": "true",
        "MCP_LOG_LEVEL": "INFO"
      },
      "disabled": false,
      "autoApprove": ["chat_casual", "chat_professional", "chat_expert"],
      "disabledTools": []
    }
  }
}
```

## 参考ドキュメント

### AWS 公式ドキュメント

- [Amazon Nova Models in Amazon Bedrock](https://aws.amazon.com/bedrock/nova/)
  - Amazon Nova Micro の技術仕様とコスト効率
- [Introducing Claude 4 in Amazon Bedrock - AWS News Blog](https://aws.amazon.com/blogs/aws/claude-opus-4-anthropics-most-powerful-model-for-coding-is-now-in-amazon-bedrock/)
  - Claude Sonnet 4 / Opus 4 の技術仕様とベストプラクティス
- [InvokeModel - Amazon Bedrock API Reference](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)
  - Bedrock API の詳細仕様とパラメータ
- [Bedrock Converse API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html)
  - 推奨される統一 API インターフェース（将来対応）

### MCP プロトコル仕様

- [MCP Release Notes - Speakeasy](https://www.speakeasy.com/mcp/release-notes)
  - 2025 年最新仕様（Streamable HTTP、OAuth 2.1 対応）
- [Model Context Protocol (MCP) - GeeksforGeeks](https://www.geeksforgeeks.org/artificial-intelligence/model-context-protocol-mcp/)
  - MCP アーキテクチャの基本概念

### 技術実装参考

- [Model context protocol (MCP) - OpenAI Agents SDK](https://openai.github.io/openai-agents-python/mcp/)
  - Python SDK の実装パターンとベストプラクティス

### セキュリティ・認証

- [AWS IAM Best Practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)
  - 最小権限の原則と認証情報管理
- [AWS SDK for Python (Boto3) Configuration](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html)
  - AWS 認証情報の設定方法

# 実装計画

- [x] 1. プロジェクト構造とコア設定の作成

  - プロジェクトディレクトリ構造を作成する
  - requirements.txt と setup.py を作成する
  - 基本的な **init**.py ファイルを作成する
  - _要件: 要件 4（Python ベストプラクティス）_

- [x] 2. 設定管理システムの実装

  - [x] 2.1 Config クラスの実装

    - Pydantic を使用した設定クラスを作成する
    - AWS プロファイル、リージョン、モデル ID の管理を実装する
    - テスト用モデル切り替え機能を実装する
    - _要件: 要件 6（テスト要件とコスト最適化）_

  - [x] 2.2 環境変数とプロファイル管理

    - MCP_AWS_PROFILE、MCP_AWS_REGION の環境変数サポートを実装する
    - AWS プロファイルの自動検出機能を実装する
    - デフォルト設定の適用ロジックを実装する
    - _要件: 要件 3（Kiro IDE 統合）、要件 5（セキュリティ）_

- [x] 3. AWS Bedrock クライアントの実装

  - [x] 3.1 BedrockClient クラスの基本実装

    - boto3 を使用した Bedrock クライアントを作成する
    - 認証情報の安全な管理を実装する
    - 基本的な接続テストメソッドを実装する
    - _要件: 要件 5（セキュリティと認証情報管理）_

  - [x] 3.2 Claude との会話機能実装

    - chat_with_claude メソッドを実装する
    - Bedrock API リクエストボディの構築を実装する
    - API レスポンスの解析と変換を実装する
    - temperature パラメータの処理を実装する
    - _要件: 要件 1（Claude Opus 4 との会話機能）_

  - [x] 3.3 エラーハンドリングの実装

    - AWS API エラーの分類と処理を実装する
    - ユーザーフレンドリーなエラーメッセージの生成を実装する
    - ログ出力機能を実装する
    - タイムアウト処理を実装する
    - _要件: 要件 2（エラーハンドリング）_

- [x] 4. MCP サーバーコアの実装

  - [x] 4.1 MCP プロトコルハンドラーの実装

    - MCP Server クラスの基本構造を作成する

    - プロトコルハンドシェイクを実装する
    - ツール登録機能を実装する
    - _要件: 要件 4（MCP プロトコル標準準拠）_

  - [x] 4.2 chat_with_claude_opus ツールの実装

    - ツールの JSON スキーマ定義を実装する
    - 入力パラメータの検証を実装する
    - BedrockClient との連携を実装する
    - MCP レスポンス形式での結果返却を実装する
    - _要件: 要件 1（Claude Opus 4 との会話機能）_

  - [x] 4.3 メインエントリーポイントの実装

    - **main**.py でのサーバー起動処理を実装する
    - 設定の初期化とバリデーションを実装する
    - 適切な終了処理を実装する
    - _要件: 要件 4（Python ベストプラクティス）_

- [x] 5. テストスイートの実装

  - [x] 5.1 単体テストの作成

    - Config クラスのテストを作成する
    - BedrockClient のモックテストを作成する
    - エラーハンドリングのテストを作成する
    - _要件: 要件 6（テスト要件）_

  - [x] 5.2 統合テストの作成

    - Claude Sonnet 4 を使用した実際の API テストを作成する
    - MCP プロトコルの動作テストを作成する
    - エンドツーエンドの会話テストを作成する
    - _要件: 要件 6（コスト最適化テスト）_

  - [x] 5.3 本番確認テストの作成

    - Claude Opus 4 を使用した最終確認テストを作成する
    - パフォーマンステスト（5 秒以内レスポンス）を作成する
    - _要件: 要件 1（パフォーマンス要件）_

- [x] 6. パッケージングとドキュメント

  - [x] 6.1 パッケージ設定の完成

    - setup.py の詳細設定を完成させる
    - requirements.txt の最終調整を行う
    - .env.example ファイルを作成する
    - _要件: 要件 4（保守可能性）_

  - [x] 6.2 ドキュメントの作成（オプション）

    - README.md を作成する
    - インストール手順を記述する
    - Kiro 統合手順を記述する
    - トラブルシューティングガイドを作成する
    - _要件: 要件 3（Kiro IDE 統合）_
    - **注記**: 実用的には完成済み。共有・公開時に必要に応じて作成

- [x] 7. Kiro IDE 統合テスト

  - [x] 7.1 ローカル統合テスト

    - mcp.json 設定ファイルを作成する
    - Kiro でのサーバー認識テストを実行する
    - autoApprove 機能のテストを実行する
    - _要件: 要件 3（Kiro IDE 統合とセットアップ）_

  - [x] 7.2 実際の会話テスト

    - Kiro から Claude Sonnet 4 との会話テストを実行する
    - エラーケースの動作確認を実行する
    - パフォーマンス測定を実行する
    - _要件: 要件 1（Claude Opus 4 との会話機能）、要件 2（エラーハンドリング）_

  - [x] 7.3 本番モデル確認

    - Claude Opus 4 での最終動作確認を実行する
    - 高度な推論タスクでの動作確認を実行する
    - _要件: 要件 6（本番確認テスト）_

- [x] 8. 実運用での問題解決と機能拡張

  - [x] 8.1 MCP プロトコル互換性の修正

    - CallToolResult から List[TextContent] への戻り値形式変更
    - GitHub Issue #987 の調査結果に基づく修正実装
    - MCP プロトコル API 変更への対応
    - _要件: 要件 4（MCP プロトコル標準準拠）_

  - [x] 8.2 多モデル対応機能の実装

    - Amazon Nova Micro モデルの追加実装
    - Claude Sonnet 4 との使い分け機能実装
    - 用途別モデル選択機能（casual/professional/expert）
    - コスト効率化のためのモデル切り替え実装
    - _要件: 要件 6（コスト最適化）_

  - [x] 8.3 AWS リソース管理機能の実装

    - IAM ユーザー管理機能の追加
    - EC2、S3、Lambda 情報取得機能の追加
    - AWS セッション管理の改善
    - 統合的な AWS 操作ツールの実装
    - _要件: 要件 5（セキュリティと認証情報管理）_

  - [x] 8.4 機能の簡素化とリファクタリング
    - ツール数を 10 個から 3 個（chat 系のみ）に削減
    - サーバー名を claude-opus-mcp から claude-mcp に短縮
    - ツールハンドラーの分離とモジュール化
    - コードの保守性向上
    - _要件: 要件 4（保守可能性）_

- [x] 9. 最終動作確認とコスト分析

  - [x] 9.1 3 モデル会話テスト

    - Claude Opus 4 での高度な技術相談テスト
    - Claude Sonnet 4 での専門的会話テスト
    - Amazon Nova Micro での軽量会話テスト
    - 各モデルの応答品質とコスト効率の確認
    - _要件: 要件 1（Claude Opus 4 との会話機能）、要件 6（コスト最適化）_

  - [x] 9.2 実際のコスト測定
    - 3 回のラリー会話でのコスト計算（約 5 円）
    - Nova Micro での軽量会話コスト測定（約 0.005 円）
    - モデル別コスト比較分析
    - コスト効率の実証
    - _要件: 要件 6（コスト最適化）_