Metadata-Version: 2.4
Name: adif-mcp
Version: 1.0.1
Summary: ADIF MCP server — spec parsing, validation, and field enumeration tools
Project-URL: Homepage, https://qso-graph.io
Project-URL: Documentation, https://qso-graph.io
Project-URL: Repository, https://github.com/qso-graph/adif-mcp
Project-URL: Issues, https://github.com/qso-graph/adif-mcp/issues
Project-URL: ADIF Specification, https://adif.org.uk/316/ADIF_316.htm
Author-email: KI7MT <ki7mt@yahoo.com>
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: adif,ai-agents,amateur-radio,eqsl,ham-radio,lotw,mcp,model-context-protocol,qrz,qso-logging
Classifier: Environment :: Console
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
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: click>=8.1.7
Requires-Dist: fastmcp>=3.0
Requires-Dist: requests>=2.32.5
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typing-extensions>=4.15.0
Provides-Extra: all
Requires-Dist: cli-test-helpers>=0.3.0; extra == 'all'
Requires-Dist: interrogate>=1.7.0; extra == 'all'
Requires-Dist: mypy>=1.11; extra == 'all'
Requires-Dist: pytest>=8.3; extra == 'all'
Requires-Dist: ruff>=0.6.8; extra == 'all'
Provides-Extra: dev
Requires-Dist: interrogate>=1.7.0; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: ruff>=0.6.8; extra == 'dev'
Provides-Extra: test
Requires-Dist: cli-test-helpers>=0.3.0; extra == 'test'
Requires-Dist: pytest>=8.3; extra == 'test'
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.qso-graph/adif-mcp -->
# adif-mcp

Core [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for **Amateur Radio Logging**, built on the [ADIF 3.1.6 specification](https://adif.org.uk/316/ADIF_316.htm).

## Overview

adif-mcp gives AI agents safe, typed access to Amateur Radio logging data. It validates and parses ADIF records, searches the full ADIF 3.1.6 specification (fields, enumerations, data types), and provides geospatial utilities for Maidenhead locators. It also provides persona management and keyring-backed credential storage used by the qso-graph family of MCP servers.

[![Made with Python](https://img.shields.io/badge/Made%20with-Python-blue)](https://www.python.org/)
[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](LICENSE)
[![ADIF 3.1.6](https://img.shields.io/badge/ADIF-3.1.6-blue)](https://adif.org.uk/316/ADIF_316.htm)
[![PyPI](https://img.shields.io/pypi/v/adif-mcp)](https://pypi.org/project/adif-mcp/)
[![CI](https://github.com/qso-graph/adif-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/qso-graph/adif-mcp/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-qso--graph.io-blue)](https://qso-graph.io/)

## Quick Start

```bash
pip install adif-mcp
```

## Configure Your MCP Client

adif-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": {
    "adif": {
      "command": "adif-mcp"
    }
  }
}
```

### Claude Code

Add to `.claude/settings.json`:

```json
{
  "mcpServers": {
    "adif": {
      "command": "adif-mcp"
    }
  }
}
```

### ChatGPT Desktop

Configure via Settings > Apps & Connectors, or in your agent definition:

```json
{
  "mcpServers": {
    "adif": {
      "command": "adif-mcp"
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "adif": {
      "command": "adif-mcp"
    }
  }
}
```

### VS Code / GitHub Copilot

Add to `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "adif": {
      "command": "adif-mcp"
    }
  }
}
```

### Gemini CLI

Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):

```json
{
  "mcpServers": {
    "adif": {
      "command": "adif-mcp"
    }
  }
}
```

## Tools

adif-mcp exposes **8 tools** via the Model Context Protocol:

| Category | Tool | Description |
|----------|------|-------------|
| **Validation** | `validate_adif_record` | Validate a raw ADIF string against the 3.1.6 spec |
| **Validation** | `parse_adif` | Streaming parser for large ADIF files with pagination |
| **Spec** | `read_specification_resource` | Retrieve raw JSON for any spec module (band, mode, fields) |
| **Spec** | `list_enumerations` | List all ADIF enumerations with entry counts |
| **Spec** | `search_enumerations` | Search enumeration records by keyword |
| **Geospatial** | `calculate_distance` | Great Circle distance (km) between two Maidenhead locators |
| **Geospatial** | `calculate_heading` | Initial beam heading (azimuth) between two locators |
| **System** | `get_version_info` | Active service version and ADIF spec version |

## Architecture

adif-mcp is the **foundation package** -- ADIF spec tools, persona management, and credential storage. Service integrations are separate MCP servers that depend on adif-mcp for identity and auth:

| Package | PyPI | What It Does |
|---------|------|-------------|
| [`adif-mcp`](https://pypi.org/project/adif-mcp/) | v0.9.6 | ADIF 3.1.6 spec tools + persona/credential management |
| [`lotw-mcp`](https://pypi.org/project/lotw-mcp/) | v0.2.0 | LoTW confirmations, QSOs, DXCC credits, user activity |
| [`eqsl-mcp`](https://pypi.org/project/eqsl-mcp/) | v0.2.0 | eQSL inbox, verification, AG status, last upload |
| [`qrz-mcp`](https://pypi.org/project/qrz-mcp/) | v0.2.1 | Callsign lookup, DXCC, logbook status/fetch |
| [`hamqth-mcp`](https://pypi.org/project/hamqth-mcp/) | v0.2.0 | Callsign lookup, DXCC, bio, activity, DX spots, RBN |
| [`pota-mcp`](https://pypi.org/project/pota-mcp/) | v0.1.1 | Parks on the Air spots, park info, stats, schedules |
| [`sota-mcp`](https://pypi.org/project/sota-mcp/) | v0.1.1 | Summits on the Air spots, alerts, summit info, stats |
| [`solar-mcp`](https://pypi.org/project/solar-mcp/) | v0.1.1 | Space weather conditions, forecasts, band outlook |
| [`wspr-mcp`](https://pypi.org/project/wspr-mcp/) | v0.1.1 | WSPR beacon spots, propagation, band activity |
| [`iota-mcp`](https://pypi.org/project/iota-mcp/) | v0.1.0 | Islands on the Air lookup, search, nearby groups |

Authenticated servers use `adif-mcp` for persona lookup and keyring-backed credentials. Operators install only the servers they need. Each server is independently versioned with no unnecessary dependencies.

## Compliance & Provenance

adif-mcp follows the [ADIF Specification](https://adif.org.uk) (currently 3.1.6) and uses **registered Program IDs** to identify all exports:

- `ADIF-MCP` -- Core engine
- `ADIF-MCP-LOTW` -- LoTW server
- `ADIF-MCP-EQSL` -- eQSL server
- `ADIF-MCP-QRZ` -- QRZ server

The project uses **APP_ fields** for provenance when augmenting records:

- `APP_ADIF-MCP_OP` -- operation performed (`normalize`, `validate`, `merge`)
- `APP_ADIF-MCP-LOTW_ACTION` -- LoTW server operation
- `APP_ADIF-MCP-EQSL_TIME` -- timestamp of eQSL merge

## License

GPL-3.0-or-later. See [LICENSE](LICENSE) for details.
