MCPChatbot Example

MCPChatbot Example

このプロジェクトは、Model Context Protocol (MCP) をカスタマイズされた LLM (例：Qwen) と統合し、MCP サーバーを通じてさまざまなツールと対話できる強力なチャットボットを作成する方法を示しています。この実装は、LLM が外部ツールをシームレスに使用できるようにすることで、MCP の柔軟性を示しています。

ヒント

中国語版については、README_ZH.md を参照してください。

Overview

Chatbot Streamlit Example

Workflow Tracer Example

• 🚩 Update (2025-04-11):
  • Chatbot streamlit example を追加しました。
• 🚩 Update (2025-04-10):
  • より複雑な LLM レスポンス解析、複数の MCP ツール呼び出しと複数のチャット反復に対応。
  • 通常モードとストリーミングモードの両方を備えた単一プロンプト例を追加しました。
  • インタラクティブなターミナルチャットボット例を追加しました。

このプロジェクトには以下が含まれます：

• シンプル / 複雑な CLI チャットボットインターフェース
• Markdown 処理ツールなどの組み込み MCP サーバーとの統合
• カスタマイズされた LLM (例：Qwen) と Ollama のサポート
• 通常モードとストリーミングモードの両方での単一プロンプト処理用スクリプト例
• 通常モードとストリーミングレスポンスモードを備えたインタラクティブなターミナルチャットボット

Requirements

• Python 3.10+
• 依存関係（requirements 経由で自動インストール）：
  • python-dotenv
  • mcp[cli]
  • openai
  • colorama

Installation

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

   git clone [email protected]:keli-wen/mcp_chatbot.git
   cd mcp_chatbot
   

2. 仮想環境をセットアップします（推奨）:

   cd folder
   
   # Install uv if you don't have it already
   pip install uv
   
   # Create a virtual environment and install dependencies
   uv venv .venv --python=3.10
   
   # Activate the virtual environment
   # For macOS/Linux
   source .venv/bin/activate
   # For Windows
   .venv\Scripts\activate
   
   # Deactivate the virtual environment
   deactivate
   

3. 依存関係をインストールします:

   pip install -r requirements.txt
   # or use uv for faster installation
   uv pip install -r requirements.txt
   

4. 環境を設定します:

   • .env.example ファイルを .env にコピーします：

     cp .env.example .env
     

   • .env ファイルを編集して、Qwen API キーを追加します（デモ用です。任意の LLM API キーを使用できます。.env ファイルで base_url と api_key を設定してください）。パスを設定します：

     LLM_MODEL_NAME=your_llm_model_name_here
     LLM_BASE_URL=your_llm_base_url_here
     LLM_API_KEY=your_llm_api_key_here
     OLLAMA_MODEL_NAME=your_ollama_model_name_here
     OLLAMA_BASE_URL=your_ollama_base_url_here
     MARKDOWN_FOLDER_PATH=/path/to/your/markdown/folder
     RESULT_FOLDER_PATH=/path/to/your/result/folder
     

Important Configuration Notes ⚠️

アプリケーションを実行する前に、以下の項目を変更する必要があります：

1. MCP サーバー設定: mcp_servers/servers_config.json を編集して、ローカル設定に合わせます：

   {
       "mcpServers": {
           "markdown_processor": {
               "command": "/path/to/your/uv",
               "args": [
                   "--directory",
                   "/path/to/your/project/mcp_servers",
                   "run",
                   "markdown_processor.py"
               ]
           }
       }
   }
   

   /path/to/your/uv を uv 実行ファイルの実際のパスに置き換えてください。which uv コマンドを使用してパスを取得できます。 /path/to/your/project/mcp_servers をプロジェクト内の mcp_servers ディレクトリへの絶対パスに置き換えてください。（Windows ユーザーの場合、Troubleshooting セクションの例を参照できます）

2. 環境変数: .env ファイルで適切なパスを設定してください：

   MARKDOWN_FOLDER_PATH="/path/to/your/markdown/folder"
   RESULT_FOLDER_PATH="/path/to/your/result/folder"
   

   アプリケーションはこれらのパスを検証し、プレースホルダー値が含まれている場合はエラーをスローします。

