mcpgawk 0.1.2__tar.gz → 0.1.4__tar.gz

{mcpgawk-0.1.2 → mcpgawk-0.1.4}/.github/workflows/ci.yml

@@ -36,3 +36,18 @@ jobs:
           python -m venv /tmp/smoke
           /tmp/smoke/bin/pip install dist/*.whl
           /tmp/smoke/bin/mcpgawk --help
+
+  version-consistency:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: CLI (pyproject.toml) and VS Code extension (package.json) versions must match
+        run: |
+          PY_VERSION=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          EXT_VERSION=$(node -p "require('./editors/vscode/package.json').version")
+          echo "pyproject.toml: $PY_VERSION"
+          echo "editors/vscode/package.json: $EXT_VERSION"
+          if [ "$PY_VERSION" != "$EXT_VERSION" ]; then
+            echo "::error::Version mismatch — CLI is $PY_VERSION but the VS Code extension is $EXT_VERSION. Bump editors/vscode/package.json (and its CHANGELOG.md) alongside every pyproject.toml release."
+            exit 1
+          fi

mcpgawk-0.1.4/.github/workflows/mcpgawk-gate-selftest.yml

@@ -0,0 +1,20 @@
+name: MCP hygiene gate (self-test)
+
+# Dogfoods the mcpgawk Action against a real open server, so the marketplace
+# listing has a live, passing example.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: MCP hygiene gate
+        uses: ./
+        with:
+          stdio: 'npx -y @modelcontextprotocol/server-filesystem /tmp'
+          max-tokens: 5000
+          fail-on-flagged: true

mcpgawk-0.1.4/.github/workflows/publish-openvsx.yml

@@ -0,0 +1,38 @@
+name: Publish VS Code extension (Open VSX)
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "editors/vscode/package.json"
+  workflow_dispatch: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: editors/vscode
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Fail loudly if the Open VSX token isn't configured
+        run: |
+          if [ -z "${{ secrets.OVSX_PAT }}" ]; then
+            echo "::error::OVSX_PAT secret is not set — add it under repo Settings > Secrets before this can publish."
+            exit 1
+          fi
+
+      - run: npm install -g @vscode/vsce ovsx
+
+      - name: Package
+        run: vsce package --no-dependencies
+
+      - name: Publish to Open VSX
+        env:
+          OVSX_PAT: ${{ secrets.OVSX_PAT }}
+        run: ovsx publish *.vsix -p "$OVSX_PAT"

mcpgawk-0.1.4/.github/workflows/publish-pypi.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "pyproject.toml"
+  workflow_dispatch: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Fail loudly if the PyPI token isn't configured
+        run: |
+          if [ -z "${{ secrets.PYPI_API_TOKEN }}" ]; then
+            echo "::error::PYPI_API_TOKEN secret is not set — add it under repo Settings > Secrets before this can publish."
+            exit 1
+          fi
+
+      - name: Skip if this version is already published (re-running main shouldn't re-publish)
+        run: |
+          LOCAL=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          LIVE=$(python -c "import json,urllib.request; print(json.load(urllib.request.urlopen('https://pypi.org/pypi/mcpgawk/json'))['info']['version'])" 2>/dev/null || echo "none")
+          echo "local=$LOCAL live=$LIVE"
+          echo "LOCAL_VERSION=$LOCAL" >> "$GITHUB_ENV"
+          if [ "$LOCAL" = "$LIVE" ]; then
+            echo "Already published — skipping."
+            echo "SKIP=1" >> "$GITHUB_ENV"
+          fi
+
+      - run: python -m pip install --upgrade pip build
+        if: env.SKIP != '1'
+
+      - run: python -m build
+        if: env.SKIP != '1'
+
+      - name: Publish to PyPI
+        if: env.SKIP != '1'
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          python -m pip install twine
+          twine upload dist/*

mcpgawk-0.1.4/.gitignore

@@ -0,0 +1,39 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+
+# dev-only QA harness
+assets/brand/_qa.html
+editors/vscode/*.vsix
+editors/vscode/node_modules/
+.vercel
+
+# ===== NEVER PUBLISH — private strategy, paid product, business/internal =====
+# Belt-and-braces guard: even if one of these is accidentally copied into this
+# public checkout, git will not track it. Primary protection is that these live
+# only in the private repo (~/devtools/mcpgawk, which has NO remote).
+HANDOFF.md
+# private strategy / research / business docs
+docs/spec/
+docs/PLATFORM-AND-FACTORY.md
+docs/foundational-decisions.md
+docs/track-v-verdict-strategy.md
+docs/platform-system-design.md
+docs/architecture-convergence.md
+docs/functional-spec.md
+docs/research-*.md
+docs/strategy-*.md
+docs/*-audit*.md
+docs/adversarial-review-prompt.md
+docs/vendor-outreach-*.md
+# the PAID platform code (verify / monitor / enforce / forge) — never in the free repo
+src/gawk_platform/
+tests/test_platform_smoke.py
+tests/test_forge_smoke.py
+# third-party study clones (Apache-2.0) — never vendored/published
+reference/

mcpgawk-0.1.4/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to mcpgawk. Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](https://semver.org/).
+
+## [0.1.4] — 2026-07-20
+
+### Added
+- `--login`: scan a remote MCP server that requires OAuth. Opens the browser, signs in once via the
+  server's own OAuth flow, and scans it — the token is stored locally (`~/.gawk/oauth`) and never
+  leaves your machine.
+- Dynamic tool-dispatch detection: flags servers that hide a larger real tool catalog behind a
+  meta-tool (the Sentry / Docker mcp-gateway shape). A passive scan structurally can't see the hidden
+  tools, so this says "this scan is incomplete" rather than letting a clean-looking result be mistaken
+  for a clean server.
+
+### Changed / Fixed
+- A probe that errors (unreachable host, wrong URL, an HTML docs page that isn't an MCP endpoint,
+  a timeout) can no longer render as CLEAN — failures are now typed, not inferred from message text.
+- Remote (`--http`/`--sse`) scans fail fast (~20s) instead of hanging up to 90s on a non-MCP URL;
+  local stdio servers keep the generous cold-start budget.
+- Heuristic signals are labelled by what they are — dynamic-dispatch, tool-name shadowing and
+  server-card mismatch are no longer all reported as "possible prompt-injection".
+- Version is single-sourced from the installed package metadata (no more hand-maintained literal that
+  could go stale).
+
+## [0.1.3] — 2026-07-12
+
+### Added
+- Report now covers 5 axes: cost (+ top-3 heaviest tools), trust surface (% write, % exfil-capable,
+  destructive-declared count), annotation completeness (score — was computed but never surfaced),
+  coverage (prompts/resources, previously `--json`-only), and bounded signals (unchanged).
+- `--verbose` — full per-tool table in CLI text output (previously only the write/exfil-flagged subset
+  was shown; the full list existed only via `--json`).
+- `--supply-chain` (opt-in) — checks the launched package against the public npm registry / PyPI JSON
+  API for deprecation (npm) / yanked (PyPI, PEP 592) status. Makes a real network call — only the package
+  name and version are sent, never the tool inventory. Off by default.
+- `--oauth-scopes` (opt-in) — locally decodes a supplied `Authorization: Bearer <jwt>` header's `scope`/
+  `scp` claim. No network call; the signature is not verified (reading a declared claim, not
+  authenticating). Opaque (non-JWT) tokens are reported as not locally inspectable, never guessed at.
+
+### Changed
+- `x-mcpgawk` label schema gains `top_heavy_tools`, `trust_surface`, `annotation_completeness`, and
+  (only when the corresponding flag is passed) `supply_chain`/`oauth_scopes`. All additive — no existing
+  key renamed or removed.
+
+## [0.1.2] — 2026-07-08
+
+### Changed
+- Plain, reader-first README and package description.
+- README images use absolute URLs so they render on PyPI (relative paths only work on GitHub).
+
+## [0.1.1] — 2026-07-08
+
+### Fixed
+- A tool declaring `destructiveHint: true` is now counted as write/mutating even when its name isn't a
+  write-verb (e.g. a `pause_job` tool). Previously the verb heuristic could leave a declared-destructive
+  tool unflagged.
+
+## [0.1.0] — 2026-07-08
+
+Initial release. Local-first MCP measurement.
+
+### Added
+- `mcpgawk scan` over stdio, streamable-HTTP, and SSE via the official `mcp` SDK (protocol-version negotiated).
+- Cost **index** (named tokenizer) + **EXACT** capability facts (write / exfil-capable / annotations) + **integrity pin**.
+- **Bounded** heuristic signals (0-FP on the tested corpus, never verdicts): injection-shaped descriptions
+  (tools and prompts), cross-server name shadowing, Server-Card under-declaration.
+- `--track` rug-pull / drift monitor with a local history store.
+- Server Card reader (`/.well-known/mcp/server-card.json`) — reads the card when present, checks
+  declared-vs-measured, falls back to live-connect. Fetched with no auth and no redirect-following.
+- Label output as a Server-Card extension (`x-mcpgawk`); `--json` for machine consumption.
+
+### Security
+- Measurement layers import no network library — cannot egress by construction (enforced by test).
+- Per-server timeout so a hung server degrades to one error row.

{mcpgawk-0.1.2 → mcpgawk-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcpgawk
-Version: 0.1.2
+Version: 0.1.4
 Summary: A local-first CLI that measures what an MCP server costs and what it can do. Nothing leaves your machine.
 Project-URL: Homepage, https://mcp.gawk.dev
 Project-URL: Documentation, https://mcp.gawk.dev
@@ -41,6 +41,8 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/pypi/pyversions/mcpgawk.svg)](https://pypi.org/project/mcpgawk/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![CI](https://github.com/gawk-dev/mcpgawk/actions/workflows/ci.yml/badge.svg)](https://github.com/gawk-dev/mcpgawk/actions/workflows/ci.yml)
+[![Open VSX](https://img.shields.io/open-vsx/v/gawk-dev/mcpgawk?label=VS%20Code%20%2F%20Cursor)](https://open-vsx.org/extension/gawk-dev/mcpgawk)
+[![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Action-blue?logo=github)](https://github.com/marketplace/actions/mcpgawk-mcp-hygiene-gate)
 [![No egress](https://img.shields.io/badge/inventory-never%20uploaded-brightgreen.svg)](#guarantees)
 
 A local-first command that measures what a [Model Context Protocol](https://modelcontextprotocol.io)
@@ -66,18 +68,39 @@ You pay for those tokens, and you haven't checked what the tools can do. mcpgawk
 ## Features
 
 - 🔌 **Any transport** — stdio, streamable-HTTP, SSE, and OAuth remotes (via the `mcp-remote` bridge).
-- 💸 **Token cost index** — exactly what each tool adds to your context at connect.
-- 🧾 **Capability facts** — write / exfil-capable / declared annotations, straight from the schema.
+- 💸 **Token cost index** — exactly what each tool adds to your context at connect, plus the 3 heaviest tools.
+- 🧾 **Capability facts** — write / exfil-capable / declared annotations, straight from the schema, plus a
+  trust-surface summary (% write, % exfil-capable, destructive-declared count) and an annotation-completeness
+  score.
 - 📌 **Integrity pin + drift** — catch a server that silently rewrites its tools (`--track`).
 - 🚩 **Bounded signals** — injection-shaped descriptions, cross-server shadowing, under-declaring Server Cards — pointers for a human, never verdicts.
 - 🔒 **Zero egress, by construction** — the measurement layers import no network library. Enforced by a test.
+  Two checks are opt-in and make an explicit exception (see [Guarantees](#guarantees)): `--supply-chain` and
+  `--oauth-scopes`.
 
-## Install
+## Get it — three ways
 
+**CLI** (any terminal):
 ```bash
 pip install mcpgawk        # or: uv tool install mcpgawk
+mcpgawk scan mcp.json
 ```
 
+**Editor** (VS Code / Cursor): install **mcpgawk** from the marketplace ([Open VSX](https://open-vsx.org/extension/gawk-dev/mcpgawk)). It scans your workspace `mcp.json` and shows cost + capability flags inline.
+
+**CI** (GitHub Action): gate every PR on token budget / drift ([Marketplace](https://github.com/marketplace/actions/mcpgawk-mcp-hygiene-gate)):
+```yaml
+- uses: gawk-dev/mcpgawk@v1
+  with: { config: mcp.json, max-tokens: 8000, fail-on-flagged: true }
+```
+
+## When to run it
+
+- **Before you add a server** — see what it costs and what it can do, before you trust it.
+- **When your agent feels slow or picks the wrong tool** — it's often MCP bloat (too many / too-heavy tools).
+- **On every PR** — the CI gate catches drift and creeping token cost.
+- **If you *publish* an MCP server** — see what it costs your users and how it reads to a client, and fix it (usually one line per tool). Lean + well-annotated is a differentiator.
+
 ## Use
 
 ```bash
@@ -87,24 +110,38 @@ mcpgawk scan --http https://host/mcp --header "Authorization: Bearer $TOKEN"
 mcpgawk scan --sse  https://host/sse
 mcpgawk scan mcp.json --track                                     # record + detect rug-pulls over time
 mcpgawk scan mcp.json --json                                      # machine-readable labels
+mcpgawk scan mcp.json --verbose                                   # full per-tool table, not just flagged tools
+mcpgawk scan mcp.json --supply-chain                              # opt-in: npm/PyPI deprecation check (network)
+mcpgawk scan mcp.json --oauth-scopes                              # opt-in: decode a supplied Bearer JWT's scope
 ```
 
 ## What it reports
 
 - **Cost index** — tokens each tool adds at connect (named tokenizer; a comparable index, not an
-  absolute Claude count).
-- **Capability facts** — write/mutating, exfil-capable, declared annotations.
+  absolute Claude count), plus the 3 heaviest tools.
+- **Trust surface** — capability facts (write/mutating, exfil-capable, declared annotations) rolled up
+  into % write, % exfil-capable, and a destructive-declared count.
+- **Annotation completeness** — a transparent composite (annotated ÷ total tools declaring read/write
+  intent), not a risk score.
+- **Coverage** — tools, prompts, and resources counted (`--verbose` for the full per-tool table).
 - **Integrity pin** — a hash that changes if the server silently rewrites its tools; `--track`
   turns it into rug-pull detection over time.
 - **Bounded signals** — precise, low-false-positive pointers *for a human to review*, never verdicts:
   injection-shaped descriptions (tools **and** prompts), cross-server name shadowing, and public
   Server Cards that under-declare what the server actually exposes.
+- **Supply-chain** (opt-in, `--supply-chain`) — checks the launched package against the public npm/PyPI
+  registry for deprecation/yank status.
+- **OAuth scopes** (opt-in, `--oauth-scopes`) — locally decodes a supplied Bearer JWT's `scope` claim.
 
 ## Guarantees
 
 - **No inventory egress.** The only network is the protocol client talking to the server you point
   it at. The measurement layers import no network library — they *cannot* egress by construction
   (enforced by a test). Public Server Card discovery is fetched with no auth and no redirect-following.
+  Two flags are the explicit, opt-in exception: `--supply-chain` sends the launched package's name
+  (and pinned version, if any) — never your tool inventory — to the public npm registry or PyPI JSON
+  API. `--oauth-scopes` makes no network call at all; it locally decodes a Bearer JWT you already
+  supplied. Neither runs unless you pass the flag.
 - **Facts ≠ heuristics.** Exact capability facts and the token index never mix with the bounded
   heuristic signals — separate in code, separate in output.
 - **Reproducible.** One command, identical numbers.
@@ -116,6 +153,21 @@ mcpgawk scan mcp.json --json                                      # machine-read
 uv run --extra dev --with mcp --with tiktoken --with httpx python -m pytest -q
 ```
 
+## CI gate — GitHub Action
+
+Scan your MCP servers on every pull request and fail the build if one gets too heavy or trips a signal.
+It runs entirely in your runner — nothing is uploaded — and posts a per-server cost/flag table to the job summary.
+
+```yaml
+- uses: gawk-dev/mcpgawk@v1
+  with:
+    config: mcp.json        # or: stdio / http / sse — a single server
+    max-tokens: 8000        # fail if any server loads more than this at connect
+    fail-on-flagged: true   # fail if any bounded signal fires
+```
+
+Available on the [GitHub Marketplace](https://github.com/marketplace/actions/mcpgawk-mcp-hygiene-gate).
+
 ## Contributing
 
 Issues and PRs welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) first, and see the design

{mcpgawk-0.1.2 → mcpgawk-0.1.4}/README.md

@@ -12,6 +12,8 @@
 [![Python](https://img.shields.io/pypi/pyversions/mcpgawk.svg)](https://pypi.org/project/mcpgawk/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![CI](https://github.com/gawk-dev/mcpgawk/actions/workflows/ci.yml/badge.svg)](https://github.com/gawk-dev/mcpgawk/actions/workflows/ci.yml)
+[![Open VSX](https://img.shields.io/open-vsx/v/gawk-dev/mcpgawk?label=VS%20Code%20%2F%20Cursor)](https://open-vsx.org/extension/gawk-dev/mcpgawk)
+[![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Action-blue?logo=github)](https://github.com/marketplace/actions/mcpgawk-mcp-hygiene-gate)
 [![No egress](https://img.shields.io/badge/inventory-never%20uploaded-brightgreen.svg)](#guarantees)
 
 A local-first command that measures what a [Model Context Protocol](https://modelcontextprotocol.io)
@@ -37,18 +39,39 @@ You pay for those tokens, and you haven't checked what the tools can do. mcpgawk
 ## Features
 
 - 🔌 **Any transport** — stdio, streamable-HTTP, SSE, and OAuth remotes (via the `mcp-remote` bridge).
-- 💸 **Token cost index** — exactly what each tool adds to your context at connect.
-- 🧾 **Capability facts** — write / exfil-capable / declared annotations, straight from the schema.
+- 💸 **Token cost index** — exactly what each tool adds to your context at connect, plus the 3 heaviest tools.
+- 🧾 **Capability facts** — write / exfil-capable / declared annotations, straight from the schema, plus a
+  trust-surface summary (% write, % exfil-capable, destructive-declared count) and an annotation-completeness
+  score.
 - 📌 **Integrity pin + drift** — catch a server that silently rewrites its tools (`--track`).
 - 🚩 **Bounded signals** — injection-shaped descriptions, cross-server shadowing, under-declaring Server Cards — pointers for a human, never verdicts.
 - 🔒 **Zero egress, by construction** — the measurement layers import no network library. Enforced by a test.
+  Two checks are opt-in and make an explicit exception (see [Guarantees](#guarantees)): `--supply-chain` and
+  `--oauth-scopes`.
 
-## Install
+## Get it — three ways
 
+**CLI** (any terminal):
 ```bash
 pip install mcpgawk        # or: uv tool install mcpgawk
+mcpgawk scan mcp.json
 ```
 
+**Editor** (VS Code / Cursor): install **mcpgawk** from the marketplace ([Open VSX](https://open-vsx.org/extension/gawk-dev/mcpgawk)). It scans your workspace `mcp.json` and shows cost + capability flags inline.
+
+**CI** (GitHub Action): gate every PR on token budget / drift ([Marketplace](https://github.com/marketplace/actions/mcpgawk-mcp-hygiene-gate)):
+```yaml
+- uses: gawk-dev/mcpgawk@v1
+  with: { config: mcp.json, max-tokens: 8000, fail-on-flagged: true }
+```
+
+## When to run it
+
+- **Before you add a server** — see what it costs and what it can do, before you trust it.
+- **When your agent feels slow or picks the wrong tool** — it's often MCP bloat (too many / too-heavy tools).
+- **On every PR** — the CI gate catches drift and creeping token cost.
+- **If you *publish* an MCP server** — see what it costs your users and how it reads to a client, and fix it (usually one line per tool). Lean + well-annotated is a differentiator.
+
 ## Use
 
 ```bash
@@ -58,24 +81,38 @@ mcpgawk scan --http https://host/mcp --header "Authorization: Bearer $TOKEN"
 mcpgawk scan --sse  https://host/sse
 mcpgawk scan mcp.json --track                                     # record + detect rug-pulls over time
 mcpgawk scan mcp.json --json                                      # machine-readable labels
+mcpgawk scan mcp.json --verbose                                   # full per-tool table, not just flagged tools
+mcpgawk scan mcp.json --supply-chain                              # opt-in: npm/PyPI deprecation check (network)
+mcpgawk scan mcp.json --oauth-scopes                              # opt-in: decode a supplied Bearer JWT's scope
 ```
 
 ## What it reports
 
 - **Cost index** — tokens each tool adds at connect (named tokenizer; a comparable index, not an
-  absolute Claude count).
-- **Capability facts** — write/mutating, exfil-capable, declared annotations.
+  absolute Claude count), plus the 3 heaviest tools.
+- **Trust surface** — capability facts (write/mutating, exfil-capable, declared annotations) rolled up
+  into % write, % exfil-capable, and a destructive-declared count.
+- **Annotation completeness** — a transparent composite (annotated ÷ total tools declaring read/write
+  intent), not a risk score.
+- **Coverage** — tools, prompts, and resources counted (`--verbose` for the full per-tool table).
 - **Integrity pin** — a hash that changes if the server silently rewrites its tools; `--track`
   turns it into rug-pull detection over time.
 - **Bounded signals** — precise, low-false-positive pointers *for a human to review*, never verdicts:
   injection-shaped descriptions (tools **and** prompts), cross-server name shadowing, and public
   Server Cards that under-declare what the server actually exposes.
+- **Supply-chain** (opt-in, `--supply-chain`) — checks the launched package against the public npm/PyPI
+  registry for deprecation/yank status.
+- **OAuth scopes** (opt-in, `--oauth-scopes`) — locally decodes a supplied Bearer JWT's `scope` claim.
 
 ## Guarantees
 
 - **No inventory egress.** The only network is the protocol client talking to the server you point
   it at. The measurement layers import no network library — they *cannot* egress by construction
   (enforced by a test). Public Server Card discovery is fetched with no auth and no redirect-following.
+  Two flags are the explicit, opt-in exception: `--supply-chain` sends the launched package's name
+  (and pinned version, if any) — never your tool inventory — to the public npm registry or PyPI JSON
+  API. `--oauth-scopes` makes no network call at all; it locally decodes a Bearer JWT you already
+  supplied. Neither runs unless you pass the flag.
 - **Facts ≠ heuristics.** Exact capability facts and the token index never mix with the bounded
   heuristic signals — separate in code, separate in output.
 - **Reproducible.** One command, identical numbers.
@@ -87,6 +124,21 @@ mcpgawk scan mcp.json --json                                      # machine-read
 uv run --extra dev --with mcp --with tiktoken --with httpx python -m pytest -q
 ```
 
+## CI gate — GitHub Action
+
+Scan your MCP servers on every pull request and fail the build if one gets too heavy or trips a signal.
+It runs entirely in your runner — nothing is uploaded — and posts a per-server cost/flag table to the job summary.
+
+```yaml
+- uses: gawk-dev/mcpgawk@v1
+  with:
+    config: mcp.json        # or: stdio / http / sse — a single server
+    max-tokens: 8000        # fail if any server loads more than this at connect
+    fail-on-flagged: true   # fail if any bounded signal fires
+```
+
+Available on the [GitHub Marketplace](https://github.com/marketplace/actions/mcpgawk-mcp-hygiene-gate).
+
 ## Contributing
 
 Issues and PRs welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) first, and see the design

mcpgawk-0.1.4/action.yml

@@ -0,0 +1,62 @@
+name: 'mcpgawk MCP hygiene gate'
+description: 'Scan your MCP servers in CI and fail the build if one is too heavy or trips a signal. Local, nothing uploaded.'
+author: 'nativerse'
+branding:
+  icon: 'shield'
+  color: 'blue'
+
+inputs:
+  config:
+    description: 'Path to an mcp.json config to scan.'
+    required: false
+    default: 'mcp.json'
+  stdio:
+    description: 'A single stdio server command to scan instead of a config (e.g. "npx -y @modelcontextprotocol/server-filesystem /tmp").'
+    required: false
+    default: ''
+  http:
+    description: 'A single streamable-HTTP MCP server URL to scan.'
+    required: false
+    default: ''
+  sse:
+    description: 'A single SSE MCP server URL to scan.'
+    required: false
+    default: ''
+  max-tokens:
+    description: 'Fail the build if any server loads more than this many tokens at connect. 0 = no budget.'
+    required: false
+    default: '0'
+  fail-on-flagged:
+    description: 'Fail the build if any server trips a bounded signal (injection-shaped / shadowing / undeclared).'
+    required: false
+    default: 'false'
+  version:
+    description: 'mcpgawk version to install from PyPI ("latest" or e.g. "0.1.2").'
+    required: false
+    default: 'latest'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    - name: Install mcpgawk
+      shell: bash
+      run: |
+        if [ "${{ inputs.version }}" = "latest" ]; then
+          pip install --quiet --disable-pip-version-check mcpgawk
+        else
+          pip install --quiet --disable-pip-version-check "mcpgawk==${{ inputs.version }}"
+        fi
+    - name: Scan and gate
+      shell: bash
+      env:
+        MCPGAWK_CONFIG: ${{ inputs.config }}
+        MCPGAWK_STDIO: ${{ inputs.stdio }}
+        MCPGAWK_HTTP: ${{ inputs.http }}
+        MCPGAWK_SSE: ${{ inputs.sse }}
+        MCPGAWK_MAX_TOKENS: ${{ inputs.max-tokens }}
+        MCPGAWK_FAIL_ON_FLAGGED: ${{ inputs.fail-on-flagged }}
+      run: python "${{ github.action_path }}/scripts/ci_gate.py"

mcpgawk-0.1.4/docs/.gitignore

@@ -0,0 +1 @@
+.vercel

mcpgawk-0.1.4/docs/api/lead.js

@@ -0,0 +1,69 @@
+// Vercel serverless function — the ONLY path into the `leads` table.
+// Verifies Cloudflare Turnstile server-side, runs honeypot/timing/email guards,
+// then inserts using the Supabase service-role key (never exposed to the browser).
+// Env vars (set in Vercel → Settings → Environment Variables):
+//   SUPABASE_URL, SUPABASE_SERVICE_ROLE, TURNSTILE_SECRET
+const DISPOSABLE = new Set([
+  'mailinator.com','guerrillamail.com','10minutemail.com','tempmail.com','temp-mail.org',
+  'trashmail.com','yopmail.com','getnada.com','sharklasers.com','maildrop.cc','dispostable.com',
+  'mailnesia.com','fakeinbox.com','throwawaymail.com','mohmal.com','mintemail.com'
+]);
+
+export default async function handler(req, res) {
+  if (req.method !== 'POST') { res.status(405).json({ error: 'method' }); return; }
+
+  const SITE = process.env.SUPABASE_URL;
+  const KEY  = process.env.SUPABASE_SERVICE_ROLE;
+  const TS   = process.env.TURNSTILE_SECRET;
+  if (!SITE || !KEY || !TS) { res.status(500).json({ error: 'not-configured' }); return; }
+
+  let body = req.body;
+  if (typeof body === 'string') { try { body = JSON.parse(body); } catch (_) { body = {}; } }
+  body = body || {};
+
+  // 1) honeypot — a bot filled the hidden field. Pretend success, insert nothing.
+  if (body.website) { res.status(200).json({ ok: true }); return; }
+
+  // 2) timing — the form must have been open at least a couple of seconds (and not for days).
+  const elapsed = Number(body.elapsed || 0);
+  if (!(elapsed >= 2500 && elapsed < 1000 * 60 * 60 * 6)) { res.status(400).json({ error: 'timing' }); return; }
+
+  // 3) field validation
+  const name  = String(body.name || '').trim().slice(0, 120);
+  const email = String(body.email || '').trim().slice(0, 200).toLowerCase();
+  if (!name || !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) { res.status(400).json({ error: 'fields' }); return; }
+  if (DISPOSABLE.has(email.split('@')[1])) { res.status(400).json({ error: 'disposable' }); return; }
+
+  // 4) Turnstile — verify the token with Cloudflare (this is what a bot cannot fake).
+  const token = String(body.turnstileToken || '');
+  if (!token) { res.status(400).json({ error: 'captcha-missing' }); return; }
+  const ip = String(req.headers['x-forwarded-for'] || '').split(',')[0].trim();
+  let verify;
+  try {
+    verify = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({ secret: TS, response: token, remoteip: ip })
+    }).then(r => r.json());
+  } catch (_) { verify = { success: false }; }
+  if (!verify || !verify.success) { res.status(400).json({ error: 'captcha-failed' }); return; }
+
+  // 5) insert via service-role (bypasses RLS; the public key can no longer write once the policy is dropped).
+  const ins = await fetch(SITE.replace(/\/$/, '') + '/rest/v1/leads', {
+    method: 'POST',
+    headers: {
+      apikey: KEY, Authorization: 'Bearer ' + KEY,
+      'Content-Type': 'application/json', Prefer: 'return=minimal'
+    },
+    body: JSON.stringify({
+      name, email,
+      company: String(body.company || '').trim().slice(0, 160) || null,
+      wants_scan: !!body.wants_scan,
+      opt_in: !!body.opt_in,
+      source: 'mcp.gawk.dev'
+    })
+  });
+  if (ins.status === 201 || ins.status === 409) { res.status(200).json({ ok: true }); return; }  // created, or already on the list
+  const detail = await ins.text().catch(() => '');
+  res.status(502).json({ error: 'insert', detail: detail.slice(0, 200) });
+}

mcpgawk-0.1.4/docs/assets/logos/alibaba.svg

@@ -0,0 +1 @@
+<svg fill="#FF6A00" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Alibaba.com</title><path d="M14.391 16.22c-.963.044-.865-.459-.302-1.234 1.32-1.768 3.82-4.236 3.906-5.982.151-2.283-2.143-3.026-4.501-3.004-1.645.022-3.344.492-4.501.906C5 8.315 2.489 10.576.909 13.076-.768 15.554-.216 17.923 3.322 18c2.716-.109 4.48-.862 6.32-1.802.01 0-5.086 1.453-6.958.383l-.008-.002c-.193-.11-.404-.264-.457-.683-.012-.885 1.46-1.802 2.283-2.097v-1.533a5.374 5.374 0 0 0 1.955.366 5.378 5.378 0 0 0 3.472-1.265c.037.13.056.278.044.447h.371c.048-.394-.172-.706-.172-.706-.333-.529-.915-.52-.915-.52s.315.137.529.466a4.953 4.953 0 0 1-4.665.932l1.21-1.2-.336-.874c2.435-.852 4.48-1.507 7.812-2.085l-.746-.624.389-.24c2.01.568 3.325.985 3.253 2.051a2.672 2.672 0 0 1-.202.611c-.584 1.158-2.326 3.09-3.029 3.898-.465.535-.92 1.06-1.245 1.562-.335.503-.54.971-.551 1.42.043 3.504 10.334-1.64 12.324-3.003-2.943 1.266-6.113 2.489-9.609 2.718Z"/></svg>

mcpgawk-0.1.4/docs/assets/logos/anthropic.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="257" preserveAspectRatio="xMidYMid" viewBox="0 0 256 257"><path fill="#D97757" d="m50.228 170.321 50.357-28.257.843-2.463-.843-1.361h-2.462l-8.426-.518-28.775-.778-24.952-1.037-24.175-1.296-6.092-1.297L0 125.796l.583-3.759 5.12-3.434 7.324.648 16.202 1.101 24.304 1.685 17.629 1.037 26.118 2.722h4.148l.583-1.685-1.426-1.037-1.101-1.037-25.147-17.045-27.22-18.017-14.258-10.37-7.713-5.25-3.888-4.925-1.685-10.758 7-7.713 9.397.649 2.398.648 9.527 7.323 20.35 15.75L94.817 91.9l3.889 3.24 1.555-1.102.195-.777-1.75-2.917-14.453-26.118-15.425-26.572-6.87-11.018-1.814-6.61c-.648-2.723-1.102-4.991-1.102-7.778l7.972-10.823L71.42 0 82.05 1.426l4.472 3.888 6.61 15.101 10.694 23.786 16.591 32.34 4.861 9.592 2.592 8.879.973 2.722h1.685v-1.556l1.36-18.211 2.528-22.36 2.463-28.776.843-8.1 4.018-9.722 7.971-5.25 6.222 2.981 5.12 7.324-.713 4.73-3.046 19.768-5.962 30.98-3.889 20.739h2.268l2.593-2.593 10.499-13.934 17.628-22.036 7.778-8.749 9.073-9.657 5.833-4.601h11.018l8.1 12.055-3.628 12.443-11.342 14.388-9.398 12.184-13.48 18.147-8.426 14.518.778 1.166 2.01-.194 30.46-6.481 16.462-2.982 19.637-3.37 8.88 4.148.971 4.213-3.5 8.62-20.998 5.184-24.628 4.926-36.682 8.685-.454.324.519.648 16.526 1.555 7.065.389h17.304l32.21 2.398 8.426 5.574 5.055 6.805-.843 5.184-12.962 6.611-17.498-4.148-40.83-9.721-14-3.5h-1.944v1.167l11.666 11.406 21.387 19.314 26.767 24.887 1.36 6.157-3.434 4.86-3.63-.518-23.526-17.693-9.073-7.972-20.545-17.304h-1.36v1.814l4.73 6.935 25.017 37.59 1.296 11.536-1.814 3.76-6.481 2.268-7.13-1.297-14.647-20.544-15.1-23.138-12.185-20.739-1.49.843-7.194 77.448-3.37 3.953-7.778 2.981-6.48-4.925-3.436-7.972 3.435-15.749 4.148-20.544 3.37-16.333 3.046-20.285 1.815-6.74-.13-.454-1.49.194-15.295 20.999-23.267 31.433-18.406 19.702-4.407 1.75-7.648-3.954.713-7.064 4.277-6.286 25.47-32.405 15.36-20.092 9.917-11.6-.065-1.686h-.583L44.07 198.125l-12.055 1.555-5.185-4.86.648-7.972 2.463-2.593 20.35-13.999-.064.065Z"/></svg>

mcpgawk-0.1.4/docs/assets/logos/baidu.svg

@@ -0,0 +1 @@
+<svg fill="#2932E1" role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Baidu</title><path d="M9.154 0C7.71 0 6.54 1.658 6.54 3.707c0 2.051 1.171 3.71 2.615 3.71 1.446 0 2.614-1.659 2.614-3.71C11.768 1.658 10.6 0 9.154 0zm7.025.594C14.86.58 13.347 2.589 13.2 3.927c-.187 1.745.25 3.487 2.179 3.735 1.933.25 3.175-1.806 3.422-3.364.252-1.555-.995-3.364-2.362-3.674a1.218 1.218 0 0 0-.261-.03zM3.582 5.535a2.811 2.811 0 0 0-.156.008c-2.118.19-2.428 3.24-2.428 3.24-.287 1.41.686 4.425 3.297 3.864 2.617-.561 2.262-3.68 2.183-4.362-.125-1.018-1.292-2.773-2.896-2.75zm16.534 1.753c-2.308 0-2.617 2.119-2.617 3.616 0 1.43.121 3.425 2.988 3.362 2.867-.063 2.553-3.238 2.553-3.988 0-.745-.62-2.99-2.924-2.99zm-8.264 2.478c-1.424.014-2.708.925-3.323 1.947-1.118 1.868-2.863 3.05-3.112 3.363-.25.309-3.61 2.116-2.864 5.42.746 3.301 3.365 3.237 3.365 3.237s1.93.19 4.171-.31c2.24-.495 4.17.123 4.17.123s5.233 1.748 6.665-1.616c1.43-3.364-.808-5.109-.808-5.109s-2.99-2.306-4.736-4.798c-1.072-1.665-2.348-2.268-3.528-2.257zm-2.234 3.84l1.542.024v8.197H7.758c-1.47-.291-2.055-1.292-2.13-1.462-.072-.173-.488-.976-.268-2.343.635-2.049 2.447-2.196 2.447-2.196h1.81zm3.964 2.39v3.881c.096.413.612.488.612.488h1.614v-4.343h1.689v5.782h-3.915c-1.517-.39-1.59-1.465-1.59-1.465v-4.317zm-5.458 1.147c-.66.197-.978.708-1.05.928-.076.22-.247.78-.1 1.269.294 1.095 1.248 1.144 1.248 1.144h1.37v-3.34z"/></svg>

mcpgawk-0.1.4/docs/assets/logos/cerebras.svg

@@ -0,0 +1,4 @@
+<svg width="50" height="50" viewBox="0 0 50 50" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M29.4186 5.62713C24.2806 5.62713 19.353 7.6682 15.7199 11.3013C12.0868 14.9345 10.0457 19.862 10.0457 25C10.0457 30.1381 12.0868 35.0656 15.7199 38.6988C19.353 42.3319 24.2806 44.373 29.4186 44.373V47.2917C17.1061 47.2917 7.12695 37.3105 7.12695 24.998C7.12695 12.6855 17.104 2.7063 29.4165 2.7063V5.62505L29.4186 5.62713ZM39.3186 13.2875C37.7794 11.9809 35.9971 10.9915 34.0741 10.3761C32.1512 9.76067 30.1256 9.53147 28.1137 9.70166C26.1019 9.87185 24.1435 10.4381 22.3513 11.3677C20.559 12.2974 18.9683 13.5722 17.6704 15.1189C16.3726 16.6655 15.3933 18.4534 14.7888 20.3798C14.1844 22.3062 13.9667 24.3332 14.1483 26.344C14.33 28.3548 14.9073 30.3099 15.8472 32.0968C16.787 33.8838 18.0709 35.4673 19.6249 36.7563L17.7478 38.9938C15.9126 37.4545 14.3987 35.5687 13.2924 33.4442C12.1862 31.3197 11.5092 28.9981 11.3003 26.6119C11.0914 24.2258 11.3545 21.8219 12.0747 19.5374C12.7949 17.253 13.9581 15.1328 15.4978 13.298C17.0373 11.4628 18.9233 9.94877 21.0479 8.84247C23.1726 7.73618 25.4944 7.05923 27.8807 6.8503C30.267 6.64136 32.6711 6.90453 34.9557 7.62477C37.2403 8.34501 39.3607 9.50822 41.1957 11.048L39.3186 13.2875ZM34.6207 15.0459C31.9818 13.6829 28.9113 13.4172 26.0776 14.3068C23.2438 15.1964 20.876 17.1691 19.4895 19.7958C18.1029 22.4224 17.8099 25.4903 18.6741 28.332C19.5384 31.1736 21.4899 33.5589 24.104 34.9688L22.7374 37.5521C19.4721 35.7617 17.0418 32.7592 15.9707 29.1927C14.8996 25.6261 15.2737 21.7815 17.0123 18.4883C18.7509 15.1952 21.7146 12.7176 25.2637 11.5903C28.8129 10.463 32.663 10.7763 35.9832 12.4625L34.6207 15.0459ZM29.4165 17.7896C27.5042 17.7896 25.6702 18.5493 24.318 19.9015C22.9658 21.2537 22.2061 23.0877 22.2061 25C22.2061 26.9124 22.9658 28.7464 24.318 30.0986C25.6702 31.4508 27.5042 32.2105 29.4165 32.2105V35.1313C26.7296 35.1313 24.1526 34.0639 22.2527 32.1639C20.3527 30.2639 19.2853 27.687 19.2853 25C19.2853 22.3131 20.3527 19.7362 22.2527 17.8362C24.1526 15.9362 26.7296 14.8688 29.4165 14.8688V17.7896Z" fill="#F15A29"/>
+<path d="M32.0981 22.5749C31.7875 22.2404 31.4295 21.9534 31.0356 21.7228C30.6925 21.519 30.3014 21.4097 29.9023 21.4062C29.371 21.4062 28.896 21.5041 28.4773 21.6978C28.0725 21.8802 27.7089 22.1425 27.4081 22.469C27.1074 22.7955 26.8758 23.1795 26.7273 23.5978C26.5731 24.0207 26.4981 24.4645 26.4981 24.9124C26.4981 25.3666 26.5731 25.8082 26.7273 26.227C26.877 26.6449 27.1091 27.0286 27.4096 27.3553C27.7102 27.682 28.0733 27.9451 28.4773 28.1291C28.8939 28.3228 29.3731 28.4207 29.9023 28.4207C30.3523 28.4207 30.771 28.3249 31.1564 28.1395C31.5481 27.952 31.8856 27.6707 32.146 27.3228L34.0794 29.4187C33.7877 29.7103 33.4544 29.9624 33.0752 30.1749C32.374 30.566 31.6108 30.8338 30.8189 30.9666C30.4648 31.0207 30.1585 31.0499 29.9023 31.0499C29.0617 31.0552 28.2271 30.9069 27.4398 30.6124C26.6954 30.3371 26.0144 29.914 25.4377 29.3687C24.8643 28.8208 24.4078 28.1624 24.096 27.4332C23.7572 26.6366 23.5883 25.778 23.6002 24.9124C23.6002 23.9874 23.7669 23.1478 24.096 22.3916C24.4085 21.6624 24.8627 21.0041 25.4356 20.4562C26.0148 19.9124 26.696 19.4895 27.4398 19.2145C28.2271 18.92 29.0617 18.7717 29.9023 18.777C30.6419 18.777 31.3856 18.9187 32.1356 19.202C32.8877 19.4895 33.5627 19.952 34.1023 20.5541L32.0981 22.5749Z" fill="black"/>
+</svg>