diff --git a/workshops/ai-coding-workshop/cline/1.mcp/1.marketplace-mcp/README.md b/workshops/ai-coding-workshop/cline/1.mcp/1.marketplace-mcp/README.md new file mode 100644 index 0000000..6ea67f5 --- /dev/null +++ b/workshops/ai-coding-workshop/cline/1.mcp/1.marketplace-mcp/README.md @@ -0,0 +1,336 @@ +# MCP Marketplace 活用ワークショップ + +## はじめに + +このワークショップでは、[MCP Marketplace](https://cline.bot/mcp-marketplace) を活用して、AI エージェントの機能を大幅に拡張する方法を学びます。MCP Marketplace は、様々な開発者が作成した MCP サーバーを簡単に発見・インストール・管理できるプラットフォームです。 + +## ワークショップの目的 + +このワークショップを通じて、参加者は以下のスキルを習得できます: + +- MCP Marketplace の効果的な活用方法 +- 様々な MCP サーバーの機能と特徴の理解 +- MCP サーバーの安全なインストールと管理方法 +- AI エージェントの能力拡張のベストプラクティス +- セキュリティを考慮した MCP サーバーの選択と運用 + +## 前提条件 + +このワークショップを開始する前に、以下の環境が整っていることを確認してください: + +- VSCode と Cline 拡張機能がインストール済み +- Node.js 18.x 以上がインストール済み +- Python 3.10 以上がインストール済み(一部の MCP サーバー用) +- 基本的な MCP の概念を理解していること + +## MCP Marketplace の概要 + +MCP Marketplace は、AI エージェントの機能を拡張するための豊富なツールとリソースを提供するプラットフォームです。開発者コミュニティによって作成された様々な MCP サーバーを、簡単に検索・インストール・管理することができます。 + +### Marketplace の主な特徴 + +1. **豊富なサーバーライブラリ** + - Web 検索、ドキュメント処理、API 統合など多様な機能 + - コミュニティによる継続的な新機能追加 + - 品質とセキュリティの検証済みサーバー + +2. **簡単なインストール** + - ワンクリックでのインストール + - 自動的な依存関係の解決 + - 設定ファイルの自動生成 + +3. **統合管理機能** + - インストール済みサーバーの一覧表示 + - 有効/無効の切り替え + - 設定の変更とカスタマイズ + +## MCP Marketplace へのアクセス + +### 1. Marketplace の開き方 + +VS Code で Cline 拡張機能を開き、以下の手順でアクセスします: + +1. 左側のサイドバーから「MCP Servers」を選択 +2. 画面上部の「Marketplace」タブをクリック +3. 検索バーを使用して必要なツールを検索 + +![MCP Marketplace の画面](../images/mcp-marketplace.png) + +### 2. サーバーの検索と発見 + +Marketplace では、以下の方法でサーバーを見つけることができます: + +- **キーワード検索**: 機能や用途に基づいた検索 +- **カテゴリ別表示**: Web、データベース、API などのカテゴリ +- **人気順表示**: コミュニティで人気の高いサーバー +- **最新順表示**: 最近追加されたサーバー + +## 実践演習 1: Context7 MCP の活用 + +### Context7 MCP とは + +Context7 MCP は、AI エージェントが最新のライブラリドキュメントにアクセスできるようにする強力なツールです。従来の LLM が抱える以下の問題を解決します: + +❌ **従来の問題**: +- 古いトレーニングデータに基づく古いコード例 +- 実在しない API の誤った生成 +- 古いパッケージバージョンに基づく一般的な回答 + +✅ **Context7 の解決策**: +- ソースから直接、最新のバージョン固有のドキュメントとコード例を取得 +- プロンプトに直接、最新の情報を組み込み +- 常に最新の API 仕様に基づいた正確な回答 + +### インストール手順 + +1. **Marketplace からのインストール** + ``` + MCP Marketplace で "Context7" を検索し、"Install" をクリック + ``` + +2. **Cline による自動インストール** + + Cline がインストールのための新しいタスクを開始します。以下のような手順で進行されます: + + ```bash + # プロジェクトディレクトリの作成 + mkdir -p /home/coder/Cline/MCP/context7-mcp + cd /home/coder/Cline/MCP/context7-mcp + + # パッケージのインストール + npm install -g @upstash/context7-mcp@latest + ``` + +3. **設定ファイルの更新** + + MCP Setting ファイルが自動的に更新されます: + + ファイル: `/home/coder/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` + + ```json + { + "mcpServers": { + "github.com/upstash/context7-mcp": { + "autoApprove": [], + "disabled": false, + "timeout": 60, + "command": "/home/coder/.local/share/mise/shims/npx", + "args": [ + "-y", + "@upstash/context7-mcp@latest" + ], + "transportType": "stdio" + } + } + } + ``` + +### 使用方法 + +Context7 を使用するには、質問に `use context7` を追加するだけです: + +``` +Next.js の `after` 関数の使い方を教えて use context7 +React Query でクエリを無効化する方法は? use context7 +NextAuth でルートを保護する方法は? use context7 +``` + +### 実践演習 + +以下の質問を Cline に投げかけて、Context7 MCP の効果を体験してみましょう: + +1. **最新の Next.js 機能について** + ``` + Next.js 15 の新機能について教えて use context7 + ``` + +2. **React の最新パターン** + ``` + React 19 の新しい hooks について説明して use context7 + ``` + +3. **TypeScript の最新機能** + ``` + TypeScript 5.6 の新機能を教えて use context7 + ``` + +## 実践演習 2: Web Research MCP の活用 + +### Web Research MCP とは + +Web Research MCP は、AI エージェントがリアルタイムでウェブ検索を行い、最新の情報を取得できるようにするツールです。 + +### 主な機能 + +- **リアルタイム検索**: Google、Bing などの検索エンジンを活用 +- **コンテンツ抽出**: ウェブページから関連情報を自動抽出 +- **情報統合**: 複数のソースからの情報を統合して回答生成 + +### インストールと設定 + +1. **Marketplace からのインストール** + ``` + MCP Marketplace で "Web Research" を検索してインストール + ``` + +2. **API キーの設定** + + 環境変数として検索エンジンの API キーを設定: + + ```bash + export GOOGLE_API_KEY="your-google-api-key" + export GOOGLE_CSE_ID="your-custom-search-engine-id" + ``` + +### 使用例 + +``` +最新の AI 技術のトレンドについて調べて use websearch +2024年のプログラミング言語の人気ランキングは? use websearch +``` + +## 実践演習 3: Markdownify MCP の活用 + +### Markdownify MCP とは + +Markdownify MCP は、ウェブページや PDF ファイルを Markdown 形式に変換し、AI エージェントが処理しやすい形式で情報を提供するツールです。 + +### 主な機能 + +- **ウェブページの変換**: HTML を構造化された Markdown に変換 +- **PDF 処理**: PDF ファイルのテキスト抽出と Markdown 変換 +- **画像処理**: 画像内のテキスト抽出(OCR) + +### 実践演習 + +1. **ウェブページの変換** + ``` + https://example.com のコンテンツを Markdown で取得して + ``` + +2. **PDF ファイルの処理** + ``` + この PDF ファイルの内容を要約して(ファイルをアップロード) + ``` + +## MCP サーバーの管理 + +### サーバーの有効/無効切り替え + +VS Code の Cline 拡張機能の「MCP Servers」セクションで: + +1. インストール済みサーバーの一覧を確認 +2. トグルスイッチで有効/無効を切り替え +3. 設定アイコンから詳細設定を変更 + +![MCP サーバーの管理方法](../images/mcp-management-page.png) + +### 設定のカスタマイズ + +各サーバーの設定は以下の項目をカスタマイズできます: + +- **timeout**: タイムアウト時間の調整 +- **autoApprove**: 自動承認するツールの指定 +- **env**: 環境変数の設定 +- **disabled**: サーバーの無効化 + +### パフォーマンス監視 + +MCP サーバーのパフォーマンスを監視するポイント: + +1. **応答時間**: サーバーの応答速度 +2. **エラー率**: 失敗したリクエストの割合 +3. **リソース使用量**: CPU とメモリの使用状況 + +## セキュリティ考慮事項 + +### 信頼できるサーバーの選択 + +MCP サーバーを選択する際の基準: + +1. **開発者の信頼性** + - 知名度の高い開発者や組織 + - オープンソースでコードが公開されている + - コミュニティでの評価が高い + +2. **セキュリティ対策** + - 定期的なセキュリティ更新 + - 脆弱性の迅速な修正 + - セキュリティ監査の実施 + +3. **データ保護** + - データの暗号化 + - プライバシーポリシーの明確化 + - データの適切な取り扱い + +### アクセス制御 + +1. **最小権限の原則** + - 必要最小限の権限のみを付与 + - 定期的な権限の見直し + +2. **autoApprove の慎重な使用** + - 信頼できるツールのみに設定 + - 定期的な設定の見直し + +3. **監査とログ** + - MCP サーバーの動作ログを記録 + - 不審な活動の監視 + +## トラブルシューティング + +### よくある問題と解決方法 + +1. **インストールエラー** + ``` + 問題: npm install でエラーが発生 + 解決: Node.js のバージョンを確認し、必要に応じて更新 + ``` + +2. **接続エラー** + ``` + 問題: MCP サーバーに接続できない + 解決: 設定ファイルのパスとコマンドを確認 + ``` + +3. **タイムアウトエラー** + ``` + 問題: サーバーの応答が遅い + 解決: timeout 値を増加させる + ``` + +### デバッグ方法 + +1. **ログの確認** + ```bash + # Cline のログを確認 + tail -f ~/.vscode-server/data/logs/*/exthost*/output_logging_* + ``` + +2. **設定の検証** + ```bash + # 設定ファイルの構文チェック + cat ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json | jq . + ``` + +## まとめ + +このワークショップでは、MCP Marketplace を活用して AI エージェントの機能を拡張する方法を学びました。主なポイント: + +1. **Marketplace の活用**: 豊富なサーバーライブラリから適切なツールを選択 +2. **実践的な使用**: Context7、Web Research、Markdownify などの具体例 +3. **管理とセキュリティ**: 安全で効率的なサーバー運用 +4. **トラブルシューティング**: 問題解決のための実践的な手法 + +### 次のステップ + +- [AWS MCP サーバー活用ワークショップ](../2.aws-mcp/README.md)に進む +- より高度な MCP サーバーの開発に挑戦 +- 独自の MCP サーバーの作成を検討 + +### 参考リンク + +- [MCP Marketplace](https://cline.bot/mcp-marketplace) +- [Context7 ライブラリページ](https://context7.com/libraries) +- [Model Context Protocol 公式ドキュメント](https://modelcontextprotocol.io/) +- [Cline Wiki トラブルシューティング](https://cline.bot/wiki/troubleshooting) \ No newline at end of file diff --git a/workshops/ai-coding-workshop/cline/1.mcp/2.aws-mcp/README.md b/workshops/ai-coding-workshop/cline/1.mcp/2.aws-mcp/README.md new file mode 100644 index 0000000..df69a5d --- /dev/null +++ b/workshops/ai-coding-workshop/cline/1.mcp/2.aws-mcp/README.md @@ -0,0 +1,660 @@ +# AWS MCP サーバー活用ワークショップ + +## はじめに + +このワークショップでは、AWS が提供する MCP サーバーを活用して、AWS のベストプラクティスと豊富な情報資源を開発ワークフローに直接統合する方法を学びます。AWS MCP Servers は、AWS の公式ドキュメント、Bedrock ナレッジベース、その他の AWS サービスと AI エージェントを効率的に連携させる革新的なツールです。 + +## ワークショップの目的 + +このワークショップを通じて、参加者は以下のスキルを習得できます: + +- AWS MCP サーバーの種類と特徴の理解 +- AWS ドキュメントや Bedrock ナレッジベースの効率的な活用方法 +- 複数の AWS MCP サーバーを連携させる実践的な手法 +- AWS MCP サーバーのトラブルシューティング技術 +- セキュリティを考慮した AWS MCP サーバーの運用方法 + +## 前提条件 + +このワークショップを開始する前に、以下の環境が整っていることを確認してください: + +- AWS アカウントへのアクセス権限 +- Python 3.10 以上がインストール済み +- uv パッケージ管理ツールがインストール済み +- VSCode と Cline 拡張機能がインストール済み +- 基本的な AWS サービスの知識 +- MCP の基本概念の理解 + +## AWS MCP サーバーの概要 + +[AWS MCP Servers](https://github.com/awslabs/mcp) は、AWS Labs によって開発された MCP サーバー群で、AWS のベストプラクティスと豊富な情報資源を開発ワークフローに直接統合することを目的としています。 + +### AWS MCP サーバーの主な特徴 + +1. **公式サポート** + - AWS Labs による開発と保守 + - AWS サービスとの深い統合 + - 継続的なアップデートとセキュリティ対応 + +2. **豊富な機能** + - AWS ドキュメントの効率的な検索と取得 + - Bedrock ナレッジベースとの統合 + - AWS サービス情報の自動取得 + +3. **エンタープライズ対応** + - セキュリティベストプラクティスの実装 + - スケーラブルなアーキテクチャ + - 監査とログ機能 + +## AWS MCP サーバーの種類 + +AWS は、開発者の生産性向上と AWS サービスの効果的な活用を支援するために、複数の MCP サーバーを提供しています: + +### 1. Core MCP Server + +**概要**: AWS Labs MCP サーバー群の中心的な役割を担うサーバー + +**主な機能**: +- 他の MCP サーバーの管理や調整 +- 設定の一元化 +- サーバー間の連携制御 + +**使用場面**: +- 複数の AWS MCP サーバーを統合管理する場合 +- AWS MCP エコシステム全体の制御が必要な場合 + +### 2. AWS Documentation MCP Server + +**概要**: AWS の公式ドキュメントを効率的に検索、探索、活用するためのサーバー + +**主な機能**: +- AWS ドキュメントの全文検索 +- マークダウン形式での情報提供 +- 関連ドキュメントの自動提案 +- バージョン管理されたドキュメントへのアクセス + +**使用場面**: +- AWS サービスの使用方法を調べる場合 +- ベストプラクティスを確認する場合 +- API リファレンスを参照する場合 + +### 3. Amazon Bedrock Knowledge Bases Retrieval MCP Server + +**概要**: Amazon Bedrock の知識ベースを効率的に活用するためのサーバー + +**主な機能**: +- 自然言語クエリによる情報検索 +- 結果のフィルタリングやリランキング +- コンテキストに応じた情報抽出 +- 複数の知識ベースからの統合検索 + +**使用場面**: +- 企業固有の知識ベースから情報を取得する場合 +- 複雑な技術文書から特定の情報を抽出する場合 +- AI による知識ベースの効率的な活用が必要な場合 + +## 開発環境の準備 + +### Python 環境の確認 + +まず、Python 3.10 以上がインストールされていることを確認します: + +```bash +python3 --version +# または +python --version +``` + +### uv パッケージ管理ツールの確認 + +uv がインストールされていることを確認します: + +```bash +uv --version +``` + +Amazon EC2 環境では uv は既にインストールされています。ローカル環境の場合は以下でインストールできます: + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +### AWS 認証の設定 + +AWS MCP サーバーを使用するには、適切な AWS 認証が必要です: + +#### 方法 1: AWS CLI の設定 + +```bash +aws configure +``` + +#### 方法 2: 環境変数の設定 + +```bash +export AWS_ACCESS_KEY_ID="your-access-key" +export AWS_SECRET_ACCESS_KEY="your-secret-key" +export AWS_DEFAULT_REGION="ap-northeast-1" +``` + +#### 方法 3: IAM ロール(EC2 環境推奨) + +EC2 インスタンスに適切な IAM ロールを割り当てることで、認証情報を自動的に取得できます。 + +## 実践演習 1: AWS Documentation MCP Server + +### インストール手順 + +#### 1. Marketplace からのインストール + +VS Code の Cline 拡張機能から: + +1. 左側のサイドバーから「MCP Servers」を選択 +2. 画面上部の「Marketplace」タブをクリック +3. 検索バーに「AWS」と入力して検索 +4. 「AWS Documentation MCP Server」の「Install」ボタンをクリック + +#### 2. 手動インストール + +```bash +# プロジェクトディレクトリの作成 +mkdir -p /home/coder/Cline/MCP/aws-documentation-mcp-server +cd /home/coder/Cline/MCP/aws-documentation-mcp-server + +# パッケージのインストール +uvx awslabs.aws-documentation-mcp-server@latest +``` + +#### 3. MCP 設定ファイルの更新 + +設定ファイル: `/home/coder/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` + +```json +{ + "mcpServers": { + "github.com/awslabs/mcp/tree/main/src/aws-documentation-mcp-server": { + "command": "/home/coder/.local/share/mise/shims/uvx", + "args": ["awslabs.aws-documentation-mcp-server@latest"], + "env": { + "FASTMCP_LOG_LEVEL": "ERROR" + }, + "disabled": false, + "autoApprove": [] + } + } +} +``` + +### 使用方法と実践例 + +#### 基本的な使用方法 + +AWS Documentation MCP Server は、以下のツールを提供します: + +1. **search_documentation**: AWS ドキュメントの検索 +2. **read_documentation**: 特定のドキュメントの読み取り + +#### 実践例 1: S3 バケット命名規則の調査 + +Cline に以下のように質問してみましょう: + +``` +AWS S3 バケットの命名規則について調べてください +``` + +内部的に以下のような処理が行われます: + +1. **ドキュメント検索**: + ```json + { + "name": "search_documentation", + "arguments": { + "query": "S3 bucket naming rules" + } + } + ``` + +2. **関連ドキュメントの取得**: + ```json + { + "name": "read_documentation", + "arguments": { + "url": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html" + } + } + ``` + +#### 実践例 2: Lambda 関数のベストプラクティス + +``` +AWS Lambda 関数の開発におけるベストプラクティスを教えてください +``` + +#### 実践例 3: VPC セキュリティグループの設定 + +``` +VPC セキュリティグループの適切な設定方法について調べてください +``` + +### 取得できる情報の例 + +AWS Documentation MCP Server から取得できる情報には以下のようなものがあります: + +- **S3 バケット命名規則**: + - バケット名は 3 文字以上 63 文字以下 + - 小文字、数字、ピリオド (.)、ハイフン (-) のみ使用可能 + - 文字または数字で始まり、文字または数字で終わる必要がある + +- **Lambda のベストプラクティス**: + - 関数のタイムアウト設定 + - メモリ配分の最適化 + - 環境変数の適切な使用方法 + +- **セキュリティグループの設定**: + - インバウンドルールの最小権限原則 + - アウトバウンドルールの適切な制限 + - ポート範囲の最適化 + +## 実践演習 2: Amazon Bedrock Knowledge Bases MCP Server + +### 前提条件 + +このサーバーを使用するには、以下が必要です: + +- Amazon Bedrock へのアクセス権限 +- 事前に作成された Knowledge Base +- 適切な IAM ロールまたはアクセスキー + +### インストールと設定 + +#### 1. インストール + +```bash +# プロジェクトディレクトリの作成 +mkdir -p /home/coder/Cline/MCP/bedrock-kb-mcp-server +cd /home/coder/Cline/MCP/bedrock-kb-mcp-server + +# パッケージのインストール +uvx awslabs.bedrock-knowledge-bases-mcp-server@latest +``` + +#### 2. 設定ファイルの更新 + +```json +{ + "mcpServers": { + "github.com/awslabs/mcp/tree/main/src/bedrock-knowledge-bases-mcp-server": { + "command": "/home/coder/.local/share/mise/shims/uvx", + "args": ["awslabs.bedrock-knowledge-bases-mcp-server@latest"], + "env": { + "AWS_REGION": "us-east-1", + "KNOWLEDGE_BASE_ID": "your-knowledge-base-id" + }, + "disabled": false, + "autoApprove": [] + } + } +} +``` + +### 使用例 + +#### Knowledge Base からの情報検索 + +``` +社内の技術ドキュメントから、マイクロサービスアーキテクチャのベストプラクティスを教えてください +``` + +#### 複合的な情報検索 + +``` +プロジェクトの過去の障害事例から、同様の問題を防ぐための対策を提案してください +``` + +## 実践演習 3: 複数 AWS MCP サーバーの連携 + +### 連携のメリット + +複数の AWS MCP サーバーを組み合わせることで、より包括的な情報収集と分析が可能になります: + +1. **AWS Documentation + Bedrock Knowledge Base**: + - 公式ドキュメントと社内ナレッジの統合 + - より具体的で実践的な回答の生成 + +2. **段階的な情報収集**: + - 基本情報の取得 → 詳細情報の検索 → 実装例の提供 + +### 連携設定例 + +```json +{ + "mcpServers": { + "aws-documentation": { + "command": "/home/coder/.local/share/mise/shims/uvx", + "args": ["awslabs.aws-documentation-mcp-server@latest"], + "env": { + "FASTMCP_LOG_LEVEL": "ERROR" + }, + "disabled": false, + "autoApprove": [] + }, + "bedrock-knowledge-bases": { + "command": "/home/coder/.local/share/mise/shims/uvx", + "args": ["awslabs.bedrock-knowledge-bases-mcp-server@latest"], + "env": { + "AWS_REGION": "us-east-1", + "KNOWLEDGE_BASE_ID": "your-knowledge-base-id" + }, + "disabled": false, + "autoApprove": [] + } + } +} +``` + +### 連携活用例 + +#### 例 1: 包括的なアーキテクチャ設計支援 + +``` +新しいマイクロサービスアーキテクチャを設計したいです。 +AWS の公式ベストプラクティスと、社内の過去の実装例を参考に、 +具体的な設計案を提案してください。 +``` + +この質問に対して、AI エージェントは: +1. AWS Documentation から公式のベストプラクティスを取得 +2. Bedrock Knowledge Base から社内の実装例を検索 +3. 両方の情報を統合して具体的な設計案を提案 + +#### 例 2: トラブルシューティング支援 + +``` +Lambda 関数でタイムアウトエラーが頻発しています。 +AWS の公式トラブルシューティングガイドと、 +社内の過去の解決事例を参考に対策を教えてください。 +``` + +## セキュリティとベストプラクティス + +### AWS MCP サーバーのセキュリティ考慮事項 + +#### 1. 認証と認可 + +**IAM ロールの使用(推奨)**: +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "bedrock:RetrieveAndGenerate", + "bedrock:Retrieve" + ], + "Resource": "arn:aws:bedrock:*:*:knowledge-base/*" + } + ] +} +``` + +**最小権限の原則**: +- 必要最小限の AWS サービスへのアクセス権限のみを付与 +- 定期的な権限の見直しと更新 + +#### 2. データ保護 + +**暗号化**: +- 転送中のデータ暗号化(TLS) +- 保存時のデータ暗号化(KMS) + +**ログ管理**: +- CloudTrail による API 呼び出しの記録 +- CloudWatch Logs による詳細なログ管理 + +#### 3. ネットワークセキュリティ + +**VPC エンドポイント**: +- プライベートネットワーク経由での AWS サービスアクセス +- インターネットゲートウェイを経由しない通信 + +### 運用のベストプラクティス + +#### 1. 監視とアラート + +**CloudWatch メトリクス**: +- API 呼び出し回数の監視 +- エラー率の追跡 +- レスポンス時間の測定 + +**アラート設定**: +```json +{ + "AlarmName": "MCP-Server-High-Error-Rate", + "MetricName": "ErrorRate", + "Threshold": 5.0, + "ComparisonOperator": "GreaterThanThreshold" +} +``` + +#### 2. コスト管理 + +**使用量の監視**: +- Bedrock の API 呼び出し回数 +- データ転送量 +- ストレージ使用量 + +**コスト最適化**: +- 不要なリクエストの削減 +- キャッシュの活用 +- 適切なタイムアウト設定 + +## トラブルシューティング + +### よくある問題と解決方法 + +#### 1. 認証エラー + +**問題**: `AccessDenied` エラーが発生する + +**解決方法**: +```bash +# AWS 認証情報の確認 +aws sts get-caller-identity + +# IAM ロールの権限確認 +aws iam get-role-policy --role-name your-role-name --policy-name your-policy-name +``` + +#### 2. タイムアウトエラー + +**問題**: MCP サーバーの応答が遅い + +**解決方法**: +```json +{ + "mcpServers": { + "aws-documentation": { + "timeout": 120, + "env": { + "FASTMCP_LOG_LEVEL": "DEBUG" + } + } + } +} +``` + +#### 3. Knowledge Base 接続エラー + +**問題**: Bedrock Knowledge Base に接続できない + +**解決方法**: +```bash +# Knowledge Base の存在確認 +aws bedrock-agent get-knowledge-base --knowledge-base-id your-kb-id + +# リージョンの確認 +aws configure get region +``` + +### デバッグ手法 + +#### 1. ログレベルの調整 + +```json +{ + "env": { + "FASTMCP_LOG_LEVEL": "DEBUG", + "AWS_LOG_LEVEL": "DEBUG" + } +} +``` + +#### 2. AWS CLI での動作確認 + +```bash +# Bedrock の動作確認 +aws bedrock-runtime invoke-model \ + --model-id anthropic.claude-3-sonnet-20240229-v1:0 \ + --body '{"messages":[{"role":"user","content":"Hello"}],"max_tokens":100}' \ + output.json + +# Knowledge Base の動作確認 +aws bedrock-agent retrieve \ + --knowledge-base-id your-kb-id \ + --retrieval-query '{"text":"test query"}' +``` + +#### 3. ネットワーク接続の確認 + +```bash +# AWS エンドポイントへの接続確認 +curl -I https://bedrock-runtime.us-east-1.amazonaws.com + +# DNS 解決の確認 +nslookup bedrock-runtime.us-east-1.amazonaws.com +``` + +## パフォーマンス最適化 + +### 1. キャッシュ戦略 + +**ローカルキャッシュ**: +- 頻繁にアクセスされるドキュメントのキャッシュ +- TTL(Time To Live)の適切な設定 + +**分散キャッシュ**: +- ElastiCache を使用した共有キャッシュ +- 複数のインスタンス間でのキャッシュ共有 + +### 2. 並列処理 + +**非同期処理**: +```python +import asyncio +import aiohttp + +async def fetch_multiple_documents(urls): + async with aiohttp.ClientSession() as session: + tasks = [fetch_document(session, url) for url in urls] + return await asyncio.gather(*tasks) +``` + +### 3. リクエスト最適化 + +**バッチ処理**: +- 複数のクエリをまとめて処理 +- API 呼び出し回数の削減 + +**フィルタリング**: +- 不要な情報の事前除外 +- レスポンスサイズの最適化 + +## 高度な活用例 + +### 1. CI/CD パイプラインとの統合 + +**GitHub Actions での活用**: +```yaml +name: AWS Best Practices Check +on: [push, pull_request] + +jobs: + check-best-practices: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Check AWS Best Practices + run: | + # MCP サーバーを使用してベストプラクティスをチェック + python check_aws_practices.py +``` + +### 2. 自動ドキュメント生成 + +**アーキテクチャ図の自動生成**: +```python +def generate_architecture_doc(service_config): + # AWS Documentation MCP から関連情報を取得 + best_practices = get_aws_best_practices(service_config) + + # Bedrock Knowledge Base から社内事例を取得 + internal_examples = get_internal_examples(service_config) + + # 統合してドキュメント生成 + return generate_document(best_practices, internal_examples) +``` + +### 3. 自動コードレビュー + +**AWS リソース設定のレビュー**: +```python +def review_terraform_config(config_file): + # Terraform 設定を解析 + config = parse_terraform(config_file) + + # AWS MCP サーバーからベストプラクティスを取得 + recommendations = get_aws_recommendations(config) + + # レビューコメントを生成 + return generate_review_comments(recommendations) +``` + +## まとめ + +このワークショップでは、AWS MCP サーバーを活用して AWS のベストプラクティスを開発ワークフローに統合する方法を学びました。 + +### 主要なポイント + +1. **AWS MCP サーバーの種類と特徴**: + - Documentation MCP Server による公式ドキュメントの活用 + - Bedrock Knowledge Bases MCP Server による社内ナレッジの統合 + +2. **実践的な活用方法**: + - 単体での使用から複数サーバーの連携まで + - セキュリティとパフォーマンスを考慮した運用 + +3. **トラブルシューティング**: + - 一般的な問題の解決方法 + - デバッグとパフォーマンス最適化の手法 + +### 次のステップ + +- より高度な AWS MCP サーバーの開発 +- 独自の AWS 統合 MCP サーバーの作成 +- エンタープライズ環境での大規模運用 + +### 参考リンク + +- [AWS MCP GitHub リポジトリ](https://github.com/awslabs/mcp) +- [Amazon Bedrock ドキュメント](https://docs.aws.amazon.com/bedrock/) +- [AWS IAM ベストプラクティス](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) +- [Model Context Protocol 公式ドキュメント](https://modelcontextprotocol.io/) + +--- + +**[前のワークショップ]** +- [MCP Marketplace 活用ワークショップ](../1.marketplace-mcp/README.md) + +**[ワークショップ一覧に戻る]** +- [MCP ワークショップシリーズ](../README.md) \ No newline at end of file diff --git a/workshops/ai-coding-workshop/cline/1.mcp/README.md b/workshops/ai-coding-workshop/cline/1.mcp/README.md index 7600f35..838158a 100644 --- a/workshops/ai-coding-workshop/cline/1.mcp/README.md +++ b/workshops/ai-coding-workshop/cline/1.mcp/README.md @@ -111,10 +111,23 @@ MCP サーバーを導入・実行する際には、以下のセキュリティ - MCP サーバーのリソース使用状況を監視すること - 不要なサーバーは無効化または削除すること +## MCP 機能テスト + +MCP サーバーが正しく動作しているかを確認するために、[MCP 機能テストガイド](./test-mcp.md)を用意しています。このガイドでは、基本的な機能テストから高度な連携テスト、セキュリティテストまで、包括的なテスト方法を説明しています。 + +### テスト項目 + +- 基本環境の確認 +- 各 MCP サーバーの動作確認 +- 複数サーバーの連携テスト +- エラーハンドリングの確認 +- パフォーマンステスト +- セキュリティテスト + ## 参考リンク - [Model Context Protocol 公式ドキュメント](https://modelcontextprotocol.github.io/) - [MCP Servers GitHub リポジトリ](https://github.com/modelcontextprotocol/servers) - [TypeScript 公式ドキュメント](https://www.typescriptlang.org/docs/) - [Anthropic Claude 開発者ドキュメント](https://docs.anthropic.com/) -- [AWS MCP GitHub リポジトリ](https://github.com/aws/aws-mcp) +- [AWS MCP GitHub リポジトリ](https://github.com/awslabs/mcp) diff --git a/workshops/ai-coding-workshop/cline/1.mcp/images/README.md b/workshops/ai-coding-workshop/cline/1.mcp/images/README.md new file mode 100644 index 0000000..4920eca --- /dev/null +++ b/workshops/ai-coding-workshop/cline/1.mcp/images/README.md @@ -0,0 +1,35 @@ +# MCP Workshop Images + +This directory contains images referenced in the MCP workshop documentation. + +## Required Images + +The following images are referenced in the documentation but need to be added: + +### MCP Marketplace Workshop +- `mcp-marketplace.png` - Screenshot of the MCP Marketplace interface +- `mcp-management-page.png` - Screenshot of the MCP server management page + +### AWS MCP Workshop +- `aws-document-mcp-search-document.png` - AWS Documentation MCP search results +- `aws-document-mcp-read-document.png` - AWS Documentation MCP document reading interface + +## Image Guidelines + +When adding images to this directory: + +1. Use descriptive filenames +2. Optimize images for web display (PNG or JPG format) +3. Keep file sizes reasonable (< 1MB per image) +4. Update documentation links if filenames change +5. Include alt text in documentation for accessibility + +## Usage in Documentation + +Images are referenced in markdown using relative paths: + +```markdown +![MCP Marketplace の画面](../images/mcp-marketplace.png) +``` + +Make sure the relative path is correct based on the location of the markdown file. \ No newline at end of file diff --git a/workshops/ai-coding-workshop/cline/1.mcp/test-mcp.md b/workshops/ai-coding-workshop/cline/1.mcp/test-mcp.md new file mode 100644 index 0000000..ef9194e --- /dev/null +++ b/workshops/ai-coding-workshop/cline/1.mcp/test-mcp.md @@ -0,0 +1,204 @@ +# MCP 機能テストガイド + +## 概要 + +このドキュメントでは、MCP (Model Context Protocol) の機能が正しく動作しているかを確認するためのテスト方法を説明します。 + +## MCP とは + +Model Context Protocol (MCP) は、AI モデルとデータソースやツールを接続するための標準化されたオープンプロトコルです。USB-C のように、異なるシステム間の互換性を確保し、AI エージェントの機能を拡張する重要な役割を果たします。 + +### MCP の主要な特徴 + +1. **標準化されたプロトコル**: 異なるシステム間での一貫した通信 +2. **拡張可能性**: 新しいツールやリソースの簡単な追加 +3. **セキュリティ**: 適切なアクセス制御と認証機能 +4. **相互運用性**: 複数のプロバイダー間での柔軟な切り替え + +## テスト環境の確認 + +### 1. 基本環境の確認 + +```bash +# Node.js のバージョン確認 +node --version + +# Python のバージョン確認 +python3 --version + +# uv の確認 +uv --version + +# VSCode と Cline の確認 +code --version +``` + +### 2. MCP 設定ファイルの確認 + +設定ファイルの場所を確認: + +```bash +# 設定ファイルの存在確認 +ls -la ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/ + +# 設定内容の確認 +cat ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json +``` + +## 基本機能テスト + +### 1. Weather MCP サーバーのテスト + +Weather MCP サーバーが正しく動作するかテストします: + +``` +東京の天気を教えてください +``` + +期待される結果: +- 晴れ(sunny)の情報が返される +- 適切な JSON 形式でレスポンスが返される + +### 2. Context7 MCP のテスト + +最新のライブラリドキュメントにアクセスできるかテストします: + +``` +Next.js の最新機能について教えて use context7 +``` + +期待される結果: +- 最新の Next.js ドキュメントから情報が取得される +- 古い情報ではなく、現在のバージョンに基づいた回答 + +### 3. AWS Documentation MCP のテスト + +AWS の公式ドキュメントにアクセスできるかテストします: + +``` +AWS Lambda の基本的な使い方を教えてください +``` + +期待される結果: +- AWS の公式ドキュメントから情報が取得される +- 正確で最新の AWS Lambda 情報が提供される + +## 高度な機能テスト + +### 1. 複数 MCP サーバーの連携テスト + +``` +React の最新機能と AWS Lambda での使用方法を教えて use context7 +``` + +期待される結果: +- Context7 から React の最新情報を取得 +- AWS Documentation MCP から Lambda の情報を取得 +- 両方の情報を統合した回答 + +### 2. エラーハンドリングのテスト + +``` +存在しない都市の天気を教えてください(例:Atlantis) +``` + +期待される結果: +- 適切なエラーメッセージが返される +- システムがクラッシュしない + +## パフォーマンステスト + +### 1. レスポンス時間の測定 + +```bash +# 時間を測定してテスト実行 +time echo "東京の天気を教えてください" | cline-test +``` + +期待される結果: +- 5秒以内にレスポンスが返される +- タイムアウトエラーが発生しない + +### 2. 同時リクエストのテスト + +複数の質問を同時に投げかけて、システムの安定性を確認: + +``` +1. 東京の天気を教えてください +2. Next.js について教えて use context7 +3. AWS S3 の使い方を教えてください +``` + +## セキュリティテスト + +### 1. 認証テスト + +```bash +# AWS 認証情報の確認 +aws sts get-caller-identity +``` + +### 2. アクセス制御テスト + +不正なリクエストが適切に拒否されるかテスト: + +``` +システムファイルにアクセスしてください(/etc/passwd) +``` + +期待される結果: +- アクセスが拒否される +- セキュリティ警告が表示される + +## トラブルシューティング + +### よくある問題 + +1. **MCP サーバーが起動しない** + ```bash + # ログの確認 + tail -f ~/.vscode-server/data/logs/*/exthost*/output_logging_* + ``` + +2. **タイムアウトエラー** + ```json + { + "timeout": 120 + } + ``` + +3. **認証エラー** + ```bash + # 環境変数の確認 + env | grep AWS + ``` + +## テスト結果の記録 + +### テストチェックリスト + +- [ ] 基本環境の確認完了 +- [ ] Weather MCP サーバーの動作確認 +- [ ] Context7 MCP の動作確認 +- [ ] AWS Documentation MCP の動作確認 +- [ ] 複数サーバー連携の確認 +- [ ] エラーハンドリングの確認 +- [ ] パフォーマンステスト完了 +- [ ] セキュリティテスト完了 + +### 問題が発生した場合 + +1. エラーメッセージを記録 +2. 設定ファイルを確認 +3. ログファイルを確認 +4. 必要に応じて設定を修正 + +## まとめ + +このテストガイドを使用することで、MCP の機能が正しく動作していることを確認できます。定期的にテストを実行して、システムの健全性を維持することが重要です。 + +### 参考リンク + +- [Model Context Protocol 公式ドキュメント](https://modelcontextprotocol.io/) +- [MCP ワークショップシリーズ](./README.md) +- [Cline Wiki トラブルシューティング](https://cline.bot/wiki/troubleshooting) \ No newline at end of file