mcp-medic 1.2.10 → 1.3.0

package/README.md

@@ -101,6 +101,9 @@ npx mcp-medic
 # Run check on a specific configuration file
 npx mcp-medic check path/to/config.json
 
+# Run selected checks only (quality coverage is shown automatically)
+npx mcp-medic check path/to/config.json --only-checks schema.missing-description,quality.prompt
+
 # Validate all configs across a monorepo
 npx mcp-medic check-all "configs/**/*.json"
 
@@ -145,6 +148,7 @@ npx mcp-medic watch path/to/config.json
 | `--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 |
+| `--only-checks <id,...>` | Run selected check IDs for `check`, `score`, or `watch`; also displays quality coverage |
 | `--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` |
@@ -308,9 +312,7 @@ 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://`).
 - **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/cli.d.ts

@@ -23,6 +23,8 @@ export interface ParsedArgs {
     showScore: boolean;
     /** "auto" (default) or an explicit MCP protocolVersion string, e.g. "2025-06-18". */
     protocolVersion: string;
+    /** IDs selected by `--only-checks` (applies to check, score, and watch). */
+    onlyCheckIds?: string[];
 }
 /** Prompts the user with `question` and resolves true for an explicit "y"/"yes" answer. */
 export type ConfirmFn = (question: string) => Promise<boolean>;

package/dist/cli.js

@@ -46,6 +46,23 @@ export function parseArgs(argv) {
         else if (arg === '--score') {
             args.showScore = true;
         }
+        else if (arg === '--only-checks') {
+            const value = argv[++i];
+            if (!value || value.startsWith('-')) {
+                throw new Error('--only-checks requires a comma-separated list of check IDs');
+            }
+            if (args.onlyCheckIds) {
+                throw new Error('--only-checks may only be specified once');
+            }
+            const ids = value.split(',').map((id) => id.trim());
+            if (ids.some((id) => id.length === 0)) {
+                throw new Error('--only-checks does not allow empty IDs; provide comma-separated check IDs');
+            }
+            if (new Set(ids).size !== ids.length) {
+                throw new Error('--only-checks does not allow duplicate check IDs');
+            }
+            args.onlyCheckIds = ids;
+        }
         else if (arg === '--help' || arg === '-h') {
             args.command = 'help';
         }
@@ -214,6 +231,7 @@ OPTIONS
   --export-json <file>  Export report in JSON format
   --export-sarif <file> Export report in SARIF 2.1.0 format (GitHub Code Scanning, etc.)
   --score               Include the MCP quality score in the report (implied by the "score" command)
+  --only-checks <ids>   Run only comma-separated check IDs (check, score, watch)
   --show-fixes          Print actionable suggested fixes under diagnostics
   --fail-on <severity>  Exit with code 1 on 'error' (default) or 'warning'
   --verbose, -v         Print raw JSON-RPC traffic and debug messages
@@ -279,7 +297,20 @@ function colorizeHumanReport(text) {
         .join('\n');
 }
 async function executeCheck(config, args) {
-    const [checks] = await Promise.all([loadChecks(args.policyPath), loadProtocol()]);
+    const [availableChecks] = await Promise.all([loadChecks(args.policyPath), loadProtocol()]);
+    let checks = availableChecks;
+    if (args.onlyCheckIds) {
+        const availableIds = new Set(availableChecks.map((check) => check.id));
+        const unknownIds = args.onlyCheckIds.filter((id) => !availableIds.has(id));
+        if (unknownIds.length > 0) {
+            console.error(pc.red(`mcp-medic usage error: unknown check ID(s): ${unknownIds.join(', ')}. ` +
+                `Available IDs: ${[...availableIds].join(', ')}.` +
+                `${args.policyPath ? ' Verify policy check IDs are enabled by the selected policy.' : ''}`));
+            return 2;
+        }
+        // Keep the registry's canonical order regardless of the order in the CLI list.
+        checks = availableChecks.filter((check) => args.onlyCheckIds.includes(check.id));
+    }
     let report = await runChecks(config, {
         timeoutMs: args.timeoutMs,
         checks,
@@ -356,7 +387,10 @@ async function executeCheck(config, args) {
         console.log(formatReportJSON(report));
     }
     else {
-        console.log(colorizeHumanReport(formatReportHuman(report, { showFixes: args.showFixes, showScore: args.showScore })));
+        console.log(colorizeHumanReport(formatReportHuman(report, {
+            showFixes: args.showFixes,
+            showScore: args.showScore || Boolean(args.onlyCheckIds),
+        })));
     }
     const hasErrors = report.summary.errors > 0;
     const hasWarnings = report.summary.warnings > 0;
@@ -524,6 +558,10 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
         console.log(getPackageVersion());
         return 0;
     }
+    if (args.onlyCheckIds && !['check', 'score', 'watch'].includes(args.command)) {
+        console.error(pc.red('--only-checks is supported only by the check, score, and watch commands.'));
+        return 2;
+    }
     if (args.command === 'fix' && args.registryServer) {
         console.error(pc.red('mcp-doctor fix does not support --registry — there is no local file to write the fix to.'));
         return 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-medic",
-  "version": "1.2.10",
+  "version": "1.3.0",
   "description": "Diagnose broken MCP (Model Context Protocol) server configs before they break your agent silently.",
   "type": "module",
   "main": "dist/index.js",