qsp-client

qsp-client

QSP — 将 MCP 工具中继到任何兼容 OpenAI 的本地 LLM 端点。

qsp-client 以 Q 信号 QSP（“请代为转达”）命名，可在本地 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 是连接大模型与 MCP 工具的严格无状态管道：

• 不缓存、不共享状态、不进行健康状态轮询
• 所有状态都保存在 MCP 服务中
• 所有推理优化都由推理服务负责（前缀缓存、KV 缓存）
• qsp-client 只负责连接两端

兼容任何 OpenAI 兼容端点：llama.cpp、Ollama、vLLM、SGLang。

安全

• 默认禁用具有写入能力的工具（需显式启用 --enable-writes）
• 凭据保留在 MCP 服务内部（操作系统密钥环）——绝不会暴露给 qsp-client 或大模型
• 不使用子进程、Shell 执行或 eval
• 所有外部连接仅使用 HTTPS（局域网端点除外）

从 qsp-mcp 迁移

qsp-client 就是更名后的 qsp-mcp：在 MCP 生态中，-mcp 后缀用于命名服务，而这是一个客户端。

• 安装新名称：pip uninstall qsp-mcp && pip install qsp-client。
• 配置仍可继续使用：新配置 ~/.config/qsp-client/config.json 和 ~/.qsp-client.json 之后，仍会读取 ~/.config/qsp-mcp/config.json 和 ~/.qsp-mcp.json。
• qsp-mcp 命令仍可使用，但会提示它已更名。请改用 qsp-client。

许可证

GPL-3.0-or-later — 详见 LICENSE。

qso-graph 生态的一部分

qso-graph.io — 面向业余无线电的 MCP 服务。