🧠 Ultimate MCP Client

🧠 Ultimate MCP Client

Jeffrey Emanuel によって開発されました

---

🎯 目的と背景

Model Context Protocol（MCP）は、AI モデルが外部機能（ツール、リソース、プロンプト）と連携する方法を標準化します。このクライアントは、MCP を活用するための究極のインターフェースを目指し、次の機能を提供します。

1. 堅牢な接続性： 回復力、高度なエラー処理、インテリジェントな検出機能を備え、多様な MCP サーバー（stdio、sse）へ確実に接続します。
2. 優れたユーザー体験： 強力な対話型 CLI と最新のリアクティブな Web UI の両方を提供し、多様なワークフローで使いやすさを実現します。
3. 高度な状態管理： 単純なチャット履歴にとどまらず、分岐可能な会話グラフ、セッションをまたいで保持される状態、スマートなコンテキスト最適化手法を備えています。
4. 開発者向けの内部情報： OpenTelemetry のメトリクスとトレースによる詳細な可観測性に加え、クライアントとサーバーの健全性やパフォーマンスを監視するライブダッシュボードを提供します。
5. シームレスな統合： ローカルのファイルシステムスクリプト、ローカルネットワーク（mDNS）サーバー、ローカルポートスキャンの結果、リモートレジストリのエントリ、さらには Claude Desktop アプリのような既存ツールの設定も簡単に検出して統合できます。

このプロジェクトは、信頼性の高い stdio 通信、非同期状態管理、CLI と Web インターフェースの両方で一貫した体験を提供することなど、重大なエンジニアリング上の課題に取り組み、真に包括的な MCP クライアントソリューションを実現します。

---

🔌 主な機能

• 2 種類のインターフェース：Web UI と CLI

  • Web UI： Alpine.js、DaisyUI、Tailwind CSS で構築された、美しくリアクティブなインターフェースです。WebSocket によるリアルタイムのチャットストリーミング、サーバー／ツール管理モーダル、視覚的な会話分岐ビュー、設定、複数のテーマ切り替え（コードのハイライト表示でライト／ダークモードを反映）、ツールの直接実行機能を備えています。
  • CLI： 機能豊富な対話型シェル（/commands、自動補完、Rich による Markdown レンダリング）と、Typer を使ったバッチモードでの操作を提供します。監視用のライブ Textual User Interface（TUI）ダッシュボードも含まれています。

• 堅牢なサーバー接続と管理

  • stdio、sse（HTTP Server-Sent Events）、および streaming-http MCP サーバーをサポートします。
  • 高度な STDIO 処理（主要なエンジニアリングの取り組み）： ノイズが多い、または仕様に準拠していない可能性のある stdio サーバーを適切に処理するために設計された、カスタムの RobustStdioSession を備えています。次の機能が含まれます。
    • ノイズフィルタリング： プロトコルを破損させる可能性のある、JSON-RPC 以外の出力を無視します。
    • Future の直接解決： 複雑なキューイングを避け、応答処理を高速化します。
    • プロセスのライフサイクル管理： stdio サーバープロセスを確実に起動、監視、終了、強制終了します。
    • 重要な STDIO 安全対策： 多層システム（StdioProtectionWrapper、safe_stdout コンテキストマネージャー、get_safe_console() 関数）により、sys.stdout への誤った書き込みが stdio チャネルを破損させるのを防ぎます。これにより、複数の stdio サーバーとユーザー出力（必要に応じて stderr にリダイレクト）を安全に共存させられます。これは安定性の確保に不可欠でした。
  • 耐障害性： 指数バックオフと、障害が発生したサーバー向けのサーキットブレーカー（@retry_with_circuit_breaker）を用いて、自動的に接続を再試行します。バックグラウンドのヘルスモニタリング（ServerMonitor）でサーバーの応答性を確認します。

