MCP Agent

MCP エージェント

Vercel AI SDK を介してさまざまな LLM（Google Gemini、Anthropic Claude、OpenAI GPT、xAI Grok）を利用し、Model Context Protocol（MCP）サーバーを通じて外部サービスと連携できる、ウェブベースの会話型エージェントです。

概要

このプロジェクトでは、ユーザーが LLM プロバイダーとモデルを選択し、選んだ LLM と会話できるチャットインターフェースを提供します。このエージェントは Vercel AI SDK を活用して複数ステップのツール実行を処理し、設定済みの MCP サーバー（例：WhatsApp、GitHub、GSuite、ウェブ検索）と LLM が連携してユーザーのリクエストに応えられるようにします。

アーキテクチャ

このプロジェクトは、以下のコンポーネントで構成されています。

1. フロントエンド（mcp-agent-app/）： http://localhost:3000 でアクセスできる、React ベースのチャットインターフェースを提供する Next.js アプリケーションです。
   • @ai-sdk/react の useChat フックを使用して、チャットの状態とストリーミング応答を管理します。
   • React Context（ChatContext）を使用して、現在のチャット ID、選択したプロバイダー／モデルなどのアプリケーション状態を管理し、useChat フックの状態や関数を利用できるようにします。
   • LLM プロバイダー／モデルの選択や、保存済みチャットの管理を行うサイドバーを備えています。
2. チャット API（mcp-agent-app/src/app/api/chat/route.ts）： 以下の処理を行う Next.js API ルートです。
   • フロントエンドからチャットメッセージ、プロバイダー ID、モデル ID を受け取ります。
   • リクエストに基づいて、適切な LLM プロバイダー（例：@ai-sdk/google、@ai-sdk/anthropic）を選択し、インスタンス化します。
   • mcp-config.json から MCP サーバーの設定を読み込みます。
   • ヘルパー（prepareStdioArgs）を使用して、サーバーコマンドのパスと環境変数を解決します。
   • ai および ai/mcp-stdio の experimental_createMCPClient と Experimental_StdioMCPTransport を使用して MCP クライアントを初期化します。
   • 初期化した MCP クライアントから mcpClient.tools() を使用して、ツールのスキーマを直接取得します。
   • Vercel AI SDK の streamText 関数を呼び出し、選択した言語モデル、メッセージ、統合した MCP ツールを渡します。
   • MCP クライアントによる自動ツール呼び出しを含む複数ステップの会話フローを、streamText（maxSteps > 1 を指定）に処理させます。
   • stdio ツールとの現在の SDK 互換性の問題により、Anthropic ではツールを無効にする回避策を含みます。
   • result.toDataStream() を使用して、応答（テキストチャンク、エラー）をフロントエンドにストリーミングします。
   • onFinish コールバックで MCP クライアントの接続を閉じます。
3. チャット永続化 API（mcp-agent-app/src/app/api/chats/）： Prisma と SQLite データベースを使用して、チャットセッションの保存、読み込み、一覧表示、削除を行う Next.js API ルートです。チャット履歴（CoreMessage[]）、タイトル、プロバイダー ID、モデル ID を保存します。
4. MCP サーバー： Model Context Protocol（MCP）を実装する外部プロセス（Python スクリプト、Docker コンテナー）です。チャット API のバックエンドは、mcp-config.json に基づいて StdioMCPTransport 経由でこれらのサーバーを起動します。
5. 設定：
   • mcp-agent-app/mcp-config.json：利用可能な MCP サーバー、起動コマンド、ツールスキーマを定義します（ただし、現在は主にスキーマを動的に取得します）。
   • mcp-agent-app/llm-config.json：フロントエンド UI で利用できる LLM プロバイダーとモデルを定義します。
   • mcp-agent-app/.env.local：バックエンドと MCP サーバーに必要な API キー、トークン、パスを保存します。

セットアップ

前提条件：

