mcpgawk 0.1.1__tar.gz → 0.1.3__tar.gz

{mcpgawk-0.1.1 → mcpgawk-0.1.3}/.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.3/.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.3/.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.3/.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.3/.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.3/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to mcpgawk. Format: [Keep a Changelog](https://keepachangelog.com/); versioning: [SemVer](https://semver.org/).
+
+## [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.1 → mcpgawk-0.1.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mcpgawk
-Version: 0.1.1
-Summary: Local-first MCP measurement — gawk at an MCP server before you trust it. No inventory ever leaves your machine.
+Version: 0.1.3
+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
 Project-URL: Repository, https://github.com/gawk-dev/mcpgawk
@@ -29,11 +29,11 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="assets/brand/wordmark-dark.png">
-    <img alt="mcpgawk by nativerse" src="assets/brand/wordmark-light.png" width="320">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gawk-dev/mcpgawk/main/assets/brand/wordmark-dark.png">
+    <img alt="mcpgawk by nativerse" src="https://raw.githubusercontent.com/gawk-dev/mcpgawk/main/assets/brand/wordmark-light.png" width="320">
   </picture>
 </p>
-<p align="center"><em>gawk at it before you trust it.</em></p>
+<p align="center"><em>Make MCP lean and honest.</em></p>
 
 # mcpgawk
 
@@ -41,22 +41,22 @@ 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)
 
-**gawk at an MCP server before you trust it.** A single, local-first command that connects to any
-[Model Context Protocol](https://modelcontextprotocol.io) server and measures what it will cost and
-expose — **without the server's inventory ever leaving your machine.**
+A local-first command that measures what a [Model Context Protocol](https://modelcontextprotocol.io)
+server costs and what it can do. It runs on your machine and uploads nothing.
 
 <p align="center">
-  <img src="assets/brand/demo.gif" alt="mcpgawk scanning an MCP server — tools, token cost, and capability flags, locally" width="760">
+  <img src="https://raw.githubusercontent.com/gawk-dev/mcpgawk/main/assets/brand/demo.gif" alt="mcpgawk scanning an MCP server — tools, token cost, and capability flags, locally" width="760">
 </p>
 <p align="center"><sub>Real output. Reproducible on your machine — no account, nothing uploaded.</sub></p>
 
 ## Why
 
-Every MCP server you connect dumps *all* its tool definitions into your model's context at connect
-time — whether you use one tool or none. That's a hidden **token tax** and an unvetted **trust
-surface**. mcpgawk measures both, **locally**, and never phones home about what it saw.
+Connect an MCP server and it loads all its tools into your AI's context. Every request. Used or not.
+You pay for those tokens, and you haven't checked what the tools can do. mcpgawk shows you both, locally.
 
 ## How it's different
 
@@ -68,18 +68,39 @@ surface**. mcpgawk measures both, **locally**, and never phones home about what
 ## 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
@@ -89,28 +110,42 @@ 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.
-- **Rides protocol evolution.** Built on the official `mcp` SDK, which negotiates the protocol version.
+- **Tracks the protocol.** Built on the official `mcp` SDK, which negotiates the protocol version.
 
 ## Develop
 
@@ -118,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.3/README.md

@@ -0,0 +1,151 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gawk-dev/mcpgawk/main/assets/brand/wordmark-dark.png">
+    <img alt="mcpgawk by nativerse" src="https://raw.githubusercontent.com/gawk-dev/mcpgawk/main/assets/brand/wordmark-light.png" width="320">
+  </picture>
+</p>
+<p align="center"><em>Make MCP lean and honest.</em></p>
+
+# mcpgawk
+
+[![PyPI](https://img.shields.io/pypi/v/mcpgawk.svg)](https://pypi.org/project/mcpgawk/)
+[![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)
+server costs and what it can do. It runs on your machine and uploads nothing.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gawk-dev/mcpgawk/main/assets/brand/demo.gif" alt="mcpgawk scanning an MCP server — tools, token cost, and capability flags, locally" width="760">
+</p>
+<p align="center"><sub>Real output. Reproducible on your machine — no account, nothing uploaded.</sub></p>
+
+## Why
+
+Connect an MCP server and it loads all its tools into your AI's context. Every request. Used or not.
+You pay for those tokens, and you haven't checked what the tools can do. mcpgawk shows you both, locally.
+
+## How it's different
+
+- **vs. cloud scanners** (e.g. Snyk/Invariant `mcp-scan`) — they upload your inventory to a server and
+  gate the verdict. mcpgawk runs entirely on your machine; nothing is uploaded, ever.
+- **vs. lazy-load gateways** — they cut tokens but tell you nothing about the *risk* surface.
+- **mcpgawk does both** — cost **and** trust — locally, reproducibly, in one command.
+
+## 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, 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`.
+
+## 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
+mcpgawk scan mcp.json                                              # a whole config
+mcpgawk scan --stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"
+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), 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.
+- **Tracks the protocol.** Built on the official `mcp` SDK, which negotiates the protocol version.
+
+## Develop
+
+```bash
+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
+boundaries in [THREAT-MODEL.md](THREAT-MODEL.md). Security reports go through [SECURITY.md](SECURITY.md)
+(privately, not a public issue).
+
+## License
+
+**Apache-2.0** — see [LICENSE](LICENSE). Part of the **nativerse** · gawk.dev family. The value is in the
+repo, not a cloud.

mcpgawk-0.1.3/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.1/docs → mcpgawk-0.1.3}/assets/brand/social-preview.svg

@@ -8,8 +8,8 @@
   <text x="256" y="196" dominant-baseline="central" font-family="Sentient, Georgia, serif" font-weight="500" font-size="104" letter-spacing="-3" fill="#16160F">mcpgawk</text>
   <text x="258" y="270" font-family="Supreme, -apple-system, sans-serif" font-size="30" letter-spacing="0.5" fill="#6B6B5E">by <tspan fill="#2A33C2" font-weight="500">nativerse</tspan></text>
   <line x1="96" y1="352" x2="1184" y2="352" stroke="#E7E6E0" stroke-width="1.5"/>
-  <text x="96" y="438" font-family="Sentient, Georgia, serif" font-size="42" fill="#3A3A30">gawk at it before you trust it.</text>
+  <text x="96" y="438" font-family="Sentient, Georgia, serif" font-size="42" fill="#3A3A30">Make it lean. Make it honest.</text>
   <text x="96" y="524" font-family="Tabular, ui-monospace, Menlo, monospace" font-size="25" fill="#717166"><tspan fill="#2A9d6b">●</tspan> cli-stdio   14 tools   2061 tok@connect   4 flagged</text>
   <circle cx="102" cy="576" r="6" fill="#2A9d6b"/>
-  <text x="120" y="576" dominant-baseline="central" font-family="Tabular, ui-monospace, Menlo, monospace" font-size="24" letter-spacing="1" fill="#6B6B5E">local · no inventory ever leaves your machine</text>
+  <text x="120" y="576" dominant-baseline="central" font-family="Tabular, ui-monospace, Menlo, monospace" font-size="24" letter-spacing="1" fill="#6B6B5E">local · nothing leaves your machine</text>
 </svg>

mcpgawk-0.1.3/docs/.gitignore

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

mcpgawk-0.1.3/docs/CNAME

@@ -0,0 +1 @@
+mcp.gawk.dev