• 最新のトランスポートのサポート

  • Streaming-HTTP： FastMCP ライブラリを通じて、最新の streaming-http トランスポートプロトコルをネイティブにサポートします。このトランスポートは、ストリーミング機能を内蔵した効率的な HTTP 双方向通信を提供するため、最新の MCP サーバーのデプロイに最適です。
  • インテリジェントなトランスポート検出： サーバー URL と検出情報に基づいて、適切なトランスポートタイプを自動検出して提案します。
    • ローカルファイルパス → stdio
    • /sse または /events パスを含む URL → sse
    • 一般的な HTTP/HTTPS URL → streaming-http（最新のサーバーのデフォルト）

• インテリジェントなサーバー検出

  • 設定されたファイルシステムパスにあるローカルの stdio サーバー（Python/JS スクリプト）を自動検出します。
  • mDNS 検出（Zeroconf）： ローカルネットワーク上の MCP サーバー（_mcp._tcp.local.）をリアルタイムで検出し、通知します。LAN サーバーを管理するための対話型コマンド（/discover list、/discover connect など）を備えています。
  • ローカルポートスキャン： 設定可能な範囲のローカルポート（例：8000-9000）を積極的にスキャンし、initialize ハンドシェイクを試みて MCP サーバーを検出します。すべてのトランスポートタイプ（stdio、sse、streaming-http）の検出をサポートします。/config port-scan ... コマンドで設定できます。
  • レジストリ連携： 設定で指定されたリモート MCP レジストリに接続し、共有サーバーを見つけて追加します。
  • Claude Desktop のインポート： プロジェクトのルートにある claude_desktop_config.json を自動検出します。設定をインテリジェントに適応します。
    • wsl.exe ... bash -c "cmd" の呼び出しを、Linux シェルの直接実行（/bin/bash -c "cmd"）にリマップします。
    • 引数内の Windows 形式のパス（C:\...）を、adapt_path_for_platform を使用して Linux/WSL 相当のパス（/mnt/c/...）に変換し、シームレスに連携します。

• 強力な AI 連携とストリーミング

  • 公式の anthropic SDK を介して Claude モデルと深く連携し、複数ターンにわたるツール使用のシナリオをサポートします。
  • リアルタイムストリーミング： WebSocket（Web UI）と Rich によるライブレンダリング（CLI）を通じて、AI の応答とツールのステータス更新をストリーミングします。構造化入力を必要とするツール向けの**部分的な JSON 入力の蓄積（input_json_delta）**など、複雑なストリーミングイベントを処理します。
  • インテリジェントなツールルーティング： 読み込まれた機能に基づいてツール呼び出しを適切な送信元サーバーに振り分けます。API 互換性のために無害化した名前を使用しながら、内部では元の名前を追跡します。
  • ツールの直接実行： /tool コマンド（CLI）または専用モーダル（Web UI）から、カスタム JSON パラメーターを指定して特定のツールを実行できます。

• 高度な会話管理

  • ブランチング: フォーク可能な会話グラフ (ConversationGraph) により、履歴を失わずに異なるインタラクションパスを探索できます。Web UI で視覚的に表現され、ナビゲート可能です。
  • 永続化: 会話グラフ (すべてのブランチとメッセージを含む) は、設定ディレクトリの JSON ファイルに自動的に保存され、セッション間でステートが保持されます。
  • コンテキスト最適化: 指定された AI モデル (設定可能) を使用した長い会話履歴の自動または手動要約 (/optimize) により、コンテキスト制限内に留まります。
  • 動的プロンプト: /prompt コマンドを使用してサーバーから取得した事前定義のプロンプトテンプレートを現在の会話コンテキストに注入します。
  • インポート/エクスポート: 会話ブランチ全体を簡単に保存 (/export) および読み込み (/import) でき、共有またはバックアップ用のポータブル JSON 形式で利用できます。

• オブザーバビリティと監視

  • OpenTelemetry: メトリクス (カウンター、opentelemetry-sdk を使用したヒストグラム) と トレース (スパン) の統合により、クライアント操作、サーバーリクエスト、ツール実行パフォーマンスを監視できます。デバッグ用にコンソールエクスポーターを有効にできます。
  • ライブダッシュボード:
    • CLI: Rich で構築されたリアルタイム TUI ダッシュボード (/dashboard) は、サーバーヘルス、ツール使用統計、およびクライアント情報を表示します。
    • Web UI: サーバーステータス、ヘルスインジケーター、およびケーパビリティ数を動的に更新します。

