Add qrz_download tool — raw ADIF export with full pagination

New download_adif() paginates through ALL records via AFTERLOGID,
concatenates ADIF fragments, wraps with proper ADIF 3.1.6 header.
Refactors option building into _build_options() shared helper.
Includes test_tools.py with mock tests for all 5 tools (16 tests).
Version bump to 0.2.0.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: KI7MT

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qrz-mcp"
-version = "0.1.2"
+version = "0.2.0"
 description = "MCP server for QRZ.com — callsign lookup, DXCC resolution, logbook queries"
 readme = "README.md"
 license = {text = "GPL-3.0-or-later"}

server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/qso-graph/qrz-mcp",
     "source": "github"
   },
-  "version": "0.1.2",
+  "version": "0.2.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "qrz-mcp",
-      "version": "0.1.2",
+      "version": "0.2.0",
       "transport": { "type": "stdio" }
     }
   ],

src/qrz_mcp/logbook_client.py

@@ -186,6 +186,34 @@ def _int(key: str) -> int:
             end_date=kv.get("END", ""),
         )
 
+    def _build_options(
+        self,
+        band: str | None = None,
+        mode: str | None = None,
+        callsign: str | None = None,
+        dxcc: int | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        confirmed_only: bool = False,
+    ) -> list[str]:
+        """Build OPTION filter list for FETCH requests."""
+        options: list[str] = []
+        if band:
+            options.append(f"BAND:{band.upper()}")
+        if mode:
+            options.append(f"MODE:{mode.upper()}")
+        if callsign:
+            options.append(f"CALL:{callsign.upper()}")
+        if dxcc is not None:
+            options.append(f"DXCC:{dxcc}")
+        if start_date:
+            options.append(f"AFTER:{start_date.replace('-', '')}")
+        if end_date:
+            options.append(f"BEFORE:{end_date.replace('-', '')}")
+        if confirmed_only:
+            options.append("STATUS:CONFIRMED")
+        return options
+
     def fetch(
         self,
         band: str | None = None,
@@ -204,29 +232,12 @@ def fetch(
 
         all_qsos: list[QsoRecord] = []
         after_logid: str | None = None
+        options = self._build_options(band, mode, callsign, dxcc, start_date, end_date, confirmed_only)
 
         while len(all_qsos) < limit:
             params: dict[str, str] = {"ACTION": "FETCH"}
-
-            # Build OPTION filter string
-            options: list[str] = []
-            if band:
-                options.append(f"BAND:{band.upper()}")
-            if mode:
-                options.append(f"MODE:{mode.upper()}")
-            if callsign:
-                options.append(f"CALL:{callsign.upper()}")
-            if dxcc is not None:
-                options.append(f"DXCC:{dxcc}")
-            if start_date:
-                options.append(f"AFTER:{start_date.replace('-', '')}")
-            if end_date:
-                options.append(f"BEFORE:{end_date.replace('-', '')}")
-            if confirmed_only:
-                options.append("STATUS:CONFIRMED")
             if options:
                 params["OPTION"] = ",".join(options)
-
             if after_logid:
                 params["AFTERLOGID"] = after_logid
 
@@ -257,3 +268,57 @@ def fetch(
                 break
 
         return all_qsos
+
+    def download_adif(
+        self,
+        band: str | None = None,
+        mode: str | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> dict[str, Any]:
+        """Download complete logbook as raw ADIF text.
+
+        Paginates through ALL records, concatenates ADIF fragments,
+        and wraps with a proper ADIF header.
+        """
+        if _is_mock():
+            header = "<ADIF_VER:5>3.1.6\n<PROGRAMID:7>qrz-mcp\n<EOH>\n"
+            adif_text = header + _MOCK_FETCH_ADIF
+            record_count = adif_text.upper().count("<EOR>")
+            return {"adif": adif_text, "record_count": record_count}
+
+        fragments: list[str] = []
+        after_logid: str | None = None
+        options = self._build_options(band=band, mode=mode, start_date=start_date, end_date=end_date)
+
+        while True:
+            params: dict[str, str] = {"ACTION": "FETCH"}
+            if options:
+                params["OPTION"] = ",".join(options)
+            if after_logid:
+                params["AFTERLOGID"] = after_logid
+
+            kv = self._post(params)
+
+            adif = kv.get("ADIF", "")
+            if not adif:
+                break
+
+            fragments.append(adif)
+
+            # Pagination cursor
+            logids = kv.get("LOGIDS", "")
+            if logids:
+                last_id = logids.split(",")[-1].strip()
+                if last_id and last_id != after_logid:
+                    after_logid = last_id
+                else:
+                    break
+            else:
+                break
+
+        header = "<ADIF_VER:5>3.1.6\n<PROGRAMID:7>qrz-mcp\n<EOH>\n"
+        body = "\n".join(fragments)
+        adif_text = header + body
+        record_count = adif_text.upper().count("<EOR>")
+        return {"adif": adif_text, "record_count": record_count}

src/qrz_mcp/server.py

@@ -122,6 +122,37 @@ def qrz_logbook_status(persona: str) -> dict[str, Any]:
         return {"error": str(e)}
 
 
+@mcp.tool()
+def qrz_download(
+    persona: str,
+    band: str | None = None,
+    mode: str | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+) -> dict[str, Any]:
+    """Download your complete QRZ logbook as raw ADIF text.
+
+    Returns the .adi file content — save to disk for import into your logger.
+    Transparently paginates to collect all records. Rate-limited to avoid API bans.
+
+    Args:
+        persona: Persona name configured in adif-mcp.
+        band: Filter by band (e.g., '20m').
+        mode: Filter by mode (e.g., 'FT8').
+        start_date: Date range start (YYYY-MM-DD).
+        end_date: Date range end (YYYY-MM-DD).
+
+    Returns:
+        Raw ADIF text and record count.
+    """
+    try:
+        return _logbook(persona).download_adif(
+            band=band, mode=mode, start_date=start_date, end_date=end_date,
+        )
+    except Exception as e:
+        return {"error": str(e)}
+
+
 @mcp.tool()
 def qrz_logbook_fetch(
     persona: str,

src/qrz_mcp/xml_client.py

@@ -7,7 +7,6 @@
 import urllib.parse
 import urllib.request
 import xml.etree.ElementTree as ET
-from typing import Any
 
 from . import __version__
 from .cache import TTLCache

tests/test_tools.py

@@ -0,0 +1,100 @@
+"""Tool tests for qrz-mcp — all 5 tools in mock mode."""
+
+from __future__ import annotations
+
+import os
+
+os.environ["QRZ_MCP_MOCK"] = "1"
+
+from qrz_mcp.server import (
+    qrz_dxcc,
+    qrz_download,
+    qrz_logbook_fetch,
+    qrz_logbook_status,
+    qrz_lookup,
+)
+
+
+# ---------------------------------------------------------------------------
+# qrz_lookup
+# ---------------------------------------------------------------------------
+
+
+class TestQrzLookup:
+    def test_returns_record(self):
+        result = qrz_lookup(persona="test", callsign="KI7MT")
+        assert "call" in result or "error" not in result
+
+    def test_callsign_present(self):
+        result = qrz_lookup(persona="test", callsign="W1AW")
+        assert result.get("call") == "W1AW" or "error" not in result
+
+
+# ---------------------------------------------------------------------------
+# qrz_dxcc
+# ---------------------------------------------------------------------------
+
+
+class TestQrzDxcc:
+    def test_returns_entity(self):
+        result = qrz_dxcc(persona="test", query="291")
+        assert "dxcc" in result or "name" in result
+
+
+# ---------------------------------------------------------------------------
+# qrz_download
+# ---------------------------------------------------------------------------
+
+
+class TestQrzDownload:
+    def test_returns_raw_adif(self):
+        result = qrz_download(persona="test")
+        assert "adif" in result
+        assert "<EOR>" in result["adif"].upper()
+
+    def test_record_count(self):
+        result = qrz_download(persona="test")
+        assert result["record_count"] == 2
+
+    def test_has_adif_header(self):
+        result = qrz_download(persona="test")
+        assert "<ADIF_VER:5>3.1.6" in result["adif"]
+        assert "<PROGRAMID:7>qrz-mcp" in result["adif"]
+        assert "<EOH>" in result["adif"]
+
+    def test_adif_contains_callsigns(self):
+        result = qrz_download(persona="test")
+        assert "KI7MT" in result["adif"]
+        assert "W1AW" in result["adif"]
+
+
+# ---------------------------------------------------------------------------
+# qrz_logbook_status
+# ---------------------------------------------------------------------------
+
+
+class TestQrzLogbookStatus:
+    def test_returns_stats(self):
+        result = qrz_logbook_status(persona="test")
+        assert result["count"] == 1547
+        assert result["dxcc"] == 142
+        assert result["callsign"] == "KI7MT"
+
+
+# ---------------------------------------------------------------------------
+# qrz_logbook_fetch
+# ---------------------------------------------------------------------------
+
+
+class TestQrzLogbookFetch:
+    def test_returns_records(self):
+        result = qrz_logbook_fetch(persona="test")
+        assert result["total"] == 2
+        assert len(result["records"]) == 2
+
+    def test_record_fields(self):
+        result = qrz_logbook_fetch(persona="test")
+        rec = result["records"][0]
+        assert rec["call"] == "KI7MT"
+        assert rec["band"] == "20M"
+        assert rec["mode"] == "FT8"