mcp-medic 1.2.2 → 1.2.3

package/dist/protocol/connect.js

@@ -67,6 +67,23 @@ function validateResponse(response, expectedId) {
     }
     return response.result;
 }
+function normalizeToolAnnotations(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const annotations = {};
+    if (typeof record.title === 'string')
+        annotations.title = record.title;
+    if (typeof record.readOnlyHint === 'boolean')
+        annotations.readOnlyHint = record.readOnlyHint;
+    if (typeof record.destructiveHint === 'boolean')
+        annotations.destructiveHint = record.destructiveHint;
+    if (typeof record.idempotentHint === 'boolean')
+        annotations.idempotentHint = record.idempotentHint;
+    if (typeof record.openWorldHint === 'boolean')
+        annotations.openWorldHint = record.openWorldHint;
+    return annotations;
+}
 function normalizeTools(result) {
     if (!Array.isArray(result.tools))
         throw new Error('tools/list response has no tools array');
@@ -77,8 +94,11 @@ function normalizeTools(result) {
         const value = tool;
         return {
             name: value.name,
+            ...(typeof value.title === 'string' ? { title: value.title } : {}),
             ...(typeof value.description === 'string' ? { description: value.description } : {}),
             inputSchema: value.inputSchema,
+            ...(value.outputSchema !== undefined ? { outputSchema: value.outputSchema } : {}),
+            ...(normalizeToolAnnotations(value.annotations) ? { annotations: normalizeToolAnnotations(value.annotations) } : {}),
         };
     });
 }
@@ -93,11 +113,29 @@ function normalizeResources(result) {
         return {
             uri: value.uri,
             ...(typeof value.name === 'string' ? { name: value.name } : {}),
+            ...(typeof value.title === 'string' ? { title: value.title } : {}),
             ...(typeof value.description === 'string' ? { description: value.description } : {}),
             ...(typeof value.mimeType === 'string' ? { mimeType: value.mimeType } : {}),
+            ...(typeof value.size === 'number' ? { size: value.size } : {}),
         };
     });
 }
+function normalizePromptArgument(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return {};
+    }
+    const record = value;
+    const arg = {};
+    if (typeof record.name === 'string')
+        arg.name = record.name;
+    if (typeof record.title === 'string')
+        arg.title = record.title;
+    if (typeof record.description === 'string')
+        arg.description = record.description;
+    if (typeof record.required === 'boolean')
+        arg.required = record.required;
+    return arg;
+}
 function normalizePrompts(result) {
     if (!Array.isArray(result.prompts))
         throw new Error('prompts/list response has no prompts array');
@@ -108,8 +146,11 @@ function normalizePrompts(result) {
         const value = prompt;
         return {
             name: value.name,
+            ...(typeof value.title === 'string' ? { title: value.title } : {}),
             ...(typeof value.description === 'string' ? { description: value.description } : {}),
-            ...(Array.isArray(value.arguments) ? { arguments: value.arguments } : {}),
+            ...(Array.isArray(value.arguments)
+                ? { arguments: value.arguments.map(normalizePromptArgument) }
+                : {}),
         };
     });
 }

package/dist/quality-score.d.ts

@@ -0,0 +1,33 @@
+import type { MCPConnection, DiagnosticResult, RunReport, QualityDimension, QualityDeduction, QualityScoreBreakdown, ReportQualityScore } from './types.js';
+/**
+ * Deterministic MCP quality score. No LLM, no randomness, no network
+ * calls beyond the MCP inspection `connect()` already performed — the same
+ * report always produces the same score.
+ *
+ * Design: diagnostics -> normalized per-checkId deductions -> capped
+ * per-dimension score -> weighted overall score. This keeps the score
+ * fully derived from (and consistent with) the diagnostics that are also
+ * shown in the report, rather than an independent "second opinion" — see
+ * .agent-room/DECISIONS.md for the full rationale.
+ *
+ * (Result types — QualityDimension, QualityDeduction, QualityScoreBreakdown,
+ * ReportQualityScore — live in src/types.ts alongside RunReport, since
+ * RunReport.quality is one of them; this module just implements the math.)
+ */
+export type { QualityDimension, QualityDeduction, QualityScoreBreakdown, ReportQualityScore };
+export declare const QUALITY_DIMENSIONS: readonly QualityDimension[];
+/** Suggested weights from the product spec; documented here since every
+ * point deduction must be explainable in terms of these. */
+export declare const QUALITY_DIMENSION_WEIGHTS: Record<QualityDimension, number>;
+/**
+ * Computes a quality score for one connection. Returns `undefined` for a
+ * connection that never connected — there's nothing meaningful to score
+ * (no tools/schema/capabilities were ever observed).
+ */
+export declare function computeConnectionQualityScore(connection: MCPConnection, diagnostics: DiagnosticResult[]): QualityScoreBreakdown | undefined;
+/**
+ * Aggregate score across every connected server in a report (simple mean —
+ * deliberately not weighted by tool count, so one huge server can't drown
+ * out the rest of a fleet). Returns `undefined` if no server connected.
+ */
+export declare function computeReportQualityScore(report: RunReport): ReportQualityScore | undefined;