• スマートキャッシング

  • ツール結果の速度向上とコスト削減のためのオプショナルなディスク (diskcache) およびメモリ内キャッシング。
  • ツールカテゴリーごと (例: weather、filesystem) の設定可能な Time-To-Live (TTL)。
  • 依存関係追跡: ツール間の関係を定義します。1 つのツールのキャッシュを無効化する (例: stock:lookup) と、依存するキャッシュを自動的に無効化できます (例: stock:analyze)。グラフは /cache dependencies で表示できます。

---

📸 スクリーンショット

Ultimate MCP Client のインターフェースの様子です：

対話型CLI：ツール呼び出し・結果のストリーミングレスポンス。	ライブTUIダッシュボード：リアルタイムサーバー＆ツール監視（/dashboard）。
Web UI：メッセージとツール操作を表示するメインチャットインターフェース。	Web UI：接続ステータスとコントロール付きサーバー管理タブ。	Web UI：会話タブが分岐グラフ構造を表示。

注記： 一部のスクリーンショットには llm_gateway:generate_completion などのツールが含まれています。これらは LLM Gateway MCP Server（同じ著者による別のプロジェクト）によって提供されます。このサーバーは MCP ネイティブゲートウェイとして機能し、高度なエージェント（このクライアントが使用する Claude など）がさまざまな他の LLM（例：Gemini、GPT-4o-mini）にインテリジェントにタスクを委譲できるようにし、多くの場合コストとパフォーマンスを最適化します。

---

🚀 クイックスタート

依存関係をインストール

Python 3.13+ が必要です

まず uv（推奨される高速な Python パッケージインストーラー）をインストールしてください：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

次にリポジトリをクローンし、Python 3.13+ を使用して仮想環境をセットアップし、パッケージをインストールします：

git clone https://github.com/Dicklesworthstone/ultimate_mcp_client
cd ultimate_mcp_client

# Create venv using uv (recommended)
uv venv --python 3.13
# Or using standard venv
# python3.13 -m venv .venv

# Activate environment
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows Powershell
# .\venv\Scripts\activate.bat # Windows CMD

# Install dependencies using uv (fastest)
uv sync --all-extras
# Or using pip (slower)
# pip install -e . # Installs only core dependencies

API キーを設定

Anthropic API キーを環境変数として設定します：

export ANTHROPIC_API_KEY="sk-ant-..."
# Or add ANTHROPIC_API_KEY="sk-ant-..." to a .env file in the project root

あるいは、対話型CLI の /config api-key ... コマンドを使用するか、Web UI の設定パネルから後で設定することもできます。

Web UI を起動（推奨）

mcpclient run --webui

次にブラウザを http://127.0.0.1:8017（またはカスタマイズされたホスト/ポート）に開きます。

ホストとポートをカスタマイズできます：

mcpclient run --webui --host 0.0.0.0 --port 8080

対話型CLIモードを実行

mcpclient run --interactive

ワンショットクエリを実行

mcpclient run --query "What's the weather in New York?"

CLI ダッシュボードを表示

mcpclient run --dashboard

ポートスキャンを設定

# Enable port scanning (if disabled)
mcpclient config port-scan enable true

# Set the range (example)
mcpclient config port-scan range 8000 8999

会話をインポート・エクスポート

# Export current conversation branch to a default filename
mcpclient export

# Export current branch to a specific file
mcpclient export --output my_conversation.json

# Export specific conversation branch by ID (first 8 chars often suffice)
mcpclient export --id 12345678 --output specific_branch.json

# Import a conversation file (creates a new branch under the current node)
mcpclient import-conv my_conversation.json

---

🌐 Web UI の機能

