Llama-Server MCP Proxy

Llama-Server MCP プロキシ

このNode.jsアプリケーションは、llama-serverのプロキシサーバーとして機能します。主な目的は、チャット完了リクエストをインターセプトし、Model Context Protocol(MCP)を介したツール機能で拡張し、言語モデル(LLM)がこれらのツールを反復的に使用できるようにすることです。

標準的なllama-server GUIリクエスト(メインページの取得など)をローカルのllama-serverインスタンスに直接プロキシし、特に/v1/chat/completionsリクエストを処理してツール相互作用を実現します。

現在のステータス

• brave searchが動作します
• search1 APIが動作します
• ファイルシステムアクセスは使用しているモデルによって問題があります
• puppeteer

主な機能

• MCPツール統合: mcp-config.jsonで定義されたMCP互換ツールサーバーに接続します。
• 動的システムプロンプト: 利用可能なツールとその説明を一覧表示するシステムプロンプトを自動生成し、LLMのコンテキストに注入します。
• 反復的なツール使用: LLMが単一のユーザーターンで複数のツール呼び出しを行うことを可能にします。プロキシはリクエスト応答フローを処理します:
  1. LLMがツール呼び出しを示します。
  2. プロキシがツール呼び出しを検出および解析します。
  3. プロキシが適切なMPCクライアント経由でツールを実行します。
  4. プロキシがツールの結果をLLMに送り返します。
  5. LLMがその結果を使用して応答を続けるか、別のツールを呼び出します。
• ストリーミング対応: LLMレスポンスのストリーミング(Server-Sent Events)をクライアントに維持し、「[ツール実行中...]」などの中間メッセージとツール結果を含めます。
• エラーハンドリング: llama-serverからのエラーをフォワードし、失敗したツール実行のエラーメッセージをLLMとクライアントに提供します。LLMがエラーを分析し、実行可能なアプローチを見つけようとします。
• 構成可能: ポート、llama-server URL、MCP構成パスの環境変数を使用します。
• デバッグログ: 環境変数経由でオプションの詳細デバッグログを提供します。

前提条件

• Node.js: バージョン18以上(@modelcontextprotocol/sdkの依存関係で示されているとおり)。
• llama-server: 実行中のllama-serverインスタンス(または互換性のあるOpenAI互換APIエンドポイント)。
• MCPツールサーバー: LLMがアクセスしたい1つ以上のMCP互換ツールサーバー。

セットアップ

1. リポジトリをクローン（またはプロジェクトディレクトリを作成）:

   # git リポジトリがある場合:
   # git clone <your-repo-url>
   # cd llama-server_mcp_proxy
   
   # ゼロから始める場合は、ディレクトリを作成して移動します:
   mkdir llama-server_mcp_proxy
   cd llama-server_mcp_proxy
   

2. package.json を作成: まだない場合は、以下の内容で package.json ファイルを作成します:

   {
     "name": "llama-server-mcp-proxy",
     "version": "1.0.0",
     "description": "A proxy for llama-server to enable MCP tool usage.",
     "main": "llama-server-mcp-proxy.js", 
     "scripts": {
       "start": "node llama-server-mcp-proxy.js"
     },
     "dependencies": {
       "@modelcontextprotocol/sdk": "^1.8.0"
     }
   }
   

3. 依存関係をインストール: プロジェクトディレクトリで以下のコマンドを実行して、必要なパッケージをインストールします:

   npm install
   

   これにより package.json（および存在して一貫性がある場合は package-lock.json）を使用して @modelcontextprotocol/sdk がインストールされます。

4. mcp-config.json を作成: このファイルは、プロキシが MCP ツールサーバーに接続する方法を指定します。デフォルトではプロキシスクリプト（例: llama-server-mcp-proxy.js）と同じディレクトリに配置するか、MCP_CONFIG_PATH 環境変数でパスを指定できます。

   クイックスタートの例として、mcp-config.json.example の名前を mcp-config.json に変更してください。

   mcp-config.json.example:

   {
     "mcpServers": {
       "search1api": {
         "command": "npx",
         "args": [
           "search1api-mcp",
           "--port",
           "0", 
           "--api-key",
           "YOUR_SEARCH1API_KEY_PLACEHOLDER" 
         ],
         "env": {
           "DEBUG": "true" 
         }
       },
       "another_tool_server": {
         "command": "path/to/your/tool/server/executable",
         "args": [
           "--some-config-for-tool", "value",
           "--api-key", "ANOTHER_API_KEY_PLACEHOLDER"
         ],
         "env": {}
       }
     }
   }
   

   • mcpServers: 各キーがツールサーバーの一意な名前（例: "search1api"、"my_custom_tools"）であるオブジェクト。
   • command: MCP ツールサーバーを開始するために実行するコマンド。npx で実行可能なパッケージ、実行ファイルへの直接パス、またはスクリプトが可能です。
   • args: コマンドに渡す引数の配列。
     • --port 0 は通常、MCP サーバーに stdio 通信用の利用可能なポートを選択させるために使用されます。
     • YOUR_SEARCH1API_KEY_PLACEHOLDER および他のプレースホルダーを実際の API キーまたは必要な設定に置き換えてください。
   • env: MCP サーバープロセス用に設定する環境変数のオプションのオブジェクト。

   例をコピーして実際の mcp-config.json を作成し、実際の API キーとパスを入力してください。

