Major Project

🚀 主要プロジェクト：ソフトウェア開発におけるコンテキスト認識型AIエージェントの統合MCPフレームワーク

このプロジェクトは、モデルコンテキストプロトコル（MCP） の核心原則に触発されたフルスタックAIエージェントシステムを実装しています。これは統一的なアーキテクチャフレームワークを提供し、AIオーケストレータが自然言語の指示を解釈し、適切なツール（ファイルシステム、ブラウザ、GitHub）を特定し、そのツールを安全に呼び出し、構造化された結果をフロントエンドのチャットインターフェイスに返すことができます。このプロジェクトは、現代的なクライアント - サーバアーキテクチャを通じて、コンテキスト認識型AIエージェントの実用的なアプリケーションを示しています。

🚀 クイックスタート

このプロジェクトでは、MCPの原則に基づいたAIエージェントシステムを構築しています。まずは、以下のセクションを参考にして、環境のセットアップとアプリケーションの実行を行いましょう。

✨ 主な機能

1. インテリジェントなツール選択

バックエンドのオーケストレータは、Geminiを使用して自然言語のリクエストを解釈し、ツールの呼び出しが必要かどうかを判断し、タスクに最適なツールを決定します。 例:

• “このGitHubリポジトリを要約して。” → GitHubツール
• “最新のクラウドセキュリティのニュースを検索して。” → ブラウザツール
• “report.txtという名前のファイルを作成し、中に内容を書き込んで。” → ファイルシステムツール

2. セキュアなファイルシステム操作

ファイルシステムツールは、以下の操作を提供します。

• ファイルの読み取り
• ファイルの書き込み
• ディレクトリの一覧表示

すべての操作は、mcp_sandbox/ディレクトリに厳密に制限されており、不正なシステムアクセスを防止します。このアプローチは、MCPが強調する機能制限付きのツール実行に一致しています。

3. ウェブブラウジングと検索

ブラウザツールは、Playwrightを使用して以下のことを行います。

• Googleスタイルの検索クエリを実行する
• ライブウェブサイトを訪問する
• ページから可視テキストコンテンツを抽出する
• 構造化されたレスポンスをオーケストレータに返す

これにより、リアルタイムの調査、情報収集、またはウェブサイトコンテンツの要約などのタスクが可能になります。

4. GitHubリポジトリ統合

PyGithubを使用して、GitHubツールは以下のことができます。

• ユーザーのリポジトリを一覧表示する
• ファイルの内容を取得する
• リポジトリのメタデータを調査する

これは、ドキュメントのレビュー、コードのチェック、またはプロジェクトの詳細を取得するなどの開発者ワークフローをサポートします。

5. ツールトレースの可視化

フロントエンドは以下を表示します。

• 呼び出されたツール
• バックエンドから返された生のJSONペイロード
• AIによって生成された説明

この透明性により、ユーザーはエージェントが内部でどのように動作するかを理解するのに役立ちます。また、MCP準拠システムのツール呼び出しトレーシング動作を反映しています。

📦 インストール

1. 前提条件

• Python 3.8以上
• Node.jsとnpm
• Google Gemini APIキー
• GitHubパーソナルアクセストークン（GitHubツールを使用する場合に必要）

2. バックエンドのセットアップ

バックエンドディレクトリに移動し、Python環境を構成します。

cd backend
python -m venv .venv

環境をアクティブ化します。

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

依存関係をインストールします。

pip install -r requirements.txt

Playwrightのブラウザバイナリをインストールします。

playwright install chromium

環境設定

backend/ディレクトリ内に.envファイルを作成します。

GEMINI_API_KEY=your_google_gemini_api_key_here
GITHUB_PAT=your_github_personal_access_token_here

3. フロントエンドのセットアップ

フロントエンドディレクトリに移動し、必要なパッケージをインストールします。

cd frontend
npm install

💻 使用例

基本的な使用法

まず、フロントエンドとバックエンドをそれぞれ起動します。

バックエンドの起動

uvicorn mcp_host_server:app --reload

バックエンドは以下のアドレスで実行されます。

http://127.0.0.1:8000

フロントエンドの起動

npm run dev

フロントエンドインターフェイスは以下のアドレスで利用できます。

http://localhost:5173

📚 ドキュメント

プロジェクトの概要

アーキテクチャ

システムはクライアント - サーバモデルに従い、以下の要素で構成されています。

1. Reactフロントエンド：ユーザーとのインタラクション、リクエストの送信、状態の表示、およびツール呼び出しトレースの可視化を担当します。
2. FastAPIバックエンド：AIオーケストレータとして機能し、リクエストのルーティング、ツールの使用決定、操作の実行、および自然言語のレスポンスの生成を担当します。

AIエンジン

バックエンドは、google-generativeai SDKを介してGoogle Geminiを使用して、プロンプトの解釈、意図分析、ツールのルーティング、および要約を行います。

目的

セキュリティ、透明性、およびモジュール性を維持しながら、ファイル操作、ウェブ調査、およびリポジトリの検査などの開発者中心のタスクを処理できる拡張可能なエージェントフレームワークを構築することです。

技術スタック

フロントエンド

• フレームワーク：高速な開発とビルドパフォーマンスのためのViteを使用したReact 19
• スタイリング：Interフォントファミリを使用したカスタムCSS
• アイコン：Lucide React
• ネットワーキング：fetchを介したREST API通信

バックエンド

• フレームワーク：FastAPI
• サーバーランナー：Uvicorn
• AI統合：Google Generative AI SDK
• ブラウザ自動化：Playwright（非同期）
• GitHub統合：PyGithub
• セキュリティ：予め定義されたディレクトリへのアクセスを制限するファイルシステムサンドボックス

プロジェクト構造

major-project/
├── backend/
│   ├── mcp_host_server.py       # メインのFastAPIアプリケーション；AIオーケストレータのロジック
│   ├── mcp_core.py              # ツールとツール実行のベースインターフェース
│   ├── filesystem_server.py     # サンドボックス内の制限付きファイル操作
│   ├── browser_server.py        # Playwrightを使用したライブウェブ検索とページ抽出
│   ├── github_server.py         # GitHubリポジトリのアクセスとファイル検査
│   ├── mcp_sandbox/             # すべてのファイル操作のための安全なディレクトリ
│   └── requirements.txt         # Pythonの依存関係
│
├── frontend/
│   ├── src/
│   │   ├── App.jsx              # メインのチャットとUIのロジック
│   │   └── App.css              # スタイリングの定義
│   └── package.json             # Node.jsの依存関係
└── README.md

🔧 技術詳細

トラブルシューティングガイド

バックエンドが応答しない場合

フロントエンドに「Backend Status: Offline」と表示される場合は、以下のことを確認してください。

• FastAPIサーバーが実行されていること
• ターミナルにランタイムエラーがないこと
• 環境変数が正しく構成されていること

Playwrightブラウザのエラー

ブラウザツールが失敗した場合は、以下のことを確認してください。

• playwright install chromiumが実行されていること
• システムがPlaywrightの必要な依存関係をサポートしていること
• Windowsの場合、mcp_host_server.pyのイベントループポリシーの修正が有効になっていること

Windowsでの環境問題

このプロジェクトには、Windows固有のイベントループ構成が含まれており、Playwrightの非同期操作がこのプラットフォームで正しく機能するようにしています。