searxng-http-mcp 1.0.0__tar.gz

searxng_http_mcp-1.0.0/.claude/rules/architecture.md

@@ -0,0 +1,31 @@
+## Architecture
+
+```
+mcp_server/          # MCP server package
+  main.py            # Entry point (HTTP or stdio mode)
+  app.py             # Starlette ASGI app (MCP + auth + reverse proxy)
+  tools.py           # MCP tools (search, autocomplete, engine_info)
+  auth.py            # API key + Basic Auth middleware
+  proxy.py           # SearXNG reverse proxy
+  patch_settings.py  # SearXNG settings patcher
+tests/               # pytest + pytest-anyio
+plugins/             # Claude Code plugin (local + remote variants)
+```
+
+## Code Style
+
+- Python 3.14+, type annotations with `Annotated` + `Field`
+- Async throughout (`async def`, `httpx.AsyncClient`)
+- No comments unless explaining non-obvious "why"
+
+## Testing
+
+- `pytest-anyio` for async tests (`@pytest.mark.anyio`)
+- Mock `httpx.AsyncClient` for unit tests
+- `stdio_client` / `streamable_http_client` for transport integration tests
+- `plugins/local/` and `plugins/remote/` skills and agents must stay identical
+
+## Gotchas
+
+- `docs/superpowers/` is in `.gitignore` — local plugin skill files, not tracked in git
+- `mcp_server` is not installed as a package — tests need `PYTHONPATH` set to project root

searxng_http_mcp-1.0.0/.claude/rules/commands.md

@@ -0,0 +1,21 @@
+## Commands
+
+```bash
+# Install dependencies
+pip install "mcp[cli]" pytest pytest-anyio httpx pytest-cov pyyaml
+
+# Run tests
+pytest tests/ -v
+
+# Run single test file
+pytest tests/test_tools.py -v
+
+# Run with coverage
+pytest tests/ -v --cov=mcp_server --cov-report=term-missing --cov-fail-under=80
+
+# Start HTTP server (requires SearXNG on port 8080)
+python -m mcp_server.main
+
+# Start stdio server
+python -m mcp_server.main --stdio
+```

searxng_http_mcp-1.0.0/.claude/rules/workflow.md

@@ -0,0 +1,16 @@
+## Project Workflow
+
+- Branching: `dev` is the development branch, `main` is the release branch. All changes go through PRs.
+- PR rules: feature/fix branches → dev → main. PRs to main must come from dev only.
+- Copilot review flow: After PR to dev, wait for CI to pass, then confirm Copilot review is submitted (use `gh api repos/{owner}/{repo}/pulls/{number}/reviews` to verify `copilot-pull-request-reviewer[bot]` has posted a review — don't just check comment count). Fix feedback on the same branch, resolve addressed comments, then merge. Delete local branch after merge (remote branch is auto-deleted by GitHub).
+- CI: push triggers test.yml. PRs to main run policy checks only (source-branch verification + fork protections), no tests.
+- Rebase all local branches (feat/fix/docs/ci etc.) onto latest dev before PR (`git fetch origin && git rebase origin/dev`).
+- After push, wait for push-triggered test.yml CI to pass before creating PR.
+- Merge strategy: always use merge commit (GitHub: "Create a merge commit", CLI: `gh pr merge --merge`). Never use squash or rebase merge.
+- Commit style: Conventional Commits.
+- `.github/` directory is protected — fork PRs cannot modify it.
+- Review external PRs locally using `scripts/review-pr.sh` (runs tests in isolated Docker container). Never execute untrusted code directly on the host.
+- When waiting for CI/Copilot review, use Bash tool's `run_in_background` parameter to poll status (e.g., `gh run watch`). Don't block the conversation with sleep.
+- Copilot review comments must be actually fixed before resolving. Never batch-resolve without fixing.
+- Manage GitHub Rulesets via `gh api repos/{owner}/{repo}/rulesets` — no need for Web UI.
+- Reusable workflow status check names use the format `{caller-job} / {reusable-job}` (e.g., `call-test / test`). Keep this in mind when configuring required checks.

searxng_http_mcp-1.0.0/.claude-plugin/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "name": "searxng-http-mcp",
+  "owner": {
+    "name": "whw23"
+  },
+  "description": "SearXNG metasearch engine MCP server",
+  "plugins": [
+    {
+      "name": "searxng-http-mcp",
+      "source": "./plugins/local",
+      "description": "SearXNG MCP server (local Docker stdio) — zero-config, self-contained",
+      "version": "1.1.0",
+      "license": "MIT",
+      "keywords": ["search", "searxng", "web-search", "mcp", "local", "docker"]
+    },
+    {
+      "name": "searxng-http-mcp-remote",
+      "source": "./plugins/remote",
+      "description": "SearXNG MCP server (remote HTTP) — connect to a deployed instance",
+      "version": "1.1.0",
+      "license": "MIT",
+      "keywords": ["search", "searxng", "web-search", "mcp", "remote", "http"]
+    }
+  ]
+}