5. mcp-config.json を .gitignore に追加: 機密 API キーを誤ってコミットするのを防ぐために、プロジェクトルートで .gitignore ファイルを作成または更新します:

   node_modules/
   mcp-config.json
   *.log
   # 無視したい他のファイル/ディレクトリを追加
   

6. プロキシコードを保存: 前のステップで提供された JavaScript プロキシコードを、例えば llama-server-mcp-proxy.js（package.json で参照）というファイルに保存します。

プロキシの実行

1. llama-server が実行されていることを確認してください。 プロキシはこれに接続する必要があります。デフォルトでは、プロキシは llama-server が http://localhost:8080 にあると想定しています。

2. プロキシサーバーを起動します: プロジェクトディレクトリでターミナルを開き、以下を実行してください:

   npm start
   

   または Node を直接使用:

   node llama-server-mcp-proxy.js
   

   プロキシが起動したこと、接続した MCP サーバー、および利用可能なツールを示すコンソール出力が表示されます。

3. 環境変数を設定します (オプション): 環境変数を使用してプロキシの動作をカスタマイズできます:

   • PORT: プロキシサーバーがリッスンするポート (デフォルト: 9090)。
   • LLAMA_SERVER_URL: 実行している llama-server インスタンスの URL (デフォルト: http://localhost:8080)。
   • MCP_CONFIG_PATH: mcp-config.json ファイルへのフルパス (デフォルト: スクリプトからの相対パス ./mcp-config.json)。
   • MCP_PROXY_DEBUG: 詳細なデバッグログを出力する場合は true に設定 (デフォルト: false)。
   • LLAMA_SERVER_TIMEOUT: llama-server へのリクエストのタイムアウト時間 (ミリ秒単位、デフォルト: 60000)。

   例 (Linux/macOS):

   PORT=9000 LLAMA_SERVER_URL=http://127.0.0.1:8081 MCP_PROXY_DEBUG=true node llama-server-mcp-proxy.js
   

   例 (Windows PowerShell):

   $env:PORT="9000"; $env:LLAMA_SERVER_URL="http://127.0.0.1:8081"; $env:MCP_PROXY_DEBUG="true"; node llama-server-mcp-proxy.js
   

使用方法

1. プロキシサーバーが実行中になったら、LLM GUI クライアント (例: 通常は llama-server と通信するウェブ UI にアクセスするブラウザ) をプロキシのアドレスとポートに指定してください (例: プロキシがポート 9090 で実行されている場合は http://localhost:9090)。
2. 通常通り LLM と対話してください。
3. 設定されたツールの 1 つから恩恵を受ける可能性のあるタスクを実行するよう LLM に依頼するとき、以下が発生します:
   • ツールを使用する意図を示します。
   • TOOL_NAME(ARG_NAME="ARG_VALUE", ...) 形式またはポテンシャルに XML 形式のツール呼び出しを出力します。
4. プロキシは以下を行います:
   • このツール呼び出しを検出します。
   • ストリーム内に "[Executing tool: TOOL_NAME...]" メッセージを表示します。
   • ツールを実行します。
   • ストリーム内に "[Tool Result for TOOL_NAME]: ...RAW_RESULT..." メッセージを表示します。
   • 結果を LLM にフィードバックします。
5. LLM はその後、ツールの結果を使用して最終応答を作成するか、別のツールを呼び出すかを決定します。

認識されるツール呼び出し形式

プロキシは、LLM が現在の応答セグメントを終了した後 ([DONE] で示される) に、LLM の出力内のツール呼び出しを 2 つの主要な形式で認識しようとします:

1. シンプル関数形式:

   tool_name(param1="value1", param2="value2")
   

   例: news(query="latest AI research", max_results=3)

2. XML 形式:

   <tool_call>
       <tool>tool_name</tool>
       <params>
           <param1>value1</param1>
           <param2>value2</param2>
       </params>
   </tool_call>
   

プロキシは各形式に応じて引数を解析します。

トラブルシューティング

• "Tool ... not found in any connected MCP server":
  • LLM が出力するツール名が、プロキシ起動時に表示されるツール名（MCP サーバーから取得）と完全に一致していることを確認してください。
  • mcp-config.json でツールサーバーのコマンドまたは設定にタイプミスがないか確認してください。
  • MCP ツールサーバーが正しく起動し、ツールを正常に登録しているか確認してください。プロキシ起動時のコンソール出力で接続メッセージを確認してください。
• プロキシエラー / llama-server エラー（500、502 など）:
  • llama-server が実行中で、LLAMA_SERVER_URL でアクセス可能であることを確認してください。
  • llama-server 自身のログで問題がないか確認してください。
  • MCP_PROXY_DEBUG=true を有効にして、プロキシからのより詳細なログを取得してください。
• ツール実行エラー（例：「402 Payment Required」）: これらのエラーは MCP ツールサーバー自身から発生します。プロキシはこれらのエラーを LLM に報告し、LLM は理想的には別のアプローチを試みるか、あなたに通知するべきです。
• 「Socket hang up」/ ECONNRESET: llama-server が予期せず接続を切断した場合に発生することがあります。これはプロキシが不正形式のリクエスト（例：JSON 構造が正しくない、問題のあるヘッダー）を送信した場合や、llama-server 自身が内部エラーが発生した場合に起こる可能性があります。プロキシと llama-server の両方のデバッグログが重要です。

依存関係

• @modelcontextprotocol/sdk: バージョン ^1.8.0（および package-lock.json に記載されている推移的な依存関係）。

---