Metadata-Version: 2.4
Name: mcp-scorecard
Version: 0.1.1
Summary: Pre-flight checks for MCP servers: passive token footprint, use-case scoping, security, and name safety. LLM-facing quality scorecard.
Project-URL: Homepage, https://github.com/kenimo49/mcp-scorecard
Project-URL: Repository, https://github.com/kenimo49/mcp-scorecard
Project-URL: Issues, https://github.com/kenimo49/mcp-scorecard/issues
Project-URL: Funding, https://github.com/sponsors/kenimo49
Author: Ken Imoto
License: MIT
License-File: LICENSE
Keywords: audit,llm,mcp,model-context-protocol,pre-flight,security,token
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: levenshtein>=0.25
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: tiktoken>=0.7
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == 'mcp'
Description-Content-Type: text/markdown

# mcp-scorecard

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![GitHub Sponsors](https://img.shields.io/github/sponsors/kenimo49?logo=githubsponsors&label=Sponsor)](https://github.com/sponsors/kenimo49)
[![Ko-fi](https://img.shields.io/badge/Ko--fi-tip-FF5E5B?logo=kofi&logoColor=white)](https://ko-fi.com/kenimo49)

> ⚠️ **Status: v0.1 alpha — under active development.**
> Rules, thresholds, and scoring are being calibrated against real-world MCP servers.

Pre-flight checks for MCP (Model Context Protocol) servers.

`mcp-scorecard` answers one question: **"Is this MCP server safe and efficient enough for LLMs to actually use?"** — before you publish it, install it, or let it into your agent config.

Existing MCP tools cover runtime security (MCP-Scan) and protocol compliance (MCP Inspector). This one covers the missing layer: **how expensive is the server just to keep registered, and are its tools scoped well enough for an LLM to pick the right one?**

Companion tool to the book **『MCP実践セキュリティ』** (Impress NextPublishing).

## The four layers

| Layer | What it measures | Status |
|-------|------------------|--------|
| **A. Passive Footprint** | Tokens the server steals from every LLM turn just by being listed. `tools/list` initial load, per-tool cost, bloat ratio, schema verbosity | v0.1 |
| **B. Use-Case Scoping** | Whether each tool is narrow enough that the LLM knows when to use it. When-to-use present, vague verb scan, overlap detection, naming consistency, AI Slop | v0.1 |
| **C. Security** | Own rules (prompt injection in description, tool shadowing, hardcoded secrets, transport hygiene) + optional MCP-Scan wrap | v0.1 own rules; wrap in v0.2 |
| **D. Name Safety** | Case collision, brand similarity, separator variants, namespace hygiene | v0.1 |

Design details: [docs/design.md](docs/design.md).

## Install

```bash
pip install mcp-scorecard              # CLI + library
pip install "mcp-scorecard[mcp]"       # + MCP server (stdio)
```

## Use as a CLI

```bash
# Full scan
mcp-scorecard scan ./path/to/server.py
mcp-scorecard scan http://localhost:8000/
mcp-scorecard scan pypi:some-mcp

# Layer-only
mcp-scorecard footprint ./server.py
mcp-scorecard scoping ./server.py
mcp-scorecard security ./server.py
mcp-scorecard name my-new-mcp

# CI-friendly
mcp-scorecard scan ./server.py --json
mcp-scorecard scan ./server.py --format sarif
# exit codes: 0=GREEN/YELLOW, 1=ORANGE, 2=RED
```

## Use as an MCP server (self-hosting)

Register `mcp-scorecard` itself as an MCP tool in Claude Code / Cursor / Windsurf, then ask the LLM to audit another MCP:

```json
{
  "mcpServers": {
    "mcp-scorecard": {
      "command": "mcp-scorecard-mcp"
    }
  }
}
```

Then in chat: *"score the MCP server at ./my-server.py"*.

## Why passive footprint matters

Every tool description and inputSchema in a registered MCP server is sent to the LLM on every turn — because the model needs to see them to decide which tool to call. A single verbose server can silently burn 5,000+ tokens per turn before anyone touches it.

`mcp-scorecard footprint` measures exactly that, so you can trim before you publish.

## Roadmap

- **v0.1** — Layers A + B + D full, Layer C own rules, CLI + MCP server
- **v0.2** — MCP-Scan wrap, SARIF, real MCP client negotiation
- **v0.3** — Book『MCP実践セキュリティ』章別ルール取り込み
- **v0.4** — Registry-source targets (`github:` / `npm:`)

## Support this project

- 💚 [GitHub Sponsors](https://github.com/sponsors/kenimo49)
- ☕ [Ko-fi](https://ko-fi.com/kenimo49)

## License

MIT.
