omiss-mcp 0.1.0__tar.gz

omiss_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+# Cancel superseded runs on the same ref (push or PR) so we don't waste
+# minutes when commits land in rapid succession.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: pytest (${{ matrix.os }}, ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            python-version: "3.10"
+          - os: windows-latest
+            python-version: "3.13"
+          - os: macos-latest
+            python-version: "3.13"
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install (locked)
+        run: uv sync --group dev --frozen
+
+      - name: Unit tests
+        run: uv run pytest tests --ignore=tests/test_security.py -v
+
+      - name: Security tests
+        run: uv run pytest tests/test_security.py -v
+
+  ci-all-green:
+    name: ci-all-green
+    needs: [test]
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Verify required jobs all succeeded
+        run: |
+          if [[ "${{ needs.test.result }}" != "success" ]]; then
+            echo "FAIL: test matrix did not all succeed (result=${{ needs.test.result }})"
+            exit 1
+          fi
+          echo "All required CI jobs passed."

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

@@ -0,0 +1,189 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  security:
+    name: Security gates
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # PyPI publishes pyproject's version; the Registry publishes the tag's.
+      # They must be the same, or the two would disagree about what was released.
+      - name: Tag matches pyproject.toml version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION="$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)"
+          echo "tag=${TAG_VERSION} pyproject=${PKG_VERSION}"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "FAIL: tag v${TAG_VERSION} does not match pyproject.toml version ${PKG_VERSION}"
+            exit 1
+          fi
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install test dependencies
+        run: pip install -e ".[test]" pip-audit
+
+      - name: Run security test suite
+        run: python -m pytest tests/test_security.py -v
+
+      - name: Audit dependencies for vulnerabilities
+        run: pip-audit --strict --desc 2>&1 || true
+
+      - name: Grep check — no subprocess/shell
+        run: |
+          if grep -rn 'subprocess\.\|os\.system\|shell=True' src/; then
+            echo "FAIL: subprocess/shell found in source"
+            exit 1
+          fi
+
+      - name: Grep check — no plaintext http://
+        run: |
+          if grep -rn 'http://' src/ | grep -v 'localhost\|127\.0\.0\.1\|::1'; then
+            echo "FAIL: non-HTTPS URL found in source"
+            exit 1
+          fi
+
+      - name: Grep check — no credential logging
+        run: |
+          if grep -rn -i 'print.*password\|print.*api_key\|logging.*password\|logging.*api_key' src/; then
+            echo "FAIL: credential logging found in source"
+            exit 1
+          fi
+
+  publish:
+    name: Build and publish to PyPI
+    needs: security
+    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
+
+  # ---------------------------------------------------------------------------
+  # Registry-publish — pushes server.json to the Official MCP Registry after
+  # PyPI publish succeeds, so discovery surfaces stay in sync with PyPI.
+  # Canonical template: https://github.com/qso-graph/.github/blob/main/TEMPLATES.md
+  # ---------------------------------------------------------------------------
+  registry-publish:
+    name: Publish to MCP Registry
+    needs: publish  # waits for PyPI publish to succeed
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # GitHub OIDC
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install jq (server.json bump)
+        run: sudo apt-get update && sudo apt-get install -y jq
+
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+          ./mcp-publisher --help > /dev/null  # smoke test
+
+      - name: Bump server.json to tag version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          echo "Setting server.json to ${TAG_VERSION}"
+          jq --arg v "$TAG_VERSION" \
+             '.version = $v | .packages[0].version = $v' \
+             server.json > /tmp/server.json
+          mv /tmp/server.json server.json
+          cat server.json
+
+      # The Registry checks PyPI itself and refuses a version PyPI isn't
+      # serving yet, which can lag the upload by a minute or more.
+      - name: Wait until PyPI serves this version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PACKAGE="$(jq -r '.packages[0].identifier' server.json)"
+          for i in $(seq 1 40); do
+            if curl -fsS "https://pypi.org/pypi/${PACKAGE}/${TAG_VERSION}/json" > /dev/null; then
+              echo "PyPI serves ${PACKAGE} ${TAG_VERSION}"
+              exit 0
+            fi
+            echo "attempt ${i}: PyPI doesn't serve ${PACKAGE} ${TAG_VERSION} yet"
+            sleep 15
+          done
+          echo "FAIL: PyPI never served ${PACKAGE} ${TAG_VERSION}"
+          exit 1
+
+      - name: Authenticate to MCP Registry (GitHub OIDC)
+        run: ./mcp-publisher login github-oidc
+
+      # Retries ride out the Registry's own transient failures. Before each
+      # retry, check whether an earlier attempt landed despite the error.
+      - name: Publish to MCP Registry
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          NAME="$(jq -r '.name' server.json)"
+          REGISTRY="https://registry.modelcontextprotocol.io/v0/servers?search=${NAME}&version=latest"
+          for i in 1 2 3 4 5; do
+            if ./mcp-publisher publish; then
+              exit 0
+            fi
+            echo "attempt ${i} failed; retrying in $((i * 30)) s"
+            sleep $((i * 30))
+            REG="$(curl -fsS "$REGISTRY" | jq -r --arg n "$NAME" '[.servers[] | select(.server.name == $n) | .server.version][0] // empty' || true)"
+            if [ "$REG" = "$TAG_VERSION" ]; then
+              echo "The Registry already has ${NAME} ${TAG_VERSION}; an earlier attempt landed"
+              exit 0
+            fi
+          done
+          echo "FAIL: the MCP Registry refused the publish 5 times"
+          exit 1
+
+  # ---------------------------------------------------------------------------
+  # Verify — a release is complete only when PyPI AND the MCP Registry both
+  # serve the tagged version. If either doesn't within 10 minutes, this run
+  # fails: a green run means published everywhere, a red one means not done.
+  # ---------------------------------------------------------------------------
+  verify:
+    name: Verify PyPI and MCP Registry
+    needs: registry-publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: PyPI and Registry serve the tagged version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PACKAGE="$(jq -r '.packages[0].identifier' server.json)"
+          NAME="$(jq -r '.name' server.json)"
+          REGISTRY="https://registry.modelcontextprotocol.io/v0/servers?search=${NAME}&version=latest"
+          for i in $(seq 1 40); do
+            PYPI="$(curl -fsS "https://pypi.org/pypi/${PACKAGE}/json" | jq -r '.info.version' || true)"
+            REG="$(curl -fsS "$REGISTRY" | jq -r --arg n "$NAME" '[.servers[] | select(.server.name == $n) | .server.version][0] // empty' || true)"
+            echo "attempt ${i}: PyPI=${PYPI:-none} Registry=${REG:-none} want=${TAG_VERSION}"
+            if [ "$PYPI" = "$TAG_VERSION" ] && [ "$REG" = "$TAG_VERSION" ]; then
+              echo "Published everywhere: ${PACKAGE} ${TAG_VERSION} on PyPI and ${NAME} ${TAG_VERSION} in the MCP Registry"
+              exit 0
+            fi
+            sleep 15
+          done
+          echo "FAIL: release incomplete. PyPI=${PYPI:-none} Registry=${REG:-none}, expected ${TAG_VERSION}"
+          exit 1

