darc-dok-mcp 0.1.0__tar.gz

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

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main, develop]
+  push:
+    branches: [main, develop]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # main takes a release PR from develop, or a security branch, and nothing else:
+  # merging into main publishes. Required on main by its branch protection.
+  release-source:
+    name: Release PR source
+    if: github.event_name == 'pull_request' && github.base_ref == 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          case "${{ github.head_ref }}" in
+            develop|security/*) echo "ok: ${{ github.head_ref }} -> main" ;;
+            *) echo "main takes a release PR from develop, or a security/ branch"; exit 1 ;;
+          esac
+
+  test:
+    name: pytest (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "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
+
+  sources:
+    name: sources (download, then check against them)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install (locked)
+        run: uv sync --group dev --frozen
+
+      - name: Download the sources (owner's documents, checked against their SHA-256)
+        run: uv run python scripts/fetch_published.py
+
+      - name: Tests against the sources (AD1C and ARRL fetched by the tests)
+        run: uv run pytest tests --live --ignore=tests/test_security.py -v
+
+  ci-all-green:
+    name: ci-all-green
+    needs: [test, sources]
+    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
+          if [[ "${{ needs.sources.result }}" != "success" ]]; then
+            echo "FAIL: checks against the sources did not succeed (result=${{ needs.sources.result }})"
+            exit 1
+          fi
+          echo "All required CI jobs passed."

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

@@ -0,0 +1,246 @@
+name: Publish to PyPI
+
+# The release flow (qso-graph/.github TEMPLATES.md): work lands on `develop`; a release is a
+# PR from `develop` into `main`, and merging it publishes. `main` is always the released code.
+on:
+  push:
+    branches: [ main ]
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  security:
+    name: Security gates
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      # main changes only by a release PR, so main's version must be new. PyPI publishes
+      # pyproject's version and the Registry server.json's, so they must agree too.
+      # Computed once; every later job uses this value (needs.security.outputs.version).
+      # The gate fails closed: anything it cannot confirm stops the release.
+      - name: The version on main is new and consistent
+        id: version
+        run: |
+          VERSION="$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)"
+          PACKAGE="$(jq -r '.packages[0].identifier' server.json)"
+          echo "pyproject=${VERSION} server.json=$(jq -r '.version' server.json)/$(jq -r '.packages[0].version' server.json)"
+          if [ "$(jq -r '.version' server.json)" != "$VERSION" ] || [ "$(jq -r '.packages[0].version' server.json)" != "$VERSION" ]; then
+            echo "FAIL: server.json does not match pyproject.toml version ${VERSION}"
+            exit 1
+          fi
+          # Only a 404 means "not published yet"; unreachable or 5xx is not a yes.
+          CODE="$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/${PACKAGE}/${VERSION}/json")"
+          case "$CODE" in
+            404) echo "PyPI: ${PACKAGE} ${VERSION} is new" ;;
+            200) echo "FAIL: ${PACKAGE} ${VERSION} is already on PyPI. main changes only by a release PR with a new version."; exit 1 ;;
+            *)   echo "FAIL: PyPI returned ${CODE}; cannot confirm ${VERSION} is new"; exit 1 ;;
+          esac
+          # git ls-remote --exit-code: 2 means no such tag; anything else (0, 128) stops.
+          set +e
+          git ls-remote --exit-code --tags origin "refs/tags/v${VERSION}" > /dev/null
+          RC=$?
+          set -e
+          case "$RC" in
+            2) echo "tag v${VERSION} does not exist yet" ;;
+            0) echo "FAIL: tag v${VERSION} already exists"; exit 1 ;;
+            *) echo "FAIL: could not check tags (git ls-remote exited ${RC})"; exit 1 ;;
+          esac
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install test dependencies
+        run: pip install pytest pip-audit
+
+      - name: Run security test suite
+        run: python -m pytest tests/test_security.py -v
+
+      - name: Audit dependencies for vulnerabilities
+        # Audits this package's declared dependencies, and can fail: a known CVE stops the release.
+        # A finding with no fix yet is excepted only explicitly: --ignore-vuln ID, with a reason and date.
+        run: pip-audit --strict --desc on .
+
+      - 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: [security, 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: Set server.json to the released version
+        run: |
+          VERSION="${{ needs.security.outputs.version }}"
+          echo "Setting server.json to ${VERSION}"
+          jq --arg v "$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: |
+          VERSION="${{ needs.security.outputs.version }}"
+          PACKAGE="$(jq -r '.packages[0].identifier' server.json)"
+          for i in $(seq 1 40); do
+            if curl -fsS "https://pypi.org/pypi/${PACKAGE}/${VERSION}/json" > /dev/null; then
+              echo "PyPI serves ${PACKAGE} ${VERSION}"
+              exit 0
+            fi
+            echo "attempt ${i}: PyPI doesn't serve ${PACKAGE} ${VERSION} yet"
+            sleep 15
+          done
+          echo "FAIL: PyPI never served ${PACKAGE} ${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: |
+          VERSION="${{ needs.security.outputs.version }}"
+          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" = "$VERSION" ]; then
+              echo "The Registry already has ${NAME} ${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: [security, registry-publish]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: PyPI and Registry serve the released version
+        run: |
+          VERSION="${{ needs.security.outputs.version }}"
+          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=${VERSION}"
+            if [ "$PYPI" = "$VERSION" ] && [ "$REG" = "$VERSION" ]; then
+              echo "Published everywhere: ${PACKAGE} ${VERSION} on PyPI and ${NAME} ${VERSION} in the MCP Registry"
+              exit 0
+            fi
+            sleep 15
+          done
+          echo "FAIL: release incomplete. PyPI=${PYPI:-none} Registry=${REG:-none}, expected ${VERSION}"
+          exit 1
+
+  # ---------------------------------------------------------------------------
+  # Tag the release, once it is published everywhere. The tag marks the commit on
+  # main that was released; nothing is triggered by it. If this job fails after a
+  # green verify, the release IS published: re-running this job is safe.
+  # ---------------------------------------------------------------------------
+  tag:
+    name: Tag the release
+    needs: [security, verify]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Create and push vX.Y.Z
+        run: |
+          VERSION="${{ needs.security.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "v${VERSION}" -m "${GITHUB_REPOSITORY#*/} ${VERSION}" "$GITHUB_SHA"
+          git push origin "v${VERSION}"

darc_dok_mcp-0.1.0/.gitignore

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

darc_dok_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to `darc-dok-mcp` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-10-06
+
+- First release: DARC's DOK lists, as published and credited, with the shared QG Reference tools
+  (`source_info`, `lookup`, `search`, `codes_for`, `valid_on`) and `get_version_info`.