mcp-server-pskreporter

PSK Reporter MCP 服务

一个模型上下文协议（MCP）服务，可通过 Claude Desktop 提供来自 PSKReporter 的业余无线电实时传播数据。

功能

• 实时传播数据：收集全球业余无线电台的实时信号报告
• 高级筛选：按波段、模式、呼号、位置和国家/地区筛选
• DXCC 实体支持：完整的国家/地区映射，并智能处理名称变体
• MCP 资源：发现可用国家/地区及其常见名称变体
• 多线程架构：通过非阻塞 MQTT 数据收集，确保响应迅速

安装

先决条件

• Python 3.13 或更高版本
• uv 包管理器
• Claude Desktop 应用程序

设置

1. 克隆或下载此代码库

   git clone <your-repo-url>
   cd mcp-server-pskreporter
   

2. 使用 uv 安装依赖项

   uv sync
   

3. 选择安装方式：

   选项 A：开发模式（用于直接执行命令）

   uv pip install -e .
   

   这会在本地虚拟环境中以开发模式安装此软件包，使 pskreporter-mcp-server 命令可在此项目的环境中使用。如果你想直接从项目目录运行该命令，请使用此方式。

   选项 B：基于项目运行（适用于 Claude Desktop——无需安装）

   uv run --project . pskreporter-mcp-server
   

   这会直接从项目目录运行服务，无需安装。这是 Claude Desktop 默认使用的方式。

4. 验证服务是否正常运行

   如果你使用了选项 A（开发模式）：

   # Make sure you're in the project directory
   pskreporter-mcp-server
   

   如果你使用了选项 B（基于项目运行）：

   uv run --project . pskreporter-mcp-server
   

   服务应会启动，并准备好接受 MCP 连接。

添加到 Claude Desktop

方法 1：使用配置文件（推荐）

1. 将配置文件复制到 Claude Desktop 的配置目录：

   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 更新 claude_desktop_config.json 中的路径，使其与你的系统相匹配：

   {
     "mcpServers": {
       "pskreporter": {
         "command": "uv",
         "args": ["run", "--project", "C:\\Users\\rokhm\\git\\mcp-server-pskreporter", "pskreporter-mcp-server"],
         "env": {}
       }
     }
   }
   

3. 重启 Claude Desktop

注意：此代码库中的 claude_desktop_config.json 文件已针对当前路径预先配置。如果移动项目，请相应更新 --project 参数中的路径。

方法 2：使用 Claude Desktop 界面

1. 打开 Claude Desktop
2. 前往 Settings → MCP Servers
3. 点击 Add Server
4. 配置服务：
   • Name：pskreporter
   • Command：uv
   • Arguments：run --project C:\Users\rokhm\git\mcp-server-pskreporter pskreporter-mcp-server
   • Working Directory：C:\Users\rokhm\git\mcp-server-pskreporter（你的项目文件夹）
5. 点击 Save

方法 3：替代命令

你也可以使用以下替代方式运行服务：

直接通过 Python 执行：

python -m pskreporter_mcp_server

使用 uv run：

uv run pskreporter-mcp-server

开发模式：

uv run mcp dev pskreporter_mcp_server.py

用法

连接到 Claude Desktop 后，你可以使用这些工具和资源：

get_spots 工具

收集实时业余无线电传播报告，并提供筛选选项。

参数：

• band：业余无线电波段（例如，“20m”“40m”“80m”“160m”“10m”“15m”“17m”“30m”“12m”“6m”“2m”）
• mode：工作模式（例如，“FT8”“FT4”“CW”“SSB”“PSK31”“RTTY”）
• sendercall：特定电台的呼号（例如，“W9KM”“JA1ABC”）
• receivercall：接收电台的呼号
• senderlocator：发送电台的 Maidenhead 网格定位（例如，“EN51”“JO20”）
• receiverlocator：接收电台的 Maidenhead 网格定位
• sendercountry：发送方所在国家/地区的名称（例如，“Japan”“USA”“Germany”）
• receivercountry：接收方所在国家/地区的名称
• duration：采集时间，单位为秒（5-30，默认值：10）

国家/地区名称功能：

• 不区分大小写：“japan”“JAPAN”“Japan”均可使用
• 部分匹配：“swains”可匹配“Swains I.”，“korea”可匹配“Republic of Korea”
• 常见别名：“USA”“UK”“Germany”会自动映射为对应的全名
• 340+ 个实体：完整支持 DXCC 实体，覆盖全球

示例：

• “显示来自 Japan、工作在 20m 波段的 FT8 活动”
• “查找工作在 40m 波段的 USA 电台”
• “W9KM 正在哪些波段工作？”
• “显示来自 Germany、工作在 80m 波段的电台”

dxcc_entities 资源

查找可用国家/地区及其别名，以便更好地进行筛选。

资源功能：

