mcp-quality 0.1.0__tar.gz

mcp_quality-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,13 @@
+---
+name: Bug report
+about: Something behaves incorrectly
+labels: bug
+---
+
+**What happened**
+
+**Expected**
+
+**Minimal reproduction**
+
+**Environment** (OS, Python version, model/provider)

mcp_quality-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,11 @@
+---
+name: Feature request
+about: Suggest an idea
+labels: enhancement
+---
+
+**Problem / motivation**
+
+**Proposed solution**
+
+**Alternatives considered**

mcp_quality-0.1.0/.github/good-first-issues.md

@@ -0,0 +1,8 @@
+# Seeded good-first-issues for mcp-quality
+
+> Filed as real GitHub issues (label: `good-first-issue`) once the org repo exists.
+
+1. Add a description-length lint to the Legibility family
+2. Document the JSON output schema for CI
+3. Add an example GitHub Action using --fail-under
+4. Add a sample server to probe against in tests

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

@@ -0,0 +1,85 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: test (py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src/ tests/
+      - name: Types
+        run: mypy src/
+      - name: Unit + component + integration + e2e (no live LLM)
+        run: pytest -m "not live_llm" -q
+      - name: Coverage floor on the correctness-critical core
+        # scorer/connect/snapshot are the parts that must not silently break (TEST-PLAN §9.3)
+        run: pytest -m "not live_llm" --cov=mcp_quality.scoring --cov=mcp_quality.snapshot --cov-fail-under=85 -q
+
+  dogfood:
+    name: dogfood the gate + badge
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e .
+      # The gate must pass a good server and fail a bloated one (proves the gate works live).
+      - name: good_server passes --fail-under B
+        run: mcp-quality run "python tests/servers/good_server.py" --fail-under B
+      - name: bloated_server fails --fail-under A
+        run: |
+          if mcp-quality run "python tests/servers/bloated_server.py" --fail-under A; then
+            echo "expected the gate to FAIL the bloated server"; exit 1
+          fi
+      - name: publish our own badge (the flywheel starts at home)
+        run: mcp-quality badge "python tests/servers/good_server.py" --out mcp-quality-badge.svg
+
+  determinism:
+    name: fast-path determinism guard
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e .
+      # Fast path must be byte-identical across runs (NFR-2). Meta/timing is excluded by
+      # comparing the report bodies with a stable serialization.
+      - name: run twice, diff the JSON
+        run: |
+          mcp-quality static tests/servers/dump.mcp.json --json > a.json
+          mcp-quality static tests/servers/dump.mcp.json --json > b.json
+          python - <<'PY'
+          import json
+          a = json.load(open("a.json")); b = json.load(open("b.json"))
+          a.pop("meta", None); b.pop("meta", None)
+          assert a == b, "fast-path output was not deterministic"
+          print("deterministic OK")
+          PY
+
+  offline:
+    name: static mode (air-gapped)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e .
+      - name: static scan needs no network
+        run: mcp-quality static tests/servers/dump.mcp.json --json

mcp_quality-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release
+
+# Publishes the `mcp-quality` package to PyPI when a GitHub Release is published. Uses
+# PyPI Trusted Publishing (OIDC) — no API token/secret is stored anywhere. One-time setup:
+#   pypi.org → Publishing → add a pending publisher:
+#     PyPI project=mcp-quality  owner=swarmproof  repo=mcp-probe  workflow=release.yml  environment=pypi
+# Then: create a GitHub Release tagged v0.1.0 → this workflow builds and uploads.
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          pip install build
+          python -m build
+      - name: Verify metadata
+        run: |
+          pip install twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mcp_quality-0.1.0/.gitignore

@@ -0,0 +1,230 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+
+# project
+*.db
+stampede-report.html
+.env
+.venv/
+
+# mcp-quality runtime artifacts (the snapshot baseline IS committed; the cache is not)
+.mcp-quality/cache/
+*.badge.svg
+mcp-quality-report.json

mcp_quality-0.1.0/.mcp-probe/cache/legibility-868b57b70e113604d1906f0c.json

@@ -0,0 +1 @@
+{"low_tools": ["archive_record"], "matrix": {"archive_record": {"delete_record": 3}, "delete_record": {}}, "mean_confusion": 1.0, "per_tool_total": {"archive_record": 3, "delete_record": 3}, "rewrites": [{"old": "Remove a record by id.", "rewrite": "Remove a record by its ID using `delete_record`. Use `archive_record` to move a record to the archive without deleting it.", "tool": "archive_record"}, {"old": "Remove a record by id.", "rewrite": "Delete a record permanently using its ID; archive a record temporarily using the 'archive_record' function.", "tool": "delete_record"}], "selection_rate": 0.5, "tool_order": ["delete_record", "archive_record"], "top_confusion": ["archive_record", "delete_record", 1.0]}

mcp_quality-0.1.0/.mcp-quality.toml.example

@@ -0,0 +1,30 @@
+# Example mcp-quality configuration. Copy to `.mcp-quality.toml` (repo root).
+# Precedence: CLI flags > this file > MCP_PROBE_* env vars > defaults.
+# Either a flat table (below) or a [tool.mcp-quality] section is accepted.
+
+# Which families to run. Default is the zero-LLM fast path: ["contract", "cost"].
+families = ["contract", "cost", "security"]
+
+# --- gating ---
+fail_under = "B"          # exit non-zero if overall grade < B
+no_regressions = true     # exit non-zero on any regression vs the committed snapshot
+
+# --- safety ---
+allow_writes = false      # never invoke destructive tools unless true (NFR-9)
+
+# --- cost ---
+tokenizer = "o200k_base"  # offline tiktoken encoding for deterministic counts
+# price_points = ["premium:3.0", "cheap:0.15"]   # $ per 1M input tokens
+# token_model = "anthropic:claude-sonnet-5"   # opt-in authoritative Claude count; needs
+#                                             # ANTHROPIC_API_KEY, else falls back to estimate
+
+# --- legibility ([llm], opt-in) ---
+# model = "ollama:qwen2.5-3b"   # pinned local model is the canonical scorer (ADR-004)
+seed = 42
+goal_set_version = "1"
+
+# --- performance ([net]) ---
+concurrency = 50
+
+# --- security ---
+deep_security = false     # true → shell out to mcp-scan / Cisco if on PATH

mcp_quality-0.1.0/AGENTS.md

@@ -0,0 +1,103 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Current state: v0.1 implemented (all five families)
+
+The v0.1 fast path and all five check families are implemented, tested, and dogfooded.
+Python 3.11+ (`src/` layout, `pip install`), official MCP SDK, `asyncio`. What deviates
+from the spec is recorded in **`docs/DECISIONS.md`** — read it before changing security
+IDs, the handshake, or the token counter.
+
+### Commands
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"   # setup
+
+.venv/bin/pytest -m "not live_llm" -q            # full suite (unit+component+integration+e2e)
+.venv/bin/pytest tests/test_scorer.py -q          # a single test file
+.venv/bin/pytest -m e2e -q                        # only the live-fixture E2E scenarios
+.venv/bin/pytest -m live_llm -q                   # opt-in, calls a real model (excluded by default)
+.venv/bin/ruff check src/ tests/                  # lint (line-length 110)
+.venv/bin/mypy src/                               # types (strict)
+
+.venv/bin/mcp-quality run ".venv/bin/python tests/servers/good_server.py"   # live probe
+.venv/bin/mcp-quality static tests/servers/dump.mcp.json --json             # offline
+.venv/bin/mcp-quality run "…" --all --model ollama:qwen2.5-3b               # all five families
+```
+
+Tests spawn fixture servers with the **same interpreter running pytest** (`sys.executable`),
+so they need the SDK installed in that env — always run via `.venv/bin/pytest`.
+
+### Package layout (`src/mcp_quality/`)
+
+- `models.py` — the frozen data model (`ServerSurface`/`Finding`/`FamilyScore`/`Report`/`CheckEngine`).
+- `config.py` · `cli.py` · `exit_codes.py` — config precedence, the 4 subcommands, CI exit codes.
+- `connect/` — `transport.py` is the **only** module importing the MCP SDK; `client.py` is the
+  façade + `FakeClient`; `discover.py` builds surfaces (live + static dump).
+- `engines/` — one file per family, each a pure `CheckEngine`; registered in `engines/__init__.py`.
+- `contract/`, `legibility/`, `security/`, `perf/`, `tokens.py` — engine-specific internals.
+- `scoring/` · `snapshot/` · `report/` · `handoff.py` · `trace.py` — aggregation & outputs.
+- `tests/servers/` — fixture MCP servers (the TEST-PLAN §2 matrix) + `dump.mcp.json`.
+
+## What mcp-quality is
+
+The **CI quality suite for MCP servers** — "the `pytest` + `lighthouse` for the servers agents depend on." It connects to an MCP server, discovers its surface, and grades it across **five check families** into a single A–F **MCP Quality Score**, designed to run as a CI gate with a README badge.
+
+Positioning is load-bearing and deliberate: security scanners (mcp-scan, Cisco) answer *"is this server dangerous?"*; mcp-quality answers *"is this server good?"* It treats security as **one light check**, defers deep security to the incumbents via `--deep-security` integration (never reimplements them), and unifies the quality *point* tools (credits mcp-xray as prior art) into a CI-native **suite and gate**. Do not drift the messaging toward "another scanner."
+
+The five families: **Contract** (LLM-free spec/schema/determinism), **Legibility** (the differentiator — agent-comprehension score + disambiguation matrix), **Cost** (toolset token weight), **Performance** (concurrent MCP-semantic load), **Security-lite** (OWASP MCP Top 10 basics + integration adapter).
+
+## Documentation hierarchy (read in this order)
+
+The docs are authoritative and layered — consult them before implementing anything:
+
+1. **`SPEC.md`** — the frozen v1.0 design spec/PRD. The baseline.
+2. **`docs/PRD.md`** — numbered, testable requirements: `REQ-*` (functional, per family) and `NFR-*` (non-functional). This is the requirement-of-record; code and tests reference these IDs.
+3. **`docs/ARCHITECTURE.md`** — system design, the core data model (`ServerSurface`, `Finding`, `FamilyScore`, `Report`, `CheckEngine`), the JSON output schema, and the **ADRs** (ADR-001..009) that bind implementation choices.
+4. **`docs/DELIVERY-PLAN.md`** — the WBS (`W0..W6`), effort sizing, critical path, and v0.1 Definition of Done.
+5. **`docs/TEST-PLAN.md`** — the acceptance backbone: E2E scenarios (`E2E-1..10`), the fixture server matrix, the `StubModel` determinism harness, and CI gates.
+6. **`docs/RESEARCH.md`** — the competitive/market analysis the positioning rests on.
+
+**Conventions in the docs that carry into code:**
+- The **`⊕ Beyond original spec`** marker flags anything extending the frozen v1.0 `SPEC.md`. Preserve it when editing docs; it tracks scope past the baseline.
+- Requirement IDs (`REQ-C4`, `NFR-2`, etc.) and finding codes (`C5-nondeterminism`, `S1-owasp-mcp05`) are stable identifiers — reference them in commits, tests, and `Finding.code`.
+- Tier labels: **[fast]** = zero-LLM deterministic, **[llm]** = needs a small model, **[net]** = needs a live server, **[static-ok]** = works offline in `static` mode.
+
+## Architecture: the binding decisions
+
+The system is a **pipeline**: `connect → discover → fan out to five engines → Scorer → Renderer/JSON/badge`. When implementing, these ADRs are constraints, not suggestions:
+
+- **ADR-001 — Engines are pure functions of `ServerSurface` (+ optional live client) → `FamilyScore`.** No engine mutates shared state; the Scorer and Renderer are the *only* aggregators. This is what makes the fast path deterministic and every engine testable with a fixed `ServerSurface` and no network/LLM. Adding a sixth family = implement the `CheckEngine` protocol and register it. **Smuggling shared mutable state into an engine violates the architecture.**
+- **ADR-002 — Zero-LLM fast path is the CI default.** Contract + Cost + Performance run with no model calls (`NFR-1`); Legibility is opt-in and off the critical path. The gate must be satisfiable by the fast path alone.
+- **ADR-003 — Version-aware connect.** The MCP spec is mid-transition (2025-11-25 legacy `initialize` handshake ↔ 2026-07-28 `server/discover` + `_meta`). Negotiate both, grade the result, require neither. This is the hardest correctness surface.
+- **ADR-004 — Canonical Legibility scorer = pinned local model, temp 0, fixed seed, cached by `(surface_hash, model_id, seed, goal_set_version)`.** Cloud models are opt-in and marked non-canonical. A rerun on an unchanged surface is a cache hit → ~$0, byte-identical.
+- **ADR-005 — `--deep-security` shells out and normalizes; never reimplements scanners.** Missing scanner → "not measured", never a failure.
+- **ADR-006 — `static` mode reports live-only checks as "not measured", never `0`.** Zeroing unmeasured checks is a bug (it punishes offline use and is gameable).
+- **ADR-009 — Read-only by default** (`NFR-9`); destructive tools (destructiveHint / heuristic) are skipped unless `--allow-writes`. Probing a `delete_*` tool must not fire it.
+
+### Determinism doctrine (the whole value prop)
+
+The tool grades code in CI, so its own output must be trustworthy:
+- **Fast path** (Contract/Cost/Security-lite built-in): **byte-identical** output for identical input, enforced by golden-file tests. No wall-clock or network-order dependence in scoring.
+- **Legibility**: deterministic only *under a fixed (model, seed, goal-set)*; tests use `StubModel` (never a real LLM) and assert the cache serves reruns with `call_count == 0`.
+- **Performance latencies**: inherently nondeterministic → assert *invariants* (percentile ordering `p50≤p95≤p99`, leak detection, degradation classification), never absolute ms.
+
+### Scoring rubric
+
+Weighted mean of five 0–100 sub-scores → letter grade. Default weights: **Cost 30%, Legibility 25%, Contract 20%, Performance 15%, Security-lite 10%** (see `docs/PRD.md` §7 for rationale). A family scoring **F caps overall at C** (the "hard-gate" — no A-grade server with a broken contract or critical security finding). Every report and badge carries `rubric_version` for cross-release comparability (`NFR-7`).
+
+### Shared primitives (vendored, bound to stampede's contracts)
+
+mcp-quality is project #3 of the seven-project **Swarm Proof** toolkit and reuses four primitives. The portfolio decision is **vendor-first**: copy minimal versions now rather than wait on extraction (~stampede v0.2). But the *contracts* are authoritative and must not be forked:
+- **concurrency-core** — the Performance load driver imports stampede's `Scheduler`/`Executor` **Protocol** and supplies uniform MCP-client tasks (not persona logic).
+- **report-renderer** — render via the shared `RunReport` model (oxblood style); register a `QualityScoreReport` view over it.
+- **trace-format** — **the OpenTelemetry GenAI semantic-conventions *profile*** (`gen_ai.*` spans + the `swarmproof.*` extension), *not* a bespoke schema. The `stampede --from-probe` handoff depends on cross-tool trace compatibility — consume the profile, don't fork it.
+- **persona-pack** — one minimal `naive` persona (`apiVersion: swarmproof.dev/persona/v1`) for the Legibility probe.
+
+## Working conventions
+
+- **Commits:** [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`), atomic, imperative mood, no AI attribution/signatures. Commit progressively as you go.
+- **Testability first:** because engines are pure functions, prefer a component test that feeds a fixed `ServerSurface` and asserts an exact `FamilyScore` over any test that needs a network or a real model. Live/LLM behavior belongs in integration/E2E with fakes (`StubModel`) or the opt-in, network-gated `-m live_llm` suite (excluded from the default/PR run).
+- **Dogfood:** the intended CI runs `mcp-quality` against its own `tests/servers/` fixtures — the tool must grade its own sample servers correctly (see `docs/TEST-PLAN.md` §9).
+- **Honest over impressive:** document boundaries; never zero an unmeasured check; mark non-canonical scores as such.