Web UI（mcpclient run --webui）は、Alpine.js、Tailwind CSS、DaisyUI で構築された、モダンで使いやすいインターフェースを提供します。

• リアルタイムチャット： WebSocket 経由で Claude からの応答をストリーミングし、リッチな Markdown レンダリング（Marked.js 経由）、コピー ボタン付きのコードブロックのシンタックスハイライト（highlight.js 経由）に対応しています。また、システムメッセージやステータス更新を明確に表示します。
• ツールの操作： ツール呼び出し（引数）とその結果（成功またはエラー）をチャットの流れの中で視覚的に区別して表示します。モーダルから、利用可能なツールをカスタム JSON パラメーターで直接実行できるため、テストやデバッグに役立ちます。
• サーバー管理： 専用のサイドバータブに、設定済みのサーバーが一覧表示されます。ユーザーは次の操作ができます。
  • モーダルフォームから新しいサーバー（STDIO/SSE/Streaming-HTTP）を追加する。
  • ステータスインジケーター（読み込み中、接続済み、切断済み、エラー）を確認しながら、サーバーに接続または切断する。
  • サーバーを有効化または無効化する（無効化すると自動的に切断されます）。
  • サーバー設定を削除する。
  • 基本的な稼働状況／ステータスと、各サーバーが提供するツールの数を確認する。
• 検出： Servers タブのボタンから、検出スキャン（ローカルファイルシステム、リモートレジストリ、mDNS）を実行できます。検出されたサーバーは一覧表示され、ワンクリックで設定に追加できます。
• 会話の分岐： Conversation タブのインタラクティブなツリービューで、ConversationGraph を視覚化します。別の分岐をクリックしてチェックアウトし（チャット表示を更新）、現在のポイントから分岐して新しい分岐を作成できます。
• コンテキスト管理： Conversation タブのボタンから、現在の分岐のメッセージを消去（親／ルートの状態にリセット）したり、API 経由でコンテキストの最適化／要約を実行したりできます。
• インポート／エクスポート： Conversation タブのボタンから、現在の分岐を JSON ファイルにエクスポートしたり、ファイル選択で以前にエクスポートした JSON ファイルをインポートしたりできます（バックエンドにアップロードされます）。
• 設定： 専用のサイドバータブから、主要な設定オプション（API キー、デフォルトモデル、最大トークン数、Temperature、ストリーミング、キャッシュ、自動検出、mDNS などの機能切り替え）を確認・変更できます。変更内容はサーバーの設定ファイルに保存されます。
• テーマの切り替え： ドロップダウンメニューから、幅広い種類の DaisyUI テーマを選択できます。UI はすぐに切り替わり、選択したテーマに応じてコードのシンタックスハイライトもライト／ダークのスタイルに自動で切り替わります。
• ステータスインジケーター： リアルタイムの WebSocket 接続ステータスアイコン、サーバー全体の接続数、利用可能なツールの合計数がヘッダーに表示されます。一時的なステータスメッセージ（例：「ツールを実行しています…」）はチャット入力欄の下に表示されます。

---

🔌 API サーバー

--webui を指定して実行すると、FastAPI サーバーからプログラムでアクセスできます。

GET    /api/status                     - Client overview (model, servers, tools, history count, current node)
GET    /api/config                     - Get current (non-sensitive) configuration
PUT    /api/config                     - Update configuration settings (e.g., { "temperature": 0.8 })
GET    /api/servers                    - List all configured servers with status, health, tools
POST   /api/servers                    - Add a new server configuration (Supports stdio/sse/streaming-http transports)
DELETE /api/servers/{server_name}    - Remove a server configuration
POST   /api/servers/{server_name}/connect    - Connect to a specific server
POST   /api/servers/{server_name}/disconnect - Disconnect from a specific server
PUT    /api/servers/{server_name}/enable?enabled={true|false} - Enable/disable a server
GET    /api/tools                      - List all available tools from connected servers
GET    /api/resources                  - List all available resources
GET    /api/prompts                    - List all available prompts
GET    /api/conversation               - Get current conversation state (messages, current node ID/name, full node graph)
POST   /api/conversation/fork          - Create a fork (optionally named) from the current conversation node
POST   /api/conversation/checkout      - Switch the current context to a different conversation node/branch (by ID)
POST   /api/conversation/clear         - Clear messages on the current node and switch to root
POST   /api/conversation/optimize      - Trigger context summarization for the current node (optional model/token args)
POST   /api/tool/execute               - Execute a specific tool with given parameters (Requires ToolExecuteRequest model)
WS     /ws/chat                        - WebSocket endpoint for streaming chat (`query`, `command`), receiving updates (`text_chunk`, `status`, `query_complete`, `error`, `state_update`).