searxng_http_mcp-1.0.0/.dockerignore

@@ -0,0 +1,22 @@
+.git
+.github
+.venv
+.pytest_cache
+.playwright-mcp
+.claude
+.claude-plugin
+.vscode
+__pycache__
+tests
+plugins
+scripts/review-pr.sh
+docs
+assets
+*.md
+!README.md
+LICENSE
+.gitignore
+.dockerignore
+.mcp.json
+.coverage
+server.json

searxng_http_mcp-1.0.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    target-branch: "dev"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    target-branch: "dev"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    target-branch: "dev"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

searxng_http_mcp-1.0.0/.github/workflows/build.yml

@@ -0,0 +1,167 @@
+name: Build and Publish
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "17 3 * * *"
+
+permissions: read-all
+
+env:
+  IMAGE_NAME: ghcr.io/whw23/searxng-http-mcp
+  UPSTREAM_IMAGE: ghcr.io/searxng/searxng:latest
+
+jobs:
+  test:
+    uses: ./.github/workflows/reusable-test.yml
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+      security-events: write
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Check upstream image digest
+        id: upstream
+        run: |
+          docker pull $UPSTREAM_IMAGE
+          DIGEST=$(docker inspect --format='{{index .RepoDigests 0}}' $UPSTREAM_IMAGE)
+          echo "digest=$DIGEST" >> "$GITHUB_OUTPUT"
+
+          UPSTREAM_VERSION=$(docker inspect --format='{{range .Config.Env}}{{println .}}{{end}}' $UPSTREAM_IMAGE | grep -oP '__SEARXNG_VERSION=\K.*' || echo "unknown")
+          echo "version=$UPSTREAM_VERSION" >> "$GITHUB_OUTPUT"
+        env:
+          UPSTREAM_IMAGE: ${{ env.UPSTREAM_IMAGE }}
+
+      - name: Restore cached upstream digest
+        if: github.event_name == 'schedule'
+        id: cache
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
+        with:
+          path: /tmp/upstream-digest
+          key: upstream-digest-${{ steps.upstream.outputs.digest }}
+          restore-keys: upstream-digest-
+
+      - name: Check if upstream changed
+        if: github.event_name == 'schedule'
+        id: changed
+        run: |
+          if [ -f /tmp/upstream-digest ] && [ "$(cat /tmp/upstream-digest)" = "${{ steps.upstream.outputs.digest }}" ]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "Upstream unchanged, skipping build."
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Decide whether to build
+        id: decide
+        run: |
+          if [ "$EVENT" != "schedule" ] || [ "$SKIP" != "true" ]; then
+            echo "should_build=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_build=false" >> "$GITHUB_OUTPUT"
+          fi
+        env:
+          EVENT: ${{ github.event_name }}
+          SKIP: ${{ steps.changed.outputs.skip }}
+
+      - name: Save upstream digest
+        if: steps.decide.outputs.should_build == 'true'
+        run: echo "${{ steps.upstream.outputs.digest }}" > /tmp/upstream-digest
+
+      - name: Set up QEMU
+        if: steps.decide.outputs.should_build == 'true'
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4
+
+      - name: Set up Docker Buildx
+        if: steps.decide.outputs.should_build == 'true'
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4
+
+      - name: Login to GHCR
+        if: steps.decide.outputs.should_build == 'true'
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate tags
+        if: steps.decide.outputs.should_build == 'true'
+        id: tags
+        run: |
+          SHORT_SHA=$(echo "$GITHUB_SHA" | cut -c1-7)
+          UPSTREAM_VERSION="${{ steps.upstream.outputs.version }}"
+          FULL_TAG="${UPSTREAM_VERSION}-${SHORT_SHA}"
+          echo "full_tag=$FULL_TAG" >> "$GITHUB_OUTPUT"
+        env:
+          GITHUB_SHA: ${{ github.sha }}
+
+      - name: Build and push
+        if: steps.decide.outputs.should_build == 'true'
+        id: build
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: |
+            ${{ env.IMAGE_NAME }}:${{ steps.tags.outputs.full_tag }}
+            ${{ env.IMAGE_NAME }}:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Scan image for vulnerabilities
+        if: steps.decide.outputs.should_build == 'true'
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+        with:
+          image-ref: ${{ env.IMAGE_NAME }}@${{ steps.build.outputs.digest }}
+          format: sarif
+          output: trivy-results.sarif
+          severity: CRITICAL,HIGH
+
+      - name: Upload Trivy results to GitHub Security
+        if: steps.decide.outputs.should_build == 'true'
+        uses: github/codeql-action/upload-sarif@7fd177fa680c9881b53cdab4d346d32574c9f7f4 # v3
+        with:
+          sarif_file: trivy-results.sarif
+
+      - name: Install Cosign
+        if: steps.decide.outputs.should_build == 'true'
+        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+
+      - name: Sign container image
+        if: steps.decide.outputs.should_build == 'true'
+        run: |
+          cosign sign --yes "$IMAGE@$DIGEST"
+        env:
+          IMAGE: ${{ env.IMAGE_NAME }}
+          DIGEST: ${{ steps.build.outputs.digest }}
+
+      - name: Install mcp-publisher
+        if: steps.decide.outputs.should_build == 'true'
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz" | tar xz mcp-publisher
+
+      - name: Update server.json version
+        if: steps.decide.outputs.should_build == 'true'
+        run: |
+          VERSION="$(date -u +%Y).${{ github.run_number }}.0"
+          jq --arg v "$VERSION" '.version = $v' server.json > server.tmp && mv server.tmp server.json
+
+      - name: Authenticate to MCP Registry
+        if: steps.decide.outputs.should_build == 'true'
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish to MCP Registry
+        if: steps.decide.outputs.should_build == 'true'
+        run: ./mcp-publisher publish || echo "Publish failed (version may already exist), continuing."