• 完整实体列表：包含所有 340 个 DXCC 实体及其官方名称
• 名称别名：每个国家/地区的常见别名（例如，用“USA”指代“United States of America”）
• 使用示例：可直接用于 get_spots 工具的示例
• 搜索提示：有效使用国家/地区名称的指南

使用方法：

• 浏览所有可用的国家和地区
• 查看每个国家/地区的常见别名
• 获取可用于 get_spots 参数的准确名称
• 发现可能尚不了解的 DXCC 实体

资源数据示例：

{
  "code": "291",
  "name": "United States of America",
  "name_variations": ["United States", "USA", "US", "America"]
}

查找国家/地区名称

dxcc_entities 资源提供全面的国家/地区信息：

• 官方名称：使用准确的 DXCC 实体名称可获得最佳结果
• 常见别名：常用缩写和替代名称
• 大小写灵活：所有名称均不区分大小写
• 部分匹配：即使名称不完整，也能查找国家/地区

常见示例：

• United States：“USA”“US”“America”“United States of America”
• United Kingdom：“UK”“Great Britain”“Britain”“England”
• Germany：“Germany”“Deutschland”“DE”
• Japan：“Japan”（没有常见别名）
• Swains Island：“Swains”“Swains I.”“Swains Island”

数据来源

此服务连接到 mqtt.pskreporter.info 上的 PSKReporter MQTT 数据流，以获取全球业余无线电电台的实时传播数据。

故障排除

常见问题

1. 服务无法启动

   • 确保已安装 Python 3.13+
   • 确保已安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh
   • 检查依赖项是否已安装：uv sync

2. 未收集到任何电台

   • 增大 duration 参数（最长 30 秒）
   • 使用范围更广的筛选条件（减少参数）
   • 检查网络连接

3. 找不到国家名称

   • 使用 dxcc_entities 资源查找准确的国家名称
   • 尝试常见的变体（例如，使用 “USA” 代替 “United States of America”）
   • 检查是否有拼写错误，并尝试部分匹配

4. Claude Desktop 无法连接

   • 确认 claude_desktop_config.json 中的路径正确
   • 确保手动运行时服务可以成功启动：uv run pskreporter-mcp-server
   • 检查 Claude Desktop 日志中的错误消息

5. “File not found” 错误

   • 确保工作目录指向包含 pskreporter_mcp_server.py 的文件夹
   • 确认所有项目文件都在同一目录中

6. “program not found” 或 “Failed to spawn” 错误

   • 如果直接运行命令时出现 “Failed to spawn 'pskreporter-mcp-server' caused by: program not found”，则需要以开发模式安装软件包：

     uv pip install -e .
     

   • 安装后，pskreporter-mcp-server 命令将在项目的虚拟环境中可用
   • 注意：Claude Desktop 使用 uv run --project，无需安装；提供的 claude_desktop_config.json 无需任何额外设置即可使用

调试信息

服务会创建调试日志文件 mcp_server_debug.log，其中包含以下详细信息：

• MQTT 连接状态
• 电台收集进度
• 国家名称解析
• 错误消息和堆栈跟踪

开发

本项目使用 uv 管理依赖项。常用命令：

• uv sync - 安装依赖项
• uv run pskreporter-mcp-server - 运行服务
• uv run --project C:\Users\rokhm\git\mcp-server-pskreporter pskreporter-mcp-server - 从任意目录运行
• python -m pskreporter_mcp_server - 作为 Python 模块运行

配置

Claude Desktop 配置

claude_desktop_config.json 文件已预先配置为使用 uv run --project：

{
  "mcpServers": {
    "pskreporter": {
      "command": "uv",
      "args": ["run", "--project", "C:\\Users\\rokhm\\git\\mcp-server-pskreporter", "pskreporter-mcp-server"],
      "env": {}
    }
  }
}

要点：

• 使用 uv run --project 命令直接运行项目
• --project 参数指向本地项目目录
• 无需预先安装（uv 会自动处理依赖项）
• 可执行文件名为 pskreporter-mcp-server（使用连字符）

DXCC 实体配置

服务使用基于 YAML 的 DXCC 实体配置（dxcc_entities.yaml），其特点如下：

• 便于维护：国家名称及其变体存储在易于阅读的 YAML 文件中
• 灵活更新：无需修改代码即可添加或修改国家名称变体
• 结构化数据：规范名称与常见变体清晰分离

文件结构：

dxcc_entities:
  "291":
    canonical_name: "United States of America"
    name_variations: ["USA", "US", "United States", "America"]
  "339":
    canonical_name: "Japan"
    name_variations: []

添加国家名称变体： 要为某个国家添加变体，只需编辑 dxcc_entities.yaml 文件：

1. 根据 DXCC 代码找到该国家
2. 将变体添加到 name_variations 数组中
3. 重启服务以应用更改

示例：

"339":
  canonical_name: "Japan"
  name_variations: ["Nippon", "Nihon"]

服务会在启动时自动加载这些更改，便于维护和扩展国家名称支持。

---

73！ Andriy W9KM