omiss_mcp-0.1.0/.gitignore

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

omiss_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 (2026-09-28)
+
+- Tools for OMISS's public pages: the net schedule and holidays, member lookup, check-in history,
+  one past net's check-ins, the Statehood schedule, officers, awards, award rules, award recipients
+  and net statistics; OMISS nets on the air from NetLogger; plus `get_version_info`.
+- Records follow `schema/contract.schema.json` (0.1); check-in fields share netlogger-mcp's names.
+- omiss.net is read one request at a time, at most one every 2 seconds, shared by every copy for
+  the user account (a locked state file). Answers cached; a stale answer stands in when the site is
+  down; a 429 or 503 stops all requests for the back-off.
+- Every value is checked before it is sent; award IDs must come from the site's list. No free text
+  ever reaches omiss.net.
+- Postal addresses and email addresses are never returned. Members are looked up one at a time.
+- A page whose layout has changed is reported as changed, not guessed at.
+- `OmissSource` usable as a plain Python library.

omiss_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>

omiss_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.5
+Name: omiss-mcp
+Version: 0.1.0
+Summary: MCP server for OMISS: net schedule, nets on the air, members, check-in history, Statehood, officers and awards
+Project-URL: Homepage, https://qso-graph.io
+Project-URL: Repository, https://github.com/qso-graph/omiss-mcp
+Project-URL: Issues, https://github.com/qso-graph/omiss-mcp/issues
+Author-email: "Greg Beam, KI7MT" <ki7mt@yahoo.com>
+License: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: amateur-radio,awards,check-ins,ham-radio,mcp,model-context-protocol,nets,omiss,sideband
+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: fastmcp>=3.0
+Requires-Dist: netlogger-mcp>=0.1.1
+Provides-Extra: test
+Requires-Dist: jsonschema; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.qso-graph/omiss-mcp -->
+# omiss-mcp
+
+[![PyPI](https://img.shields.io/pypi/v/omiss-mcp?label=PyPI&color=blue)](https://pypi.org/project/omiss-mcp/)
+[![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0%2Fservers%3Fsearch%3Dio.github.qso-graph%2Fomiss-mcp%26version%3Dlatest&query=%24.servers%5B0%5D.server.version&label=MCP%20Registry&color=blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.qso-graph/omiss-mcp&version=latest)
+
+MCP server for [OMISS](https://www.omiss.net/), the Old Man International Sideband Society: the net schedule, OMISS nets on the air now, member lookup, past nets and who checked in, the Statehood schedule, officers, awards and net statistics, through any MCP-compatible AI assistant.
+
+Data from omiss.net's public pages; nets on the air from NetLogger. Part of the [qso-graph](https://qso-graph.io/) project. **No login or API key needed.**
+
+## Install
+
+```bash
+uvx omiss-mcp            # run it; nothing to install
+pip install omiss-mcp    # or install it into your own environment
+```
+
+## Tools
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `omiss_net_schedule` | Every net's band, UTC time, frequency, days and band coordinator; holiday dates | — |
+| `omiss_nets_on_air` | OMISS nets on the air now, from NetLogger | — |
+| `omiss_member_lookup` | One member: OM number, call, name, status, grid, state, county, last check-in | callsign or om_number |
+| `omiss_checkin_history` | Past nets, newest first, optionally only a member's, a band's or a date's | callsign, om_number, band, date, net_control |
+| `omiss_net_checkins` | One past net: net control, relays, notes, and the check-in list | net_id |
+| `omiss_statehood_schedule` | 40m net dates and their free-call states, and the next one | — |
+| `omiss_officers` | Officers, band coordinators, committees, appointees, past presidents | — |
+| `omiss_awards` | The awards, with the IDs the other award tools take | — |
+| `omiss_award_rules` | An award's rules, or every award's summary | award_id |
+| `omiss_award_recipients` | Who holds an award, newest first, or check one member | award_id, callsign, om_number |
+| `omiss_net_statistics` | Nets per band, last net per band, top check-ins and net controls, last check-in by state | state, top |
+| `omiss_set_callsign` | Save your callsign, for `omiss_nets_on_air` (asked once) | callsign |
+| `get_version_info` | Service version + upstream spec version (fleet identity attestation) | — |
+
+## What is OMISS?
+
+OMISS is an amateur-radio society that runs SSB nets on HF, from 10 to 160 meters, every day of the week. Members exchange OM numbers on the nets and work toward the society's awards. Its website publishes the net schedule, the member roster, check-in history for every net, and the award rules and recipients.
+
+## Your Callsign
+
+Only `omiss_nets_on_air` needs it: it asks NetLogger, which is told which station is asking. On first use the assistant asks for your callsign and saves it. You're asked once. The other tools don't need it.
+
+## Good Neighbour Policy
+
+omiss.net is a volunteer-run club website, not an API. We read it gently:
+
+| Measure | Detail |
+|---------|--------|
+| **One request at a time** | At most one request every 2 seconds, shared by every copy you run (Claude Desktop, Claude Code, a script) through a locked file in your settings folder. |
+| **Response caching** | Schedule, officers, Statehood, members and award recipients 24 hours; awards and rules 7 days; history and statistics 1 hour. |
+| **Stale answers over errors** | When the site is down or busy, the last answer comes back with its age rather than an error. |
+| **Back-off** | A "too many requests" or "unavailable" answer stops all requests for at least a minute, longer if the site asks. |
+| **Request timeout** | 20-second timeout. |
+| **User-Agent header** | Every request names this project, so the site's operators can see who is asking. |
+| **NetLogger** | `omiss_nets_on_air` keeps to NetLogger's call limits, shared with [netlogger-mcp](https://github.com/qso-graph/netlogger-mcp) if you run it too. |
+
+## Security and Privacy
+
+- **Every value is checked before it is sent**: callsigns, OM numbers, bands from a fixed list, `YYYY`, `YYYY-MM` or `YYYY-MM-DD` dates, numeric net IDs, and award IDs from the site's own list. Free text is never sent to omiss.net.
+- **No postal addresses or email addresses are ever returned**, even where a page prints one.
+- **Members are looked up one at a time**, by callsign or OM number. There's no search by state, county or grid, and no roster download.
+
+## Quick Start
+
+### Configure your MCP client
+
+omiss-mcp works with any MCP-compatible client. Add the server config and restart. The tools appear automatically.
+
+#### Claude Desktop
+
+Add to `claude_desktop_config.json` (`~/Library/Application Support/Claude/` on macOS, `%APPDATA%\Claude\` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "omiss": {
+      "command": "uvx",
+      "args": ["omiss-mcp"]
+    }
+  }
+}
+```
+
+#### Claude Code
+
+Add to `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "omiss": {
+      "command": "uvx",
+      "args": ["omiss-mcp"]
+    }
+  }
+}
+```
+
+#### ChatGPT Desktop
+
+```json
+{
+  "mcpServers": {
+    "omiss": {
+      "command": "uvx",
+      "args": ["omiss-mcp"]
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "omiss": {
+      "command": "uvx",
+      "args": ["omiss-mcp"]
+    }
+  }
+}
+```
+
+#### VS Code / GitHub Copilot
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "omiss": {
+      "command": "uvx",
+      "args": ["omiss-mcp"]
+    }
+  }
+}
+```
+
+#### Gemini CLI
+
+Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "omiss": {
+      "command": "uvx",
+      "args": ["omiss-mcp"]
+    }
+  }
+}
+```
+
+Installed with pip instead? Use `"command": "omiss-mcp"` in any config above.
+
+### Ask questions
+
+> "When is the OMISS 40m net, and on what frequency?"
+
+> "Is KI7MT an OMISS member? What's their OM number?"
+
+> "Which OMISS nets are on the air right now?"
+
+> "Which nets did OM 7212 check in to this year?"
+
+> "Who checked in to last night's 80m net?"
+
+> "What are the free-call states on the next 40m Statehood net?"
+
+> "What does the Alphabet Soup award require, and have I earned it?"
+
+> "Who ran the most OMISS nets as net control in the last 90 days?"
+
+## As a Python Library
+
+The same code works without an AI, with the same spacing and cache:
+
+```python
+from omiss_mcp.omiss import OmissSource
+
+om = OmissSource()
+me = om.member_lookup(callsign="KI7MT")["members"][0]
+for net in om.checkin_history(om_number_=me["om_number"], date_="2026")["nets"]:
+    print(net["time"], net["name"], net["checkin_count"])
+```
+
+Apps can name themselves, using ADIF's `PROGRAMID` and `PROGRAMVERSION`: `OmissSource(program_id="MyLogger", program_version="1.0")`.
+
+## Testing Without Network
+
+```bash
+OMISS_MCP_MOCK=1 omiss-mcp
+```
+
+## MCP Inspector
+
+```bash
+omiss-mcp --transport streamable-http --port 8015
+```
+
+## Development
+
+```bash
+git clone https://github.com/qso-graph/omiss-mcp.git
+cd omiss-mcp
+uv sync --group dev
+uv run pytest
+```
+
+## License
+
+GPL-3.0-or-later