mcp-reportcard 0.1.0__tar.gz

mcp_reportcard-0.1.0/.env.example

@@ -0,0 +1,2 @@
+# mcp-reportcard v1 needs no environment variables or API keys.
+# (The planned tool-selection eval will read a model API key from here.)

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

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+      - name: Dogfood on the good example
+        run: mcp-reportcard check "python examples/good_server.py" --fuzz --fail-under 90 -f markdown

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

@@ -0,0 +1,40 @@
+name: Release to PyPI
+
+# Publishes when a GitHub Release is published (e.g. tag v0.1.0).
+# Uses PyPI Trusted Publishing (OIDC): no API token is stored anywhere.
+# One-time setup on pypi.org: add a "pending publisher" for this repo,
+# workflow file `release.yml`, environment `pypi`.
+
+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"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

mcp_reportcard-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.env
+reports/
+space/_site/

mcp_reportcard-0.1.0/FINDINGS.md

@@ -0,0 +1,35 @@
+# FINDINGS — mcp-reportcard field test
+
+Date: 2026-11-14 · mcp-reportcard v0.1.0 · Windows 11, Python 3.13, Node 22 · every run used `--fuzz` (read-only tools only)
+
+## Servers tested
+| Server | Version | Language | Transport |
+|---|---|---|---|
+| @modelcontextprotocol/server-everything | 2.3.0 | Node | stdio **and** Streamable HTTP |
+| @modelcontextprotocol/server-filesystem | 2.3.0 | Node | stdio |
+| @modelcontextprotocol/server-memory | 2.1.1 | Node | stdio |
+| mcp-server-fetch | 2026.11.11 | Python | stdio |
+| mcp-server-time | 2026.11.11 | Python | stdio |
+| mcp-server-git | 2026.11.11 | Python | stdio |
+
+All six connected and completed without crashes. 159 fuzz cases were sent in total.
+
+## False positives found and fixed
+1. **F002 "leaks internals" fired on file paths.** The filesystem and git servers return messages like `Repository path 'x' is outside the allowed repository 'C:\...\repo'`. That's helpful, not a leak. F002 now matches only real stack traces (Python, Node, JVM, Go, Rust). The filesystem server went from B 88 to A 100.
+2. **D005 "no when-to-use guidance" was noise.** It fired on 30 tools across well-written servers, e.g. fetch's single tool. It now fires only when a tool has a similar sibling (≥35% word overlap) the model could confuse it with, and it names that sibling.
+3. **Connection failures printed an unreadable `ExceptionGroup`.** The CLI now digs out the root cause, e.g. "Connection closed (the server exited during startup; rerun with --server-logs to see its output)".
+
+## Final results (after fixes)
+| Server | Grade | Score | Tools | Tokens/turn | Fuzz cases | Fuzz problems | Remaining issues |
+|---|---|---:|---:|---:|---:|---:|---|
+| everything | A | 94 | 22 | 2,797 | 32 | 0 | X001 (two async trigger tools described almost identically), D005 ×6 |
+| fetch | A | 100 | 1 | 296 | 6 | 0 | none |
+| filesystem | A | 100 | 16 | 2,925 | 46 | 0 | none |
+| memory | A | 99 | 9 | 1,736 | 10 | 0 | D005 ×2 |
+| time | A | 98 | 3 | 500 | 20 | 0 | D005 ×2 |
+| git | B | 83 | 14 | 1,435 | 45 | 0 | S003 (parameters have a `title` but no `description`), D002, D005 |
+
+## Assessment
+- **The remaining findings look legitimate.** git's undocumented parameters are a real, common Python issue: pydantic generates `title` but not `description`. The everything server's two async trigger tools really are described almost word for word alike.
+- **Fuzzing:** every server rejected bad input cleanly. Skipped tools were exactly the ones not annotated read-only, as designed.
+- **Not covered yet:** CI on Linux and macOS (runs once pushed to GitHub), community servers outside the official set, and servers that need authentication.

