Skip to content

Commit d00c620

Browse files
KI7MTclaude
KI7MT
and
claude
committed
Initial qso-graph.io documentation site
MkDocs Material site with 23 source files covering all 9 MCP packages (44 tools total). Green theme, dual palette, auto-deploy via GitHub Actions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
0 parents  commit d00c620

24 files changed

Lines changed: 1830 additions & 0 deletions

‎.github/workflows/deploy.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
name: Deploy MkDocs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
deploy:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
17+
- uses: actions/setup-python@v5
18+
with:
19+
python-version: '3.12'
20+
21+
- name: Install dependencies
22+
run: pip install -r requirements.txt
23+
24+
- name: Build and deploy
25+
run: mkdocs gh-deploy --force

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
site/
2+
__pycache__/
3+
.cache/
4+
*.pyc

‎CNAME‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
qso-graph.io

‎Makefile‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
SHELL := /bin/bash
2+
PYTHON ?= python3
3+
MKDOCS ?= mkdocs
4+
PORT ?= 8080
5+
6+
.PHONY: help install build serve clean distclean
7+
8+
help: ## Show this help
9+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
10+
awk 'BEGIN {FS = ":.*?## "}; {printf " %-14s %s\n", $$1, $$2}'
11+
12+
install: ## Install Python dependencies
13+
$(PYTHON) -m pip install -r requirements.txt
14+
15+
build: ## Build the static site into site/
16+
$(MKDOCS) build
17+
18+
serve: ## Start the dev server on PORT (default 8080)
19+
$(MKDOCS) serve --dev-addr localhost:$(PORT)
20+
21+
clean: ## Remove build artifacts
22+
rm -rf site/
23+
24+
distclean: clean ## Remove build artifacts and Python caches
25+
rm -rf __pycache__ .cache
26+
find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
27+
find . -type f -name '*.pyc' -delete 2>/dev/null || true

‎docs/CNAME‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
qso-graph.io