package/dist/quality-score.js

@@ -0,0 +1,163 @@
+import { categoryOf } from './diagnostics.js';
+export const QUALITY_DIMENSIONS = [
+    'protocol',
+    'schema',
+    'usability',
+    'security',
+    'reliability',
+];
+/** Suggested weights from the product spec; documented here since every
+ * point deduction must be explainable in terms of these. */
+export const QUALITY_DIMENSION_WEIGHTS = {
+    protocol: 0.25,
+    schema: 0.2,
+    usability: 0.2,
+    security: 0.2,
+    reliability: 0.15,
+};
+// Deduction weights: chosen so a handful of real problems meaningfully move
+// the score, while a single noisy checkId can never wipe out a whole
+// dimension on its own (the per-checkId cap) — this directly implements
+// "avoid double-counting" / "sensible caps" from the product spec: e.g. 20
+// tools sharing one description problem cost at most 15 points total, not 60.
+const SEVERITY_POINTS = { error: 8, warning: 3, info: 1 };
+const SEVERITY_CAP_PER_CHECK = { error: 25, warning: 15, info: 5 };
+function categoryToDimension(category) {
+    switch (category) {
+        case 'protocol':
+            return 'protocol';
+        case 'schema':
+            return 'schema';
+        case 'security':
+            return 'security';
+        case 'reliability':
+            return 'reliability';
+        // 'usability', 'quality' (the broad bucket most tool/resource/prompt
+        // quality checks use), and 'configuration' (policy.* checks) all land
+        // under the "Agent usability" dimension from the product spec.
+        case 'usability':
+        case 'quality':
+        case 'configuration':
+        default:
+            return 'usability';
+    }
+}
+function describeDeduction(checkId, severity, count) {
+    const plural = count === 1 ? '' : 's';
+    return `${count} ${severity}${plural} from "${checkId}"`;
+}
+function deductionsFromDiagnostics(dimension, diagnostics) {
+    const grouped = new Map();
+    for (const d of diagnostics) {
+        if (categoryToDimension(categoryOf(d)) !== dimension)
+            continue;
+        const key = `${d.checkId}|${d.severity}`;
+        const entry = grouped.get(key) ?? { checkId: d.checkId, severity: d.severity, count: 0 };
+        entry.count += 1;
+        grouped.set(key, entry);
+    }
+    const deductions = [];
+    for (const { checkId, severity, count } of grouped.values()) {
+        const points = Math.min(count * SEVERITY_POINTS[severity], SEVERITY_CAP_PER_CHECK[severity]);
+        deductions.push({ dimension, checkId, severity, count, points, description: describeDeduction(checkId, severity, count) });
+    }
+    return deductions;
+}
+/** Protocol-dimension facts that live on `MCPConnection` rather than as
+ * diagnostics (capability negotiation isn't produced by a `Check`). */
+function protocolConnectionDeductions(connection) {
+    const deductions = [];
+    if (connection.capabilityErrors?.resources) {
+        deductions.push({
+            dimension: 'protocol',
+            checkId: 'protocol.capability-error',
+            severity: 'warning',
+            count: 1,
+            points: 15,
+            description: 'resources/list failed despite being declared as a capability',
+        });
+    }
+    if (connection.capabilityErrors?.prompts) {
+        deductions.push({
+            dimension: 'protocol',
+            checkId: 'protocol.capability-error',
+            severity: 'warning',
+            count: 1,
+            points: 15,
+            description: 'prompts/list failed despite being declared as a capability',
+        });
+    }
+    if (connection.protocolVersion &&
+        connection.protocolVersion.negotiated &&
+        connection.protocolVersion.negotiated !== connection.protocolVersion.requested) {
+        deductions.push({
+            dimension: 'protocol',
+            checkId: 'protocol.version-downgrade',
+            severity: 'info',
+            count: 1,
+            points: 5,
+            description: `server negotiated ${connection.protocolVersion.negotiated} instead of the requested ${connection.protocolVersion.requested}`,
+        });
+    }
+    if (!connection.serverInfo?.name) {
+        deductions.push({
+            dimension: 'protocol',
+            checkId: 'protocol.missing-server-info',
+            severity: 'info',
+            count: 1,
+            points: 5,
+            description: 'server did not report its name/version in serverInfo',
+        });
+    }
+    return deductions;
+}
+function dimensionScore(deductions) {
+    const totalPoints = deductions.reduce((sum, d) => sum + d.points, 0);
+    return Math.max(0, Math.min(100, Math.round(100 - totalPoints)));
+}
+/**
+ * Computes a quality score for one connection. Returns `undefined` for a
+ * connection that never connected — there's nothing meaningful to score
+ * (no tools/schema/capabilities were ever observed).
+ */
+export function computeConnectionQualityScore(connection, diagnostics) {
+    if (connection.status !== 'connected')
+        return undefined;
+    const relevant = diagnostics.filter((d) => d.serverName === connection.server.name);
+    const allDeductions = [
+        ...protocolConnectionDeductions(connection),
+        ...QUALITY_DIMENSIONS.flatMap((dim) => deductionsFromDiagnostics(dim, relevant)),
+    ];
+    const dimensions = Object.fromEntries(QUALITY_DIMENSIONS.map((dim) => [dim, dimensionScore(allDeductions.filter((d) => d.dimension === dim))]));
+    const overall = Math.round(QUALITY_DIMENSIONS.reduce((sum, dim) => sum + dimensions[dim] * QUALITY_DIMENSION_WEIGHTS[dim], 0));
+    return {
+        overall,
+        dimensions,
+        deductions: allDeductions.filter((d) => d.points > 0).sort((a, b) => b.points - a.points),
+    };
+}
+/**
+ * Aggregate score across every connected server in a report (simple mean —
+ * deliberately not weighted by tool count, so one huge server can't drown
+ * out the rest of a fleet). Returns `undefined` if no server connected.
+ */
+export function computeReportQualityScore(report) {
+    const perServer = {};
+    for (const connection of report.connections) {
+        const breakdown = computeConnectionQualityScore(connection, report.diagnostics);
+        if (breakdown)
+            perServer[connection.server.name] = breakdown;
+    }
+    const names = Object.keys(perServer);
+    if (names.length === 0)
+        return undefined;
+    const dimensions = Object.fromEntries(QUALITY_DIMENSIONS.map((dim) => [
+        dim,
+        Math.round(names.reduce((sum, n) => sum + perServer[n].dimensions[dim], 0) / names.length),
+    ]));
+    const overall = Math.round(names.reduce((sum, n) => sum + perServer[n].overall, 0) / names.length);
+    const deductions = names
+        .flatMap((n) => perServer[n].deductions)
+        .sort((a, b) => b.points - a.points);
+    return { overall, dimensions, deductions, perServer };
+}