mcp_quality-0.1.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to mcp-quality are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/); versions follow [SemVer](https://semver.org/).
+
+## [0.1.0] — unreleased
+
+First public release: the CI quality suite for MCP servers. Grades any MCP server across
+five check families into a single **MCP Quality Score**, gates CI, and prints a badge.
+
+### Added
+- **Contract** `[fast]` — JSON-RPC/handshake conformance, JSON-Schema validity,
+  deterministic argument synthesis + invocation, output-shape conformance, and a
+  determinism probe. Read-only by default; destructive tools skipped unless `--allow-writes`.
+- **Cost** `[fast]` — whole-toolset token count, leave-one-out per-tool attribution,
+  $-per-task. Offline-deterministic (tiktoken, labeled as an estimate) with an **opt-in**
+  authoritative Anthropic `count_tokens` path (`--token-model anthropic:<model>`) that
+  falls back silently without a key.
+- **Security-lite** `[fast]` — injection/tool-poisoning, secrets (regex + entropy), and
+  dangerous-capability lints mapped to the **OWASP MCP Top 10** (`MCP01/03/05:2025`);
+  `--deep-security` folds in mcp-scan (Snyk) / Cisco findings when installed.
+- **Performance** `[net]` — concurrent load with real MCP semantics, p50/p95/p99, max
+  stable concurrency, degradation classification, and connection-leak detection.
+- **Legibility** `[llm]` — offline description lints + lexical confusable-shortlist
+  always; a seeded comprehension probe, an **N×N disambiguation matrix**, and proposed
+  rewrites when a model is configured. Results cached by
+  `(surface_hash, model, seed, goal_set)` — warm reruns invoke the model zero times.
+- Transports: **stdio**, **Streamable-HTTP**, and legacy **SSE**; version-aware
+  `initialize` handshake (spec `2025-11-25`).
+- CLI: `run` · `static` (offline/air-gapped) · `snapshot` (+ `--no-regressions`) · `badge`.
+- Outputs: graded terminal report, HTML, versioned JSON (`mcp-quality/report@1`) with
+  `--fail-under`, an SVG + shields.io badge, and the `stampede --from-probe` handoff seed.
+- Scoring: weighted mean (Cost 30 / Legibility 25 / Contract 20 / Performance 15 /
+  Security 10), hard-gate cap at C, versioned rubric (`2026.07.1`).
+- 139 tests (unit + component + integration + E2E over stdio & HTTP/SSE), opt-in
+  `live_llm` / `deep_security` suites, and a dogfooding CI (test / dogfood / determinism /
+  offline jobs).
+- A reproducible [leaderboard](docs/leaderboard.md) of real public MCP servers and a
+  captured [demo](docs/demo.md).
+
+Also included (planned as the "v0.2" milestone, shipped in this first release):
+- **Legibility auto-fix** — `mcp-quality fix` applies the proposed description rewrites to
+  source (name-anchored find/replace), with `--apply` / `--pr` (REQ-L7).
+- **Historical tracking** — `mcp-quality run --record` + `mcp-quality compare` + a sticky PR
+  score-delta comment workflow.
+- **Cost** — response-bloat sampling (`--response-bloat`) and lazy-loading remediation
+  hints (REQ-$5/$6).
+- **Contract** — error-path conformance (malformed input must not crash) + deprecated-SSE
+  forward-compat lint (REQ-C9/C10).
+- **Security** — Cisco `readiness` analyzer folded into Performance/Contract (REQ-S6).
+- **Transport/gating** — HTTP/SSE auth headers (`--header`), per-family gates
+  (`--fail-under-family`).
+- **Registry scoring API** — `mcp-quality serve` (`POST /score` · `/verify` · `/healthz`),
+  in the `[registry]` extra.
+
+### Dependencies
+- Pinned `mcp>=1.28,<2`: SDK v2 renamed `FastMCP`→`MCPServer` and changed result-field
+  casing. Migration to v2 is tracked separately.
+
+### Notes
+- Deviations from the design spec are recorded in [docs/DECISIONS.md](docs/DECISIONS.md)
+  (OWASP MCP Top 10 mapping; why the `2026-07-28` stateless `server/discover` path is not
+  yet implemented; the offline-token estimate).
+
+[0.1.0]: https://github.com/swarmproof/mcp-probe/releases/tag/v0.1.0

mcp_quality-0.1.0/CITATION.cff

@@ -0,0 +1,16 @@
+cff-version: 1.2.0
+message: "If you use this software or dataset, please cite it as below."
+title: "mcp-quality"
+abstract: "The CI quality suite for MCP server builders. Part of the Swarm Proof toolkit."
+authors:
+  - family-names: Boudoukha
+    given-names: Maroua
+repository-code: "https://github.com/swarmproof/mcp-probe"
+url: "https://github.com/swarmproof/mcp-probe"
+license: Apache-2.0
+type: software
+keywords:
+  - ai-agents
+  - agent-reliability
+  - llm
+  - mcp