‎docs/about/contributing.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Contributing
2+
3+
## Reporting Issues
4+
5+
Found a bug or have a feature request? Open an issue on the relevant repository:
6+
7+
| Package | Issues |
8+
|---------|--------|
9+
| eqsl-mcp | [github.com/qso-graph/eqsl-mcp/issues](https://github.com/qso-graph/eqsl-mcp/issues) |
10+
| qrz-mcp | [github.com/qso-graph/qrz-mcp/issues](https://github.com/qso-graph/qrz-mcp/issues) |
11+
| clublog-mcp | [github.com/qso-graph/clublog-mcp/issues](https://github.com/qso-graph/clublog-mcp/issues) |
12+
| lotw-mcp | [github.com/qso-graph/lotw-mcp/issues](https://github.com/qso-graph/lotw-mcp/issues) |
13+
| hamqth-mcp | [github.com/qso-graph/hamqth-mcp/issues](https://github.com/qso-graph/hamqth-mcp/issues) |
14+
| pota-mcp | [github.com/qso-graph/pota-mcp/issues](https://github.com/qso-graph/pota-mcp/issues) |
15+
| sota-mcp | [github.com/qso-graph/sota-mcp/issues](https://github.com/qso-graph/sota-mcp/issues) |
16+
| solar-mcp | [github.com/qso-graph/solar-mcp/issues](https://github.com/qso-graph/solar-mcp/issues) |
17+
| wspr-mcp | [github.com/qso-graph/wspr-mcp/issues](https://github.com/qso-graph/wspr-mcp/issues) |
18+
| This documentation site | [github.com/qso-graph/qso-graph.github.io/issues](https://github.com/qso-graph/qso-graph.github.io/issues) |
19+
20+
---
21+
22+
## Pull Requests
23+
24+
1. Fork the repository
25+
2. Create a feature branch from `main`
26+
3. Make your changes
27+
4. Ensure all tests pass (`pytest`)
28+
5. Submit a pull request
29+
30+
### Code Style
31+
32+
- Python 3.10+ type hints
33+
- No `subprocess`, `os.system`, or `shell=True` (see [Security](../security.md))
34+
- All external URLs must be HTTPS
35+
- Error messages must not include user input values
36+
- Rate limiting on all external API calls
37+
38+
---
39+
40+
## Security Vulnerabilities
41+
42+
**Do NOT open public GitHub issues for security vulnerabilities.**
43+
44+
Report security issues privately:
45+
46+
- **Email**: [ki7mt@yahoo.com](mailto:ki7mt@yahoo.com)
47+
- **Subject**: `[SECURITY] qso-graph vulnerability report`
48+
49+
Include:
50+
- Affected package and version
51+
- Steps to reproduce
52+
- Potential impact
53+
54+
We will acknowledge receipt within 24 hours and provide a fix timeline.
55+
56+
---
57+
58+
## Development Setup
59+
60+
```bash
61+
# Clone any package
62+
git clone https://github.com/qso-graph/eqsl-mcp.git
63+
cd eqsl-mcp
64+
65+
# Create a development venv
66+
python3 -m venv .venv
67+
source .venv/bin/activate
68+
69+
# Install in editable mode with dev dependencies
70+
pip install -e ".[dev]"
71+
72+
# Run tests
73+
pytest
74+
75+
# Run in mock mode
76+
EQSL_MCP_MOCK=1 eqsl-mcp
77+
78+
# Test with MCP Inspector
79+
eqsl-mcp --transport streamable-http --port 8001
80+
```

‎docs/about/index.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# About qso-graph
2+
3+
## Mission
4+
5+
qso-graph connects AI assistants to ham radio services through the [Model Context Protocol](https://modelcontextprotocol.io/). Instead of switching between browser tabs, logging platforms, and propagation tools, operators can ask questions in natural language and get answers from their actual data.
6+
7+
"Do I have any new LoTW confirmations?" "What's the solar forecast?" "Is 3Y0J in the Club Log?" — these should be as easy to ask as they are to think.
8+
9+
---
10+
11+
## The Name
12+
13+
A **QSO** is a radio contact between two stations. **Graph** refers to the network of connections between operators, bands, modes, and propagation paths. qso-graph is the connective tissue between ham radio services and the tools operators actually use.
14+
15+
---
16+
17+
## Author
18+
19+
**Greg Beam, KI7MT** — Extra class amateur radio operator, software engineer, and builder of the [IONIS](https://ionis-ai.com/) HF propagation prediction system. 49,000+ QSOs across all HF bands. Based in Idaho.
20+
21+
qso-graph grew out of the IONIS project's need to integrate with ham radio services for validation and analysis. The MCP servers were designed to be useful on their own — you don't need IONIS to use qso-graph.
22+
23+
---
24+
25+
## Related Projects
26+
27+
- **[IONIS](https://ionis-ai.com/)** — Ionospheric Neural Inference System. Physics-constrained neural network for HF propagation prediction, trained on 14 billion amateur radio observations.
28+
- **[ionis-mcp](https://pypi.org/project/ionis-mcp/)** — MCP server for propagation analytics using IONIS datasets (175M+ signatures from WSPR, RBN, contests, and PSK Reporter).
29+
- **[ionis-jupyter](https://pypi.org/project/ionis-jupyter/)** — Jupyter notebooks for propagation research.
30+
- **[adif-mcp](https://pypi.org/project/adif-mcp/)** — Foundation library for ADIF parsing and credential management. Used by all authenticated qso-graph servers.
31+
32+
---
33+
34+
## License
35+
36+
All qso-graph packages are released under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html).
37+
38+
---
39+
40+
## Links
41+
42+
- **GitHub**: [github.com/qso-graph](https://github.com/qso-graph)
43+
- **Domains**: [qso-graph.io](https://qso-graph.io) · [qso-graph.org](https://qso-graph.org) · [qso-graph.com](https://qso-graph.com)

0 commit comments

Comments
 (0)