• Node.js（LTS バージョンを推奨）
• npm または yarn
• uv（Python パッケージマネージャー）
• Docker（GitHub MCP サーバー用）
• LLM API キー： 使用するプロバイダー（Google Gemini、Anthropic Claude、OpenAI GPT、xAI Grok）のキーを取得し、.env.local に設定してください。
• GitHub Personal Access Token（PAT）： 適切なスコープ（例：repo、read:user）を指定して作成し、.env.local の GITHUB_PERSONAL_ACCESS_TOKEN に設定してください。
• GSuite OAuth2 認証情報： GSuite MCP Server セクションの手順に従ってください。

インストールと設定：

1. リポジトリをクローンします：

   git clone <repository_url>
   cd mcp-agent
   

2. Next.js アプリの依存関係をインストールします：

   cd mcp-agent-app
   npm install
   # or yarn install
   

3. 環境変数を設定します：
   • mcp-agent-app/ に .env.local を作成します。
   • API キー、トークン、設定パスを追加します。例：

     # .env.local
     
     # LLM API Keys (Add keys for providers you want to use)
     GOOGLE_API_KEY=YOUR_GEMINI_API_KEY
     ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
     OPENAI_API_KEY=YOUR_OPENAI_API_KEY
     XAI_API_KEY=YOUR_XAI_API_KEY
     
     # GitHub Token
     GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT
     
     # Paths (Adjust if needed, especially if uv isn't in PATH)
     # UV_PATH=/path/to/your/uv # Optional override
     WHATSAPP_MCP_SCRIPT_DIR=../whatsapp-mcp/whatsapp-mcp-server # Relative paths often work
     GSUITE_MCP_SCRIPT_DIR=../mcp-gsuite
     GSUITE_GAUTH_FILE=../mcp-gsuite/.gauth.json
     GSUITE_ACCOUNTS_FILE=../mcp-gsuite/.accounts.json
     GSUITE_CREDENTIALS_DIR=../mcp-gsuite/gsuite-credentials # Directory for storing token.json
     DDG_MCP_SCRIPT_DIR=../duckduckgo-mcp-server
     
     # Database URL (SQLite)
     DATABASE_URL="file:./dev.db"
     

   • プレースホルダーを置き換えてください。パスが mcp-agent-app ディレクトリからの相対パスとして正しいことを確認するか、絶対パスを使用してください。
4. データベースをセットアップします：

   npx prisma migrate dev --name init # Or your latest migration name
   

アプリケーションの実行：

• MCP サーバー： 必要な MCP サーバーが実行中、またはアクセス可能であることを確認してください（例：GitHub 用に Docker デーモンを実行する、必要に応じて他のサーバーを手動で起動する。ただし、アプリは stdio 経由での起動を試みます）。
  • 注： 現在の実装では、StdioMCPTransport を介して MCP サーバーを必要に応じて起動します。特定のサーバーをデバッグする場合を除き、通常は手動で起動する必要はありません。サーバーで必要な場合は、WhatsApp Go bridge などの前提条件も実行中であることを確認してください。
• Next.js アプリを起動します：

  cd mcp-agent-app
  npm run dev
  # or yarn dev
  

• http://localhost:3000 を開きます。

使用方法

• サイドバーのドロップダウンから、使用する LLM プロバイダーとモデルを選択します。
• チャットインターフェースでやり取りします。
• エージェントは選択した LLM を使用し、適切な場合は設定済みの MCP ツールの使用を試みます（Anthropic では現在ツールが無効になっています）。
• 会話を保存するには「Save Chat」ボタンを使用します。履歴一覧から以前のチャットを読み込めます。

プロンプトの例：

• Who are you?
• Search the web for the latest AI news.（ddg-search を使用）
• Get issue number 1 from the vercel/ai repository.（github を使用）
• Send a WhatsApp message to [Number] saying "Test from MCP Agent"（whatsapp を使用）
• What's on my main Google Calendar today?（gsuite を使用）

新しい MCP サーバーの追加

