Content
# mcp-prompts-resources
Validate and grade an MCP server's **resources** and **prompts** primitives, A to F, over the stdio transport.
The Model Context Protocol has three primitives: `tools`, `resources`, and `prompts`. Most tooling only ever looks at `tools`. This CLI is for the other two. It launches your MCP server, exercises its resource and prompt surface, and reports a graded scorecard you can gate a CI pipeline on.
- Zero dependencies (Python standard library only, 3.9+)
- Grades four dimensions: resource hygiene, prompt hygiene, capability consistency, error correctness
- Output as console, JSON, Markdown, or a shields.io badge
- `--min-grade` gate for CI (non-zero exit on failure)
- Ships a healthy sample server (grades A) and a broken one (grades F) so you can try it immediately
## Install
```bash
pip install .
# or run without installing:
python -m mcp_prompts_resources --help
```
## Quick start
Try the bundled samples:
```bash
mcp-prompts-resources --sample healthy
mcp-prompts-resources --sample broken
```
Point it at your own server (anything launched over stdio):
```bash
mcp-prompts-resources -- python my_server.py
mcp-prompts-resources --command "node build/index.js" --format markdown
```
Gate a build so it fails below grade B:
```bash
mcp-prompts-resources --command "python my_server.py" --min-grade B
```
## What it checks
**Resource hygiene**
- Each listed resource has a `name` and a `uri` with a valid scheme
- `mimeType` is present and well-formed (recommended)
- Advertised URI templates are valid RFC 6570
- `resources/read` on each listed resource returns contents whose `uri` matches and that carry a `text` or `blob` body
**Prompt hygiene**
- Each prompt has a `name` and well-formed argument definitions
- `prompts/get` with all required arguments supplied returns a valid `messages` array with proper roles
- The rendered prompt has no leftover `{{placeholder}}` or `{arg}` tokens
**Capability consistency**
- A server that serves resources or prompts also declares the matching capability (and vice versa)
- If `resources.subscribe` is advertised, a `resources/subscribe` call actually works
- The server writes only JSON to stdout (stdio transport hygiene)
**Error correctness**
- Reading an unknown resource returns a clean JSON-RPC error, not a fake success
- `prompts/get` with a missing required argument errors instead of ignoring it
- `prompts/get` for an unknown prompt name errors
- The server stays alive after each bad-input probe (a crash is a critical finding)
## Grading
Each dimension starts at 100 and loses points per finding by severity (critical 40, high 25, medium 15, low 8, floored at 0). The overall score is the weight-normalised average over the dimensions that actually applied, so a prompts-only server is not penalised for having no resources. Any critical finding caps the overall grade at D.
| Dimension | Weight |
| --- | --- |
| Resource hygiene | 30% |
| Prompt hygiene | 30% |
| Capability consistency | 20% |
| Error correctness | 20% |
Letters: A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F below 60.
## Output formats
```bash
mcp-prompts-resources --sample healthy --format console # default
mcp-prompts-resources --sample healthy --format json
mcp-prompts-resources --sample healthy --format markdown
mcp-prompts-resources --sample healthy --format badge # shields.io URL
mcp-prompts-resources --sample healthy --format badge-endpoint # shields endpoint JSON
```
## Options
```
--command STR server command as a single string
--sample {healthy,broken} run against a bundled sample server
-- <cmd...> server command after a bare --
--only {resources,prompts} check just one primitive
--format {console,json,markdown,badge,badge-endpoint}
--min-grade A..F exit 1 if the overall grade is below this
--timeout SECONDS per-request timeout (default 10)
```
## Exit codes
- `0` passed (or no gate set)
- `1` overall grade below `--min-grade`
- `2` usage error or the server failed to launch
## CI example
```yaml
- name: Grade MCP prompts and resources
run: mcp-prompts-resources --command "python my_server.py" --min-grade B
```
## Where it fits
This is the prompts-and-resources counterpart to the tool-focused MCP checkers. Use it alongside conformance, surface-diff, fuzz, load, and context-budget tooling; it slots in cleanly as another scorecard dimension.
## License
MIT
MCP Store