Skip to content

Commit 583ad2b

Browse files
KI7MTclaude
KI7MT
and
claude
committed
Add credential setup guide, fix CLI syntax in getting-started
New docs/credentials.md with full end-to-end walkthrough: persona creation, per-server examples (all 5 auth providers), creds doctor verification, CLI reference, multiple personas, and troubleshooting. Fix getting-started.md: positional args (not --persona/--provider), add missing persona add step, add hamqth + qrz_logbook providers, remove --password from CLI examples (use interactive prompt). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 2cda4dd commit 583ad2b

3 files changed

Lines changed: 241 additions & 11 deletions

File tree

‎docs/credentials.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
# Credential Setup Guide
2+
3+
## How It Works
4+
5+
qso-graph uses two layers for credential management: a **persona index** (non-secret YAML file with your callsign and date range) and the **OS keyring** (where secrets are stored). A persona is your callsign identity; a provider is a service like eQSL or QRZ. Credentials are never stored in config files — only in your operating system's secure keyring.
6+
7+
---
8+
9+
## Quick Start
10+
11+
```bash
12+
# 1. Install the foundation package
13+
pip install adif-mcp
14+
15+
# 2. Create a persona (your callsign identity)
16+
adif-mcp persona add --name ki7mt --callsign KI7MT --start 2020-01-01
17+
18+
# 3. Store credentials for a service (prompts for username + password)
19+
adif-mcp creds set ki7mt eqsl
20+
21+
# 4. Verify everything is wired up
22+
adif-mcp creds doctor
23+
```
24+
25+
That's it. The MCP servers will find your credentials automatically.
26+
27+
---
28+
29+
## Per-Server Credential Setup
30+
31+
| Server | Provider | Auth Type | What You Need |
32+
|--------|----------|-----------|---------------|
33+
| eqsl-mcp | `eqsl` | username + password | eQSL.cc login |
34+
| lotw-mcp | `lotw` | username + password | LoTW website login |
35+
| qrz-mcp (lookup) | `qrz` | username + password | QRZ.com login (XML subscription for full data) |
36+
| qrz-mcp (logbook) | `qrz_logbook` | username + API key | QRZ API key from Settings → API |
37+
| hamqth-mcp | `hamqth` | username + password | HamQTH.com login (free account) |
38+
| pota-mcp | — | none | Public API, no setup needed |
39+
| sota-mcp | — | none | Public API, no setup needed |
40+
| solar-mcp | — | none | Public API, no setup needed |
41+
| wspr-mcp | — | none | Public API, no setup needed |
42+
43+
!!! note "QRZ has two providers"
44+
The XML API (callsign lookup, DXCC) uses your **QRZ password** via the `qrz` provider. The Logbook API (fetch QSOs, logbook status) uses a separate **API key** via the `qrz_logbook` provider. You only need `qrz_logbook` if you want logbook tools. Get your API key from QRZ → Settings → API.
45+
46+
### eQSL
47+
48+
```bash
49+
adif-mcp creds set ki7mt eqsl
50+
```
51+
52+
```
53+
Username: KI7MT
54+
Password: ********
55+
✓ Stored eqsl credentials for ki7mt
56+
```
57+
58+
### LoTW
59+
60+
```bash
61+
adif-mcp creds set ki7mt lotw
62+
```
63+
64+
```
65+
Username: KI7MT
66+
Password: ********
67+
✓ Stored lotw credentials for ki7mt
68+
```
69+
70+
### QRZ (Callsign Lookup)
71+
72+
```bash
73+
adif-mcp creds set ki7mt qrz
74+
```
75+
76+
```
77+
Username: KI7MT
78+
Password: ********
79+
✓ Stored qrz credentials for ki7mt
80+
```
81+
82+
### QRZ (Logbook API)
83+
84+
```bash
85+
adif-mcp creds set ki7mt qrz_logbook
86+
```
87+
88+
```
89+
Username: KI7MT
90+
API Key: ********
91+
✓ Stored qrz_logbook credentials for ki7mt
92+
```
93+
94+
### HamQTH
95+
96+
```bash
97+
adif-mcp creds set ki7mt hamqth
98+
```
99+
100+
```
101+
Username: KI7MT
102+
Password: ********
103+
✓ Stored hamqth credentials for ki7mt
104+
```
105+
106+
---
107+
108+
## Verify Your Setup
109+
110+
Run the doctor command to check all credentials at once:
111+
112+
```bash
113+
adif-mcp creds doctor
114+
```
115+
116+
```
117+
Credential Health Check
118+
=======================
119+
✓ ki7mt:eqsl — stored (username_password)
120+
✓ ki7mt:lotw — stored (username_password)
121+
✓ ki7mt:qrz — stored (username_password)
122+
✓ ki7mt:qrz_logbook — stored (api_key)
123+
✓ ki7mt:hamqth — stored (username_password)
124+
125+
Summary: stored=5, missing=0
126+
```
127+
128+
To check a single persona:
129+
130+
```bash
131+
adif-mcp creds doctor --persona ki7mt
132+
```
133+
134+
---
135+
136+
## CLI Reference
137+
138+
### Persona Commands
139+
140+
| Command | Description |
141+
|---------|-------------|
142+
| `adif-mcp persona add --name NAME --callsign CALL --start YYYY-MM-DD` | Create a persona |
143+
| `adif-mcp persona list` | List all personas |
144+
| `adif-mcp persona list --verbose` | List with callsign and date range |
145+
| `adif-mcp persona show NAME` | Show persona details |
146+
| `adif-mcp persona set-active NAME` | Set the active persona |
147+
| `adif-mcp persona remove NAME` | Delete a persona |
148+
149+
### Credential Commands
150+
151+
| Command | Description |
152+
|---------|-------------|
153+
| `adif-mcp creds set PERSONA PROVIDER` | Store credentials (interactive prompt) |
154+
| `adif-mcp creds get PERSONA PROVIDER` | Show credentials (redacted) |
155+
| `adif-mcp creds get PERSONA PROVIDER --raw` | Show credentials (unmasked) |
156+
| `adif-mcp creds delete PERSONA PROVIDER` | Remove credentials from keyring |
157+
| `adif-mcp creds doctor` | Check all personas for missing credentials |
158+
159+
### Provider Commands
160+
161+
| Command | Description |
162+
|---------|-------------|
163+
| `adif-mcp provider list` | List supported providers |
164+
| `adif-mcp provider enable PERSONA PROVIDER` | Enable a provider for a persona |
165+
| `adif-mcp provider disable PERSONA PROVIDER` | Disable a provider for a persona |
166+
167+
---
168+
169+
## Multiple Personas
170+
171+
If you have multiple callsigns (contest calls, special events, club stations), create a persona for each:
172+
173+
```bash
174+
# Primary callsign
175+
adif-mcp persona add --name ki7mt --callsign KI7MT --start 2020-01-01
176+
adif-mcp creds set ki7mt eqsl
177+
adif-mcp creds set ki7mt qrz
178+
179+
# Contest callsign (with end date)
180+
adif-mcp persona add --name k7mt --callsign K7MT --start 2024-06-01 --end 2024-06-30
181+
adif-mcp creds set k7mt eqsl
182+
183+
# Set your primary as active
184+
adif-mcp persona set-active ki7mt
185+
```
186+
187+
---
188+
189+
## Troubleshooting
190+
191+
### Keyring backend not found (headless Linux)
192+
193+
On servers or headless Linux systems without a desktop keyring, install the alternative backend:
194+
195+
```bash
196+
pip install keyrings.alt
197+
```
198+
199+
This uses an encrypted file-based keyring instead of GNOME Keyring or KWallet.
200+
201+
### "No credentials found" errors
202+
203+
Run `adif-mcp creds doctor` to see which providers are missing credentials. The fix is always:
204+
205+
```bash
206+
adif-mcp creds set PERSONA PROVIDER
207+
```
208+
209+
### Wrong username or password
210+
211+
Delete and re-set the credentials:
212+
213+
```bash
214+
adif-mcp creds delete ki7mt eqsl
215+
adif-mcp creds set ki7mt eqsl
216+
```
217+
218+
### Where are credentials stored?
219+
220+
| OS | Keyring Backend |
221+
|----|----------------|
222+
| macOS | Keychain Access |
223+
| Windows | Credential Manager |
224+
| Linux (desktop) | GNOME Keyring or KWallet |
225+
| Linux (headless) | `keyrings.alt` encrypted file |
226+
227+
Credentials are stored under the service name `adif_mcp` with the key format `persona:provider`. You can view them in your OS keyring manager, but the CLI is the easiest way to manage them.