searxng_http_mcp-1.0.0/.github/workflows/codeql.yml

@@ -0,0 +1,35 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [dev]
+  schedule:
+    - cron: "37 4 * * 1"
+
+permissions: read-all
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    strategy:
+      matrix:
+        language: [python]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@7fd177fa680c9881b53cdab4d346d32574c9f7f4 # v3
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@7fd177fa680c9881b53cdab4d346d32574c9f7f4 # v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@7fd177fa680c9881b53cdab4d346d32574c9f7f4 # v3

searxng_http_mcp-1.0.0/.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,33 @@
+name: Dependabot Auto-Merge
+
+on:
+  pull_request_target:
+    branches: [dev]
+
+permissions: read-all
+
+jobs:
+  auto-merge:
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Fetch Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@21025c705c08248db411dc16f3619e6b5f9ea21a # v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Approve and auto-merge patch/minor/security updates
+        if: >-
+          steps.metadata.outputs.update-type == 'version-update:semver-patch' ||
+          steps.metadata.outputs.update-type == 'version-update:semver-minor' ||
+          steps.metadata.outputs.update-type == 'security-update'
+        run: |
+          gh pr review "$PR_URL" --approve
+          gh pr merge "$PR_URL" --auto --merge
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

searxng_http_mcp-1.0.0/.github/workflows/reusable-test.yml

@@ -0,0 +1,66 @@
+name: Reusable Test
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 2
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.14"
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install "mcp[cli]" pytest pytest-anyio httpx pytest-cov pyyaml
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short --junitxml=test-results.xml --cov=mcp_server --cov-report=term-missing --cov-report=xml:coverage.xml --cov-fail-under=80
+
+      - name: Coverage summary
+        if: always()
+        run: |
+          if [ -f coverage.xml ]; then
+            echo "## Coverage Report" >> "$GITHUB_STEP_SUMMARY"
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo '```' >> "$GITHUB_STEP_SUMMARY"
+            python -m coverage report 2>/dev/null || echo "Coverage data not available"
+            echo '```' >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - name: Test report summary
+        if: always()
+        uses: test-summary/action@37b508cfee6d4d080eedd00b5bb240a6a784a6a5 # v2
+        with:
+          paths: test-results.xml
+
+      - name: Upload test artifacts
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: test-reports
+          path: |
+            test-results.xml
+            coverage.xml
+
+  consistency-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Check plugin consistency (local vs remote)
+        run: |
+          diff -r plugins/local/skills plugins/remote/skills || { echo "::error::Skills differ between local and remote plugins"; exit 1; }
+          diff -r plugins/local/agents plugins/remote/agents || { echo "::error::Agents differ between local and remote plugins"; exit 1; }
+          echo "Plugins are consistent."

