mcpgawk 0.1.0__py3-none-any.whl

mcpgawk/__init__.py

@@ -0,0 +1,16 @@
+"""mcpgawk — local-first MCP measurement.
+
+gawk at an MCP server before you trust it: measure what it costs and exposes,
+without the server's inventory ever leaving your machine.
+
+Pipeline: Observe (probe) -> Bound (measure) -> Attest (label).
+"""
+from .probe import ServerSnapshot, probe_stdio, probe_http, probe_sse
+from .measure import Measurement, measure
+from .label import build_label
+
+__version__ = "0.1.0"
+__all__ = [
+    "ServerSnapshot", "probe_stdio", "probe_http", "probe_sse",
+    "Measurement", "measure", "build_label", "__version__",
+]

mcpgawk/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

mcpgawk/cli.py

@@ -0,0 +1,121 @@
+"""mcpgawk CLI — one command, zero config.
+
+    mcpgawk scan <mcp.json> [--only a,b] [--json]
+    mcpgawk scan --stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"
+    mcpgawk scan --http https://host/mcp [--header "Authorization: Bearer ..."]
+    mcpgawk scan --sse  https://host/sse
+
+Local-first: the only network is the SDK talking to the server you point it at.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import shlex
+import sys
+from datetime import datetime, timezone
+
+from . import drift, history
+from .label import build_label, render_cli, render_summary
+from .measure import measure
+from .probe import ServerSnapshot, probe, probe_http, probe_sse, probe_stdio
+from .signals import as_dicts, detect, detect_card_mismatch, detect_shadowing
+
+
+def _load_config(path: str) -> dict:
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    return data.get("mcpServers", data)
+
+
+async def _scan_config(cfg: dict, only: set[str] | None) -> list[ServerSnapshot]:
+    targets = [(n, e) for n, e in cfg.items() if not only or n in only]
+    return await asyncio.gather(*(probe(e, n) for n, e in targets))
+
+
+def _headers(pairs: list[str] | None) -> dict[str, str]:
+    out = {}
+    for p in pairs or []:
+        k, _, v = p.partition(":")
+        out[k.strip()] = v.strip()
+    return out
+
+
+async def _run(args) -> list[ServerSnapshot]:
+    if args.stdio:
+        parts = shlex.split(args.stdio)
+        return [await probe_stdio("cli-stdio", parts[0], parts[1:])]
+    if args.http:
+        return [await probe_http("cli-http", args.http, _headers(args.header))]
+    if args.sse:
+        return [await probe_sse("cli-sse", args.sse, _headers(args.header))]
+    only = set(args.only.split(",")) if args.only else None
+    return await _scan_config(_load_config(args.config), only)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="mcpgawk", description="gawk at an MCP server before you trust it")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("scan", help="measure MCP server(s) locally")
+    s.add_argument("config", nargs="?", help="path to an mcp.json config")
+    s.add_argument("--stdio", help='one stdio server, e.g. "npx -y @modelcontextprotocol/server-filesystem /tmp"')
+    s.add_argument("--http", help="one streamable-HTTP server URL")
+    s.add_argument("--sse", help="one SSE server URL")
+    s.add_argument("--header", action="append", help='HTTP header, e.g. "Authorization: Bearer XYZ" (repeatable)')
+    s.add_argument("--only", help="comma-separated server names to scan from the config")
+    s.add_argument("--no-signals", action="store_true", help="skip BOUNDED heuristic signals (facts only)")
+    s.add_argument("--track", action="store_true",
+                   help="record this scan locally and report DRIFT vs the last sighting (rug-pull detection)")
+    s.add_argument("--json", action="store_true", help="emit JSON labels instead of a table")
+    args = p.parse_args(argv)
+
+    if args.cmd == "scan" and not (args.config or args.stdio or args.http or args.sse):
+        p.error("give a config path or one of --stdio/--http/--sse")
+
+    snaps = asyncio.run(_run(args))
+    measurements = [measure(sn) for sn in snaps]
+    # Cross-server shadowing needs all snapshots together; merge into each involved server's signals.
+    shadow = {} if args.no_signals else detect_shadowing(snaps)
+    labels = []
+    for sn, m in zip(snaps, measurements):
+        sigs = None
+        if not args.no_signals:
+            sigs = (as_dicts(detect(sn)) + as_dicts(shadow.get(sn.name, []))
+                    + as_dicts(detect_card_mismatch(sn)))
+        labels.append(build_label(sn, m, bounded_signals=(sigs or None)))
+
+    # --track: record locally and diff against the last sighting (rug-pull detection).
+    drift_reports: dict[str, drift.DriftReport] = {}
+    if args.track:
+        now = datetime.now(timezone.utc).isoformat(timespec="seconds")
+        store = history.load()
+        for sn, m in zip(snaps, measurements):
+            if sn.error:
+                continue
+            key = history.key_for(sn)
+            record = drift.build_record(sn, m, measured_at=now)
+            rep = drift.compare(history.last(store, key), record)
+            if rep and rep.any:
+                drift_reports[sn.name] = rep
+            history.append(store, key, record)
+        history.save(store)
+
+    if args.json:
+        print(json.dumps(labels, indent=2))
+        return 0
+
+    print(f"\n{'='*70}\nmcpgawk 0.1 — LOCAL scan (no inventory uploaded)\n{'='*70}")
+    any_error = False
+    for lab in labels:
+        print("\n" + render_cli(lab))
+        rep = drift_reports.get(lab["name"])
+        if rep:
+            print(drift.render(lab["name"], rep))
+        any_error = any_error or bool(lab["x-mcpgawk"].get("caveats"))
+    print("\n" + render_summary(labels) + "\n")
+    return 1 if any_error else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mcpgawk/drift.py

@@ -0,0 +1,84 @@
+"""Drift / rug-pull detection — pure diff over stored measurements.
+
+The integrity pin (measure.py) already changes when a server silently rewrites its tools. Drift
+turns that into an actionable, per-tool diff: what was ADDED, REMOVED, or CHANGED (same tool name,
+different description = the classic tool-poisoning rug-pull signature) since you last trusted it.
+
+Pure functions, no I/O, no clock (the caller stamps time). history.py handles the local store.
+"""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Any
+
+from .measure import Measurement
+from .probe import ServerSnapshot
+
+
+def _tool_hashes(snap: ServerSnapshot) -> dict[str, str]:
+    """name -> hash(description). Detects silent description edits per tool."""
+    return {t.get("name", "?"): hashlib.sha256((t.get("description") or "").encode()).hexdigest()[:12]
+            for t in snap.tools}
+
+
+def build_record(snap: ServerSnapshot, m: Measurement, measured_at: str | None = None) -> dict[str, Any]:
+    """A storable snapshot: enough to diff, small enough to keep forever."""
+    return {
+        "measured_at": measured_at,
+        "pin": m.integrity_pin,
+        "tool_count": m.tool_count,
+        "cost_index": m.total_tokens,
+        "tokenizer": m.tokenizer,          # so token_delta isn't compared across tokenizers
+        "protocol_version": snap.protocol_version,
+        "tools": _tool_hashes(snap),
+    }
+
+
+@dataclass
+class DriftReport:
+    pin_changed: bool
+    added: list[str]
+    removed: list[str]
+    changed: list[str]       # same name, description hash differs = rug-pull signature
+    token_delta: int
+    prev_at: str | None
+
+    @property
+    def any(self) -> bool:
+        return self.pin_changed or bool(self.added or self.removed or self.changed)
+
+
+def compare(prev: dict[str, Any] | None, curr: dict[str, Any]) -> DriftReport | None:
+    """None if there's no prior record (first sighting — nothing to drift from)."""
+    if not prev:
+        return None
+    pa, ca = prev.get("tools", {}), curr.get("tools", {})
+    added = sorted(set(ca) - set(pa))
+    removed = sorted(set(pa) - set(ca))
+    changed = sorted(n for n in (set(pa) & set(ca)) if pa[n] != ca[n])
+    # token_delta is only meaningful when both runs used the same tokenizer; else it lies (an
+    # index change from swapping tiktoken, not a real server change). Rug-pull detection (pin +
+    # description hashes) is tokenizer-independent, so it stays correct.
+    same_tok = prev.get("tokenizer") == curr.get("tokenizer")
+    delta = (curr.get("cost_index", 0) - prev.get("cost_index", 0)) if same_tok else 0
+    return DriftReport(
+        pin_changed=prev.get("pin") != curr.get("pin"),
+        added=added, removed=removed, changed=changed,
+        token_delta=delta,
+        prev_at=prev.get("measured_at"),
+    )
+
+
+def render(name: str, r: DriftReport) -> str:
+    since = f" since {r.prev_at}" if r.prev_at else ""
+    lines = [f"    ⟳ DRIFT on {name}{since} — server changed after you last saw it:"]
+    if r.changed:
+        lines.append(f"        ! description CHANGED (rug-pull signature): {', '.join(r.changed)}")
+    if r.added:
+        lines.append(f"        + tools added: {', '.join(r.added)}")
+    if r.removed:
+        lines.append(f"        - tools removed: {', '.join(r.removed)}")
+    if r.token_delta:
+        lines.append(f"        Δ cost index: {r.token_delta:+d} tok")
+    return "\n".join(lines)

