mcp-medic 1.2.2 → 1.2.3

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

@@ -0,0 +1,121 @@
+/** MCP's `Tool.name` (from `BaseMetadata`) has no documented pattern or
+ * length constraint in the spec — so none of these are "protocol
+ * violations" in the strict sense. Empty and duplicate names are still
+ * treated as errors here because a tool a client cannot reference or
+ * distinguish is functionally broken, not merely unstylish; everything
+ * else is a warning. */
+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);
+}
+export const qualityToolNamesCheck = {
+    id: 'quality.tool-name',
+    description: 'Flags empty, duplicate, overly long, or placeholder-looking tool names.',
+    run(connection) {
+        const results = [];
+        try {
+            if (!connection.tools || !Array.isArray(connection.tools)) {
+                return results;
+            }
+            const seen = new Map();
+            for (const tool of connection.tools) {
+                const name = tool.name;
+                seen.set(name, (seen.get(name) ?? 0) + 1);
+                if (name.trim() === '') {
+                    results.push({
+                        checkId: 'quality.tool-name',
+                        severity: 'error',
+                        message: 'Tool has an empty name — a client cannot reference or distinguish it.',
+                        serverName: connection.server.name,
+                        toolName: name,
+                        category: 'quality',
+                        suggestedFix: { description: 'Give the tool a non-empty, descriptive name.' },
+                    });
+                    continue;
+                }
+                if (name.length > MAX_REASONABLE_NAME_LENGTH) {
+                    results.push({
+                        checkId: 'quality.tool-name',
+                        severity: 'warning',
+                        message: `Tool "${name.slice(0, 40)}..." name is ${name.length} characters, exceeding the recommended ${MAX_REASONABLE_NAME_LENGTH}.`,
+                        serverName: connection.server.name,
+                        toolName: name,
+                        category: 'quality',
+                        confidence: 'medium',
+                        suggestedFix: { description: 'Shorten the tool name to something concise and memorable.' },
+                    });
+                }
+                if (hasInvalidCharacters(name)) {
+                    results.push({
+                        checkId: 'quality.tool-name',
+                        severity: 'warning',
+                        message: `Tool name "${JSON.stringify(name)}" contains whitespace/control characters that may break client tooling.`,
+                        serverName: connection.server.name,
+                        toolName: name,
+                        category: 'quality',
+                        suggestedFix: { description: 'Use only plain, printable characters in tool names (letters, digits, -, _).' },
+                    });
+                }
+                if (name.length === 1 || PLACEHOLDER_NAMES.has(name.trim().toLowerCase())) {
+                    results.push({
+                        checkId: 'quality.tool-name',
+                        severity: 'warning',
+                        message: `Tool name "${name}" is ambiguous or looks like a placeholder — it doesn't communicate what the tool does.`,
+                        serverName: connection.server.name,
+                        toolName: name,
+                        category: 'quality',
+                        confidence: 'medium',
+                        suggestedFix: { description: 'Rename the tool to describe its action, e.g. "search_flights" instead of "tool".' },
+                    });
+                }
+            }
+            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;
 }

package/dist/cli.js

@@ -14,6 +14,7 @@ import { loadPolicy, createPolicyChecks } from './policy.js';
 import { runFleetChecks, diffConfigs, filterDiagnosticsByBaseline } from './fleet.js';
 import { formatReportJUnit, formatFleetReportJUnit } from './junit.js';
 import { formatReportSarif } from './sarif.js';
+import { computeReportQualityScore } from './quality-score.js';
 import { SUPPORTED_PROTOCOL_VERSIONS } from './protocol/versions.js';
 import pc from 'picocolors';
 export function parseArgs(argv) {
@@ -25,6 +26,7 @@ export function parseArgs(argv) {
         failOn: 'error',
         dryRun: false,
         protocolVersion: 'auto',
+        showScore: false,
     };
     const positional = [];
     for (let i = 0; i < argv.length; i++) {
@@ -41,6 +43,9 @@ export function parseArgs(argv) {
         else if (arg === '--dry-run') {
             args.dryRun = true;
         }
+        else if (arg === '--score') {
+            args.showScore = true;
+        }
         else if (arg === '--help' || arg === '-h') {
             args.command = 'help';
         }
@@ -114,7 +119,7 @@ export function parseArgs(argv) {
     }
     if (args.command !== 'help' && args.command !== 'version') {
         const first = positional[0];
-        if (first === 'check' || first === 'watch' || first === 'check-all' || first === 'diff' || first === 'fix') {
+        if (first === 'check' || first === 'watch' || first === 'check-all' || first === 'diff' || first === 'fix' || first === 'score') {
             args.command = first;
             if (first === 'diff') {
                 args.configPath = positional[1];
@@ -128,6 +133,9 @@ export function parseArgs(argv) {
                     args.configPath = positional[1];
                 }
             }
+            if (first === 'score') {
+                args.showScore = true;
+            }
         }
         else if (first && !args.configPath) {
             args.configPath = first;
@@ -183,6 +191,7 @@ USAGE
   $ mcp-medic [check] [path/to/config.json] [options]
   $ mcp-medic check --registry <server-id> [options]
   $ mcp-medic check-all "<glob-pattern>" [options]
+  $ mcp-medic score <path/to/config.json> [options]
   $ mcp-medic diff <configA.json> <configB.json>
   $ mcp-medic watch <path/to/config.json> [options]
   $ mcp-medic fix <path/to/config.json> [--check <id>] [--dry-run]
@@ -196,10 +205,11 @@ OPTIONS
   --export-junit <file> Export report in JUnit XML format
   --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)
   --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
-  --json                Output report in JSON format
+  --json                Output report in JSON format (always includes a "quality" field)
   --timeout <ms>        Per-server handshake timeout in milliseconds (default: 5000)
   --protocol-version <v> MCP protocolVersion to request: "auto" (default, latest supported)
                         or an explicit version, e.g. ${SUPPORTED_PROTOCOL_VERSIONS[SUPPORTED_PROTOCOL_VERSIONS.length - 1]}
@@ -212,6 +222,13 @@ PROTOCOL VERSIONS
   older version instead; mcp-medic reports both and fails cleanly if the
   negotiated version isn't one this client supports.
 
+MCP QUALITY SCORE
+  A deterministic 0-100 score (no LLM, no randomness) across five weighted
+  dimensions: Protocol (25%), Schema (20%), Agent usability (20%), Security
+  (20%), Reliability (15%). Every point deducted is derived from an actual
+  diagnostic and is explained in the report's "Deductions" list. Policy can
+  gate on it via "quality": { "minimumScore": N } in .mcp-medic-policy.json.
+
 FIX OPTIONS (mcp-medic fix)
   --check <id>          Only offer fixes from this check id (e.g. security.untrusted-remote)
   --dry-run             Show every available fix as a diff; apply nothing, prompt for nothing
@@ -266,12 +283,32 @@ async function executeCheck(config, args) {
             try {
                 const baseline = JSON.parse(readFileSync(args.snapshotPath, 'utf-8'));
                 report = filterDiagnosticsByBaseline(report, baseline);
+                // The quality score must reflect what's actually being reported —
+                // recompute it against the post-baseline-filter diagnostics rather
+                // than leaving the pre-filter score (computed by runChecks) stale.
+                report.quality = computeReportQualityScore(report);
             }
             catch (err) {
                 console.error(pc.yellow(`Warning: Could not read snapshot baseline: ${String(err)}`));
             }
         }
     }
+    // Policy gate: fail if the computed quality score is below the configured
+    // minimum. This can't be a `Check` (it needs the score computed from every
+    // check's output, not a single connection), so it's enforced here instead.
+    const policy = loadPolicy(args.policyPath);
+    if (typeof policy?.quality?.minimumScore === 'number' && report.quality) {
+        if (report.quality.overall < policy.quality.minimumScore) {
+            report.diagnostics.push({
+                checkId: 'policy.minimum-quality-score',
+                severity: 'error',
+                message: `MCP quality score ${report.quality.overall} is below the policy minimum of ${policy.quality.minimumScore}.`,
+                serverName: config.servers.map((s) => s.name).join(', ') || '(no servers)',
+                category: 'configuration',
+            });
+            report.summary.errors += 1;
+        }
+    }
     // Handle update snapshot
     if (args.updateSnapshotPath) {
         try {
@@ -315,7 +352,7 @@ async function executeCheck(config, args) {
         console.log(formatReportJSON(report));
     }
     else {
-        console.log(colorizeHumanReport(formatReportHuman(report, { showFixes: args.showFixes })));
+        console.log(colorizeHumanReport(formatReportHuman(report, { showFixes: args.showFixes, showScore: args.showScore })));
     }
     const hasErrors = report.summary.errors > 0;
     const hasWarnings = report.summary.warnings > 0;

package/dist/diagnostics.d.ts

@@ -0,0 +1,11 @@
+import type { DiagnosticCategory, DiagnosticResult } from './types.js';
+/**
+ * Infers a stable category from a checkId's namespace prefix, for
+ * diagnostics that don't set `category` explicitly. This lets every
+ * existing check (schema.*, security.*, policy.*) participate in
+ * category-aware reporting/scoring without having to touch each one —
+ * only checks written after the taxonomy existed set `category` directly.
+ */
+export declare function inferDiagnosticCategory(checkId: string): DiagnosticCategory;
+/** The effective category of a diagnostic: its own `category` if set, else inferred from `checkId`. */
+export declare function categoryOf(diagnostic: DiagnosticResult): DiagnosticCategory;

package/dist/diagnostics.js

@@ -0,0 +1,28 @@
+/**
+ * Infers a stable category from a checkId's namespace prefix, for
+ * diagnostics that don't set `category` explicitly. This lets every
+ * existing check (schema.*, security.*, policy.*) participate in
+ * category-aware reporting/scoring without having to touch each one —
+ * only checks written after the taxonomy existed set `category` directly.
+ */
+export function inferDiagnosticCategory(checkId) {
+    if (checkId.startsWith('protocol.'))
+        return 'protocol';
+    if (checkId.startsWith('schema.'))
+        return 'schema';
+    if (checkId.startsWith('security.'))
+        return 'security';
+    if (checkId.startsWith('usability.'))
+        return 'usability';
+    if (checkId.startsWith('reliability.'))
+        return 'reliability';
+    if (checkId.startsWith('quality.'))
+        return 'quality';
+    if (checkId.startsWith('policy.') || checkId.startsWith('configuration.'))
+        return 'configuration';
+    return 'quality';
+}
+/** The effective category of a diagnostic: its own `category` if set, else inferred from `checkId`. */
+export function categoryOf(diagnostic) {
+    return diagnostic.category ?? inferDiagnosticCategory(diagnostic.checkId);
+}

package/dist/index.d.ts

@@ -21,4 +21,6 @@ export { allChecks } from './checks/index.js';
 export { SUPPORTED_PROTOCOL_VERSIONS, LATEST_SUPPORTED_PROTOCOL_VERSION, KNOWN_UNSUPPORTED_PROTOCOL_VERSIONS, isSupportedProtocolVersion, resolveRequestedProtocolVersion, } from './protocol/versions.js';
 export type { SupportedProtocolVersion, ProtocolVersionNegotiation } from './protocol/versions.js';
 export { isSecretKey, redactRecord, redactDeep, sanitizeServerConfig } from './redact.js';
+export { inferDiagnosticCategory, categoryOf } from './diagnostics.js';
+export { computeConnectionQualityScore, computeReportQualityScore, QUALITY_DIMENSIONS, QUALITY_DIMENSION_WEIGHTS, } from './quality-score.js';
 export * from './types.js';

package/dist/index.js

@@ -13,4 +13,6 @@ export { formatReportSarif } from './sarif.js';
 export { allChecks } from './checks/index.js';
 export { SUPPORTED_PROTOCOL_VERSIONS, LATEST_SUPPORTED_PROTOCOL_VERSION, KNOWN_UNSUPPORTED_PROTOCOL_VERSIONS, isSupportedProtocolVersion, resolveRequestedProtocolVersion, } from './protocol/versions.js';
 export { isSecretKey, redactRecord, redactDeep, sanitizeServerConfig } from './redact.js';
+export { inferDiagnosticCategory, categoryOf } from './diagnostics.js';
+export { computeConnectionQualityScore, computeReportQualityScore, QUALITY_DIMENSIONS, QUALITY_DIMENSION_WEIGHTS, } from './quality-score.js';
 export * from './types.js';

package/dist/orchestrator.js

@@ -1,4 +1,5 @@
 import { sanitizeServerConfig } from './redact.js';
+import { computeReportQualityScore } from './quality-score.js';
 async function connectStub(config) {
     return {
         server: config,
@@ -57,10 +58,15 @@ export async function runChecks(config, options = {}) {
         errors: diagnostics.filter((d) => d.severity === 'error').length,
         warnings: diagnostics.filter((d) => d.severity === 'warning').length,
     };
-    return {
+    const report = {
         configSource: config.sourcePath,
         connections,
         diagnostics,
         summary,
     };
+    const quality = computeReportQualityScore(report);
+    if (quality) {
+        report.quality = quality;
+    }
+    return report;
 }

package/dist/policy.d.ts

@@ -3,7 +3,16 @@ export interface MCPMedicPolicy {
     bannedTransports?: TransportType[];
     allowedDomains?: string[];
     minDescriptionLength?: number;
+    /** @deprecated use `quality.requireToolDescriptions` — kept for backward compatibility, same effect. */
     requireToolDescriptions?: boolean;
+    quality?: {
+        /** Gate: `check`/`check-all` fail (an error diagnostic is added) if the computed MCP quality score falls below this. */
+        minimumScore?: number;
+        /** Overrides quality.tool-surface's default 100-tool warning threshold with an org-enforced error threshold. */
+        maxTools?: number;
+        /** Same effect as the top-level (deprecated) `requireToolDescriptions`; this nested form takes precedence if both are set. */
+        requireToolDescriptions?: boolean;
+    };
 }
 export type MCPDoctorPolicy = MCPMedicPolicy;
 /**

package/dist/policy.js

@@ -145,5 +145,77 @@ export function createPolicyChecks(policy) {
             },
         });
     }
+    // 4. Require tool descriptions (nested quality.requireToolDescriptions takes
+    // precedence over the deprecated top-level field; either enables this).
+    const requireToolDescriptions = policy.quality?.requireToolDescriptions ?? policy.requireToolDescriptions;
+    if (requireToolDescriptions) {
+        checks.push({
+            id: 'policy.require-tool-descriptions',
+            description: 'Organizational policy: every tool must have a non-empty description.',
+            run(connection) {
+                const results = [];
+                try {
+                    if (!connection.tools)
+                        return results;
+                    for (const tool of connection.tools) {
+                        if (!tool.description || tool.description.trim() === '') {
+                            results.push({
+                                checkId: 'policy.require-tool-descriptions',
+                                severity: 'error',
+                                message: `Tool "${tool.name}" has no description — organizational policy requires one.`,
+                                serverName: connection.server.name,
+                                toolName: tool.name,
+                                category: 'configuration',
+                                suggestedFix: { description: `Add a description to tool "${tool.name}".` },
+                            });
+                        }
+                    }
+                }
+                catch (err) {
+                    results.push({
+                        checkId: 'policy.require-tool-descriptions',
+                        severity: 'error',
+                        message: `policy check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                        serverName: connection.server.name,
+                    });
+                }
+                return results;
+            },
+        });
+    }
+    // 5. Max tools (org-enforced hard limit; distinct from quality.tool-surface's
+    // default 100-tool *warning*, which stays a recommendation, not a policy gate).
+    if (typeof policy.quality?.maxTools === 'number' && policy.quality.maxTools > 0) {
+        const maxTools = policy.quality.maxTools;
+        checks.push({
+            id: 'policy.max-tools',
+            description: `Organizational policy: a server may expose at most ${maxTools} tools.`,
+            run(connection) {
+                const results = [];
+                try {
+                    const count = connection.tools?.length ?? 0;
+                    if (count > maxTools) {
+                        results.push({
+                            checkId: 'policy.max-tools',
+                            severity: 'error',
+                            message: `Server exposes ${count} tools, exceeding organizational policy limit of ${maxTools}.`,
+                            serverName: connection.server.name,
+                            category: 'configuration',
+                            details: { toolCount: count, maxTools },
+                        });
+                    }
+                }
+                catch (err) {
+                    results.push({
+                        checkId: 'policy.max-tools',
+                        severity: 'error',
+                        message: `policy check failed internally: ${err instanceof Error ? err.message : String(err)}`,
+                        serverName: connection.server.name,
+                    });
+                }
+                return results;
+            },
+        });
+    }
     return checks;
 }