‎docs/getting-started.md‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -26,25 +26,27 @@ All packages require **Python 3.10+**.
2626

2727
Servers that access your accounts use [adif-mcp](https://pypi.org/project/adif-mcp/) to store credentials securely in your OS keyring.
2828

29-
### Create a Persona
30-
31-
A persona is a named identity that holds your credentials:
32-
3329
```bash
3430
pip install adif-mcp
3531

36-
# Set up credentials for each service you use
37-
adif-mcp creds set --persona ki7mt --provider eqsl --password YOUR_PASSWORD
38-
adif-mcp creds set --persona ki7mt --provider qrz --password YOUR_PASSWORD
39-
adif-mcp creds set --persona ki7mt --provider lotw --password YOUR_PASSWORD
40-
adif-mcp creds set --persona ki7mt --provider hamqth --password YOUR_PASSWORD
32+
# Create a persona (your callsign identity)
33+
adif-mcp persona add --name ki7mt --callsign KI7MT --start 2020-01-01
4134

42-
# QRZ Logbook requires a separate API key
43-
adif-mcp creds set --persona ki7mt --provider qrz --api-key YOUR_API_KEY
35+
# Store credentials for each service (prompts interactively — never pass passwords on the command line)
36+
adif-mcp creds set ki7mt eqsl
37+
adif-mcp creds set ki7mt lotw
38+
adif-mcp creds set ki7mt qrz
39+
adif-mcp creds set ki7mt qrz_logbook
40+
adif-mcp creds set ki7mt hamqth
41+
42+
# Verify everything is wired up
43+
adif-mcp creds doctor
4444
```
4545

4646
Your credentials are stored in the OS keyring (macOS Keychain, Windows Credential Manager, or Linux Secret Service) — never in config files.
4747

48+
See the [Credential Setup Guide](credentials.md) for full details, per-server examples, and troubleshooting.
49+
4850
---
4951

5052
## MCP Client Configuration

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ extra:
6363
nav:
6464
- Home: index.md
6565
- Getting Started: getting-started.md
66+
- Credential Setup: credentials.md
6667
- Servers:
6768
- servers/index.md
6869
- Foundation:

0 commit comments

Comments
 (0)