# Mcpgauge

> A deterministic, offline quality grader for MCP servers. pip install mcpgauge

- **Type:** MCP server
- **Install:** `agentstack add mcp-michael-whitecapdata-mcpgauge`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Michael-WhiteCapData](https://agentstack.voostack.com/s/michael-whitecapdata)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Michael-WhiteCapData](https://github.com/Michael-WhiteCapData)
- **Source:** https://github.com/Michael-WhiteCapData/mcpgauge

## Install

```sh
agentstack add mcp-michael-whitecapdata-mcpgauge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcpgauge

**Grade an MCP server's tool definitions in seconds — deterministic, offline, no account.**

[](https://github.com/Michael-WhiteCapData/mcpgauge/actions/workflows/ci.yml)
[](https://pypi.org/project/mcpgauge/)
[](https://www.python.org/)
[](LICENSE)

An agent only uses an [MCP](https://modelcontextprotocol.io/) server well if its
**tool definitions** are clear — good names, real descriptions, documented
parameters. `mcpgauge` launches a server, reads its tools, and scores their
definition quality against a [published, deterministic rubric](docs/METHODOLOGY.md).
No LLM, no network beyond the server you point it at, no sign-up.

## Quickstart

```bash
pipx install mcpgauge          # or: uvx mcpgauge ...
mcpgauge "uvx ollama-handoff"
```

```
Grade A  (4.18/5)  —  8 tools
mean 4.31 · min 3.72 · methodology v0

  [B] summarize_local  3.72/5
      purpose █████  params █████  behavior █████  schema █████  naming █████  concise ████·
  [A] query  4.80/5
      ...
```

- `--json` — machine-readable output for tooling.
- `--min B` — exit non-zero if the server grades below `B` (drop it in CI).
- `--quiet` — print only the final grade line.

## Why it exists

Most MCP servers are thin wrappers with vague tool descriptions, and agents pick
the wrong tool as a result. The only comparable quality score is closed and
requires registering your server on a third-party site. `mcpgauge` is the
opposite: **open methodology, offline, reproducible, and CI-runnable.** You can
read exactly how every point is awarded in [docs/METHODOLOGY.md](docs/METHODOLOGY.md)
and argue with it.

## How scoring works (short version)

Each tool is scored 0–5 on six dimensions — Purpose Clarity, Parameter Semantics,
Behavioral Transparency, Schema Validity, Naming, Conciseness. The server score is
`0.6 · mean + 0.4 · min` across tools, so one badly-described tool drags the whole
server down (which is exactly how agents fail). Full rubric:
[docs/METHODOLOGY.md](docs/METHODOLOGY.md).

## Status

Early and honest: v0 of the rubric, stdio servers, deterministic checks only. An
optional LLM "would an agent pick the right tool?" pass and remote-HTTP support are
on the roadmap. Issues and rubric critiques welcome.

## Development

```bash
uv pip install -e ".[dev]"
pytest
ruff check src tests
```

## License

MIT — see [LICENSE](LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Michael-WhiteCapData](https://github.com/Michael-WhiteCapData)
- **Source:** [Michael-WhiteCapData/mcpgauge](https://github.com/Michael-WhiteCapData/mcpgauge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-michael-whitecapdata-mcpgauge
- Seller: https://agentstack.voostack.com/s/michael-whitecapdata
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.