searxng_http_mcp-1.0.0/.github/workflows/scorecard.yml

@@ -0,0 +1,34 @@
+name: OpenSSF Scorecard
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "23 4 * * 1"
+
+permissions: read-all
+
+jobs:
+  analysis:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+
+      - name: Run Scorecard
+        uses: ossf/scorecard-action@f49aabe0b5af0936a0987cfb85d86b75731b0186 # v2.4.1
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: Upload SARIF
+        uses: github/codeql-action/upload-sarif@7fd177fa680c9881b53cdab4d346d32574c9f7f4 # v3
+        with:
+          sarif_file: results.sarif

searxng_http_mcp-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,110 @@
+name: Test
+
+on:
+  push:
+    branches-ignore: [main]
+  pull_request:
+    branches: [dev, main]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  check-pr-source:
+    if: github.event_name == 'pull_request' && github.base_ref == 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify PRs to main come from upstream dev
+        run: |
+          if [ "$IS_FORK" = "true" ]; then
+            echo "::error::Fork PRs cannot target main. Please PR to dev instead."
+            exit 1
+          fi
+          if [ "$HEAD_REF" != "dev" ]; then
+            echo "::error::PRs to main must come from the dev branch, got '$HEAD_REF'"
+            exit 1
+          fi
+        env:
+          HEAD_REF: ${{ github.head_ref }}
+          IS_FORK: ${{ github.event.pull_request.head.repo.fork }}
+
+  check-protected-files:
+    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true
+    runs-on: ubuntu-latest
+    steps:
+      - name: Block fork PRs that modify .github/
+        run: |
+          CHANGED=$(gh pr diff "$PR_NUMBER" --name-only --repo "$REPO")
+          PROTECTED=$(echo "$CHANGED" | grep -E '^\.github/' || true)
+          if [ -n "$PROTECTED" ]; then
+            echo "::error::Fork PRs cannot modify files in .github/. Changed: $PROTECTED"
+            exit 1
+          fi
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+
+  check-changes:
+    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.base_ref == 'dev')
+    runs-on: ubuntu-latest
+    outputs:
+      skip: ${{ steps.changes.outputs.skip }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+
+      - name: Check for docs-only changes
+        id: changes
+        run: |
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            FILES=$(gh pr diff "$PR_NUMBER" --name-only --repo "$REPO")
+          else
+            if [ "$BEFORE_SHA" = "0000000000000000000000000000000000000000" ]; then
+              FILES=$(git diff --name-only HEAD~1)
+            else
+              FILES=$(git diff --name-only "$BEFORE_SHA".."$AFTER_SHA" 2>/dev/null || git diff --name-only HEAD~1)
+            fi
+          fi
+          NON_DOCS=$(echo "$FILES" | grep -v -E '(^[^/]*\.md$|^docs/|^assets/|^LICENSE$)' || true)
+          if [ -z "$NON_DOCS" ]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "Only docs changed, skipping tests."
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EVENT_NAME: ${{ github.event_name }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          BEFORE_SHA: ${{ github.event.before }}
+          AFTER_SHA: ${{ github.sha }}
+
+  call-test:
+    needs: check-changes
+    if: needs.check-changes.outputs.skip != 'true'
+    uses: ./.github/workflows/reusable-test.yml
+
+  test-gate:
+    needs: [check-changes, call-test]
+    if: always() && (github.event_name == 'push' || (github.event_name == 'pull_request' && github.base_ref == 'dev'))
+    runs-on: ubuntu-latest
+    steps:
+      - name: Evaluate test results
+        run: |
+          if [ "$SKIP" = "true" ]; then
+            echo "Tests skipped (docs-only changes)"
+            exit 0
+          fi
+          if [ "$RESULT" != "success" ]; then
+            echo "Tests failed or were cancelled"
+            exit 1
+          fi
+          echo "All tests passed"
+        env:
+          SKIP: ${{ needs.check-changes.outputs.skip }}
+          RESULT: ${{ needs.call-test.result }}

searxng_http_mcp-1.0.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docs (plugin caches)
+docs/superpowers/
+
+# Playwright MCP
+.playwright-mcp/
+
+# Test / Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.superpowers/

searxng_http_mcp-1.0.0/CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+Rules are auto-discovered from `.claude/rules/`.