Terminal-based Chat Client with MCP Server Integration

MCP サーバー連携機能を備えたターミナルベースのチャットクライアント

このプロジェクトでは、MCP サーバーに接続し、OpenAI の API と連携するターミナルベースのチャットクライアントインターフェースの構築方法を紹介します。MCP の機能の例として、シンプルな天気サービスが含まれています。

前提条件

• Python 3.8 以降
• UV パッケージマネージャー（高速で信頼性の高い Python パッケージインストーラーおよびリゾルバー）

インストール

1. UV のインストール

UV は、従来の pip などのツールと比べて大幅にパフォーマンスが向上する、最新の Python パッケージマネージャーです。Rust で書かれており、次の機能を備えています。

• パッケージをより高速にインストール
• 信頼性の高い依存関係の解決
• 仮想環境管理機能を内蔵
• 既存の Python ツールと互換性あり

UV をインストールするには、次のコマンドを実行します。

curl -LsSf https://astral.sh/uv/install.sh | sh

2. プロジェクトのセットアップ

1. 新しいプロジェクトを初期化します。

uv init

2. 仮想環境を作成して有効化します。

uv venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows

3. 必要なパッケージをインストールします。

uv pip install httpx mcp[cli] openai python-dotenv

プロジェクト構成と実装ガイド

このプロジェクトは、チャットクライアント（client.py）と天気サービス（weather.py）の 2 つの主要なコンポーネントで構成されています。それぞれのコンポーネントがどのように構築され、各部分が何をするのかを見ていきましょう。

チャットクライアントの構築（client.py）

チャットクライアントは、MCP サーバーと OpenAI の API の両方に接続する非同期 Python アプリケーションとして構築されています。構成は次のとおりです。

1. インポートとセットアップ

   import asyncio
   import os
   import sys
   from typing import Optional
   from contextlib import AsyncExitStack
   from dotenv import load_dotenv
   import openai
   from mcp import ClientSession, StdioServerParameters
   from mcp.client.stdio import stdio_client
   

   • asyncio：非同期プログラミングに使用
   • AsyncExitStack：非同期リソースのクリーンアップを管理
   • dotenv：.env ファイルから環境変数を読み込み
   • mcp：サーバー通信に使用する MCP の中核機能

2. MCPClient クラス メインのクライアントクラスは、次の処理を担います。

   • MCP サーバーへの接続
   • OpenAI API との連携
   • メッセージ処理
   • ツールの実行

   主なメソッド：

   • connect_to_server()：MCP サーバーへの接続を確立します
   • process_query()：ユーザーの問い合わせとツールの実行を処理します
   • chat_loop()：対話型のチャットセッションを管理します
   • cleanup()：リソースを適切にクリーンアップします

3. メイン関数

   async def main():
       client = MCPClient()
       try:
           await client.connect_to_server(sys.argv[1])
           await client.chat_loop()
       finally:
           await client.cleanup()
   

   • クライアントを初期化するエントリーポイント
   • 指定されたサーバーに接続
   • チャットループを実行
   • 適切なクリーンアップを保証

天気サービスの構築（weather.py）

天気サービスは、National Weather Service API を通じて天気情報を提供する MCP サーバーとして構築されています。

1. サービスの初期化

   from mcp.server.fastmcp import FastMCP
   mcp = FastMCP("weather")
   

   • 「weather」という名前の MCP サーバーインスタンスを作成
   • サーバーのインフラストラクチャをセットアップ

2. API 連携

   NWS_API_BASE = "https://api.weather.gov"
   USER_AGENT = "weather-app/1.0"
   

   • National Weather Service API の定数を定義
   • API リクエスト用の適切なユーザーエージェントを設定

3. ヘルパー関数

   • make_nws_request()：適切なエラー処理を行いながら API リクエストを処理します
   • format_alert()：気象警報を読みやすいテキストに整形します

4. MCP ツール 主なツールを 2 つ実装しています。

   a. get_alerts(state)：

   • 米国の州を対象に、有効な気象警報を取得します
   • 整形済みの警報情報を返します

   b. get_forecast(latitude, longitude)：

   • 指定した場所の天気予報を取得します
   • 詳細な天気予報情報を返します

5. サーバーの実行

   if __name__ == "__main__":
       mcp.run(transport="stdio")
   

   • stdio トランスポートを使用して MCP サーバーを実行
   • チャットクライアントとの通信を可能にします

使用方法

1. OpenAI API キーを記載した .env ファイルを作成します。

OPENAI_API_KEY=your_api_key_here

2. MCP サーバーを起動します。

python weather.py

3. 別のターミナルで、チャットクライアントを実行します。

python client.py weather.py

4. チャットインターフェースを操作します。
   • 一般的な質問をして AI とチャットします
   • 天気に関する質問をして天気情報を取得します
   • 例：「カリフォルニアの天気は？」または「ニューヨークに警報は出ていますか？」

Cursor の Agent モードでの使用

この MCP サーバーは Cursor の Agent モードに直接統合できます（注：Cursor の Ask 機能とは異なり、Agent モードでのみ動作します）。セットアップ方法は次のとおりです。

Cursor への MCP サーバーの追加

1. Cursor の設定を開きます
2. Features > MCP に移動します
3. + Add New MCP Server をクリックします
4. フォームに入力します：
   • Type：stdio を選択します
   • Name：「Weather Service」（または任意の名前）
   • Command：weather サーバーを実行するためのフルパスを入力します：

     python /full/path/to/your/weather.py
     

代替方法：プロジェクト固有の設定

.cursor/mcp.json ファイルを作成して、プロジェクト用に MCP サーバーを設定することもできます：

1. プロジェクトのルートに .cursor ディレクトリを作成します：

mkdir .cursor

2. 以下の内容で mcp.json を作成します：

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": [
        "/full/path/to/your/weather.py"
      ]
    }
  }
}

Weather ツールの使用

1. Cursor の Composer（エージェントモード）を開きます
2. エージェントは、天気情報が必要なときに自動的に検出します
3. 質問の例：
   • 「サンフランシスコの現在の天気は？」
   • 「カリフォルニア州に気象警報は出ていますか？」
   • 「ニューヨーク市の天気予報を教えて」

重要な注意事項

• ツールは Cursor のエージェントモード（Composer）でのみ使用でき、Ask モードでは使用できません
• デフォルトでは、Cursor は MCP ツールを使用する前に承認を求めます
• 新しく追加したツールを表示するには、MCP 設定の更新ボタンをクリックする必要がある場合があります
• サーバーはローカルマシンで実行されている必要があります（リモートサーバーには SSE トランスポートが必要です）

機能

• OpenAI と連携したリアルタイムのチャットインターフェース
• 拡張可能な機能を実現する MCP サーバー連携
• 警報と予報に対応した気象サービス
• パフォーマンスを向上させる非同期処理
• 適切なエラー処理とリソースのクリーンアップ
• API キー用の環境変数設定

コントリビューション

問題の報告や機能改善のリクエストをぜひお寄せください！