（注：ServerAddRequest や ToolExecuteRequest などの実際のリクエスト／レスポンスモデルは Python コード内で定義されており、FastAPI による検証に使用されます。）

---

⚙️ コマンド

CLI オプション

詳細については、mcpclient --help または mcpclient [COMMAND] --help を実行してください。

インタラクティブシェルコマンド（mcpclient run --interactive）

/ に続けてコマンドを入力します。

/help         Show this help message
/exit, /quit  Exit the client
/config       Manage configuration (api-key, model, max-tokens, history-size, auto-discover, discovery-path, port-scan)
/servers      Manage MCP servers (list, add, remove, connect, disconnect, enable, disable, status)
/discover     Discover/manage LAN servers (list, connect <NAME>, refresh, auto <on|off>)
/tools        List available tools (optionally filter by server: /tools <server_name>)
/tool         Directly execute a tool: /tool <tool_name> '{"param": "value"}'
/resources    List available resources (optionally filter by server: /resources <server_name>)
/prompts      List available prompt templates (optionally filter by server: /prompts <server_name>)
/prompt       Apply a prompt template to the current conversation context: /prompt <prompt_name>
/model        View or change the current AI model: /model [<model_name>]
/fork         Create a new branch from the current conversation point: /fork [Optional Branch Name]
/branch       Manage branches (list, checkout <node_id_prefix>)
/export       Export current branch: /export [--id <node_id>] [--output <file.json>]
/import       Import conversation file: /import <file.json>
/history      View recent conversation history (optionally specify number: /history 10)
/cache        Manage tool cache (list, clear [--all|tool_name], clean, dependencies [tool_name])
/dashboard    Show the live Textual User Interface (TUI) dashboard (requires separate run)
/optimize     Summarize current conversation context: /optimize [--model <model>] [--tokens <num>]
/reload       Disconnect, reload capabilities, and reconnect to enabled servers
/clear        Clear messages in the current branch and optionally reset to root

---

🏗️ アーキテクチャとエンジニアリングの特長

このクライアントでは、堅牢で機能豊富なエクスペリエンスを提供するために、いくつかの手法を採用しています。

