eqsl-mcp 0.1.0__tar.gz

eqsl_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

eqsl_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/

eqsl_mcp-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  For the full license text, see <https://www.gnu.org/licenses/gpl-3.0.html>

eqsl_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: eqsl-mcp
+Version: 0.1.0
+Summary: MCP server for eQSL.cc — inbox download, QSO verification, AG status checks
+Project-URL: Homepage, https://qso-graph.io/
+Project-URL: Repository, https://github.com/qso-graph/eqsl-mcp
+Project-URL: Issues, https://github.com/qso-graph/eqsl-mcp/issues
+Author: Greg Beam, KI7MT
+License: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: amateur-radio,confirmation,eqsl,ham-radio,mcp,model-context-protocol,qsl,qso
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Ham Radio
+Requires-Python: >=3.10
+Requires-Dist: adif-mcp>=0.6.2
+Requires-Dist: fastmcp>=3.0
+Description-Content-Type: text/markdown
+
+# eqsl-mcp
+
+MCP server for [eQSL.cc](https://www.eqsl.cc/) — download incoming eQSLs, verify QSOs, check AG status, and query upload history through any MCP-compatible AI assistant.
+
+Part of the [qso-graph](https://qso-graph.io/) project. Depends on [adif-mcp](https://pypi.org/project/adif-mcp/) for persona and credential management.
+
+## Install
+
+```bash
+pip install eqsl-mcp
+```
+
+## Tools
+
+| Tool | Auth | Description |
+|------|------|-------------|
+| `eqsl_inbox` | Yes | Download incoming eQSLs with date/confirmation filters |
+| `eqsl_verify` | No | Check if a specific QSO exists in eQSL |
+| `eqsl_ag_check` | No | Check if a callsign has AG (Authenticity Guaranteed) status |
+| `eqsl_last_upload` | No | When did a persona last upload to eQSL |
+
+## Quick Start
+
+### 1. Set up credentials
+
+eqsl-mcp uses adif-mcp personas for credential management:
+
+```bash
+# Install adif-mcp if you haven't
+pip install adif-mcp
+
+# Create a persona and add eQSL credentials
+adif-mcp persona create ki7mt --callsign KI7MT
+adif-mcp persona provider ki7mt eqsl --username KI7MT
+adif-mcp persona secret ki7mt eqsl
+```
+
+### 2. Configure your MCP client
+
+eqsl-mcp works with any MCP-compatible client. Add the server config and restart — tools appear automatically.
+
+#### Claude Desktop
+
+Add to `claude_desktop_config.json` (`~/Library/Application Support/Claude/` on macOS, `%APPDATA%\Claude\` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "eqsl": {
+      "command": "eqsl-mcp"
+    }
+  }
+}
+```
+
+#### Claude Code
+
+Add to `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "eqsl": {
+      "command": "eqsl-mcp"
+    }
+  }
+}
+```
+
+#### ChatGPT Desktop
+
+ChatGPT supports MCP via the [OpenAI Agents SDK](https://developers.openai.com/api/docs/mcp/). Add under Settings > Apps & Connectors, or configure in your agent definition:
+
+```json
+{
+  "mcpServers": {
+    "eqsl": {
+      "command": "eqsl-mcp"
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "eqsl": {
+      "command": "eqsl-mcp"
+    }
+  }
+}
+```
+
+#### VS Code / GitHub Copilot
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "eqsl": {
+      "command": "eqsl-mcp"
+    }
+  }
+}
+```
+
+#### Gemini CLI
+
+Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "eqsl": {
+      "command": "eqsl-mcp"
+    }
+  }
+}
+```
+
+### 3. Ask questions
+
+> "Show me all eQSLs received this week"
+
+> "How many unconfirmed eQSLs do I have on 20m FT8?"
+
+> "Does W1AW have AG status on eQSL?"
+
+> "Verify my QSO with KI7MT on 20m on March 1, 2026"
+
+## Testing Without Credentials
+
+The two public tools (`eqsl_verify` and `eqsl_ag_check`) work without any credentials.
+
+For `eqsl_inbox` testing, set the mock environment variable:
+
+```bash
+EQSL_MCP_MOCK=1 eqsl-mcp
+```
+
+Or point to a local ADIF file:
+
+```bash
+EQSL_MCP_MOCK=1 EQSL_MCP_ADIF=/path/to/test.adi eqsl-mcp
+```
+
+## MCP Inspector
+
+```bash
+eqsl-mcp --transport streamable-http --port 8001
+```
+
+Then open the MCP Inspector at `http://localhost:8001`.
+
+## Development
+
+```bash
+git clone https://github.com/qso-graph/eqsl-mcp.git
+cd eqsl-mcp
+pip install -e .
+```
+
+## Date Formats
+
+eQSL uses different date formats across endpoints. eqsl-mcp normalizes everything — you always use `YYYY-MM-DD`:
+
+| You provide | eqsl-mcp sends | Endpoint |
+|-------------|----------------|----------|
+| `2026-03-01` | `202603010000` | DownloadInBox (RcvdSince) |
+| `2026-03-01` | `03/01/2026` | VerifyQSO (QSODate) |
+
+## Mode Matching
+
+eQSL requires exact mode matching. `SSB` won't match `USB`/`LSB`. `PSK` won't match `PSK31`. Use the exact mode logged by the other station.
+
+## License
+
+GPL-3.0-or-later

eqsl_mcp-0.1.0/README.md

@@ -0,0 +1,183 @@
+# eqsl-mcp
+
+MCP server for [eQSL.cc](https://www.eqsl.cc/) — download incoming eQSLs, verify QSOs, check AG status, and query upload history through any MCP-compatible AI assistant.
+
+Part of the [qso-graph](https://qso-graph.io/) project. Depends on [adif-mcp](https://pypi.org/project/adif-mcp/) for persona and credential management.
+
+## Install
+
+```bash
+pip install eqsl-mcp
+```
+
+## Tools
+
+| Tool | Auth | Description |
+|------|------|-------------|
+| `eqsl_inbox` | Yes | Download incoming eQSLs with date/confirmation filters |
+| `eqsl_verify` | No | Check if a specific QSO exists in eQSL |
+| `eqsl_ag_check` | No | Check if a callsign has AG (Authenticity Guaranteed) status |
+| `eqsl_last_upload` | No | When did a persona last upload to eQSL |
+
+## Quick Start
+
+### 1. Set up credentials
+
+eqsl-mcp uses adif-mcp personas for credential management:
+
+```bash
+# Install adif-mcp if you haven't
+pip install adif-mcp
+
+# Create a persona and add eQSL credentials
+adif-mcp persona create ki7mt --callsign KI7MT
+adif-mcp persona provider ki7mt eqsl --username KI7MT
+adif-mcp persona secret ki7mt eqsl
+```
+
+### 2. Configure your MCP client
+
+eqsl-mcp works with any MCP-compatible client. Add the server config and restart — tools appear automatically.
+
+#### Claude Desktop
+
+Add to `claude_desktop_config.json` (`~/Library/Application Support/Claude/` on macOS, `%APPDATA%\Claude\` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "eqsl": {
+      "command": "eqsl-mcp"
+    }
+  }
+}
+```
+
+#### Claude Code
+
+Add to `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "eqsl": {
+      "command": "eqsl-mcp"
+    }
+  }
+}
+```
+
+#### ChatGPT Desktop
+
+ChatGPT supports MCP via the [OpenAI Agents SDK](https://developers.openai.com/api/docs/mcp/). Add under Settings > Apps & Connectors, or configure in your agent definition:
+
+```json
+{
+  "mcpServers": {
+    "eqsl": {
+      "command": "eqsl-mcp"
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "eqsl": {
+      "command": "eqsl-mcp"
+    }
+  }
+}
+```
+
+#### VS Code / GitHub Copilot
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "eqsl": {
+      "command": "eqsl-mcp"
+    }
+  }
+}
+```
+
+#### Gemini CLI
+
+Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "eqsl": {
+      "command": "eqsl-mcp"
+    }
+  }
+}
+```
+
+### 3. Ask questions
+
+> "Show me all eQSLs received this week"
+
+> "How many unconfirmed eQSLs do I have on 20m FT8?"
+
+> "Does W1AW have AG status on eQSL?"
+
+> "Verify my QSO with KI7MT on 20m on March 1, 2026"
+
+## Testing Without Credentials
+
+The two public tools (`eqsl_verify` and `eqsl_ag_check`) work without any credentials.
+
+For `eqsl_inbox` testing, set the mock environment variable:
+
+```bash
+EQSL_MCP_MOCK=1 eqsl-mcp
+```
+
+Or point to a local ADIF file:
+
+```bash
+EQSL_MCP_MOCK=1 EQSL_MCP_ADIF=/path/to/test.adi eqsl-mcp
+```
+
+## MCP Inspector
+
+```bash
+eqsl-mcp --transport streamable-http --port 8001
+```
+
+Then open the MCP Inspector at `http://localhost:8001`.
+
+## Development
+
+```bash
+git clone https://github.com/qso-graph/eqsl-mcp.git
+cd eqsl-mcp
+pip install -e .
+```
+
+## Date Formats
+
+eQSL uses different date formats across endpoints. eqsl-mcp normalizes everything — you always use `YYYY-MM-DD`:
+
+| You provide | eqsl-mcp sends | Endpoint |
+|-------------|----------------|----------|
+| `2026-03-01` | `202603010000` | DownloadInBox (RcvdSince) |
+| `2026-03-01` | `03/01/2026` | VerifyQSO (QSODate) |
+
+## Mode Matching
+
+eQSL requires exact mode matching. `SSB` won't match `USB`/`LSB`. `PSK` won't match `PSK31`. Use the exact mode logged by the other station.
+
+## License
+
+GPL-3.0-or-later

eqsl_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "eqsl-mcp"
+version = "0.1.0"
+description = "MCP server for eQSL.cc — inbox download, QSO verification, AG status checks"
+readme = "README.md"
+license = {text = "GPL-3.0-or-later"}
+authors = [{name = "Greg Beam, KI7MT"}]
+requires-python = ">=3.10"
+dependencies = [
+    "adif-mcp>=0.6.2",
+    "fastmcp>=3.0",
+]
+keywords = [
+    "amateur-radio", "ham-radio", "eqsl", "qsl", "qso",
+    "mcp", "model-context-protocol", "confirmation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Communications :: Ham Radio",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://qso-graph.io/"
+Repository = "https://github.com/qso-graph/eqsl-mcp"
+Issues = "https://github.com/qso-graph/eqsl-mcp/issues"
+
+[project.scripts]
+eqsl-mcp = "eqsl_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/eqsl_mcp"]

eqsl_mcp-0.1.0/src/eqsl_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""eqsl-mcp: MCP server for eQSL.cc confirmation data."""
+
+from __future__ import annotations
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("eqsl-mcp")
+except Exception:
+    __version__ = "0.0.0-dev"

eqsl_mcp-0.1.0/src/eqsl_mcp/ag_cache.py

@@ -0,0 +1,72 @@
+"""AG (Authenticity Guaranteed) member list with file-based cache."""
+
+from __future__ import annotations
+
+import os
+import time
+import urllib.request
+
+_AG_URL = "https://www.eqsl.cc/qslcard/DownloadedFiles/AGMemberList.txt"
+_CACHE_TTL = 4 * 3600  # 4 hours — list updated ~6x daily
+
+
+def _cache_path() -> str:
+    """Return OS-appropriate cache file path."""
+    if os.name == "nt":
+        base = os.environ.get("LOCALAPPDATA", os.path.expanduser("~"))
+    else:
+        base = os.environ.get("XDG_CACHE_HOME", os.path.expanduser("~/.cache"))
+    d = os.path.join(base, "eqsl-mcp")
+    os.makedirs(d, exist_ok=True)
+    return os.path.join(d, "ag_members.txt")
+
+
+def _is_fresh(path: str) -> bool:
+    """True if the cache file exists and is younger than TTL."""
+    try:
+        return (time.time() - os.path.getmtime(path)) < _CACHE_TTL
+    except OSError:
+        return False
+
+
+def _download_ag_list() -> set[str]:
+    """Fetch the AG member list from eQSL and cache it."""
+    path = _cache_path()
+    req = urllib.request.Request(_AG_URL, method="GET")
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        data = resp.read().decode("utf-8", errors="replace")
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(data)
+    return _parse_ag(data)
+
+
+def _parse_ag(text: str) -> set[str]:
+    """Parse the AG list into a set of uppercase callsigns."""
+    calls: set[str] = set()
+    for line in text.splitlines():
+        line = line.strip()
+        # Skip header/blank lines — callsigns are alphanumeric+slash
+        if not line or line.startswith("#") or line.startswith("List"):
+            continue
+        # Each line is one callsign
+        call = line.split()[0].upper()
+        if call.isascii() and len(call) >= 3:
+            calls.add(call)
+    return calls
+
+
+def load_ag_set() -> set[str]:
+    """Return the AG member set, using cache if fresh."""
+    path = _cache_path()
+    if _is_fresh(path):
+        try:
+            with open(path, encoding="utf-8") as f:
+                return _parse_ag(f.read())
+        except OSError:
+            pass
+    return _download_ag_list()
+
+
+def is_ag(callsign: str) -> bool:
+    """Check if a callsign has AG status."""
+    return callsign.upper() in load_ag_set()

eqsl_mcp-0.1.0/src/eqsl_mcp/client.py

@@ -0,0 +1,155 @@
+"""HTTP client layer for eQSL.cc endpoints."""
+
+from __future__ import annotations
+
+import os
+import re
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from adif_mcp.identity import PersonaManager
+
+from .parser import FetchResult, QsoRecord, parse_adif, to_mmddyyyy, to_qso, to_yyyymmddhhmm
+
+_BASE = "https://www.eqsl.cc"
+
+# Mock ADIF for testing without credentials
+_MOCK_ADIF = (
+    "<CALL:5>KI7MT<QSO_DATE:8>20250901<TIME_ON:6>010203<BAND:3>20M<MODE:3>FT8"
+    "<EQSL_QSL_RCVD:1>Y<EQSL_QSLRDATE:8>20250902<APP_EQSL_AG:1>Y<EOR>"
+    "<CALL:5>K7ABC<QSO_DATE:8>20250901<TIME_ON:6>040506<BAND:3>40M<MODE:2>CW"
+    "<EQSL_QSL_RCVD:1>N<EOR>"
+)
+
+# Regex to find the .adi download link in the HTML response
+_ADI_LINK_RE = re.compile(r'href="([^"]*\.adi)"', re.IGNORECASE)
+
+
+def _is_mock() -> bool:
+    return os.getenv("EQSL_MCP_MOCK") == "1"
+
+
+def _get(url: str, query: dict[str, Any] | None = None,
+         timeout: float = 15.0) -> tuple[int, str]:
+    """HTTP GET, return (status, text)."""
+    if query:
+        qs = urllib.parse.urlencode(query, doseq=True)
+        url = f"{url}?{qs}"
+    req = urllib.request.Request(url, method="GET")
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return resp.status, resp.read().decode("utf-8", errors="replace")
+
+
+# ---------------------------------------------------------------------------
+# eqsl_inbox
+# ---------------------------------------------------------------------------
+
+def download_inbox(
+    pm: PersonaManager,
+    persona: str,
+    since: str | None = None,
+    qth_nickname: str | None = None,
+) -> FetchResult:
+    """Download incoming eQSLs for a persona.
+
+    Two-step flow: GET DownloadInBox.cfm → parse HTML for .adi link → fetch ADIF.
+    Fallback: if the response body contains <EOH> or <EOR>, treat as direct ADIF.
+    """
+    if _is_mock():
+        sample = os.getenv("EQSL_MCP_ADIF")
+        if sample and os.path.exists(sample):
+            text = open(sample, encoding="utf-8").read()
+        else:
+            text = _MOCK_ADIF
+        return FetchResult(records=[to_qso(r) for r in parse_adif(text)])
+
+    username, password = pm.require(persona, "eqsl")
+
+    query: dict[str, Any] = {
+        "UserName": username,
+        "Password": password,
+        "RcvdSince": to_yyyymmddhhmm(since),
+    }
+    if qth_nickname:
+        query["QTHNickname"] = qth_nickname
+
+    status, body = _get(f"{_BASE}/qslcard/DownloadInBox.cfm", query)
+    if status != 200:
+        return FetchResult(records=[])
+
+    # Check if this is already ADIF (some responses come direct)
+    upper = body.upper()
+    if "<EOH>" in upper or "<EOR>" in upper:
+        return FetchResult(records=[to_qso(r) for r in parse_adif(body)])
+
+    # Two-step: extract .adi link from HTML
+    m = _ADI_LINK_RE.search(body)
+    if not m:
+        return FetchResult(records=[])
+
+    adi_url = m.group(1)
+    if not adi_url.startswith("http"):
+        adi_url = f"{_BASE}{adi_url}" if adi_url.startswith("/") else f"{_BASE}/{adi_url}"
+
+    _, adif_text = _get(adi_url)
+    return FetchResult(records=[to_qso(r) for r in parse_adif(adif_text)])
+
+
+# ---------------------------------------------------------------------------
+# eqsl_verify
+# ---------------------------------------------------------------------------
+
+def verify_qso(
+    from_call: str,
+    to_call: str,
+    band: str,
+    qso_date: str,
+    mode: str | None = None,
+) -> dict[str, Any]:
+    """Verify a QSO exists in eQSL (public, no auth).
+
+    Args:
+        qso_date: YYYY-MM-DD format.
+    """
+    if _is_mock():
+        return {"verified": True, "ag": True, "message": "Result - QSO on file for AG member"}
+
+    query: dict[str, Any] = {
+        "Callsign": from_call.upper(),
+        "HisCall": to_call.upper(),
+        "QSOBand": band.upper(),
+        "QSODate": to_mmddyyyy(qso_date),
+    }
+    if mode:
+        query["QSOMode"] = mode.upper()
+
+    _, body = _get(f"{_BASE}/qslcard/VerifyQSO.cfm", query)
+
+    text = body.strip()
+    verified = "qso on file" in text.lower()
+    ag = "ag member" in text.lower()
+    return {"verified": verified, "ag": ag, "message": text}
+
+
+# ---------------------------------------------------------------------------
+# eqsl_last_upload
+# ---------------------------------------------------------------------------
+
+def last_upload_date(pm: PersonaManager, persona: str) -> dict[str, Any]:
+    """Get the last upload date for a persona."""
+    if _is_mock():
+        return {"persona": persona, "last_upload": "2026-03-01 12:00:00"}
+
+    username, password = pm.require(persona, "eqsl")
+
+    query: dict[str, Any] = {
+        "UserName": username,
+        "Password": password,
+    }
+    status, body = _get(f"{_BASE}/qslcard/DisplayLastUploadDate.cfm", query)
+    if status != 200:
+        return {"persona": persona, "last_upload": None, "error": f"HTTP {status}"}
+
+    # The response is typically plain text with the date
+    return {"persona": persona, "last_upload": body.strip()}

eqsl_mcp-0.1.0/src/eqsl_mcp/parser.py

@@ -0,0 +1,144 @@
+"""Minimal ADIF parser and QSO record types for eQSL responses."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import date, datetime
+from typing import TypedDict
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+
+class QsoRecord(TypedDict, total=False):
+    """Normalized QSO record from eQSL inbox."""
+
+    call: str
+    qso_date: str       # YYYYMMDD
+    time_on: str        # HHMM or HHMMSS
+    band: str | None
+    mode: str | None
+    freq: float | None  # MHz
+    rst_sent: str | None
+    rst_rcvd: str | None
+    gridsquare: str | None
+    eqsl_qsl_rcvd: str | None   # Y/N/I/…
+    eqsl_qslrdate: str | None   # YYYYMMDD
+    app_eqsl_ag: str | None     # Y/N
+    qslmsg: str | None
+    adif: dict[str, str]
+
+
+@dataclass(frozen=True)
+class FetchResult:
+    """Container for parsed inbox records."""
+
+    records: list[QsoRecord]
+
+
+# ---------------------------------------------------------------------------
+# ADIF parser
+# ---------------------------------------------------------------------------
+
+_FIELD_RE = re.compile(
+    r"<([A-Za-z0-9_]+):(\d+)(?::[A-Za-z])?>([^<]*)", re.IGNORECASE
+)
+
+
+def parse_adif(text: str) -> list[dict[str, str]]:
+    """Extract tag→value pairs per <EOR> from raw ADIF text.
+
+    Not a full ADIF parser — sufficient for eQSL response payloads.
+    """
+    out: list[dict[str, str]] = []
+    current: dict[str, str] = {}
+    i = 0
+    n = len(text)
+    while i < n:
+        if text[i : i + 5].upper() == "<EOR>":
+            if current:
+                out.append(current)
+                current = {}
+            i += 5
+            continue
+        m = _FIELD_RE.match(text, i)
+        if not m:
+            i += 1
+            continue
+        tag, length_s, value = m.group(1), m.group(2), m.group(3)
+        try:
+            length = int(length_s)
+        except ValueError:
+            length = len(value)
+        if len(value) < length:
+            end = m.end()
+            need = length - len(value)
+            value = value + text[end : end + need]
+            i = end + need
+        else:
+            i = m.end()
+        current[tag.upper()] = value
+    if current:
+        out.append(current)
+    return out
+
+
+def to_qso(rec: dict[str, str]) -> QsoRecord:
+    """Convert a raw ADIF tag dict into a normalized QsoRecord."""
+
+    def _float(s: str | None) -> float | None:
+        try:
+            return float(s) if s else None
+        except Exception:
+            return None
+
+    return QsoRecord(
+        call=rec.get("CALL", "").upper(),
+        qso_date=rec.get("QSO_DATE", ""),
+        time_on=rec.get("TIME_ON", ""),
+        band=rec.get("BAND"),
+        mode=rec.get("MODE"),
+        freq=_float(rec.get("FREQ")),
+        rst_sent=rec.get("RST_SENT"),
+        rst_rcvd=rec.get("RST_RCVD"),
+        gridsquare=rec.get("GRIDSQUARE"),
+        eqsl_qsl_rcvd=rec.get("EQSL_QSL_RCVD"),
+        eqsl_qslrdate=rec.get("EQSL_QSLRDATE"),
+        app_eqsl_ag=rec.get("APP_EQSL_AG"),
+        qslmsg=rec.get("QSLMSG"),
+        adif=rec,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Date helpers
+# ---------------------------------------------------------------------------
+
+
+def to_yyyymmddhhmm(d: str | date | None) -> str:
+    """Convert a date to YYYYMMDDHHMM (eQSL RcvdSince format).
+
+    Accepts ISO date strings (YYYY-MM-DD), date objects, or None (→ 30 days ago).
+    """
+    if d is None:
+        dt = datetime.utcnow()
+        from datetime import timedelta
+        dt = dt - timedelta(days=30)
+        return dt.strftime("%Y%m%d0000")
+    if isinstance(d, date):
+        return d.strftime("%Y%m%d0000")
+    try:
+        return date.fromisoformat(d).strftime("%Y%m%d0000")
+    except Exception:
+        return datetime.utcnow().strftime("%Y%m%d0000")
+
+
+def to_mmddyyyy(d: str) -> str:
+    """Convert YYYY-MM-DD to MM/DD/YYYY (eQSL VerifyQSO format)."""
+    try:
+        dt = date.fromisoformat(d)
+        return dt.strftime("%m/%d/%Y")
+    except Exception:
+        return d

eqsl_mcp-0.1.0/src/eqsl_mcp/server.py

@@ -0,0 +1,162 @@
+"""eqsl-mcp: MCP server for eQSL.cc confirmation data."""
+
+from __future__ import annotations
+
+import sys
+
+from fastmcp import FastMCP
+
+from adif_mcp.identity import PersonaManager
+from adif_mcp.identity.errors import CredentialError
+
+from . import __version__
+from .ag_cache import is_ag
+from .client import download_inbox, last_upload_date, verify_qso
+
+mcp = FastMCP(
+    "eqsl-mcp",
+    version=__version__,
+    instructions="MCP server for eQSL.cc — inbox, verification, AG status",
+)
+
+
+def _pm() -> PersonaManager:
+    return PersonaManager()
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def eqsl_inbox(
+    persona: str,
+    since: str | None = None,
+    confirmed_only: bool = False,
+    unconfirmed_only: bool = False,
+    qth_nickname: str | None = None,
+) -> dict:
+    """Download incoming eQSLs (confirmations others have sent you).
+
+    Args:
+        persona: Persona name configured in adif-mcp.
+        since: Only records added since this date (YYYY-MM-DD). Default: last 30 days.
+        confirmed_only: Only return records you have confirmed back.
+        unconfirmed_only: Only return records you have NOT confirmed.
+        qth_nickname: QTH profile name (for multi-QTH callsigns).
+
+    Returns:
+        Total count, confirmed count, breakdown by band, and QSO records.
+    """
+    try:
+        result = download_inbox(_pm(), persona, since=since, qth_nickname=qth_nickname)
+    except CredentialError as e:
+        return {"error": str(e)}
+
+    records = result.records
+
+    if confirmed_only:
+        records = [r for r in records if (r.get("eqsl_qsl_rcvd") or "").upper() == "Y"]
+    elif unconfirmed_only:
+        records = [r for r in records if (r.get("eqsl_qsl_rcvd") or "").upper() != "Y"]
+
+    # Band tally
+    tally: dict[str, int] = {}
+    confirmed = 0
+    for r in records:
+        band = (r.get("band") or "UNKNOWN").upper()
+        tally[band] = tally.get(band, 0) + 1
+        if (r.get("eqsl_qsl_rcvd") or "").upper() == "Y":
+            confirmed += 1
+
+    return {
+        "total": len(records),
+        "confirmed": confirmed,
+        "by_band": [{"band": k, "count": v} for k, v in sorted(tally.items())],
+        "records": records,
+    }
+
+
+@mcp.tool()
+def eqsl_verify(
+    from_call: str,
+    to_call: str,
+    band: str,
+    qso_date: str,
+    mode: str | None = None,
+) -> dict:
+    """Check if a specific QSO exists in eQSL (public, no auth required).
+
+    Args:
+        from_call: Sender's callsign.
+        to_call: Receiver's callsign.
+        band: Band (e.g., '20m').
+        qso_date: QSO date in YYYY-MM-DD format.
+        mode: Mode (exact match — use 'USB' not 'SSB', 'PSK31' not 'PSK').
+
+    Returns:
+        Whether the QSO is verified, AG status, and the raw message.
+    """
+    return verify_qso(from_call, to_call, band, qso_date, mode)
+
+
+@mcp.tool()
+def eqsl_ag_check(callsign: str) -> dict:
+    """Check if a callsign has Authenticity Guaranteed (AG) status on eQSL.
+
+    Public, no auth required. Uses a cached copy of the AG member list
+    (refreshed every 4 hours).
+
+    Args:
+        callsign: The callsign to check.
+
+    Returns:
+        Callsign and AG status.
+    """
+    try:
+        ag = is_ag(callsign)
+        return {"callsign": callsign.upper(), "ag": ag}
+    except Exception as e:
+        return {"callsign": callsign.upper(), "ag": None, "error": str(e)}
+
+
+@mcp.tool()
+def eqsl_last_upload(persona: str) -> dict:
+    """Check when a persona last uploaded QSOs to eQSL.
+
+    Args:
+        persona: Persona name configured in adif-mcp.
+
+    Returns:
+        Persona name and last upload timestamp.
+    """
+    try:
+        return last_upload_date(_pm(), persona)
+    except CredentialError as e:
+        return {"error": str(e)}
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    """Run the eqsl-mcp server."""
+    transport = "stdio"
+    port = 8001
+    for i, arg in enumerate(sys.argv[1:], 1):
+        if arg == "--transport" and i < len(sys.argv) - 1:
+            transport = sys.argv[i + 1]
+        if arg == "--port" and i < len(sys.argv) - 1:
+            port = int(sys.argv[i + 1])
+
+    if transport == "streamable-http":
+        mcp.run(transport=transport, port=port)
+    else:
+        mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()