1. MCP サーバーを実装する： stdio/JSON-RPC 経由で通信するサーバーを開発します。
2. mcp-config.jsonを更新する： サーバーのid、description、command（executableEnvVar／defaultExecutable、argsTemplate、scriptDirEnvVar、envVarsを含む）を定義するエントリーを追加します。設定内のツールスキーマは動的に検出されるようになったため、重要度は下がっていますが、説明は役立ちます。
3. .env.localを更新する： 新しいサーバーのコマンドで必要な環境変数を追加します。
4. mcp-agent-appを再起動する： バックエンドが新しいサーバーへの接続を試み、ツールを検出します。

現在の MCP サーバー

(説明はほぼ同じですが、実行はStdioMCPTransportが処理するようになりました)

WhatsApp MCP サーバー

• ソース： whatsapp-mcp/
• 実行： uv run経由でPythonスクリプトを実行します。Goブリッジを別途起動しておく必要があります。
• 設定： WHATSAPP_MCP_SCRIPT_DIR

GitHub MCP サーバー

• ソース： Dockerイメージ（ghcr.io/github/github-mcp-server）
• 実行： docker run経由でDockerコンテナを実行します。Dockerデーモンが起動している必要があります。
• 設定： GITHUB_PERSONAL_ACCESS_TOKEN

GSuite MCP サーバー

• ソース： mcp-gsuite/
• 実行： uv run経由でPythonスクリプトを実行します。
• 設定： GSUITE_MCP_SCRIPT_DIR、GSUITE_GAUTH_FILE、GSUITE_ACCOUNTS_FILE、GSUITE_CREDENTIALS_DIR。OAuth2の設定が必要です。

DuckDuckGo検索 MCP サーバー

• ソース： duckduckgo-mcp-server/
• 実行： uv run経由でPythonモジュールを実行します。
• 設定： DDG_MCP_SCRIPT_DIR

ファイルとフォルダーの構成

mcp-agent/ (Project Root)
├── .gitignore
├── LICENSE
├── README.md (This file)
├── docs/ (Additional documentation)
├── mcp-agent-app/ (Next.js Application)
│   ├── .env.local (API Keys, Paths, DB URL)
│   ├── llm-config.json (LLM Provider/Model definitions for UI)
│   ├── mcp-config.json (MCP server command configurations)
│   ├── next.config.ts
│   ├── package.json
│   ├── prisma/
│   │   └── schema.prisma (Database schema)
│   │   └── migrations/
│   ├── src/
│   │   ├── app/
│   │   │   ├── api/
│   │   │   │   ├── chat/route.ts (Main chat API, uses Vercel AI SDK)
│   │   │   │   └── chats/ (API routes for saving/loading chats)
│   │   │   └── page.tsx (Main page component)
│   │   ├── components/ (React components: ChatInterface, Sidebar, etc.)
│   │   ├── context/
│   │   │   └── ChatContext.tsx (Manages app state, integrates useChat hook)
│   │   └── lib/
│   │       └── prisma.ts (Prisma client instance)
│   └── ... (Other Next.js files)
├── duckduckgo-mcp-server/
├── github-mcp-server/ (Source code, not directly run if using Docker image)
├── mcp-gsuite/
└── whatsapp-mcp/
    ├── whatsapp-bridge/ (Go component - needs separate execution)
    └── whatsapp-mcp-server/ (Python component)

デバッグ

• Next.jsサーバー（npm run dev）のターミナルログを確認します。APIキーの状態、プロバイダー／モデルの使用状況、MCPの初期化手順、streamText中に発生したエラーを確認してください。
• コンテキスト操作やフロントエンドで発生した可能性のあるエラーについて、ブラウザーのコンソールログを確認します。
• MCPサーバーの初期化に失敗する場合は、prepareStdioArgsのログを確認し、.env.local内のパスと環境変数が正しいことを確認してください。
• APIキーとトークンを確認します。

ライセンス

このプロジェクトは、MITオープンソースライセンスの条項に基づいてライセンスされています。ライセンスの全文についてはMITを参照してください。