• 非同期コア： ネットワーク I/O（HTTP、WebSockets、SSE）、サブプロセスとの通信（stdio）、ファイルシステム操作（aiofiles）、バックグラウンドの並行タスク（監視、検出、ポートスキャン）を効率的に処理するため、全面的に Python の asyncio を基盤としています。
• コンポーネントベースの設計： 使いやすさを考慮して主に単一のスクリプトとしてパッケージ化されていますが、内部では関心事を次のクラスに分離しています。
  • MCPClient：UI ループ、コマンド処理、コアロジックを統括するメインアプリケーションクラスです。
  • ServerManager：サーバーの設定、ライフサイクル（接続、切断、再起動）、検出メカニズム、機能（ツール、リソース、プロンプト）の集約を処理し、サーバープロセスとセッションを管理します。確実なリソース解放には AsyncExitStack を使用します。FastMCP との統合により、最新の streaming-http プロトコルを含むすべてのトランスポートタイプをサポートします。
  • RobustStdioSession（重要なエンジニアリングの取り組み）： stdio サーバー専用に調整した、mcp.ClientSession のカスタム実装です。次のロジックを備えています。
    • プロトコルエラーを防ぐため、サーバーの stdout から JSON-RPC 以外の出力をフィルタリングします。
    • リクエスト ID に関連付けられた asyncio.Future オブジェクトを直接解決してレスポンスを処理します。これにより、キューベースのアプローチよりパフォーマンスが向上する可能性があります。
    • stdout の読み取りと、取得した stderr のログファイルへの非同期書き込みをバックグラウンドタスクで管理します。
    • プロセスの終了とクリーンアップを適切に処理します。
  • STDIO セーフティメカニズム（重要）： stdio ベースのプロトコルにとって致命的な、意図しない stdout の混入を防ぐ多層防御です。
    • StdioProtectionWrapper：sys.stdout をグローバルにラップして書き込みを捕捉し、stdio サーバーが稼働している場合は stderr にリダイレクトします。
    • safe_stdout()：サーバー接続などの重要な処理中に、stdout を一時的に stderr にリダイレクトするコンテキストマネージャーです。
    • get_safe_console() / safe_print()：稼働中の stdio サーバーに応じて、UI 出力（Rich 経由）に適切なストリーム（stdout または stderr）を使用するユーティリティ関数です。
    • これらの対策により、機密性の高い stdio サーバーと通信している場合でも、クライアント UI とログ機能が正しく動作します。
  • ConversationGraph：ConversationNode オブジェクトを使用して、分岐を持つ非線形の会話構造を管理します。JSON との相互保存も処理します。
  • ToolCache：永続化には diskcache、高速化にはメモリ内レイヤーを使用して、キャッシュロジックを実装します。TTL の管理と依存関係の無効化も含まれます。
  • ServerRegistry / ServerMonitor：mDNS/Zeroconf による検出と登録、および復旧の試行を伴うバックグラウンドのサーバーヘルスチェックを処理します。
• デュアルインターフェースの実装：
  • Web バックエンド： 整理された REST API 構成には FastAPI、ASGI サーバーには uvicorn、双方向のリアルタイムチャットには websockets を使用します。FastAPI の lifespan コンテキストマネージャーにより、起動時に MCPClient が適切に初期化され、終了時にクリーンアップされます。依存性注入によって、エンドポイントからクライアントインスタンスにアクセスできます。
  • Web フロントエンド： HTML 内で軽量なリアクティビティとコンポーネントロジックを実現するため、Alpine.js を活用します。スタイルと事前構築済みコンポーネントには Tailwind CSS と DaisyUI を使用します。Markdown とコードを安全かつ魅力的に表示するため、Marked.js、highlight.js、DOMPurify を利用します。ツールチップには Tippy.js を使用します。
  • CLI/TUI： コマンドラインインターフェースの定義と引数の解析には Typer を使用します。整形済みのコンソール出力、テーブル、プログレスバー、Markdown のレンダリング、構文強調表示、ライブ TUI ダッシュボードには Rich を多用します。複雑な操作中に Rich Live の表示がネストして問題が起きないよう、_run_with_progress や _run_with_simple_progress などのヘルパーで慎重に管理します。
• レジリエンスとエラー処理： ツール実行時のリトライや標準化されたエラー報告など、一般的なパターンにはデコレーター（@retry_with_circuit_breaker、@with_tool_error_handling）を使用します。堅牢性を高めるため、全体を通して構造化された try...except...finally ブロックを使用しています。
• 可観測性： 構造化メトリクス（リクエストカウンター、レイテンシーヒストグラム、ツール実行）と分散トレーシング（クエリ処理、サーバー接続、ツール呼び出しなどの操作をスパンで追跡）には OpenTelemetry を統合しています。これにより、パフォーマンス分析とデバッグが容易になります。
• 設定： config.yaml ファイル、環境変数（特に ANTHROPIC_API_KEY などの機密キー）、インタラクティブコマンドまたは Web UI の設定を利用できる柔軟な設定システムです。変更は YAML ファイルに保存されます。

---

🔄 スマートキャッシュ依存関係の追跡

スマートキャッシュ依存関係システムでは、ツールがほかのツールへの依存関係を宣言できます。

