mcp-medic 1.2.2 → 1.2.4

package/dist/checks/quality-tool-annotations.js

@@ -0,0 +1,63 @@
+/**
+ * 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 const qualityToolAnnotationsCheck = {
+    id: 'quality.tool-annotations',
+    description: 'Flags tool annotation hints that are internally contradictory (e.g. both read-only and destructive).',
+    run(connection) {
+        const results = [];
+        try {
+            if (!connection.tools || !Array.isArray(connection.tools)) {
+                return results;
+            }
+            for (const tool of connection.tools) {
+                const annotations = tool.annotations;
+                if (!annotations || typeof annotations !== 'object')
+                    continue;
+                if (annotations.readOnlyHint === true && annotations.destructiveHint === true) {
+                    results.push({
+                        checkId: 'quality.tool-annotations',
+                        severity: 'warning',
+                        message: `Tool "${tool.name}" declares both readOnlyHint and destructiveHint as true — these are contradictory (a read-only tool cannot also be destructive).`,
+                        serverName: connection.server.name,
+                        toolName: tool.name,
+                        category: 'quality',
+                        confidence: 'high',
+                        suggestedFix: {
+                            description: `Correct "${tool.name}"'s annotations so readOnlyHint and destructiveHint aren't both true.`,
+                        },
+                    });
+                }
+                if (annotations.readOnlyHint === true && annotations.idempotentHint === false) {
+                    // Not a hard contradiction (idempotentHint's meaning is about repeat
+                    // calls with the same args), but worth a low-confidence note: a
+                    // read-only operation is idempotent by construction in practice.
+                    results.push({
+                        checkId: 'quality.tool-annotations',
+                        severity: 'info',
+                        message: `Tool "${tool.name}" declares readOnlyHint: true but idempotentHint: false — read-only operations are usually idempotent; double-check this is intentional.`,
+                        serverName: connection.server.name,
+                        toolName: tool.name,
+                        category: 'quality',
+                        confidence: 'low',
+                    });
+                }
+            }
+        }
+        catch (err) {
+            results.push({
+                checkId: 'quality.tool-annotations',
+                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-descriptions.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from '../types.js';
+export declare const qualityToolDescriptionsCheck: Check;

package/dist/checks/quality-tool-descriptions.js

@@ -0,0 +1,106 @@
+/**
+ * Complements `schema.missing-description` (which flags *absent* descriptions).
+ * This check only looks at descriptions that ARE present, and flags ones that
+ * exist but carry no real semantic information — the "someone typed
+ * something to satisfy a linter" case. Deterministic heuristics only, no LLM;
+ * conservative by design so legitimately short-but-meaningful descriptions
+ * (e.g. "Returns the current time.") are never flagged.
+ */
+const PLACEHOLDER_DESCRIPTIONS = new Set([
+    'todo',
+    'test',
+    'foo',
+    'bar',
+    'description',
+    'tool',
+    'tbd',
+    'n/a',
+    'na',
+    'none',
+    'placeholder',
+    'xxx',
+    'wip',
+    'change me',
+    'fill me in',
+    'description here',
+    'a tool',
+    'this is a tool',
+]);
+function wordCount(text) {
+    return text.split(/\s+/).filter(Boolean).length;
+}
+export const qualityToolDescriptionsCheck = {
+    id: 'quality.vague-description',
+    description: 'Flags tool descriptions that are present but carry no useful semantic information (placeholder text, single words, or a copy of the tool name).',
+    run(connection) {
+        const results = [];
+        try {
+            if (!connection.tools || !Array.isArray(connection.tools)) {
+                return results;
+            }
+            for (const tool of connection.tools) {
+                const description = tool.description;
+                if (typeof description !== 'string')
+                    continue; // absence is schema.missing-description's job
+                const trimmed = description.trim();
+                if (trimmed === '')
+                    continue; // ditto
+                const normalized = trimmed.toLowerCase();
+                if (PLACEHOLDER_DESCRIPTIONS.has(normalized)) {
+                    results.push({
+                        checkId: 'quality.vague-description',
+                        severity: 'warning',
+                        message: `Tool "${tool.name}" description ("${trimmed}") looks like placeholder text, not a real description.`,
+                        serverName: connection.server.name,
+                        toolName: tool.name,
+                        category: 'quality',
+                        confidence: 'high',
+                        suggestedFix: {
+                            description: `Write a real description for "${tool.name}" explaining what it does and when an agent should call it.`,
+                        },
+                    });
+                    continue;
+                }
+                if (normalized === tool.name.trim().toLowerCase()) {
+                    results.push({
+                        checkId: 'quality.vague-description',
+                        severity: 'warning',
+                        message: `Tool "${tool.name}" description is just the tool's own name — it adds no information beyond what the name already says.`,
+                        serverName: connection.server.name,
+                        toolName: tool.name,
+                        category: 'quality',
+                        confidence: 'high',
+                        suggestedFix: {
+                            description: `Describe what "${tool.name}" actually does, not just repeat its name.`,
+                        },
+                    });
+                    continue;
+                }
+                if (wordCount(trimmed) <= 1) {
+                    results.push({
+                        checkId: 'quality.vague-description',
+                        severity: 'warning',
+                        message: `Tool "${tool.name}" description ("${trimmed}") is a single word — too short to convey what the tool does.`,
+                        serverName: connection.server.name,
+                        toolName: tool.name,
+                        category: 'quality',
+                        confidence: 'medium',
+                        suggestedFix: {
+                            description: `Expand "${tool.name}"'s description into at least a short sentence.`,
+                        },
+                    });
+                }
+            }
+        }
+        catch (err) {
+            results.push({
+                checkId: 'quality.vague-description',
+                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-names.d.ts

@@ -0,0 +1,35 @@
+import type { Check } from '../types.js';
+import { type ToolNameProtocolRules } from '../protocol/quality-rules.js';
+export interface ToolNameFinding {
+    severity: 'error' | 'warning';
+    /** 'protocol' only when `rules` itself defines a hard constraint the name
+     * violates; everything else is 'quality' (a recommendation, never a
+     * protocol violation) — see module doc. */
+    category: 'protocol' | 'quality';
+    message: string;
+    confidence?: 'low' | 'medium' | 'high';
+    suggestedFixDescription: string;
+}
+/**
+ * Pure evaluation of a single tool name, independent of the rest of the
+ * connection (duplicate detection is connection-wide and stays in `run()`).
+ * Exported so tests can inject a synthetic `ToolNameProtocolRules` (e.g. a
+ * hypothetical future protocol version with a real length/pattern
+ * constraint) without needing that version to actually exist yet — see
+ * src/protocol/quality-rules.ts.
+ *
+ * The A/B/C distinction this check makes:
+ *   A. PROTOCOL VIOLATION — only possible if `rules.maxLength`/`rules.pattern`
+ *      is defined by the negotiated version AND the name violates it.
+ *      Reported as category 'protocol', severity 'error'.
+ *   B. QUALITY WARNING — technically spec-valid, but likely to hurt agent
+ *      usability (too long by convention, odd characters, ambiguous name).
+ *      Reported as category 'quality', severity 'warning'.
+ *   C. Empty name is kept as a 'quality' error (not 'protocol') — no
+ *      supported version's spec actually forbids an empty string, but a
+ *      tool a client can't reference or distinguish is functionally
+ *      broken, which still deserves error severity without mislabeling it
+ *      a protocol violation.
+ */
+export declare function evaluateToolName(name: string, rules: ToolNameProtocolRules): ToolNameFinding[];
+export declare const qualityToolNamesCheck: Check;

package/dist/checks/quality-tool-names.js

@@ -0,0 +1,160 @@
+import { getProtocolQualityRules } from '../protocol/quality-rules.js';
+/** Ecosystem recommendation, not a protocol constraint — see the module-level
+ * note on `evaluateToolName` for the A/B/C distinction this check makes. */
+const MAX_REASONABLE_NAME_LENGTH = 128;
+/** Conservative, curated list — exact (case-insensitive) matches only, to
+ * avoid false-positiving on legitimately short/plain real tool names. */
+const PLACEHOLDER_NAMES = new Set([
+    'tool',
+    'test',
+    'temp',
+    'foo',
+    'bar',
+    'function',
+    'func',
+    'untitled',
+    'new_tool',
+    'newtool',
+    'example',
+    'sample',
+    'todo',
+    'tbd',
+    'xxx',
+]);
+function hasInvalidCharacters(name) {
+    // Whitespace (beyond a single space) and control characters break most
+    // client UIs and tool-name-as-identifier assumptions, even though the
+    // spec doesn't forbid them outright.
+    // eslint-disable-next-line no-control-regex
+    return /[\t\n\r\x00-\x08\x0b\x0c\x0e-\x1f]/.test(name);
+}
+/**
+ * Pure evaluation of a single tool name, independent of the rest of the
+ * connection (duplicate detection is connection-wide and stays in `run()`).
+ * Exported so tests can inject a synthetic `ToolNameProtocolRules` (e.g. a
+ * hypothetical future protocol version with a real length/pattern
+ * constraint) without needing that version to actually exist yet — see
+ * src/protocol/quality-rules.ts.
+ *
+ * The A/B/C distinction this check makes:
+ *   A. PROTOCOL VIOLATION — only possible if `rules.maxLength`/`rules.pattern`
+ *      is defined by the negotiated version AND the name violates it.
+ *      Reported as category 'protocol', severity 'error'.
+ *   B. QUALITY WARNING — technically spec-valid, but likely to hurt agent
+ *      usability (too long by convention, odd characters, ambiguous name).
+ *      Reported as category 'quality', severity 'warning'.
+ *   C. Empty name is kept as a 'quality' error (not 'protocol') — no
+ *      supported version's spec actually forbids an empty string, but a
+ *      tool a client can't reference or distinguish is functionally
+ *      broken, which still deserves error severity without mislabeling it
+ *      a protocol violation.
+ */
+export function evaluateToolName(name, rules) {
+    const findings = [];
+    if (name.trim() === '') {
+        findings.push({
+            severity: 'error',
+            category: 'quality',
+            message: 'Tool has an empty name — a client cannot reference or distinguish it.',
+            suggestedFixDescription: 'Give the tool a non-empty, descriptive name.',
+        });
+        return findings; // nothing else meaningful to evaluate on an empty name
+    }
+    if (rules.maxLength !== undefined && name.length > rules.maxLength) {
+        findings.push({
+            severity: 'error',
+            category: 'protocol',
+            message: `Tool name "${name.slice(0, 40)}..." is ${name.length} characters, exceeding the negotiated protocol's maximum of ${rules.maxLength} — this is a protocol violation, not a style recommendation.`,
+            suggestedFixDescription: `Shorten the tool name to ${rules.maxLength} characters or fewer to comply with the negotiated protocol version.`,
+        });
+    }
+    else if (name.length > MAX_REASONABLE_NAME_LENGTH) {
+        findings.push({
+            severity: 'warning',
+            category: 'quality',
+            confidence: 'medium',
+            message: `Tool name "${name.slice(0, 40)}..." name is ${name.length} characters, exceeding the recommended ${MAX_REASONABLE_NAME_LENGTH}.`,
+            suggestedFixDescription: 'Shorten the tool name to something concise and memorable.',
+        });
+    }
+    if (rules.pattern && !rules.pattern.test(name)) {
+        findings.push({
+            severity: 'error',
+            category: 'protocol',
+            message: `Tool name "${name}" does not match the naming pattern required by the negotiated protocol version — this is a protocol violation, not a style recommendation.`,
+            suggestedFixDescription: 'Rename the tool to match the naming pattern required by the negotiated protocol version.',
+        });
+    }
+    else if (hasInvalidCharacters(name)) {
+        findings.push({
+            severity: 'warning',
+            category: 'quality',
+            message: `Tool name "${JSON.stringify(name)}" contains whitespace/control characters that may break client tooling.`,
+            suggestedFixDescription: 'Use only plain, printable characters in tool names (letters, digits, -, _).',
+        });
+    }
+    if (name.length === 1 || PLACEHOLDER_NAMES.has(name.trim().toLowerCase())) {
+        findings.push({
+            severity: 'warning',
+            category: 'quality',
+            confidence: 'medium',
+            message: `Tool name "${name}" is ambiguous or looks like a placeholder — it doesn't communicate what the tool does.`,
+            suggestedFixDescription: 'Rename the tool to describe its action, e.g. "search_flights" instead of "tool".',
+        });
+    }
+    return findings;
+}
+export const qualityToolNamesCheck = {
+    id: 'quality.tool-name',
+    description: 'Flags empty, duplicate, overly long, or placeholder-looking tool names; distinguishes protocol-version-defined violations from quality recommendations.',
+    run(connection) {
+        const results = [];
+        try {
+            if (!connection.tools || !Array.isArray(connection.tools)) {
+                return results;
+            }
+            const rules = getProtocolQualityRules(connection.protocolVersion?.negotiated).toolName;
+            const seen = new Map();
+            for (const tool of connection.tools) {
+                const name = tool.name;
+                seen.set(name, (seen.get(name) ?? 0) + 1);
+                for (const finding of evaluateToolName(name, rules)) {
+                    results.push({
+                        checkId: 'quality.tool-name',
+                        severity: finding.severity,
+                        message: finding.message,
+                        serverName: connection.server.name,
+                        toolName: name,
+                        category: finding.category,
+                        ...(finding.confidence ? { confidence: finding.confidence } : {}),
+                        suggestedFix: { description: finding.suggestedFixDescription },
+                    });
+                }
+            }
+            for (const [name, count] of seen) {
+                if (count > 1) {
+                    results.push({
+                        checkId: 'quality.tool-name',
+                        severity: 'error',
+                        message: `Tool name "${name}" is declared ${count} times — a client cannot reliably invoke a specific one by name.`,
+                        serverName: connection.server.name,
+                        toolName: name,
+                        category: 'quality',
+                        details: { duplicateCount: count },
+                        suggestedFix: { description: `Rename duplicate "${name}" tools so every tool name is unique.` },
+                    });
+                }
+            }
+        }
+        catch (err) {
+            results.push({
+                checkId: 'quality.tool-name',
+                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-output-schema.d.ts

@@ -0,0 +1,10 @@
+import type { Check } from '../types.js';
+/**
+ * `outputSchema` is optional per the MCP spec (2025-06-18+) — this check
+ * never flags its absence. It only inspects an `outputSchema` that IS
+ * present, and only for basic structural validity (same shape rules as
+ * `inputSchema`: must be an object, should declare "object" as its type).
+ * Malformed output schemas are a quality warning, not a protocol error,
+ * since a client can simply ignore an outputSchema it can't parse.
+ */
+export declare const qualityToolOutputSchemaCheck: Check;

package/dist/checks/quality-tool-output-schema.js

@@ -0,0 +1,76 @@
+/**
+ * `outputSchema` is optional per the MCP spec (2025-06-18+) — this check
+ * never flags its absence. It only inspects an `outputSchema` that IS
+ * present, and only for basic structural validity (same shape rules as
+ * `inputSchema`: must be an object, should declare "object" as its type).
+ * Malformed output schemas are a quality warning, not a protocol error,
+ * since a client can simply ignore an outputSchema it can't parse.
+ */
+export const qualityToolOutputSchemaCheck = {
+    id: 'quality.output-schema',
+    description: 'Flags tool outputSchemas that are present but structurally malformed. Never flags a missing outputSchema — it is optional.',
+    run(connection) {
+        const results = [];
+        try {
+            if (!connection.tools || !Array.isArray(connection.tools)) {
+                return results;
+            }
+            for (const tool of connection.tools) {
+                const schema = tool.outputSchema;
+                if (schema === undefined)
+                    continue; // optional; absence is fine
+                if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+                    const actualType = schema === null ? 'null' : Array.isArray(schema) ? 'array' : typeof schema;
+                    results.push({
+                        checkId: 'quality.output-schema',
+                        severity: 'warning',
+                        message: `Tool "${tool.name}" declares an outputSchema, but it is ${actualType} instead of a JSON Schema object.`,
+                        serverName: connection.server.name,
+                        toolName: tool.name,
+                        category: 'quality',
+                        details: { actualType },
+                        suggestedFix: {
+                            description: 'Replace outputSchema with a valid JSON Schema object, or remove it if not needed.',
+                        },
+                    });
+                    continue;
+                }
+                const schemaObj = schema;
+                const hasType = typeof schemaObj.type === 'string' || Array.isArray(schemaObj.type);
+                const hasCombinatorOrRef = Boolean(schemaObj.$ref) || Boolean(schemaObj.oneOf) || Boolean(schemaObj.anyOf) || Boolean(schemaObj.allOf);
+                if (!hasType && !hasCombinatorOrRef) {
+                    results.push({
+                        checkId: 'quality.output-schema',
+                        severity: 'warning',
+                        message: `Tool "${tool.name}" outputSchema is missing a "type" or combinator field.`,
+                        serverName: connection.server.name,
+                        toolName: tool.name,
+                        category: 'quality',
+                        suggestedFix: { description: 'Add `"type": "object"` to the outputSchema.' },
+                    });
+                }
+                else if (typeof schemaObj.type === 'string' && schemaObj.type !== 'object') {
+                    results.push({
+                        checkId: 'quality.output-schema',
+                        severity: 'warning',
+                        message: `Tool "${tool.name}" outputSchema declares type "${schemaObj.type}" instead of "object".`,
+                        serverName: connection.server.name,
+                        toolName: tool.name,
+                        category: 'quality',
+                        suggestedFix: { description: 'Change outputSchema\'s top-level "type" to "object".' },
+                    });
+                }
+            }
+        }
+        catch (err) {
+            results.push({
+                checkId: 'quality.output-schema',
+                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-surface.d.ts

@@ -0,0 +1,13 @@
+import type { Check } from '../types.js';
+export declare const DEFAULT_MAX_TOOLS_WARNING_THRESHOLD = 100;
+/**
+ * Factory rather than a static Check, so the tool-count threshold can be
+ * overridden by policy (see `policy.ts`'s `quality.maxTools`) without
+ * needing a second, parallel check — same pattern `createPolicyChecks`
+ * already uses for configurable org rules.
+ */
+export declare function createToolSurfaceCheck(options?: {
+    maxTools?: number;
+}): Check;
+/** Default instance (threshold 100) for the standard `allChecks` list. */
+export declare const qualityToolSurfaceCheck: Check;

package/dist/checks/quality-tool-surface.js

@@ -0,0 +1,99 @@
+export const DEFAULT_MAX_TOOLS_WARNING_THRESHOLD = 100;
+function normalizeForSimilarity(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+/**
+ * Factory rather than a static Check, so the tool-count threshold can be
+ * overridden by policy (see `policy.ts`'s `quality.maxTools`) without
+ * needing a second, parallel check — same pattern `createPolicyChecks`
+ * already uses for configurable org rules.
+ */
+export function createToolSurfaceCheck(options = {}) {
+    const maxTools = options.maxTools ?? DEFAULT_MAX_TOOLS_WARNING_THRESHOLD;
+    return {
+        id: 'quality.tool-surface',
+        description: `Flags excessive tool counts (default warning threshold: ${DEFAULT_MAX_TOOLS_WARNING_THRESHOLD}) and near-duplicate tool names/descriptions.`,
+        run(connection) {
+            const results = [];
+            try {
+                const tools = connection.tools;
+                if (!tools || !Array.isArray(tools) || tools.length === 0) {
+                    return results;
+                }
+                if (tools.length > maxTools) {
+                    results.push({
+                        checkId: 'quality.tool-surface',
+                        severity: 'warning',
+                        message: `Server exposes ${tools.length} tools, exceeding the ${maxTools}-tool threshold. Large tool surfaces can increase agent/tool-selection complexity.`,
+                        serverName: connection.server.name,
+                        category: 'quality',
+                        details: { toolCount: tools.length, threshold: maxTools },
+                        suggestedFix: {
+                            description: 'Consider splitting this server, consolidating overlapping tools, or raising the policy threshold if this is intentional.',
+                        },
+                    });
+                }
+                // Near-duplicate names: same normalized form but not byte-identical.
+                // (Exact duplicates are quality.tool-name's job.)
+                const byNormalized = new Map();
+                for (const tool of tools) {
+                    const key = normalizeForSimilarity(tool.name);
+                    if (!key)
+                        continue;
+                    const group = byNormalized.get(key) ?? [];
+                    group.push(tool.name);
+                    byNormalized.set(key, group);
+                }
+                for (const group of byNormalized.values()) {
+                    const distinct = [...new Set(group)];
+                    if (distinct.length > 1) {
+                        results.push({
+                            checkId: 'quality.tool-surface',
+                            severity: 'warning',
+                            message: `Tools ${distinct.map((n) => `"${n}"`).join(', ')} have near-identical names — this can confuse tool selection.`,
+                            serverName: connection.server.name,
+                            category: 'quality',
+                            details: { similarNames: distinct },
+                            suggestedFix: { description: 'Rename these tools to be clearly distinct from one another.' },
+                        });
+                    }
+                }
+                // Repeated, non-trivial descriptions shared by 3+ tools.
+                const byDescription = new Map();
+                for (const tool of tools) {
+                    const desc = tool.description?.trim();
+                    if (!desc || desc.length < 15)
+                        continue; // trivial/short strings collide legitimately
+                    const names = byDescription.get(desc) ?? [];
+                    names.push(tool.name);
+                    byDescription.set(desc, names);
+                }
+                for (const [desc, names] of byDescription) {
+                    if (names.length >= 3) {
+                        results.push({
+                            checkId: 'quality.tool-surface',
+                            severity: 'warning',
+                            message: `${names.length} tools (${names.map((n) => `"${n}"`).join(', ')}) share the exact same description — each tool should describe its own specific behavior.`,
+                            serverName: connection.server.name,
+                            category: 'quality',
+                            details: { sharedDescription: desc, toolNames: names },
+                            suggestedFix: { description: 'Write a distinct, specific description for each of these tools.' },
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                results.push({
+                    checkId: 'quality.tool-surface',
+                    severity: 'error',
+                    message: `check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                    serverName: connection.server.name,
+                    category: 'quality',
+                });
+            }
+            return results;
+        },
+    };
+}
+/** Default instance (threshold 100) for the standard `allChecks` list. */
+export const qualityToolSurfaceCheck = createToolSurfaceCheck();

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 export interface ParsedArgs {
-    command: 'check' | 'watch' | 'check-all' | 'diff' | 'fix' | 'help' | 'version';
+    command: 'check' | 'watch' | 'check-all' | 'diff' | 'fix' | 'score' | 'help' | 'version';
     configPath?: string;
     configPathB?: string;
     globPattern?: string;
@@ -18,6 +18,8 @@ export interface ParsedArgs {
     failOn: 'error' | 'warning';
     checkFilter?: string;
     dryRun: boolean;
+    /** Include the MCP quality score section in the report (`--score`, or implied by the `score` command). */
+    showScore: boolean;
     /** "auto" (default) or an explicit MCP protocolVersion string, e.g. "2025-06-18". */
     protocolVersion: string;
 }