qsp-client

qsp-client

QSP — MCP ツールを、OpenAI 互換の任意のローカル LLM エンドポイントに中継します。

Q信号の QSP（「中継してもらえますか？」）にちなんで名付けられた qsp-client は、ローカル LLM とMCPサーバーの間でツール呼び出しを中継します。これは MCP クライアントです。関数呼び出しに対応した任意のモデルが、クラウドではなくローカルの重みから、qso-graph サーバーのツールを利用できます。

以前の名称は qsp-mcp です。 qsp-mcp からの移行をご覧ください。

インストール

uv tool install qsp-client   # the qsp-client command, on your PATH
pip install qsp-client       # or into your own environment

クイックスタート

# Interactive mode
qsp-client --config ~/.config/qsp-client/config.json

# Single query
qsp-client --query "What bands are open from DN13 to JN48 right now?"

# Direct endpoint (no config file needed if no MCP servers configured)
qsp-client --endpoint http://localhost:8000/v1/chat/completions --api-key sk-xxx

設定

設定形式はClaude Desktop 互換です。既存の mcpServers ブロックをそのままコピーできます。

{
  "mcpServers": {
    "ionis": {
      "command": "ionis-mcp",
      "env": { "IONIS_DATA_DIR": "/path/to/datasets/v1.0" }
    },
    "solar": {
      "command": "solar-mcp"
    },
    "wspr": {
      "command": "wspr-mcp"
    }
  },
  "bridge": {
    "endpoint": "http://localhost:8000/v1/chat/completions",
    "model": "AstroSage-70B",
    "temperature": 0.3,
    "system_prompt": "You are an expert ham radio operator and RF engineer.",
    "max_tool_calls_per_turn": 5,
    "profiles": {
      "contest": {
        "servers": ["n1mm", "ionis", "solar", "wspr"],
        "temperature": 0.2,
        "system_prompt": "You are a contest advisor. Be concise."
      },
      "propagation": {
        "servers": ["ionis", "solar", "wspr"],
        "temperature": 0.3
      },
      "full": {
        "servers": "*",
        "temperature": 0.3
      }
    },
    "server_timeouts": {
      "ionis": 1,
      "solar": 8,
      "qrz": 5
    }
  }
}

mcpServers ブロックは Claude Desktop とまったく同じ形式です。bridge セクションは qsp-client 固有のもので、Claude Desktop では無視されます。

CLI オプション

qsp-client [OPTIONS]

Options:
  -c, --config PATH       Config file path (default: ~/.config/qsp-client/config.json)
  -e, --endpoint URL      LLM endpoint URL (overrides config)
  -k, --api-key KEY       API key for the LLM endpoint
  -m, --model NAME        Model name (overrides config)
  -p, --profile NAME      Tool profile (contest, dx, propagation, full)
  -q, --query TEXT        Single query mode — ask one question and exit
  --enable-writes         Enable write-capable tools (disabled by default)
  --list-tools            List available tools and exit
  --version               Show version

対話型コマンド

コマンド	操作
/tools	使用可能なツールを一覧表示します
/help	ヘルプを表示します
quit	終了します（exit、q、73 も使用できます）

ADIF ツール

qsp-adif-convert は ADIF（.adi）ログを JSON または NDJSON に変換します。バンド、モード、コールサイン、日付範囲、確認済み QSO で絞り込めます。

qsp-adif-convert -i mylog.adi -o mylog.json
qsp-adif-convert --help

自分のマシン上のファイルを処理し、接続は行いません。以前は adif-mcp convert でした。現在、adif-mcp は MCP サーバー専用です。

設計

qsp-client は、LLM と MCP ツールをつなぐ厳密なステートレスパイプです。

• キャッシュなし、共有状態なし、ヘルスチェックのポーリングなし
• すべての状態は MCP サーバー内に保持されます
• 推論の最適化（プレフィックスキャッシュ、KV キャッシュ）はすべて推論サーバーで行われます
• qsp-client は両者を接続するだけです

llama.cpp、Ollama、vLLM、SGLang など、OpenAI 互換の任意のエンドポイントで動作します。

セキュリティ

• 書き込み可能なツールはデフォルトで無効です（--enable-writes で明示的に有効化）
• 認証情報は MCP サーバー内（OS キーリング）に保持され、qsp-client や LLM に公開されることはありません
• サブプロセス、シェル実行、eval はありません
• すべての外部接続は HTTPS のみです（LAN エンドポイントは例外）

qsp-mcp からの移行

qsp-client は qsp-mcp の名称変更版です。MCP の世界では、-mcp という名前はサーバーを表しますが、これはクライアントです。

• 新しい名称でインストールしてください：pip uninstall qsp-mcp && pip install qsp-client。
• 設定はそのまま使用できます。~/.config/qsp-mcp/config.json と ~/.qsp-mcp.json は、新しい ~/.config/qsp-client/config.json と ~/.qsp-client.json の後に引き続き読み込まれます。
• qsp-mcp コマンドは引き続き使用でき、名称変更について案内します。qsp-client を使用してください。

ライセンス

GPL-3.0-or-later — 詳細は LICENSE をご覧ください。

qso-graph エコシステムの一部

qso-graph.io — アマチュア無線向け MCP サーバー。