• ツールのキャッシュが無効化されると、依存関係にあるすべてのツールのキャッシュも自動的に無効化されます
• サーバーがツール間の関係を宣言すると、依存関係が登録されます
• /cache dependencies で依存関係のグラフを表示できます
• 関連するツールで常に最新のデータを使用できるため、データの一貫性が向上します

依存関係の流れの例：

weather:current → weather:forecast → travel:recommendations

現在の天気データが更新されると、予報と旅行のおすすめのキャッシュが両方とも自動的に無効化されます。

---

🔍 ツールとサーバーの検出

このクライアントでは、MCP サーバーを検索して統合する方法を複数利用できます。

• 設定済みパス： config.yaml の discovery_paths に指定されているディレクトリを検索し、ローカルの stdio サーバースクリプト（例：.py、.js）を見つけます。デフォルトでは次のパスが含まれます。
  • .mcpclient_config/servers（プロジェクトのルート）
  • ~/mcp-servers
  • ~/modelcontextprotocol/servers
• Claude Desktop の設定（claude_desktop_config.json）： このファイルがプロジェクトのルートにある場合、セットアップ中にクライアントがサーバー定義を自動的にインポートします。
  • コマンドのインテリジェントな適応：
    • wsl.exe ... <shell> -c "command ..." のパターンを検出します。
    • Linux の <shell>（例：bash、sh）と "command ..." を抽出します。
    • 設定を、特定された Linux シェル（例：/bin/bash -c "command ..."）でコマンドを直接実行するように変更し、wsl.exe を経由しないようにします。
    • その他のコマンド（例：npx ...）では、adapt_path_for_platform を使用して引数内の Windows 形式のパス（C:\Users\...）を検索し、対応する /mnt/c/Users/... 形式に変換することで、WSL/Linux でクライアントを実行する際の互換性を確保します。
• リモートレジストリ： config.yaml で定義された MCP レジストリサーバーの URL（registry_urls）に接続し、公開または共有されているサーバー（通常は SSE）を検出します。
• ローカルネットワーク（mDNS/Zeroconf）：
  • zeroconf ライブラリを使用してローカルネットワーク上で _mcp._tcp.local. のサービス告知をリッスンします。
  • 新しいサーバーの出現や消失を、対話型 CLI でリアルタイムに通知します。
  • /discover コマンド群を使って、検出したサーバーを管理できます。
    • /discover list：現在表示されている LAN サーバーの詳細を表示します。
    • /discover connect <NAME>：検出したサーバーを設定ファイルに追加し、接続を試みます。
    • /discover refresh：ネットワークの再スキャンを手動で開始します。
    • /discover auto [on|off]：mDNS の継続的なバックグラウンドスキャンを切り替えます（設定で enable_local_discovery: true が必要です）。
• ローカルポートスキャン：
  • 有効にすると（config.yaml の enable_port_scanning: true、または /config port-scan enable true を使用）、起動時の検出中に、指定したローカル IP アドレスのポート範囲を積極的にスキャンします。
  • 各ポートで基本的な MCP の initialize ハンドシェイクを試み、応答する MCP サーバーを検出します。サーバーの応答と HTTP ヘッダーに基づき、sse および streaming-http のトランスポートタイプを自動的に検出できます。
  • mDNS でサービスを告知しないサーバーの検出に役立ちます。
  • スキャンする範囲、対象 IP、同時実行数、タイムアウトは、config.yaml または /config port-scan ... コマンドで設定できます。
  • 検出されたサーバーは、任意で設定に追加できるよう、ほかの検出済みサーバーとともに表示されます。

---

📡 テレメトリー + デバッグ