mcpgawk/history.py

@@ -0,0 +1,49 @@
+"""Local, human-readable drift history. JSON on disk — never leaves the machine.
+
+Default: $MCPGAWK_HISTORY or ~/.mcpgawk/history.json. This is the ONLY state mcpgawk persists,
+and it's the user's own machine. No sync, no cloud.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from .probe import ServerSnapshot
+
+
+def default_path() -> str:
+    return os.environ.get("MCPGAWK_HISTORY") or os.path.expanduser("~/.mcpgawk/history.json")
+
+
+def load(path: str | None = None) -> dict[str, Any]:
+    path = path or default_path()
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {"servers": {}}
+
+
+def save(store: dict[str, Any], path: str | None = None) -> None:
+    path = path or default_path()
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(store, f, indent=2, sort_keys=True)
+    os.replace(tmp, path)  # atomic
+
+
+def key_for(snap: ServerSnapshot) -> str:
+    return f"{snap.transport}:{snap.name}"
+
+
+def last(store: dict[str, Any], key: str) -> dict[str, Any] | None:
+    hist = store.get("servers", {}).get(key, {}).get("history", [])
+    return hist[-1] if hist else None
+
+
+def append(store: dict[str, Any], key: str, record: dict[str, Any], keep: int = 50) -> None:
+    hist = store.setdefault("servers", {}).setdefault(key, {}).setdefault("history", [])
+    hist.append(record)
+    del hist[:-keep]  # bounded — keep the last `keep` sightings

mcpgawk/label.py

@@ -0,0 +1,89 @@
+"""ATTEST — build the MCP Label as a Server-Card extension, and render it.
+
+The label complements the emerging LF `.well-known` Server Card standard rather than competing:
+standard-ish card fields at the top, our measurements under the `x-mcpgawk` namespace. Nothing
+here is a verdict — token cost is a named index; capabilities are facts; there are no risk
+'scores' in v1.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .measure import Measurement
+from .probe import ServerSnapshot
+from .servercard import compare_to_reality
+
+LABEL_SCHEMA = "mcpgawk/label@0.1"
+
+
+def build_label(snap: ServerSnapshot, m: Measurement, measured_at: str | None = None,
+                bounded_signals: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+    """measured_at is passed in (the library never reads the clock — keeps output reproducible).
+    bounded_signals (optional) are BOUNDED-layer heuristic findings — kept in their own key,
+    never merged into the EXACT tool facts."""
+    return {
+        # ---- Server-Card-compatible surface ----
+        "name": snap.name,
+        "transport": snap.transport,
+        "protocolVersion": snap.protocol_version,
+        "serverInfo": snap.server_info or None,
+        # ---- our independent measurement extension ----
+        "x-mcpgawk": {
+            "schema": LABEL_SCHEMA,
+            "measured_at": measured_at,
+            "tokenizer": m.tokenizer,
+            "cost_index_tokens": m.total_tokens,     # INDEX (tokenizer named above)
+            "tool_count": m.tool_count,
+            "prompt_count": m.prompt_count,
+            "resource_count": m.resource_count,
+            "integrity_pin": m.integrity_pin,        # EXACT — rug-pull anchor
+            # server's self-declaration checked against what we measured (http/sse only)
+            "server_card": (compare_to_reality(snap.server_card, [t.name for t in m.tools])
+                            if snap.server_card else {"present": False}),
+            "tools": [
+                {"name": t.name, "tokens": t.tokens,
+                 "write": t.write, "exfil_capable": t.exfil_capable,
+                 "annotations": t.annotations or None}
+                for t in m.tools
+            ],
+            "caveats": m.caveats or None,
+            # BOUNDED layer — heuristic signals, kept apart from the EXACT facts above.
+            "bounded_signals": bounded_signals or None,
+            "disclaimer": "Local measurement. Token cost is a comparable index, not an absolute "
+                          "Claude count. Capabilities are structural facts, not risk verdicts. "
+                          "bounded_signals are heuristic pointers for a human to review, not verdicts.",
+        },
+    }
+
+
+def render_cli(label: dict[str, Any]) -> str:
+    x = label["x-mcpgawk"]
+    lines = [
+        f"● {label['name']:<22} [{label['transport']}]  proto={label.get('protocolVersion') or '?'}",
+        f"    {x['tool_count']:>3} tools   {x['cost_index_tokens']:>6} tok@connect   pin:{x['integrity_pin']}",
+    ]
+    flagged = [t for t in x["tools"] if t["write"] or t["exfil_capable"]]
+    for t in flagged:
+        caps = []
+        if t["write"]:
+            caps.append("write" if (t.get("annotations") or {}) else "write/no-annotation")
+        if t["exfil_capable"]:
+            caps.append("exfil-capable")
+        if (t.get("annotations") or {}).get("destructiveHint") is True:
+            caps.append("destructive-declared")
+        lines.append(f"      · {t['name']:<28} {t['tokens']:>5} tok   {', '.join(caps)}")
+    for s in (x.get("bounded_signals") or []):
+        lines.append(f"    ⚠ SIGNAL {s['kind']:<26} [{s['tool']}]  — review: {s['evidence']!r}")
+    if x.get("caveats"):
+        lines.append(f"    ! {'; '.join(x['caveats'])}")
+    return "\n".join(lines)
+
+
+def render_summary(labels: list[dict[str, Any]]) -> str:
+    tools = sum(l["x-mcpgawk"]["tool_count"] for l in labels)
+    toks = sum(l["x-mcpgawk"]["cost_index_tokens"] for l in labels)
+    flagged = sum(1 for l in labels for t in l["x-mcpgawk"]["tools"] if t["write"] or t["exfil_capable"])
+    tzs = {l["x-mcpgawk"]["tokenizer"] for l in labels}
+    return ("-" * 70 + f"\nTOTAL: {tools} tools | {toks} tok loaded at connect | "
+            f"{flagged} capability-flagged | tokenizer: {', '.join(tzs)}\n"
+            "Nothing was uploaded. Re-run for identical numbers.")

mcpgawk/measure.py

@@ -0,0 +1,103 @@
+"""BOUND — measure a snapshot. Pure, offline, deterministic.
+
+The EXACT/INDEX/BOUNDED wall (enforced here):
+  * EXACT  — structural capability facts + integrity pin. Facts, not estimates.
+  * INDEX  — token cost via a *named* tokenizer (cl100k). A comparable ranking index, NOT
+             an absolute Claude count (tiktoken undercounts Claude ~15-20%). Honestly labelled.
+  * BOUNDED— heuristic risk signals. NOT in v1 (security is a 0-FP fast-follow). Kept out of
+             this module entirely so an estimate can never contaminate a fact.
+
+No network. No LLM. Scanning the inventory is pure computation.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from .probe import ServerSnapshot
+
+TOKENIZER_NAME = "cl100k_base (approx index; not Claude-exact)"
+
+# Structural capability detectors — deliberately conservative, fact-level only.
+_WRITE = re.compile(
+    r"\b(create|delete|remove|write|update|send|post|put|patch|execute|run|modify|drop|"
+    r"insert|upload|push|merge|deploy|revoke|grant|edit|rename|move|set|add)\b", re.I)
+_EXFIL_PARAM = re.compile(r"\b(url|uri|endpoint|webhook|href|callback|redirect)\b", re.I)
+_EXFIL_NAME = re.compile(r"\b(fetch|http|request|download|browse|scrape|curl|web)\b", re.I)
+
+
+@dataclass
+class ToolMeasure:
+    name: str
+    tokens: int                      # INDEX
+    write: bool                      # EXACT (structural)
+    exfil_capable: bool              # EXACT (structural)
+    annotations: dict[str, Any]      # EXACT (declared)
+
+
+@dataclass
+class Measurement:
+    tokenizer: str
+    total_tokens: int                # INDEX — sum at connect
+    tool_count: int
+    tools: list[ToolMeasure]
+    integrity_pin: str               # EXACT — rug-pull anchor
+    prompt_count: int = 0
+    resource_count: int = 0
+    caveats: list[str] = field(default_factory=list)
+
+
+def _encoder():
+    try:
+        import tiktoken
+        return tiktoken.get_encoding("cl100k_base"), TOKENIZER_NAME
+    except Exception:
+        return None, "chars/4 (rough fallback — tiktoken unavailable)"
+
+
+def _count(enc, text: str) -> int:
+    return len(enc.encode(text)) if enc is not None else max(1, len(text) // 4)
+
+
+def _exfil_capable(tool: dict[str, Any]) -> bool:
+    if _EXFIL_NAME.search(tool.get("name", "") + " " + (tool.get("description") or "")):
+        return True
+    props = ((tool.get("inputSchema") or {}).get("properties") or {})
+    return any(_EXFIL_PARAM.search(k) for k in props)
+
+
+def _is_write(tool: dict[str, Any], ann: dict[str, Any]) -> bool:
+    if ann.get("readOnlyHint") is True:      # declared read-only wins over the verb heuristic
+        return False
+    text = tool.get("name", "") + " " + (tool.get("description") or "")
+    return bool(_WRITE.search(text))
+
+
+def measure(snap: ServerSnapshot, enc=None, tokenizer_name: str | None = None) -> Measurement:
+    if enc is None and tokenizer_name is None:
+        enc, tokenizer_name = _encoder()
+    tools: list[ToolMeasure] = []
+    total = 0
+    for t in snap.tools:
+        # Tokenise exactly what a model's context would carry for this tool.
+        blob = json.dumps({k: t.get(k) for k in ("name", "description", "inputSchema", "annotations")
+                           if t.get(k) is not None}, sort_keys=True)
+        tk = _count(enc, blob)
+        total += tk
+        ann = t.get("annotations") or {}
+        tools.append(ToolMeasure(
+            name=t.get("name", "?"), tokens=tk,
+            write=_is_write(t, ann), exfil_capable=_exfil_capable(t), annotations=ann))
+    # Integrity pin = stable hash of the (name, description) pairs the server presents.
+    pin_src = json.dumps(sorted((t.get("name"), t.get("description")) for t in snap.tools),
+                         sort_keys=True).encode()
+    pin = hashlib.sha256(pin_src).hexdigest()[:16]
+    m = Measurement(
+        tokenizer=tokenizer_name, total_tokens=total, tool_count=len(tools), tools=tools,
+        integrity_pin=pin, prompt_count=len(snap.prompts), resource_count=len(snap.resources))
+    if snap.error:
+        m.caveats.append(f"probe error: {snap.error}")
+    return m

mcpgawk/probe.py

@@ -0,0 +1,129 @@
+"""OBSERVE — connect to an MCP server via the official `mcp` SDK and snapshot it.
+
+We use the maintained protocol client (`ClientSession` + the stdio/streamable-http/sse
+transports). The SDK negotiates the protocol version and tracks the spec by definition, so
+mcpgawk rides protocol evolution instead of owning a stale fork. We are a *one-shot client*,
+not a man-in-the-middle proxy — that keeps us off the runtime-enforcement lane.
+
+Egress note: the only network here is the SDK talking to the server being scanned. Nothing
+about the captured inventory is sent anywhere else.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+from mcp.client.sse import sse_client
+from mcp.client.streamable_http import streamablehttp_client
+
+from .servercard import fetch_card
+
+
+@dataclass
+class ServerSnapshot:
+    """Everything we captured from one server. Raw wire-shape tool dicts, so measurement
+    sees exactly what a model's context would see."""
+    name: str
+    transport: str
+    protocol_version: str | None
+    tools: list[dict[str, Any]] = field(default_factory=list)
+    prompts: list[dict[str, Any]] = field(default_factory=list)
+    resources: list[dict[str, Any]] = field(default_factory=list)
+    server_info: dict[str, Any] = field(default_factory=dict)
+    server_card: dict[str, Any] | None = None   # self-declared .well-known card (http/sse only)
+    error: str | None = None
+
+
+def _dump(items: list[Any]) -> list[dict[str, Any]]:
+    """Pydantic model -> wire-shape dict (by_alias gives `inputSchema`, `readOnlyHint`, ...)."""
+    out = []
+    for it in items:
+        if hasattr(it, "model_dump"):
+            out.append(it.model_dump(by_alias=True, exclude_none=True, mode="json"))
+        elif isinstance(it, dict):
+            out.append(it)
+    return out
+
+
+async def _snapshot(session: ClientSession, name: str, transport: str) -> ServerSnapshot:
+    init = await session.initialize()
+    snap = ServerSnapshot(
+        name=name,
+        transport=transport,
+        protocol_version=getattr(init, "protocolVersion", None),
+        server_info=(init.serverInfo.model_dump(mode="json") if getattr(init, "serverInfo", None) else {}),
+    )
+    # tools/list is the load-bearing surface; prompts/resources are optional per server.
+    snap.tools = _dump((await session.list_tools()).tools)
+    for attr, method in (("prompts", "list_prompts"), ("resources", "list_resources")):
+        try:
+            res = await getattr(session, method)()
+            setattr(snap, attr, _dump(getattr(res, attr)))
+        except Exception:
+            pass  # server doesn't advertise that capability — not an error for us
+    return snap
+
+
+# Per-server wall-clock bound. A hung / slow-loris server must degrade to ONE error row, never
+# block the whole scan. Generous enough for a cold npx/uvx first-run install.
+DEFAULT_TIMEOUT = 90.0
+
+
+async def _bounded(coro_factory, name: str, transport: str, timeout: float) -> ServerSnapshot:
+    try:
+        return await asyncio.wait_for(coro_factory(), timeout)
+    except Exception as e:  # noqa: BLE001 — incl. TimeoutError; surface, never crash the scan
+        return ServerSnapshot(name=name, transport=transport, protocol_version=None,
+                              error=f"{type(e).__name__}: {e}")
+
+
+async def probe_stdio(name: str, command: str, args: list[str] | None = None,
+                      env: dict[str, str] | None = None, timeout: float = DEFAULT_TIMEOUT) -> ServerSnapshot:
+    async def _do():
+        params = StdioServerParameters(command=command, args=args or [],
+                                       env={**os.environ, **(env or {})})
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                return await _snapshot(session, name, "stdio")
+    return await _bounded(_do, name, "stdio", timeout)
+
+
+async def probe_http(name: str, url: str, headers: dict[str, str] | None = None,
+                     timeout: float = DEFAULT_TIMEOUT) -> ServerSnapshot:
+    """Streamable-HTTP transport — for hosted MCPs. `headers` carries a user-supplied bearer/OAuth
+    token for the MCP connection ONLY; the public Server Card fetch never sees it (see servercard.py)."""
+    async def _do():
+        async with streamablehttp_client(url, headers=headers or {}) as (read, write, _sid):
+            async with ClientSession(read, write) as session:
+                snap = await _snapshot(session, name, "http")
+        snap.server_card = await fetch_card(url)   # public, unauthenticated; tolerant
+        return snap
+    return await _bounded(_do, name, "http", timeout)
+
+
+async def probe_sse(name: str, url: str, headers: dict[str, str] | None = None,
+                    timeout: float = DEFAULT_TIMEOUT) -> ServerSnapshot:
+    async def _do():
+        async with sse_client(url, headers=headers or {}) as (read, write):
+            async with ClientSession(read, write) as session:
+                snap = await _snapshot(session, name, "sse")
+        snap.server_card = await fetch_card(url)
+        return snap
+    return await _bounded(_do, name, "sse", timeout)
+
+
+async def probe(entry: dict[str, Any], name: str) -> ServerSnapshot:
+    """Dispatch a config entry (mcp.json shape) to the right transport."""
+    if entry.get("command"):
+        return await probe_stdio(name, entry["command"], entry.get("args"), entry.get("env"))
+    url = entry.get("url")
+    if not url:
+        return ServerSnapshot(name=name, transport="?", protocol_version=None,
+                              error="entry has neither `command` (stdio) nor `url` (http/sse)")
+    transport = entry.get("transport", "http")
+    headers = entry.get("headers")
+    return await (probe_sse if transport == "sse" else probe_http)(name, url, headers)

mcpgawk/servercard.py

@@ -0,0 +1,69 @@
+"""Server Card reader — read a server's self-declaration and check it against reality.
+
+SEP-1649 / SEP-2127: an HTTP MCP server MAY publish `/.well-known/mcp/server-card.json` describing
+itself for pre-connection discovery. mcpgawk reads it when present, but does NOT trust it: we still
+live-connect and MEASURE, then compare. A card that *under-declares* (hides tools it actually
+exposes) is a trust signal — exactly the independent-measurement value mcpgawk exists for.
+
+Tolerant by design: any fetch/parse failure -> no card -> fall back to live measurement. The card
+fetch is to the server being scanned (the one allowed network touch), same as connecting. Applies to
+HTTP/SSE servers only (stdio has no well-known URL).
+"""
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+WELL_KNOWN = "/.well-known/mcp/server-card.json"
+
+
+def card_url_for(server_url: str) -> str:
+    p = urlsplit(server_url)
+    return urlunsplit((p.scheme, p.netloc, WELL_KNOWN, "", ""))
+
+
+def _looks_like_card(d: Any) -> bool:
+    return isinstance(d, dict) and bool(
+        d.get("serverInfo") or d.get("name") or d.get("protocolVersion") or "$schema" in d)
+
+
+async def fetch_card(server_url: str, timeout: float = 8.0) -> dict[str, Any] | None:
+    """GET the well-known card. Returns the parsed card, or None on any failure (tolerant).
+
+    SECURITY: Server Cards are PUBLIC pre-connection discovery, so we send NO auth headers and
+    do NOT follow redirects — otherwise a `.well-known` endpoint could 3xx to an attacker host and
+    (if we forwarded the user's bearer) leak their credential cross-origin. Neither is negotiable.
+    """
+    import httpx
+    try:
+        async with httpx.AsyncClient(timeout=timeout, follow_redirects=False) as c:
+            r = await c.get(card_url_for(server_url))   # no headers — public, unauthenticated
+        if r.status_code != 200:
+            return None
+        data = r.json()
+        return data if _looks_like_card(data) else None
+    except Exception:  # noqa: BLE001 — a missing/broken card must never break a scan
+        return None
+
+
+def compare_to_reality(card: dict[str, Any], measured_tool_names: list[str]) -> dict[str, Any]:
+    """What the card declares vs what we actually measured."""
+    out: dict[str, Any] = {
+        "present": True,
+        "declared_version": card.get("version"),
+        "declared_protocol": card.get("protocolVersion"),
+    }
+    ct = card.get("tools")
+    if isinstance(ct, list):
+        declared = sorted({t.get("name") for t in ct if isinstance(t, dict) and t.get("name")})
+        real = sorted(set(measured_tool_names))
+        undeclared = sorted(set(real) - set(declared))   # present but hidden from the card
+        phantom = sorted(set(declared) - set(real))       # claimed but not actually present
+        out.update({
+            "declared_tool_count": len(declared),
+            "measured_tool_count": len(real),
+            "undeclared_tools": undeclared,   # the trust-relevant case
+            "phantom_tools": phantom,
+            "matches_reality": not (undeclared or phantom),
+        })
+    return out

mcpgawk/signals.py

@@ -0,0 +1,129 @@
+"""BOUND / BOUNDED layer — heuristic risk *signals*, kept physically apart from measure.py.
+
+The wall: this module has NO token math and NO capability facts; measure.py has NO signals.
+An estimate can therefore never contaminate a fact.
+
+0-FP discipline (authdrift lesson): every detector here is deliberately *precise* — it fires only
+on language aimed at the reader/model, never on legitimate tool capability keywords (a `url` param
+or a `delete` verb is a FACT, handled in measure.py, not a signal here). A detector ships only after
+a measured 0 false positives on a real clean corpus (see tests/test_signals.py + the live FP gate).
+
+A signal is a SIGNAL, never a verdict. We never say "server X is insecure".
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from .probe import ServerSnapshot
+
+# --- Detector 1: hidden markup in a description (HTML comments / pseudo-system tags). ---
+# Legit tool descriptions are plain prose; an embedded comment or <important>/<system> tag is
+# the classic tool-poisoning carrier (Invariant's own local rule keyed on <IMPORTANT>).
+_HIDDEN_MARKUP = re.compile(r"<!--.*?-->|<\s*/?\s*(important|system|secret|admin|instruction|tool_call)\b",
+                            re.IGNORECASE | re.DOTALL)
+
+# --- Detector 2: reader-directed instructions (the model is the audience, not the caller). ---
+_READER_DIRECTED = re.compile(
+    r"ignore\s+(?:all\s+|the\s+|your\s+|any\s+)*(?:previous|prior|above|earlier|preceding)\s+"
+    r"(?:instruction|prompt|message|context)"
+    r"|disregard\s+(?:the\s+|all\s+|any\s+)*(?:previous|prior|above|earlier)"
+    r"|do\s*n?o?t?'?\s*(?:tell|inform|mention|reveal|notify|disclose)\s+(?:the\s+)?(?:user|human)"
+    r"|(?:you\s+are|act\s+as|you\s+must\s+act)\s+an?\s+(?:ai|assistant|language\s+model|agent)"
+    r"|(?:your|the)\s+system\s+prompt"
+    r"|new\s+instructions?\s*:",
+    re.IGNORECASE)
+
+# --- Detector 3: secret-exfil directives (read a secret AND move it). ---
+# Tightened after a real false positive: Vercel's `get_access_to_vercel_url` says "access ... without
+# requiring login credentials" — benign. "access" and a bare "credential" are NOT suspicious. We fire on
+# (a) reading an unambiguous secret FILE, or (b) a secret WORD paired with an explicit exfil verb.
+# Only unambiguous secret FILES — a legit tool description has no reason to name these. Secret *words*
+# ("api key", "password", "credential") appear in countless benign descriptions, so they are NOT used
+# (that was the FP source: "pass/fail with an API key", "access without credentials", etc.). Other
+# injection styles are still caught by the hidden-markup and reader-directed detectors above.
+_SECRET_FILE = r"(?:\.env\b|~/\.ssh|id_rsa|/etc/passwd|/etc/shadow)"
+_EXFIL_VERB = r"(?:pass|send|include|attach|exfiltrat\w*|leak|upload|post|forward)"
+_EXFIL_DIRECTIVE = re.compile(
+    r"(?:read|open|cat|load|retrieve|dump)\b[^.]{0,40}" + _SECRET_FILE   # read a secret file
+    + r"|" + _SECRET_FILE + r"[^.]{0,40}\b" + _EXFIL_VERB,                # secret file → moved out
+    re.IGNORECASE | re.DOTALL)
+
+_DETECTORS = (
+    ("injection:hidden-markup", _HIDDEN_MARKUP),
+    ("injection:reader-directed", _READER_DIRECTED),
+    ("injection:secret-exfil", _EXFIL_DIRECTIVE),
+)
+
+
+@dataclass
+class Finding:
+    tool: str
+    kind: str
+    evidence: str            # the matched span — so a human can judge, we never auto-verdict
+    confidence: str = "signal"   # never "confirmed"; this layer only signals
+
+
+def _scan_text(text: str, tool: str) -> list[Finding]:
+    out: list[Finding] = []
+    for kind, rx in _DETECTORS:
+        m = rx.search(text or "")
+        if m:
+            span = m.group(0).strip()
+            out.append(Finding(tool=tool, kind=kind, evidence=span[:120]))
+    return out
+
+
+def detect(snap: ServerSnapshot) -> list[Finding]:
+    """Run the BOUNDED detectors over the injection surface: tool AND prompt descriptions.
+    (Prompts are model-facing text too — the tool-poisoning surface isn't only tools/list.)"""
+    findings: list[Finding] = []
+    for t in snap.tools:
+        findings.extend(_scan_text(t.get("description") or "", t.get("name", "?")))
+    for pr in snap.prompts:
+        findings.extend(_scan_text(pr.get("description") or "", f"prompt:{pr.get('name', '?')}"))
+    return findings
+
+
+def detect_shadowing(snaps: list[ServerSnapshot]) -> dict[str, list[Finding]]:
+    """CROSS-SERVER signal: a tool name exposed by more than one server. All connected servers share
+    one context, so a malicious server can register the same name as a trusted one and shadow it
+    (mcp-secret-exfil-threat-model: 'cross-tool shadowing'). Naturally 0-FP — fires only on a genuine
+    collision between distinct servers. Returns {server_name -> [Finding]}.
+    """
+    owners: dict[str, set[str]] = {}
+    for s in snaps:
+        for t in s.tools:
+            owners.setdefault(t.get("name", "?"), set()).add(s.name)
+    out: dict[str, list[Finding]] = {}
+    for s in snaps:
+        for t in s.tools:
+            nm = t.get("name", "?")
+            others = owners.get(nm, set()) - {s.name}
+            if others:
+                out.setdefault(s.name, []).append(Finding(
+                    tool=nm, kind="shadowing:name-collision",
+                    evidence=f"also exposed by: {', '.join(sorted(others))}"))
+    return out
+
+
+def detect_card_mismatch(snap: ServerSnapshot) -> list[Finding]:
+    """Signal: the server's public .well-known card UNDER-DECLARES — hides tools it actually exposes.
+    A fact-based, 0-FP signal (fires only on a real declared-vs-measured gap). Independent
+    measurement catching a self-declaration that doesn't match reality."""
+    if not snap.server_card:
+        return []
+    from .servercard import compare_to_reality
+    cmp = compare_to_reality(snap.server_card, [t.get("name", "?") for t in snap.tools])
+    out: list[Finding] = []
+    if cmp.get("undeclared_tools"):
+        u = cmp["undeclared_tools"]
+        out.append(Finding(tool="<server-card>", kind="servercard:undeclared-tools",
+                           evidence=f"exposes {len(u)} tool(s) absent from its public card: {', '.join(u[:6])}"))
+    return out
+
+
+def as_dicts(findings: list[Finding]) -> list[dict[str, Any]]:
+    return [{"tool": f.tool, "kind": f.kind, "evidence": f.evidence, "confidence": f.confidence}
+            for f in findings]

mcpgawk-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: mcpgawk
+Version: 0.1.0
+Summary: Local-first MCP measurement — gawk at an MCP server before you trust it. No inventory ever 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
+Project-URL: Issues, https://github.com/gawk-dev/mcpgawk/issues
+Author: Neelagiri
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agents,cli,llm,local-first,mcp,model-context-protocol,security,tokenizer,tokens
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2,>=1.28
+Requires-Dist: tiktoken>=0.7
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+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">
+  </picture>
+</p>
+<p align="center"><em>gawk at it before you trust it.</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)
+[![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.**
+
+<p align="center">
+  <img src="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.
+
+## 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.
+- 🧾 **Capability facts** — write / exfil-capable / declared annotations, straight from the schema.
+- 📌 **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.
+
+## Install
+
+```bash
+pip install mcpgawk        # or: uv tool install mcpgawk
+```
+
+## 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
+```
+
+## 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.
+- **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.
+
+## 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.
+- **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.
+
+## Develop
+
+```bash
+uv run --extra dev --with mcp --with tiktoken --with httpx python -m pytest -q
+```
+
+## 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.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+mcpgawk/__init__.py,sha256=Q9bCMOJxfGthhAgB8WOk6svVW_G7j8w7EMfMhEHUiBc,554
+mcpgawk/__main__.py,sha256=4JMK66Wj4uLZTKbF-sT3LAxOsr6buig77PmOkJCRRxw,83
+mcpgawk/cli.py,sha256=XXwCZVECkOL-_pj7YLzCkmE6aOJObyEFNv9A49udky8,5009
+mcpgawk/drift.py,sha256=iDK5KFvCKGDmZpRXUk5g_TkoIz3NF1Nw6RNyPIRE4Ro,3447
+mcpgawk/history.py,sha256=TivyJKqoGmhmO8kmUx7DnhgCIWI4tK6YuUBoZzY7Cr0,1593
+mcpgawk/label.py,sha256=2pWUxX56nzPSMaFiWITQ00QRcFAkBAx6jLlXP8yFu7Q,4390
+mcpgawk/measure.py,sha256=45kVD_GsRZRAB1oWOEBtbDNgXuaE_Y-SxJ4QnwVFb3E,4172
+mcpgawk/probe.py,sha256=14y0-QnYDG31a-ayCjO9iRjvCyjc-byE-6qEhw-WtVI,5947
+mcpgawk/servercard.py,sha256=T1wYIj0y2KPOLGRBJ3Ex8LrC2-xIV8K9IhPs0PAqKhY,3159
+mcpgawk/signals.py,sha256=MJcWik5JQpgDu4zzLYPttBdgQng5iRk_0B7syc4GiH4,6405
+mcpgawk-0.1.0.dist-info/METADATA,sha256=A0u4VJLZnrnNmzZMjOSaJ6ULBW00fSjtSBLMpFclagU,6228
+mcpgawk-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+mcpgawk-0.1.0.dist-info/entry_points.txt,sha256=EeoYYkkcXlaHh2avJEY4LAc17mesGti3GyjR4SNz4Xo,45
+mcpgawk-0.1.0.dist-info/licenses/LICENSE,sha256=kBVAMbcL7--sAlEG9JMSRTDhPGCLh2zBQYtfZbqUXxQ,11347
+mcpgawk-0.1.0.dist-info/licenses/NOTICE,sha256=q0rLw5ACo07HFaLw8SNjQEZIsujEJni5_sHvDw3wv9k,601
+mcpgawk-0.1.0.dist-info/RECORD,,

mcpgawk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcpgawk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcpgawk = mcpgawk.cli:main

mcpgawk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Invariant Labs AG
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mcpgawk-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,10 @@
+The reference/ directory contains unmodified third-party source cloned for study,
+each under the Apache License 2.0, © Invariant Labs / Snyk:
+
+  - invariantlabs-ai/invariant           (reference/invariant-analyzer)
+  - invariantlabs-ai/invariant-gateway   (reference/invariant-gateway)
+  - invariantlabs-ai/mcp-scan            (reference/mcp-scan-hist, reference/recovered-local-engine)
+
+These retain their upstream LICENSE files and git history. They are NOT our code and are
+not vendored into this project's git history. Any code we derive from them will carry the
+required Apache-2.0 attribution.