mcp_reportcard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scaleup Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_reportcard-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: mcp-reportcard
+Version: 0.1.0
+Summary: A health check for MCP servers: lint tool descriptions and schemas, estimate token cost, fuzz error handling, and get a graded report card.
+Project-URL: Homepage, https://scaleup-solutions.in/
+Project-URL: Repository, https://github.com/builditwithgk/mcp-reportcard
+Project-URL: Issues, https://github.com/builditwithgk/mcp-reportcard/issues
+Author: Gopi K Aitham (builditwithgk)
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,fuzzing,lint,llm,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: mcp>=2.0
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: flask>=3.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: tiktoken>=0.7; extra == 'dev'
+Provides-Extra: tokens
+Requires-Dist: tiktoken>=0.7; extra == 'tokens'
+Provides-Extra: web
+Requires-Dist: flask>=3.0; extra == 'web'
+Description-Content-Type: text/markdown
+
+# mcp-reportcard
+
+> **A health check for MCP servers.** Lint your tools, measure their token cost, fuzz their error handling — and get a graded report card with a concrete fix for every issue.
+
+![Python](https://img.shields.io/badge/python-3.10%2B-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Version](https://img.shields.io/badge/version-0.1.0-blue) ![MCP](https://img.shields.io/badge/MCP-any%20server%2C%20any%20language-brightgreen) [![CI](https://github.com/builditwithgk/mcp-reportcard/actions/workflows/ci.yml/badge.svg)](https://github.com/builditwithgk/mcp-reportcard/actions/workflows/ci.yml) [![Hugging Face Space](https://img.shields.io/badge/%F0%9F%A4%97%20Space-live%20demo-yellow)](https://huggingface.co/spaces/builditwithgk/mcp-reportcard)
+
+When an agent picks the wrong tool, sends malformed arguments, or burns context on bloated definitions, the cause is usually in the server — and the model only ever sees what your `tools/list` says. `mcp-reportcard` checks exactly that, in seconds, for any MCP server in any language.
+
+**Try it in the browser:** [huggingface.co/spaces/builditwithgk/mcp-reportcard](https://huggingface.co/spaces/builditwithgk/mcp-reportcard) — paste a `tools/list` JSON, get the report card.
+
+## Why it's different
+
+**It grades what the model sees, not what your code does.**
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is for poking at a server by hand. `mcp-reportcard` is automated and opinionated: it scores tool names, descriptions, schemas and safety annotations against the things that actually make models misbehave — vague descriptions, undocumented parameters, near-duplicate tools, missing `readOnlyHint`s, stack traces in error replies — and it runs in CI.
+
+Every finding comes with a rule ID, a severity and a specific fix. No LLM is involved in the checks, so results are deterministic and safe to gate a merge on.
+
+## Example output
+
+Running against the deliberately sloppy server in [`examples/bad_server.py`](https://github.com/builditwithgk/mcp-reportcard/blob/main/examples/bad_server.py):
+
+```text
+┌──────── mcp-reportcard · acme-orders (bad example) ─────────┐
+│ Grade D  ·  score 67/100                                 │
+│ 7 tools  ·  1 errors  ·  16 warnings  ·  5 info          │
+│ ~351 tokens per turn (tiktoken o200k_base (approximate)) │
+└──────────────────────────────────────────────────────────┘
+  F002 lookup_invoice Error output exposes internals: `Traceback (most recent call last)`
+       fix: Log stack traces server-side; return a short, safe message to the client.
+  X001 server `find_items` and `search_items` are described almost the same way (88% word overlap)
+       fix: Say in each description when to use it instead of the other, or merge them.
+  ...
+```
+
+The same service written properly, [`examples/good_server.py`](https://github.com/builditwithgk/mcp-reportcard/blob/main/examples/good_server.py), scores **A (100)**.
+
+**Field-tested:** run against six official MCP reference servers (Node and Python, stdio and HTTP) — 159 fuzz cases, zero crashes, and two over-eager rules fixed as a result. Numbers and details in [`FINDINGS.md`](https://github.com/builditwithgk/mcp-reportcard/blob/main/FINDINGS.md).
+
+## Install & run
+
+Requires Python 3.10+.
+
+```bash
+pip install "mcp-reportcard[tokens] @ git+https://github.com/builditwithgk/mcp-reportcard"
+
+# …or from source
+git clone https://github.com/builditwithgk/mcp-reportcard
+cd mcp-reportcard
+pip install -e ".[dev]"
+```
+
+A PyPI release (`pip install mcp-reportcard`) is coming. The `[tokens]` extra adds tiktoken for more accurate token counts; without it, a characters/4 estimate is used.
+
+## Command line
+
+```bash
+# A stdio server (any language): pass the command that starts it
+mcp-reportcard check "python server.py"
+mcp-reportcard check "npx -y @modelcontextprotocol/server-everything"
+
+# A Streamable HTTP server
+mcp-reportcard check http://localhost:8000/mcp
+
+# A saved tools/list JSON (offline, no server needed)
+mcp-reportcard check tools.json
+
+# Also test error handling with bad inputs (read-only tools only — see below)
+mcp-reportcard check "python server.py" --fuzz
+
+# Reports for PRs and CI
+mcp-reportcard check "python server.py" -f markdown -o report.md
+mcp-reportcard check "python server.py" -f json --fail-under 80
+
+# Save a server's tool list (for offline checks or the web demo)
+mcp-reportcard dump "python server.py" -o tools.json
+
+# List every check
+mcp-reportcard rules
+```
+
+## Use in CI
+
+`--fail-under` exits 1 when the score drops below the threshold:
+
+```yaml
+# .github/workflows/mcp-reportcard.yml
+on: pull_request
+jobs:
+  mcp-reportcard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install "mcp-reportcard @ git+https://github.com/builditwithgk/mcp-reportcard"
+      - run: mcp-reportcard check "python server.py" --fuzz -f markdown -o mcp-reportcard.md --fail-under 80
+```
+
+This repo dogfoods it: CI runs `mcp-reportcard` against [`examples/good_server.py`](https://github.com/builditwithgk/mcp-reportcard/blob/main/examples/good_server.py) with `--fail-under 90` on Linux, macOS and Windows.
+
+## What it checks
+
+| ID | Severity | Check |
+| --- | --- | --- |
+| N001–N005 | error / warning / info | Missing, duplicate, invalid or over-long names; mixed naming styles |
+| D001–D005 | error / warning / info | Missing, too short, too long, or name-restating descriptions; no "when to use" guidance when a similar tool exists |
+| S001–S008 | error / warning / info | Missing object schema, untyped or undocumented parameters, broken `required`, free-form objects, deep nesting, missing `enum`, too many parameters |
+| A001–A002 | warning | Missing or contradictory `readOnlyHint` / `destructiveHint` |
+| T001, X002 | info / warning | Heavy tool definitions; total token cost per turn |
+| X001, X003, X004 | warning / error | Tools with overlapping descriptions; too many tools; no tools |
+| F001–F003 | warning / error | (fuzz) Accepts schema-violating input; leaks stack traces; crashes or hangs |
+
+**Scoring:** each tool starts at 100 and loses 25 per error, 10 per warning and 3 per info. The server score is the average tool score minus server-level penalties (capped at 40). Grades: A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F below.
+
+## Fuzzing safety
+
+`--fuzz` calls your tools with missing arguments, wrong types, out-of-enum values, 10,000-character strings and tricky Unicode, then checks for clean `isError` responses.
+
+- By default it **only calls tools annotated `readOnlyHint: true`** (and not `destructiveHint: true`). Everything else is skipped — and listed in the report, never silently.
+- `--allow-unsafe` fuzzes every tool. **Only use it against a test instance**, never production data.
+- A stdio server's own stderr is hidden to keep the report readable; add `--server-logs` to see it.
+
+## Web demo
+
+The demo runs the static checks only — it never connects to servers, calls tools or contacts an LLM, and nothing pasted is stored. Because the core is pure standard-library Python, it ships two ways from the same code:
+
+- **In the browser** — [`space/`](https://github.com/builditwithgk/mcp-reportcard/tree/main/space) is a static page that runs `src/mcp_reportcard` client-side with [Pyodide](https://pyodide.org). That's the [Hugging Face Space](https://huggingface.co/spaces/builditwithgk/mcp-reportcard): no server, free tier. `bash space/build.sh` assembles it into `space/_site/`; `bash space/deploy.sh` publishes it. The same folder works on GitHub Pages or any static host.
+- **As a Flask app** — [`web/`](https://github.com/builditwithgk/mcp-reportcard/tree/main/web), for Python hosting such as cPanel: create a Python app with `web/` as the root and `passenger_wsgi.py` as the startup file, install `web/requirements.txt`, and upload `src/` and `examples/` alongside.
+
+```bash
+pip install flask
+python web/app.py     # http://localhost:5000
+```
+
+## Limitations
+
+- Token counts are **estimates**. Each provider wraps tool definitions in its own format; use the numbers to compare tools and track changes, not as a bill.
+- Description checks are heuristics. A D005 ("no usage guidance") is a nudge, not a hard rule.
+- Leak detection (F002) looks for stack traces only. File paths in error messages are not flagged — file and git tools legitimately name paths.
+- Fuzzing can't prove a tool is correct; it shows how it fails on bad input.
+- v1 checks tools only, not resources or prompts.
+
+## Roadmap
+
+- Tool-selection eval (bring your own API key): generate realistic tasks per tool and measure how often a model picks the right one.
+- README badge (`mcp-reportcard: A`).
+- Resource and prompt checks.
+- PyPI release.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest
+```
+
+Tests cover every lint rule, scoring, leak detection, fuzz-case generation, the CLI and the web demo — plus end-to-end runs against both example servers, in-process and as real stdio subprocesses.
+
+## Author
+
+Built by **Gopi K Aitham** ([builditwithgk](https://github.com/builditwithgk)) — see [scaleup-solutions.in](https://scaleup-solutions.in/). Available for freelance and contract work on AI, agent, and MCP tooling.
+
+## License
+
+MIT

mcp_reportcard-0.1.0/README.md

@@ -0,0 +1,167 @@
+# mcp-reportcard
+
+> **A health check for MCP servers.** Lint your tools, measure their token cost, fuzz their error handling — and get a graded report card with a concrete fix for every issue.
+
+![Python](https://img.shields.io/badge/python-3.10%2B-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Version](https://img.shields.io/badge/version-0.1.0-blue) ![MCP](https://img.shields.io/badge/MCP-any%20server%2C%20any%20language-brightgreen) [![CI](https://github.com/builditwithgk/mcp-reportcard/actions/workflows/ci.yml/badge.svg)](https://github.com/builditwithgk/mcp-reportcard/actions/workflows/ci.yml) [![Hugging Face Space](https://img.shields.io/badge/%F0%9F%A4%97%20Space-live%20demo-yellow)](https://huggingface.co/spaces/builditwithgk/mcp-reportcard)
+
+When an agent picks the wrong tool, sends malformed arguments, or burns context on bloated definitions, the cause is usually in the server — and the model only ever sees what your `tools/list` says. `mcp-reportcard` checks exactly that, in seconds, for any MCP server in any language.
+
+**Try it in the browser:** [huggingface.co/spaces/builditwithgk/mcp-reportcard](https://huggingface.co/spaces/builditwithgk/mcp-reportcard) — paste a `tools/list` JSON, get the report card.
+
+## Why it's different
+
+**It grades what the model sees, not what your code does.**
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is for poking at a server by hand. `mcp-reportcard` is automated and opinionated: it scores tool names, descriptions, schemas and safety annotations against the things that actually make models misbehave — vague descriptions, undocumented parameters, near-duplicate tools, missing `readOnlyHint`s, stack traces in error replies — and it runs in CI.
+
+Every finding comes with a rule ID, a severity and a specific fix. No LLM is involved in the checks, so results are deterministic and safe to gate a merge on.
+
+## Example output
+
+Running against the deliberately sloppy server in [`examples/bad_server.py`](https://github.com/builditwithgk/mcp-reportcard/blob/main/examples/bad_server.py):
+
+```text
+┌──────── mcp-reportcard · acme-orders (bad example) ─────────┐
+│ Grade D  ·  score 67/100                                 │
+│ 7 tools  ·  1 errors  ·  16 warnings  ·  5 info          │
+│ ~351 tokens per turn (tiktoken o200k_base (approximate)) │
+└──────────────────────────────────────────────────────────┘
+  F002 lookup_invoice Error output exposes internals: `Traceback (most recent call last)`
+       fix: Log stack traces server-side; return a short, safe message to the client.
+  X001 server `find_items` and `search_items` are described almost the same way (88% word overlap)
+       fix: Say in each description when to use it instead of the other, or merge them.
+  ...
+```
+
+The same service written properly, [`examples/good_server.py`](https://github.com/builditwithgk/mcp-reportcard/blob/main/examples/good_server.py), scores **A (100)**.
+
+**Field-tested:** run against six official MCP reference servers (Node and Python, stdio and HTTP) — 159 fuzz cases, zero crashes, and two over-eager rules fixed as a result. Numbers and details in [`FINDINGS.md`](https://github.com/builditwithgk/mcp-reportcard/blob/main/FINDINGS.md).
+
+## Install & run
+
+Requires Python 3.10+.
+
+```bash
+pip install "mcp-reportcard[tokens] @ git+https://github.com/builditwithgk/mcp-reportcard"
+
+# …or from source
+git clone https://github.com/builditwithgk/mcp-reportcard
+cd mcp-reportcard
+pip install -e ".[dev]"
+```
+
+A PyPI release (`pip install mcp-reportcard`) is coming. The `[tokens]` extra adds tiktoken for more accurate token counts; without it, a characters/4 estimate is used.
+
+## Command line
+
+```bash
+# A stdio server (any language): pass the command that starts it
+mcp-reportcard check "python server.py"
+mcp-reportcard check "npx -y @modelcontextprotocol/server-everything"
+
+# A Streamable HTTP server
+mcp-reportcard check http://localhost:8000/mcp
+
+# A saved tools/list JSON (offline, no server needed)
+mcp-reportcard check tools.json
+
+# Also test error handling with bad inputs (read-only tools only — see below)
+mcp-reportcard check "python server.py" --fuzz
+
+# Reports for PRs and CI
+mcp-reportcard check "python server.py" -f markdown -o report.md
+mcp-reportcard check "python server.py" -f json --fail-under 80
+
+# Save a server's tool list (for offline checks or the web demo)
+mcp-reportcard dump "python server.py" -o tools.json
+
+# List every check
+mcp-reportcard rules
+```
+
+## Use in CI
+
+`--fail-under` exits 1 when the score drops below the threshold:
+
+```yaml
+# .github/workflows/mcp-reportcard.yml
+on: pull_request
+jobs:
+  mcp-reportcard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install "mcp-reportcard @ git+https://github.com/builditwithgk/mcp-reportcard"
+      - run: mcp-reportcard check "python server.py" --fuzz -f markdown -o mcp-reportcard.md --fail-under 80
+```
+
+This repo dogfoods it: CI runs `mcp-reportcard` against [`examples/good_server.py`](https://github.com/builditwithgk/mcp-reportcard/blob/main/examples/good_server.py) with `--fail-under 90` on Linux, macOS and Windows.
+
+## What it checks
+
+| ID | Severity | Check |
+| --- | --- | --- |
+| N001–N005 | error / warning / info | Missing, duplicate, invalid or over-long names; mixed naming styles |
+| D001–D005 | error / warning / info | Missing, too short, too long, or name-restating descriptions; no "when to use" guidance when a similar tool exists |
+| S001–S008 | error / warning / info | Missing object schema, untyped or undocumented parameters, broken `required`, free-form objects, deep nesting, missing `enum`, too many parameters |
+| A001–A002 | warning | Missing or contradictory `readOnlyHint` / `destructiveHint` |
+| T001, X002 | info / warning | Heavy tool definitions; total token cost per turn |
+| X001, X003, X004 | warning / error | Tools with overlapping descriptions; too many tools; no tools |
+| F001–F003 | warning / error | (fuzz) Accepts schema-violating input; leaks stack traces; crashes or hangs |
+
+**Scoring:** each tool starts at 100 and loses 25 per error, 10 per warning and 3 per info. The server score is the average tool score minus server-level penalties (capped at 40). Grades: A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F below.
+
+## Fuzzing safety
+
+`--fuzz` calls your tools with missing arguments, wrong types, out-of-enum values, 10,000-character strings and tricky Unicode, then checks for clean `isError` responses.
+
+- By default it **only calls tools annotated `readOnlyHint: true`** (and not `destructiveHint: true`). Everything else is skipped — and listed in the report, never silently.
+- `--allow-unsafe` fuzzes every tool. **Only use it against a test instance**, never production data.
+- A stdio server's own stderr is hidden to keep the report readable; add `--server-logs` to see it.
+
+## Web demo
+
+The demo runs the static checks only — it never connects to servers, calls tools or contacts an LLM, and nothing pasted is stored. Because the core is pure standard-library Python, it ships two ways from the same code:
+
+- **In the browser** — [`space/`](https://github.com/builditwithgk/mcp-reportcard/tree/main/space) is a static page that runs `src/mcp_reportcard` client-side with [Pyodide](https://pyodide.org). That's the [Hugging Face Space](https://huggingface.co/spaces/builditwithgk/mcp-reportcard): no server, free tier. `bash space/build.sh` assembles it into `space/_site/`; `bash space/deploy.sh` publishes it. The same folder works on GitHub Pages or any static host.
+- **As a Flask app** — [`web/`](https://github.com/builditwithgk/mcp-reportcard/tree/main/web), for Python hosting such as cPanel: create a Python app with `web/` as the root and `passenger_wsgi.py` as the startup file, install `web/requirements.txt`, and upload `src/` and `examples/` alongside.
+
+```bash
+pip install flask
+python web/app.py     # http://localhost:5000
+```
+
+## Limitations
+
+- Token counts are **estimates**. Each provider wraps tool definitions in its own format; use the numbers to compare tools and track changes, not as a bill.
+- Description checks are heuristics. A D005 ("no usage guidance") is a nudge, not a hard rule.
+- Leak detection (F002) looks for stack traces only. File paths in error messages are not flagged — file and git tools legitimately name paths.
+- Fuzzing can't prove a tool is correct; it shows how it fails on bad input.
+- v1 checks tools only, not resources or prompts.
+
+## Roadmap
+
+- Tool-selection eval (bring your own API key): generate realistic tasks per tool and measure how often a model picks the right one.
+- README badge (`mcp-reportcard: A`).
+- Resource and prompt checks.
+- PyPI release.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest
+```
+
+Tests cover every lint rule, scoring, leak detection, fuzz-case generation, the CLI and the web demo — plus end-to-end runs against both example servers, in-process and as real stdio subprocesses.
+
+## Author
+
+Built by **Gopi K Aitham** ([builditwithgk](https://github.com/builditwithgk)) — see [scaleup-solutions.in](https://scaleup-solutions.in/). Available for freelance and contract work on AI, agent, and MCP tooling.
+
+## License
+
+MIT

mcp_reportcard-0.1.0/examples/bad_server.py

@@ -0,0 +1,65 @@
+"""A deliberately sloppy MCP server for demos and tests. Every tool has a common mistake.
+
+Run:  mcp-reportcard check "python examples/bad_server.py" --fuzz
+"""
+
+import traceback
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp_types import ToolAnnotations
+
+server = MCPServer("acme-orders (bad example)")
+
+ORDERS = {"1001": {"status": "shipped", "total": 49.0}, "1002": {"status": "pending", "total": 12.5}}
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=True))
+def search(query: str, mode: str = "fuzzy") -> list[str]:
+    """Search."""  # too short, `mode` should be an enum, no parameter descriptions
+    return [oid for oid in ORDERS if query in oid]
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=True))
+def find_items(keyword: str) -> list[str]:
+    """Search the store catalogue items by keyword and return the matching items."""
+    return []
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=True))
+def search_items(keyword: str) -> list[str]:
+    """Search store catalogue items by keyword and return matching catalogue items."""
+    return []  # near-duplicate of find_items: the model can't tell which to use
+
+
+@server.tool()
+def getCustomer(id: str) -> dict:  # noqa: N802  camelCase mixed with snake_case, no annotations
+    """Get customer"""
+    return {"id": id}
+
+
+@server.tool(annotations=ToolAnnotations(read_only_hint=True))
+def lookup_invoice(invoice_id: str) -> dict:
+    """Look up an invoice by its numeric ID and return the amount due."""
+    try:
+        n = int(invoice_id)
+        return {"invoice": n, "due": 0}
+    except Exception:
+        raise ToolError(traceback.format_exc())  # leaks a stack trace and file paths
+
+
+@server.tool()
+def delete_order(order_id: str) -> str:
+    """Deletes an order permanently."""  # destructive, but not annotated as such
+    ORDERS.pop(order_id, None)
+    return "deleted"
+
+
+@server.tool()
+def update_settings(settings: dict) -> str:
+    """Update account settings."""  # free-form object: the model must guess the keys
+    return "ok"
+
+
+if __name__ == "__main__":
+    server.run()