• OpenTelemetry： 主要な操作のトレースとメトリクスを生成します。デフォルトではデータは収集されますが、エクスポートされません。トレースとメトリクスをデバッグするためにコンソールへ大量の出力を有効にするには、mcpclient.py の先頭付近で use_console_exporter = True に設定します。本番環境では、適切な OTel エクスポーター（例：Jaeger、Prometheus）を設定してください。
• ダッシュボード：
  • CLI： Rich を使用したリアルタイムの TUI 監視画面を表示するには、mcpclient run --dashboard を実行します。サーバーのステータス、健全性、接続状態、基本的なツール使用状況の統計、クライアント情報が表示されます。定期的に更新されます。
  • Web UI： 「Servers」タブにはサーバーのステータス（接続状態、アイコンによる健全性）が視覚的に表示され、ヘッダーには全体の件数が表示されます。
• ロギング： Python 標準の logging を使用し、コンソールに見やすく出力するため RichHandler で設定されています（stdio との競合を避けるため、出力先は stderr です）。
  • 詳細な内部情報を確認するには、--verbose または -v フラグを使用してログレベルを DEBUG に上げます。
  • 詳細モードでは、詳細な stdio セッションロギング（USE_VERBOSE_SESSION_LOGGING = True）も有効になり、生の JSON-RPC メッセージを確認できます（MCP サーバーのデバッグに便利です）。
• エラートレースバック： 実行前に環境変数 MCP_CLIENT_DEBUG=1 を設定すると、予期しないエラーが発生した際に CLI が Python の完全なトレースバックを出力し、クライアント側の問題のデバッグに役立ちます。
• STDIO サーバーログ： stdio サーバーからの stderr 出力は非同期で取得され、設定ディレクトリ内のログファイル（例：.mcpclient_config/<server_name>_stderr.log）に書き込まれます。これはサーバー側の問題を診断するうえで重要です。

---

📦 設定

• 主要ファイル： 設定はプロジェクトのルートディレクトリにある .mcpclient_config/config.yaml から読み込まれ、保存されます。
• 環境変数： ANTHROPIC_API_KEY は API キーを指定する主な方法で、設定ファイルに保存されているキーより優先されます。EDITOR は /config edit で使用されます。MCP_CLIENT_DEBUG=1 を設定するとトレースバックが有効になります。
• 対話型 CLI： /config コマンドを使うと、api-key、model、max-tokens、discovery-path、ポートスキャンのパラメーターなどの設定を表示・変更できます。変更内容は config.yaml に保存されます。
• Web UI の設定： Web UI の「Settings」タブでは、一般的な設定項目を操作できます。ここで行った変更は API 経由で送信され、config.yaml に保存されます。

現在の設定を表示：

mcpclient config --show
# OR in interactive mode:
/config

設定ファイルを手動で編集：

mcpclient config --edit
# (This will open .mcpclient_config/config.yaml in the editor specified by your $EDITOR environment variable)

---

🧪 開発に関する注意事項

• コア： Python 3.13+、asyncio
• CLI： Typer、Rich
• Web： FastAPI、Uvicorn、WebSockets、Alpine.js、Tailwind CSS、DaisyUI
• MCP： mcp SDK（mcp>=1.0.0）、fastmcp（streaming-http トランスポート用）
• AI： anthropic SDK（anthropic>=0.15.0）
• 可観測性： opentelemetry-sdk、opentelemetry-api、opentelemetry-instrumentation
• ユーティリティ： httpx、PyYAML、python-dotenv、psutil、aiofiles、diskcache、tiktoken、zeroconf、colorama
• リンティング／フォーマット： ruff は pyproject.toml で設定されています。uv run lint または ruff check . && ruff format . を使用してください。
• 型チェック： mypy は pyproject.toml で設定されています。uv run typecheck または mypy mcpclient.py を使用してください。

配布とコードの把握を容易にするため、プロジェクトの大部分は mcpclient.py にまとめられていますが、内部ではクラスベースのモジュール化が維持されています。Web UI は自己完結型の mcp_client_ui.html ファイルから提供され、シンプルさを保つために CDN でホストされたライブラリを利用しています。堅牢な stdio 処理や非同期管理などの主要な複雑なロジックは、RobustStdioSession や ServerManager といった専用クラスに配置されています。

---

📝 ライセンス

MIT ライセンス（OpenAI/Anthropic Rider 付き）。LICENSE を参照してください。