package/dist/report.d.ts

@@ -1,6 +1,9 @@
 import type { RunReport } from './types.js';
 export interface FormatReportOptions {
     showFixes?: boolean;
+    /** Include the MCP quality score section (Phase 7). Off by default so a
+     * plain `check` report stays short; `--score`/`score` turn it on. */
+    showScore?: boolean;
 }
 /** Human-readable plain text report formatter. */
 export declare function formatReportHuman(report: RunReport, options?: FormatReportOptions): string;

package/dist/report.js

@@ -1,3 +1,26 @@
+const DIMENSION_LABELS = {
+    protocol: 'Protocol',
+    schema: 'Schema',
+    usability: 'Agent usability',
+    security: 'Security',
+    reliability: 'Reliability',
+};
+function formatScoreBlock(label, score) {
+    const lines = [];
+    lines.push(label);
+    for (const [dim, value] of Object.entries(score.dimensions)) {
+        const name = (DIMENSION_LABELS[dim] ?? dim).padEnd(17, ' ');
+        lines.push(`  ${name} ${String(value).padStart(3, ' ')}/100`);
+    }
+    lines.push(`  ${'MCP QUALITY SCORE'.padEnd(17, ' ')} ${String(score.overall).padStart(3, ' ')}/100`);
+    if (score.deductions.length > 0) {
+        lines.push('  Deductions:');
+        for (const d of score.deductions) {
+            lines.push(`    -${d.points} ${d.description}`);
+        }
+    }
+    return lines;
+}
 /** Human-readable plain text report formatter. */
 export function formatReportHuman(report, options = {}) {
     const lines = [];
@@ -30,6 +53,15 @@ export function formatReportHuman(report, options = {}) {
         if (conn.error) {
             lines.push(`  ${conn.error.stage}: ${conn.error.message}`);
         }
+        const perServerScore = options.showScore ? report.quality?.perServer[conn.server.name] : undefined;
+        if (perServerScore) {
+            lines.push('');
+            lines.push(...formatScoreBlock('QUALITY', perServerScore));
+        }
+    }
+    if (options.showScore && report.quality && Object.keys(report.quality.perServer).length > 1) {
+        lines.push('');
+        lines.push(...formatScoreBlock('OVERALL QUALITY (all servers)', report.quality));
     }
     if (report.diagnostics.length > 0) {
         lines.push('');

package/dist/types.d.ts

@@ -14,21 +14,48 @@ export interface MCPConfig {
     servers: MCPServerConfig[];
     sourcePath?: string;
 }
+/** Per the MCP spec's `ToolAnnotations`: optional client *hints*, not
+ * authoritative security guarantees — a server can lie about any of these. */
+export interface MCPToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
 export interface MCPToolDefinition {
     name: string;
+    title?: string;
     description?: string;
     inputSchema: unknown;
+    /** Optional per spec; same shape as `inputSchema` when present. */
+    outputSchema?: unknown;
+    annotations?: MCPToolAnnotations;
 }
 export interface MCPResourceDefinition {
     uri: string;
+    /** Required by the MCP spec's `Resource` (extends `BaseMetadata`) — kept
+     * optional here because mcp-medic reports a missing name as a diagnostic
+     * rather than failing the whole `resources/list` response over it. */
     name?: string;
+    title?: string;
     description?: string;
     mimeType?: string;
+    size?: number;
+}
+export interface MCPPromptArgument {
+    /** Required by the MCP spec's `PromptArgument` (extends `BaseMetadata`) —
+     * kept optional here for the same reason as `MCPResourceDefinition.name`. */
+    name?: string;
+    title?: string;
+    description?: string;
+    required?: boolean;
 }
 export interface MCPPromptDefinition {
     name: string;
+    title?: string;
     description?: string;
-    arguments?: unknown[];
+    arguments?: MCPPromptArgument[];
 }
 export interface ProtocolVersionInfo {
     /** The protocolVersion this client sent in `initialize`. */
@@ -68,6 +95,10 @@ export interface MCPConnection {
     latencyMs?: number;
 }
 export type Severity = 'error' | 'warning' | 'info';
+/** Stable diagnostic taxonomy. Optional and additive — existing checks that
+ * don't set this are categorized by `inferDiagnosticCategory()` (src/diagnostics.ts)
+ * from their `checkId` prefix, so nothing that already works needs to change. */
+export type DiagnosticCategory = 'protocol' | 'schema' | 'quality' | 'security' | 'reliability' | 'usability' | 'configuration';
 export interface SuggestedFix {
     description: string;
     patch?: unknown;
@@ -80,6 +111,12 @@ export interface DiagnosticResult {
     toolName?: string;
     details?: unknown;
     suggestedFix?: SuggestedFix;
+    /** Optional; see `DiagnosticCategory`. */
+    category?: DiagnosticCategory;
+    /** Optional: how confident the check is that this is a real problem (vs. a heuristic guess). */
+    confidence?: 'low' | 'medium' | 'high';
+    /** Optional: link to a doc explaining the rule this diagnostic enforces. */
+    documentationUrl?: string;
 }
 export interface Check {
     id: string;
@@ -94,6 +131,28 @@ export interface RunOptions {
     /** "auto" (default) requests the newest protocol version this client supports; an explicit version string requests that version instead. */
     protocolVersion?: string;
 }
+/** The five scored dimensions of MCP quality (see src/quality-score.ts for the scoring model). */
+export type QualityDimension = 'protocol' | 'schema' | 'usability' | 'security' | 'reliability';
+export interface QualityDeduction {
+    dimension: QualityDimension;
+    checkId: string;
+    severity: Severity;
+    /** How many diagnostics from this checkId (at this severity) contributed. */
+    count: number;
+    /** Points actually deducted, after the per-checkId cap. */
+    points: number;
+    description: string;
+}
+export interface QualityScoreBreakdown {
+    overall: number;
+    dimensions: Record<QualityDimension, number>;
+    /** Only deductions with points > 0, most-costly first — every deduction here explains itself. */
+    deductions: QualityDeduction[];
+}
+export interface ReportQualityScore extends QualityScoreBreakdown {
+    /** Per-connected-server breakdown; a server that never connected has no entry (nothing to score). */
+    perServer: Record<string, QualityScoreBreakdown>;
+}
 export interface RunReport {
     configSource?: string;
     connections: MCPConnection[];
@@ -105,4 +164,7 @@ export interface RunReport {
         errors: number;
         warnings: number;
     };
+    /** Deterministic quality score derived from `diagnostics`/`connections` — see src/quality-score.ts.
+     * `undefined` when no server connected (nothing to score). */
+    quality?: ReportQualityScore;
 }

package/package.json

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