mcp-medic 1.2.2 → 1.2.4

package/README.md

@@ -4,9 +4,9 @@
 [![npm version](https://img.shields.io/npm/v/mcp-medic.svg)](https://www.npmjs.com/package/mcp-medic)
 [![license](https://img.shields.io/npm/l/mcp-medic.svg)](./LICENSE)
 
-Diagnose broken MCP (Model Context Protocol) server configs before they break your agent silently.
+An MCP quality gate for developers and CI — not just "does my config parse," but "is this MCP server high-quality, safe, well-described, and usable by an AI agent."
 
-`mcp-medic` validates MCP server configurations, executes full protocol initialization handshakes across stdio/SSE/HTTP transports, checks all exposed tool JSON schemas against standard specifications, and simulates sample calls — providing actionable suggestions and CI-ready exit codes.
+`mcp-medic` validates MCP server configurations, executes full protocol initialization handshakes across stdio/SSE/HTTP transports (with real protocol version negotiation), passively inspects every declared tool/resource/prompt, checks JSON schemas against the MCP spec, and computes a deterministic 0–100 **MCP Quality Score** — providing actionable diagnostics, a stable diagnostic taxonomy, and CI-ready exit codes.
 
 > [!NOTE]
 > **Naming & Installation**: The npm package for this tool is **`mcp-medic`** (`npx mcp-medic` / `npm i -g mcp-medic`). While this GitHub repository is named `mcp-doctor`, an unrelated older package already occupies the npm name `mcp-doctor` (different author). Users who want this tool must install **`mcp-medic`**, not `mcp-doctor`.
@@ -27,16 +27,18 @@ This is the whole point (a real handshake, not a schema guess) — but it means
 
 ## Features
 
+- 🏆 **MCP Quality Score**: a deterministic 0–100 score across five weighted dimensions (Protocol, Schema, Agent usability, Security, Reliability) via `mcp-medic score <config>` or `check --score`. No LLM, no randomness — every point is traced back to a real diagnostic.
+- 🧠 **Tool/Resource/Prompt Quality Checks**: flags empty/duplicate/placeholder tool names, vague or placeholder descriptions, malformed input/output schemas, contradictory tool annotations, excessive tool surface (bloat), and duplicate/malformed resources and prompts.
 - 🔍 **Auto-Discovery**: Run `mcp-medic check` with no arguments to auto-discover Claude Desktop, `.mcp.json`, and VS Code/Cursor MCP configuration paths across macOS, Windows, and Linux.
 - 💡 **Auto-Fix Suggestions**: Diagnose issues with clear, actionable fix suggestions using `--show-fixes`.
 - 🌐 **Registry Validation**: Validate published registry entries directly using `mcp-medic check --registry <server-id>`.
 - 🧪 **Fleet Validation** (experimental): Scan and validate monorepos or multi-team configurations with `mcp-medic check-all "<glob>"`.
 - 🧪 **Drift Detection** (experimental): Catch environment divergence between staging and production configs with `mcp-medic diff <configA> <configB>`.
-- 📜 **Policy-as-Code**: Enforce organizational constraints (e.g., banned transports, domain allowlists, minimum description lengths) via `.mcp-medic-policy.json` / `--policy`.
+- 📜 **Policy-as-Code**: Enforce organizational constraints (banned transports, domain allowlists, minimum description lengths, a minimum quality score, a max tool count, required tool descriptions) via `.mcp-medic-policy.json` / `--policy`.
 - 📸 **Snapshot Baseline Mode**: Filter out legacy diagnostics with `--snapshot <baseline.json>` to gate only on newly introduced regressions.
-- 📊 **CI Reporting**: Export standard JUnit XML (`--export-junit <file.xml>`) and JSON (`--export-json <file.json>`) for seamless CI dashboard visualization.
+- 📊 **CI Reporting**: Export JUnit XML (`--export-junit`), JSON (`--export-json`, always includes the quality score), and SARIF 2.1.0 (`--export-sarif`, for GitHub Code Scanning).
 - 👀 **Watch Mode**: Re-run validation on save using `mcp-medic watch <path>`.
-- ⚡ **Transport Hardening**: Full handshake validation across stdio, HTTP (with OAuth token refresh), and SSE (with automatic retry resilience).
+- ⚡ **Protocol Correctness**: real protocol version negotiation (client requests a version, server's actual negotiated version is validated — not assumed), full handshake validation across stdio, HTTP (with OAuth token refresh), and SSE (with automatic retry resilience), plus passive `resources/list`/`prompts/list` capability inspection.
 - 🧪 **VS Code Extension** (experimental, not yet on the Marketplace): in-editor squiggles and hover tooltips — runnable from source today, see [vscode-extension/](./vscode-extension/).
 - 🚦 **CI Usability & Exit Codes**: Strict exit code taxonomy (`0` clean, `1` diagnostic failures, `2` usage/syntax errors) and `--fail-on <error|warning>`.
 - 🤖 **GitHub Action**: Drop-in CI integration via `shivam039/mcp-doctor@main` (or `mcp-medic-action`).
@@ -44,6 +46,50 @@ This is the whole point (a real handshake, not a schema guess) — but it means
 
 ---
 
+## MCP Quality Engine
+
+`mcp-medic` computes a deterministic **MCP Quality Score** (0–100) from the same diagnostics shown in the report — there's no separate, opaque scoring model guessing independently. Every point deducted traces back to one or more real diagnostics, and the same input always produces the same score (no LLM, no randomness, no extra network calls beyond the MCP inspection already performed).
+
+**What the score means — and doesn't**: it's a measurement of what mcp-medic's passive checks actually found (or looked for), not a certification. "Security 93/100" means *mcp-medic's heuristic security checks found issues worth 7 points* — it is not a security audit, and a 100 is not a guarantee the server is safe. Every report includes this disclaimer and a coverage figure so you can tell what was actually inspected (see below).
+
+```bash
+mcp-medic score path/to/config.json
+# or, alongside the normal report:
+mcp-medic check path/to/config.json --score
+```
+
+### Dimensions
+
+| Dimension | Weight | What it reflects |
+|---|---|---|
+| Protocol | 25% | Version negotiation compatibility, capability-inspection health (`resources/list`/`prompts/list` succeeding), `serverInfo` presence, version downgrades |
+| Schema | 20% | `schema.*` diagnostics — malformed/missing input schemas, type mismatches, missing required fields |
+| Agent usability | 20% | Tool/resource/prompt naming, description quality, output schemas, annotations, tool-surface bloat |
+| Security | 20% | `security.*` heuristic diagnostics (untrusted remotes, overbroad permissions, prompt-injection-risk patterns) |
+| Reliability | 15% | Whether the server connects at all (currently binary — see [Known Limitations](#known-limitations)) |
+
+These weights are a deliberate, documented choice — not arbitrary — and are not changed casually; see `.agent-room/DECISIONS.md` if you're curious why.
+
+### How deductions work
+
+Each dimension starts at 100. Diagnostics are grouped by `checkId` and severity (`error`/`warning`/`info`), each contributing capped points (errors up to 25/checkId, warnings up to 15/checkId, info up to 5/checkId) — so **one noisy check can never dominate a dimension**: 20 tools sharing the same description problem cost at most 15 points, not 300. The report's "Deductions" list names exactly which checks cost how many points. **Nothing is deducted that isn't also a visible diagnostic** — including protocol-level facts like a negotiated version downgrade or a capability that failed to list, which are their own `protocol.*` diagnostics, not a hidden number baked into the score.
+
+### Coverage: what was actually inspected
+
+A dimension's score only means something if the checks that produce it actually ran. If you run `mcp-medic` with a custom, restricted check set (`runChecks({ checks: [...] })` via the library API), the score's `coverage` tells you which dimensions were fully evaluated (`'covered'`), partially evaluated (`'partial'` — some but not all of that dimension's checks ran), or not evaluated at all (`'not-covered'`). A `security: 'not-covered'` next to `Security 100/100` means "nothing was looked for," not "nothing is wrong." `coveragePercent` summarizes all five as one number. The standard CLI (`check`/`score`) always runs the full built-in check set, so coverage is 100% there by default.
+
+A server that fails to connect is never silently averaged out of a fleet's score either — it's named in `quality.unscoredServers`, and the human report calls it out explicitly.
+
+### Protocol-version-aware quality rules
+
+Some things a check might flag could be a genuine protocol violation for a given negotiated MCP version, or merely an ecosystem style recommendation — mcp-medic never mislabels one as the other. `src/protocol/quality-rules.ts` centralizes what each supported version actually requires (today: no version defines a hard tool-name length or character-pattern constraint, so this distinction is currently latent — the abstraction exists so a future version that *does* add one only needs a new entry there, not a rewrite of every check).
+
+### Diagnostic categories
+
+Every diagnostic has a stable category (`protocol`, `schema`, `quality`, `security`, `reliability`, `usability`, `configuration`) — set explicitly by newer checks, or inferred from the `checkId` prefix for older ones, so nothing that already worked had to change.
+
+---
+
 ## Quick Start
 
 > **Preferred invocation**: Run `npx mcp-medic` (the npm package is `mcp-medic`, not `mcp-doctor`).
@@ -71,6 +117,9 @@ npx mcp-medic check path/to/config.json --policy .mcp-medic-policy.json --export
 # Display suggested fixes for flagged diagnostics
 npx mcp-medic check path/to/config.json --show-fixes
 
+# Compute the deterministic MCP quality score
+npx mcp-medic score path/to/config.json
+
 # Watch mode (re-runs checks on save)
 npx mcp-medic watch path/to/config.json
 ```
@@ -87,12 +136,16 @@ npx mcp-medic watch path/to/config.json
 | `check --registry <id>` | Validate a published registry server directly |
 | `watch <path>` | Watch configuration file and re-run checks on file save |
 | `fix <path>` | Interactively apply mechanical suggested fixes (see [Auto-Fix](#auto-fix-mcp-medic-fix) below) |
+| `score <path>` | Print the report with the MCP quality score section (same as `check --score`) |
 | `--config <path>` | Explicit configuration path |
 | `--policy <path>` | Apply organizational policy rules (`.mcp-medic-policy.json`) |
 | `--snapshot <path>` | Compare against baseline snapshot, reporting regressions only |
 | `--update-snapshot <path>` | Save diagnostic report as new baseline snapshot |
 | `--export-junit <file>` | Export report in JUnit XML format |
-| `--export-json <file>` | Export report in JSON format |
+| `--export-json <file>` | Export report in JSON format (always includes `quality`) |
+| `--export-sarif <file>` | Export report in SARIF 2.1.0 format (GitHub Code Scanning, etc.) |
+| `--score` | Include the MCP quality score section in the human report |
+| `--protocol-version <v>` | MCP protocolVersion to request: `auto` (default) or an explicit version |
 | `--show-fixes` | Show suggested fixes inline under diagnostics |
 | `--fail-on <severity>` | Fail with exit code 1 on `error` (default) or `warning` |
 | `--verbose`, `-v` | Output raw JSON-RPC traffic and debug messages |
@@ -137,10 +190,19 @@ Define organization-wide policies that compose with built-in checks:
 {
   "bannedTransports": ["stdio"],
   "allowedDomains": ["corp.internal", "mcp.example.com"],
-  "minDescriptionLength": 20
+  "minDescriptionLength": 20,
+  "quality": {
+    "minimumScore": 80,
+    "maxTools": 100,
+    "requireToolDescriptions": true
+  }
 }
 ```
 
+`quality.minimumScore` fails the run (adds an error diagnostic) if the computed MCP Quality Score falls below the threshold. `quality.maxTools` is an org-enforced hard limit — distinct from the built-in `quality.tool-surface` check's default 100-tool *warning*, which stays a recommendation. `quality.requireToolDescriptions` (or the equivalent top-level `requireToolDescriptions`) turns every missing tool description into a policy error rather than the default warning.
+
+A `minimumScore` gate is also coverage-aware: if the score was computed from incomplete coverage (or a server that couldn't be scored), a `policy.partial-coverage-with-minimum-score` **warning** is added alongside it — a passing score should never look like a clean bill of health when only part of the server was actually evaluated. This never changes the pass/fail outcome of the `minimumScore` check itself (that stays a plain score-vs-threshold comparison), it just makes a partial assessment visible.
+
 ---
 
 ## VS Code Extension (experimental)
@@ -219,7 +281,14 @@ The action adheres to strict exit code taxonomy:
 | `security.untrusted-remote` | `mcp-medic` | **Official** (heuristic) | Flags non-HTTPS or raw-IP SSE/HTTP server URLs |
 | `security.overbroad-permissions` | `mcp-medic` | **Official** (heuristic) | Flags tools with unscoped shell/filesystem/network parameters |
 | `security.prompt-injection-risk` | `mcp-medic` | **Official** (heuristic) | Flags instruction-like language in tool descriptions aimed at the model |
-| `policy.*` | `mcp-medic` | **Official** | Evaluates policy-as-code rules (transports, domains, length) |
+| `quality.tool-name` | `mcp-medic` | **Official** | Flags empty/duplicate (error) and overly-long/ambiguous/placeholder (warning) tool names |
+| `quality.vague-description` | `mcp-medic` | **Official** | Flags present-but-vague tool descriptions (placeholder text, single words, name repeated as description) |
+| `quality.output-schema` | `mcp-medic` | **Official** | Flags a malformed `outputSchema` — never flags its absence, which is optional per spec |
+| `quality.tool-annotations` | `mcp-medic` | **Official** | Flags internally contradictory `ToolAnnotations` hints (e.g. both read-only and destructive) |
+| `quality.tool-surface` | `mcp-medic` | **Official** | Flags excessive tool counts (default 100) and near-duplicate names/descriptions |
+| `quality.resource` | `mcp-medic` | **Official** | Flags duplicate/empty resource URIs and missing required `name` from passive `resources/list` results |
+| `quality.prompt` | `mcp-medic` | **Official** | Flags duplicate/empty prompt or argument names and placeholder descriptions from passive `prompts/list` results |
+| `policy.*` | `mcp-medic` | **Official** | Evaluates policy-as-code rules (transports, domains, length, quality thresholds) |
 | `community.strict-typing` | `mcp-medic-check-strict-typing` | *Planned / example* | Would enforce strict property type annotations |
 | `community.no-empty-enums` | `mcp-medic-check-no-empty-enums` | *Planned / example* | Would ensure non-empty enum option lists |
 
@@ -236,6 +305,11 @@ The `security.*` checks are heuristic — they pattern-match on what a server *d
 - **`security.*` checks are heuristic pattern-matching**, not a security audit — see the note above. They can both miss real issues and flag benign configs (e.g. a legitimate local dev server on plain `http://`).
 - **Fleet commands (`check-all`, `diff`) are newer and less battle-tested** than `check`/`watch` — the core check pipeline they're built on is the same, but edge cases in glob matching or drift diffing are more likely.
 - **The VS Code extension and community check packages are not shipped/published** — see the sections above.
+- **The Reliability quality dimension is currently binary**: 100 if the server connected, 0 if it didn't (plus any future `reliability.*` diagnostics — none exist yet). Signals like latency trends, retry behavior, or flakiness across repeated runs aren't scored yet.
+- **`resources/list`/`prompts/list` pagination (`nextCursor`) is not followed** — mcp-medic inspects only the first page a server returns, matching the existing (also unpaginated) `tools/list` handling. A server with a very large resource/prompt catalog behind pagination will be under-inspected.
+- **The quality score never calls `resources/read`, `prompts/get`, or any tool** — it's entirely derived from the passive `initialize`/`tools/list`/`resources/list`/`prompts/list` responses already gathered during a normal `check`. See [SECURITY.md](./SECURITY.md) for the full passive-only guarantee.
+- **The CLI cannot currently restrict the check set** (no `--only-checks` flag), so `coverage` is always 100% via `check`/`score`. Partial coverage (and the coverage-aware `minimumScore` warning) only happens when the library API's `runChecks({ checks: [...] })` is called with a restricted list.
+- **No currently-supported MCP protocol version defines a hard tool-name length or character-pattern constraint**, so `src/protocol/quality-rules.ts`'s protocol-vs-quality distinction for tool names is real but currently dormant — every finding today is a quality recommendation, never a protocol violation, because no version actually requires one. The abstraction is there for when a future version does.
 - **npm README sync**: Latest docs live on GitHub main; npm README updates on the next publish.
 - **First run via `npx`** pays a one-time cost to resolve and download the package; once installed (or on a warm npx cache), `--help`/`--version` return in well under 100ms.
 

package/dist/checks/index.d.ts

@@ -6,4 +6,12 @@ export { sampleCallSimulationCheck } from './sample-call-simulation.js';
 export { securityUntrustedRemoteCheck } from './security-untrusted-remote.js';
 export { securityOverbroadPermissionsCheck } from './security-overbroad-permissions.js';
 export { securityPromptInjectionRiskCheck } from './security-prompt-injection-risk.js';
+export { qualityToolNamesCheck } from './quality-tool-names.js';
+export { qualityToolDescriptionsCheck } from './quality-tool-descriptions.js';
+export { qualityToolOutputSchemaCheck } from './quality-tool-output-schema.js';
+export { qualityToolAnnotationsCheck } from './quality-tool-annotations.js';
+export { qualityToolSurfaceCheck, createToolSurfaceCheck, DEFAULT_MAX_TOOLS_WARNING_THRESHOLD } from './quality-tool-surface.js';
+export { qualityResourcesCheck } from './quality-resources.js';
+export { qualityPromptsCheck } from './quality-prompts.js';
+export { protocolConnectionHealthCheck } from './protocol-connection-health.js';
 export declare const allChecks: import("../types.js").Check[];

package/dist/checks/index.js

@@ -6,6 +6,14 @@ export { sampleCallSimulationCheck } from './sample-call-simulation.js';
 export { securityUntrustedRemoteCheck } from './security-untrusted-remote.js';
 export { securityOverbroadPermissionsCheck } from './security-overbroad-permissions.js';
 export { securityPromptInjectionRiskCheck } from './security-prompt-injection-risk.js';
+export { qualityToolNamesCheck } from './quality-tool-names.js';
+export { qualityToolDescriptionsCheck } from './quality-tool-descriptions.js';
+export { qualityToolOutputSchemaCheck } from './quality-tool-output-schema.js';
+export { qualityToolAnnotationsCheck } from './quality-tool-annotations.js';
+export { qualityToolSurfaceCheck, createToolSurfaceCheck, DEFAULT_MAX_TOOLS_WARNING_THRESHOLD } from './quality-tool-surface.js';
+export { qualityResourcesCheck } from './quality-resources.js';
+export { qualityPromptsCheck } from './quality-prompts.js';
+export { protocolConnectionHealthCheck } from './protocol-connection-health.js';
 import { malformedSchemaCheck } from './malformed-schema.js';
 import { missingRequiredFieldsCheck } from './missing-required-fields.js';
 import { typeMismatchCheck } from './type-mismatch.js';
@@ -14,7 +22,16 @@ import { sampleCallSimulationCheck } from './sample-call-simulation.js';
 import { securityUntrustedRemoteCheck } from './security-untrusted-remote.js';
 import { securityOverbroadPermissionsCheck } from './security-overbroad-permissions.js';
 import { securityPromptInjectionRiskCheck } from './security-prompt-injection-risk.js';
+import { qualityToolNamesCheck } from './quality-tool-names.js';
+import { qualityToolDescriptionsCheck } from './quality-tool-descriptions.js';
+import { qualityToolOutputSchemaCheck } from './quality-tool-output-schema.js';
+import { qualityToolAnnotationsCheck } from './quality-tool-annotations.js';
+import { qualityToolSurfaceCheck } from './quality-tool-surface.js';
+import { qualityResourcesCheck } from './quality-resources.js';
+import { qualityPromptsCheck } from './quality-prompts.js';
+import { protocolConnectionHealthCheck } from './protocol-connection-health.js';
 export const allChecks = [
+    protocolConnectionHealthCheck,
     malformedSchemaCheck,
     missingRequiredFieldsCheck,
     typeMismatchCheck,
@@ -23,4 +40,11 @@ export const allChecks = [
     securityUntrustedRemoteCheck,
     securityOverbroadPermissionsCheck,
     securityPromptInjectionRiskCheck,
+    qualityToolNamesCheck,
+    qualityToolDescriptionsCheck,
+    qualityToolOutputSchemaCheck,
+    qualityToolAnnotationsCheck,
+    qualityToolSurfaceCheck,
+    qualityResourcesCheck,
+    qualityPromptsCheck,
 ];

package/dist/checks/malformed-schema.js

@@ -48,6 +48,23 @@ export const malformedSchemaCheck = {
                         },
                     });
                 }
+                else if (typeof schemaObj.type === 'string' && schemaObj.type !== 'object') {
+                    // Per the MCP spec, a tool's inputSchema MUST describe an object
+                    // (tool arguments are always passed as a JSON object) — a
+                    // top-level type other than "object" is a protocol violation,
+                    // not merely a style issue.
+                    results.push({
+                        checkId: 'schema.malformed',
+                        severity: 'error',
+                        message: `Tool "${tool.name}" inputSchema declares type "${schemaObj.type}", but the MCP spec requires tool inputSchema to be type "object".`,
+                        serverName: connection.server.name,
+                        toolName: tool.name,
+                        details: { inputSchema: schema },
+                        suggestedFix: {
+                            description: 'Change inputSchema\'s top-level "type" to "object".',
+                        },
+                    });
+                }
             }
         }
         catch (err) {

package/dist/checks/protocol-connection-health.d.ts

@@ -0,0 +1,17 @@
+import type { Check } from '../types.js';
+/**
+ * Surfaces connection-level protocol facts as real, visible diagnostics —
+ * previously these (capability-inspection failures, a version downgrade, a
+ * missing serverInfo) were deducted from the quality score directly from
+ * `MCPConnection` metadata inside src/quality-score.ts, with no
+ * corresponding diagnostic a user could actually see in the report or
+ * `--json` output. That meant a developer looking at "why did my protocol
+ * score drop" would find nothing in `diagnostics` explaining it.
+ *
+ * This check makes those same facts flow through the standard
+ * connection -> diagnostics -> dimension -> score pipeline like every
+ * other check, so every point deducted is explainable from a visible
+ * DiagnosticResult (see .agent-room/DECISIONS.md for the full rationale,
+ * including why this also changes some of the exact point values).
+ */
+export declare const protocolConnectionHealthCheck: Check;

package/dist/checks/protocol-connection-health.js

@@ -0,0 +1,78 @@
+/**
+ * Surfaces connection-level protocol facts as real, visible diagnostics —
+ * previously these (capability-inspection failures, a version downgrade, a
+ * missing serverInfo) were deducted from the quality score directly from
+ * `MCPConnection` metadata inside src/quality-score.ts, with no
+ * corresponding diagnostic a user could actually see in the report or
+ * `--json` output. That meant a developer looking at "why did my protocol
+ * score drop" would find nothing in `diagnostics` explaining it.
+ *
+ * This check makes those same facts flow through the standard
+ * connection -> diagnostics -> dimension -> score pipeline like every
+ * other check, so every point deducted is explainable from a visible
+ * DiagnosticResult (see .agent-room/DECISIONS.md for the full rationale,
+ * including why this also changes some of the exact point values).
+ */
+export const protocolConnectionHealthCheck = {
+    id: 'protocol.connection-health',
+    description: 'Flags protocol-level connection facts: a negotiated version downgrade, a missing serverInfo, or a declared capability whose list call failed.',
+    run(connection) {
+        const results = [];
+        try {
+            if (connection.protocolVersion?.negotiated &&
+                connection.protocolVersion.negotiated !== connection.protocolVersion.requested) {
+                results.push({
+                    checkId: 'protocol.version-downgrade',
+                    severity: 'info',
+                    message: `Server negotiated protocol version ${connection.protocolVersion.negotiated} instead of the requested ${connection.protocolVersion.requested}.`,
+                    serverName: connection.server.name,
+                    category: 'protocol',
+                    details: {
+                        requested: connection.protocolVersion.requested,
+                        negotiated: connection.protocolVersion.negotiated,
+                    },
+                });
+            }
+            if (!connection.serverInfo?.name) {
+                results.push({
+                    checkId: 'protocol.missing-server-info',
+                    severity: 'info',
+                    message: 'Server did not report its name/version in serverInfo during initialize.',
+                    serverName: connection.server.name,
+                    category: 'protocol',
+                    suggestedFix: { description: 'Have the server include a serverInfo.name in its initialize response.' },
+                });
+            }
+            if (connection.capabilityErrors?.resources) {
+                results.push({
+                    checkId: 'protocol.capability-error',
+                    severity: 'error',
+                    message: `Server declared the "resources" capability, but resources/list failed: ${connection.capabilityErrors.resources}`,
+                    serverName: connection.server.name,
+                    category: 'protocol',
+                    details: { capability: 'resources', error: connection.capabilityErrors.resources },
+                });
+            }
+            if (connection.capabilityErrors?.prompts) {
+                results.push({
+                    checkId: 'protocol.capability-error',
+                    severity: 'error',
+                    message: `Server declared the "prompts" capability, but prompts/list failed: ${connection.capabilityErrors.prompts}`,
+                    serverName: connection.server.name,
+                    category: 'protocol',
+                    details: { capability: 'prompts', error: connection.capabilityErrors.prompts },
+                });
+            }
+        }
+        catch (err) {
+            results.push({
+                checkId: 'protocol.connection-health',
+                severity: 'error',
+                message: `check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                serverName: connection.server.name,
+                category: 'protocol',
+            });
+        }
+        return results;
+    },
+};

package/dist/checks/quality-prompts.d.ts

@@ -0,0 +1,8 @@
+import type { Check } from '../types.js';
+/**
+ * Inspects only what `prompts/list` already returned (see
+ * MCPConnection.prompts, populated passively in src/protocol/connect.ts).
+ * Never calls `prompts/get` — that would retrieve/render the prompt, out
+ * of scope for a passive `check`.
+ */
+export declare const qualityPromptsCheck: Check;

package/dist/checks/quality-prompts.js

@@ -0,0 +1,121 @@
+/** Same conservative placeholder list used for tool descriptions. */
+const PLACEHOLDER_DESCRIPTIONS = new Set([
+    'todo',
+    'test',
+    'foo',
+    'bar',
+    'description',
+    'prompt',
+    'tbd',
+    'n/a',
+    'na',
+    'none',
+    'placeholder',
+    'xxx',
+]);
+/**
+ * Inspects only what `prompts/list` already returned (see
+ * MCPConnection.prompts, populated passively in src/protocol/connect.ts).
+ * Never calls `prompts/get` — that would retrieve/render the prompt, out
+ * of scope for a passive `check`.
+ */
+export const qualityPromptsCheck = {
+    id: 'quality.prompt',
+    description: 'Flags duplicate/empty prompt names, placeholder descriptions, and malformed argument definitions in prompts/list results.',
+    run(connection) {
+        const results = [];
+        try {
+            const prompts = connection.prompts;
+            if (!prompts || !Array.isArray(prompts)) {
+                return results;
+            }
+            const byName = new Map();
+            for (const prompt of prompts) {
+                const name = prompt.name;
+                if (typeof name !== 'string' || name.trim() === '') {
+                    results.push({
+                        checkId: 'quality.prompt',
+                        severity: 'error',
+                        message: 'Prompt has an empty or invalid "name" — the MCP spec requires prompts to have a name.',
+                        serverName: connection.server.name,
+                        category: 'schema',
+                        details: { prompt },
+                    });
+                    continue;
+                }
+                byName.set(name, (byName.get(name) ?? 0) + 1);
+                const description = prompt.description?.trim();
+                if (!description) {
+                    results.push({
+                        checkId: 'quality.prompt',
+                        severity: 'info',
+                        message: `Prompt "${name}" has no description, making it harder for an agent to know when to use it.`,
+                        serverName: connection.server.name,
+                        category: 'quality',
+                    });
+                }
+                else if (PLACEHOLDER_DESCRIPTIONS.has(description.toLowerCase())) {
+                    results.push({
+                        checkId: 'quality.prompt',
+                        severity: 'warning',
+                        message: `Prompt "${name}" description ("${description}") looks like placeholder text.`,
+                        serverName: connection.server.name,
+                        category: 'quality',
+                        confidence: 'high',
+                    });
+                }
+                if (Array.isArray(prompt.arguments)) {
+                    const argNames = new Map();
+                    for (const arg of prompt.arguments) {
+                        if (!arg.name || arg.name.trim() === '') {
+                            results.push({
+                                checkId: 'quality.prompt',
+                                severity: 'error',
+                                message: `Prompt "${name}" has an argument with an empty or missing "name" — required by the MCP spec's PromptArgument type.`,
+                                serverName: connection.server.name,
+                                category: 'schema',
+                                details: { promptName: name, argument: arg },
+                            });
+                            continue;
+                        }
+                        argNames.set(arg.name, (argNames.get(arg.name) ?? 0) + 1);
+                    }
+                    for (const [argName, count] of argNames) {
+                        if (count > 1) {
+                            results.push({
+                                checkId: 'quality.prompt',
+                                severity: 'error',
+                                message: `Prompt "${name}" declares argument "${argName}" ${count} times.`,
+                                serverName: connection.server.name,
+                                category: 'schema',
+                                details: { promptName: name, argumentName: argName, duplicateCount: count },
+                            });
+                        }
+                    }
+                }
+            }
+            for (const [name, count] of byName) {
+                if (count > 1) {
+                    results.push({
+                        checkId: 'quality.prompt',
+                        severity: 'error',
+                        message: `Prompt name "${name}" is declared ${count} times — a client cannot reliably invoke a specific one by name.`,
+                        serverName: connection.server.name,
+                        category: 'schema',
+                        details: { duplicateCount: count },
+                    });
+                }
+            }
+        }
+        catch (err) {
+            results.push({
+                checkId: 'quality.prompt',
+                severity: 'error',
+                message: `check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                serverName: connection.server.name,
+                category: 'quality',
+            });
+        }
+        return results;
+    },
+};

package/dist/checks/quality-resources.d.ts

@@ -0,0 +1,8 @@
+import type { Check } from '../types.js';
+/**
+ * Inspects only what `resources/list` already returned (see
+ * MCPConnection.resources, populated passively in src/protocol/connect.ts).
+ * Never calls `resources/read` — that would be real content retrieval, out
+ * of scope for a passive `check`.
+ */
+export declare const qualityResourcesCheck: Check;

package/dist/checks/quality-resources.js

@@ -0,0 +1,92 @@
+/**
+ * Inspects only what `resources/list` already returned (see
+ * MCPConnection.resources, populated passively in src/protocol/connect.ts).
+ * Never calls `resources/read` — that would be real content retrieval, out
+ * of scope for a passive `check`.
+ */
+export const qualityResourcesCheck = {
+    id: 'quality.resource',
+    description: 'Flags duplicate/empty resource URIs, missing required names, and other resources/list quality issues.',
+    run(connection) {
+        const results = [];
+        try {
+            const resources = connection.resources;
+            if (!resources || !Array.isArray(resources)) {
+                return results;
+            }
+            const byUri = new Map();
+            for (const resource of resources) {
+                const uri = resource.uri;
+                if (typeof uri !== 'string' || uri.trim() === '') {
+                    results.push({
+                        checkId: 'quality.resource',
+                        severity: 'error',
+                        message: 'Resource has an empty or invalid "uri" — the MCP spec requires resources to have a URI.',
+                        serverName: connection.server.name,
+                        category: 'schema',
+                        details: { resource },
+                    });
+                    continue;
+                }
+                byUri.set(uri, (byUri.get(uri) ?? 0) + 1);
+                // Per the MCP spec's Resource type (extends BaseMetadata), "name" is
+                // a required field, not optional.
+                if (!resource.name || resource.name.trim() === '') {
+                    results.push({
+                        checkId: 'quality.resource',
+                        severity: 'error',
+                        message: `Resource "${uri}" is missing a "name" — required by the MCP spec's Resource type.`,
+                        serverName: connection.server.name,
+                        category: 'schema',
+                        details: { uri },
+                        suggestedFix: { description: `Add a "name" field to the resource at "${uri}".` },
+                    });
+                }
+                // description is optional per spec — absence is a quality
+                // recommendation, not a violation.
+                if (!resource.description || resource.description.trim() === '') {
+                    results.push({
+                        checkId: 'quality.resource',
+                        severity: 'info',
+                        message: `Resource "${uri}" has no description, making it harder for an agent to know when to read it.`,
+                        serverName: connection.server.name,
+                        category: 'quality',
+                        details: { uri },
+                    });
+                }
+                if (resource.size !== undefined && (typeof resource.size !== 'number' || resource.size < 0)) {
+                    results.push({
+                        checkId: 'quality.resource',
+                        severity: 'warning',
+                        message: `Resource "${uri}" declares an invalid "size" (${JSON.stringify(resource.size)}) — size must be a non-negative number.`,
+                        serverName: connection.server.name,
+                        category: 'schema',
+                        details: { uri, size: resource.size },
+                    });
+                }
+            }
+            for (const [uri, count] of byUri) {
+                if (count > 1) {
+                    results.push({
+                        checkId: 'quality.resource',
+                        severity: 'error',
+                        message: `Resource URI "${uri}" is declared ${count} times — resource URIs must be unique.`,
+                        serverName: connection.server.name,
+                        category: 'schema',
+                        details: { uri, duplicateCount: count },
+                    });
+                }
+            }
+        }
+        catch (err) {
+            results.push({
+                checkId: 'quality.resource',
+                severity: 'error',
+                message: `check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                serverName: connection.server.name,
+                category: 'quality',
+            });
+        }
+        return results;
+    },
+};

package/dist/checks/quality-tool-annotations.d.ts

@@ -0,0 +1,10 @@
+import type { Check } from '../types.js';
+/**
+ * MCP `ToolAnnotations` are optional client *hints* the spec explicitly
+ * does not treat as authoritative — a server can declare `readOnlyHint:
+ * true` and still do something destructive. This check only flags
+ * internally self-contradictory combinations of hints (the server's own
+ * declaration doesn't add up), never infers "this tool is dangerous" from
+ * an annotation, and never treats annotations as a security guarantee.
+ */
+export declare const qualityToolAnnotationsCheck: Check;