次のコマンドを実行して設定を確認できます：

bash scripts/check.sh

Usage

Unit Test

次のコマンドを実行してユニットテストを実行できます：

bash scripts/unittest.sh

Examples

Single Prompt Examples

プロジェクトには 2 つの単一プロンプト例が含まれています：

1. 通常モード: 単一プロンプトを処理して完全なレスポンスを表示

   python example/single_prompt/single_prompt.py
   

2. ストリーミングモード: 単一プロンプトをリアルタイムストリーミング出力で処理

   python example/single_prompt/single_prompt_stream.py
   

両方の例は、使用する LLM プロバイダーを指定するオプション --llm パラメーターを受け入れます：

python example/single_prompt/single_prompt.py --llm=ollama

メモ

詳細については、Single Prompt Example README を参照してください。

ターミナルチャットボット例

このプロジェクトには、2 つのインタラクティブなターミナルチャットボット例が含まれています。

1. 通常モード: 完全な応答を含むインタラクティブなターミナルチャット

   python example/chatbot_terminal/chatbot_terminal.py
   

2. ストリーミングモード: ストリーミング応答を含むインタラクティブなターミナルチャット

   python example/chatbot_terminal/chatbot_terminal_stream.py
   

どちらの例も、使用する LLM プロバイダーを指定するためのオプションの --llm パラメータを受け入れます。

python example/chatbot_terminal/chatbot_terminal.py --llm=ollama

メモ

詳細については、ターミナルチャットボット例の README を参照してください。

Streamlit ウェブチャットボット例

このプロジェクトには、Streamlit を使用したインタラクティブなウェブベースのチャットボット例が含まれています。

streamlit run example/chatbot_streamlit/app.py

この例の特徴：

• インタラクティブなチャットインターフェース。
• リアルタイムストリーミング応答。
• 詳細な MCP ツールワークフローの視覚化。
• サイドバーを使用した設定可能な LLM 設定 (OpenAI/Ollama) と MCP ツール表示。

メモ

詳細については、Streamlit チャットボット例の README を参照してください。

プロジェクト構成

• mcp_chatbot/: コアライブラリコード
  • chat/: チャットセッション管理
  • config/: 設定処理
  • llm/: LLM クライアント実装
  • mcp/: MCP クライアントとツール統合
  • utils/: ユーティリティ関数 (WorkflowTrace と StreamPrinter など)
• mcp_servers/: カスタム MCP サーバー実装
  • markdown_processor.py: Markdown ファイルを処理するサーバー
  • servers_config.json: MCP サーバーの設定
• data-example/: テスト用のサンプル Markdown ファイル
• example/: さまざまなユースケースのサンプルスクリプト
  • single_prompt/: 単一プロンプト処理の例 (通常およびストリーミング)
  • chatbot_terminal/: インタラクティブなターミナルチャットボット例 (通常およびストリーミング)
  • chatbot_streamlit/: Streamlit を使用したインタラクティブなウェブチャットボット例

プロジェクトの拡張

このプロジェクトは次の方法で拡張できます。

1. mcp_servers/ ディレクトリに新しい MCP サーバーを追加する
2. servers_config.json を更新して、新しいサーバーを含める
3. 既存のサーバーに新しい機能を実装する
4. 提供されたテンプレートに基づいて新しい例を作成する

トラブルシューティング

Windows ユーザーの場合、次の servers_config.json を例として使用できます。

{
    "mcpServers": {
        "markdown_processor": {
            "command": "C:\\Users\\13430\\.local\\bin\\uv.exe",
            "args": [
                "--directory",
                "C:\\Users\\13430\\mcp_chatbot\\mcp_servers",
                "run", 
                "markdown_processor.py"
            ]
        }
    }
}

• パスの問題: 設定ファイル内のすべてのパスがお使いのシステムに適した絶対パスであることを確認してください
• MCP サーバーエラー: ツールが正しくインストールされ設定されていることを確認してください
• API キーエラー: API キーが .env ファイルに正しく設定されていることを確認してください