mcp-lint 0.7.0 → 0.9.0

package/dist/audit/report.js

@@ -0,0 +1,327 @@
+import { z } from 'zod';
+import { computeQualityReport } from '../core/quality-score.js';
+import { buildTokenBudget, DEFAULT_TOKEN_THRESHOLDS, } from './tokens.js';
+import { VERSION } from '../version.js';
+export const AUDIT_REPORT_SCHEMA_VERSION = 1;
+export const QUALITY_ALGORITHM = 'quality-v2';
+export class AuditInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuditInputError';
+    }
+}
+const severitySchema = z.enum(['error', 'warning', 'info']);
+const findingSchema = z.object({
+    ruleId: z.string().min(1),
+    severity: severitySchema,
+    message: z.string(),
+    toolName: z.string(),
+    path: z.string(),
+    clients: z.array(z.string()),
+    fixable: z.boolean(),
+}).strict();
+const auditToolSchema = z.object({
+    name: z.string().min(1),
+    hasDescription: z.boolean(),
+    hasInputSchema: z.boolean(),
+    hasOutputSchema: z.boolean(),
+}).strict();
+const tokenBudgetSchema = z.object({
+    method: z.literal('chars-div-4'),
+    approximate: z.literal(true),
+    chars: z.number().int().nonnegative(),
+    tokens: z.number().int().nonnegative(),
+    toolCount: z.number().int().nonnegative(),
+    thresholds: z.object({
+        warn: z.number().int().positive(),
+        over: z.number().int().positive(),
+        schemaWarn: z.number().int().positive(),
+    }).strict(),
+    level: z.enum(['ok', 'warn', 'over']),
+    tools: z.array(z.object({
+        name: z.string(),
+        chars: z.number().int().nonnegative(),
+        tokens: z.number().int().nonnegative(),
+        schemaTokens: z.number().int().nonnegative(),
+        oversizedSchema: z.boolean(),
+    }).strict()),
+    repeatedDescriptions: z.array(z.object({
+        description: z.string(),
+        tools: z.array(z.string()),
+    }).strict()),
+    note: z.string().min(1),
+}).strict();
+const qualitySchema = z.object({
+    algorithm: z.literal(QUALITY_ALGORITHM),
+    overall: z.number().int().min(0).max(100),
+    grade: z.enum(['A', 'B', 'C', 'D', 'F']),
+    weights: z.object({
+        description: z.literal(25),
+        inputSchema: z.literal(25),
+        outputSchema: z.literal(10),
+        lintClean: z.literal(40),
+        error: z.literal(15),
+        warning: z.literal(5),
+    }).strict(),
+    coverage: z.object({
+        toolCount: z.number().int().nonnegative(),
+        withDescription: z.number().int().nonnegative(),
+        withInputSchema: z.number().int().nonnegative(),
+        withOutputSchema: z.number().int().nonnegative(),
+    }).strict(),
+    confidence: z.enum(['low', 'medium']),
+    note: z.string().min(1),
+}).strict();
+function sectionSchema(data) {
+    return z.object({
+        status: z.enum(['ran', 'not_run', 'partial', 'failed']),
+        reason: z.string().min(1).optional(),
+        data: data.optional(),
+    }).strict().superRefine((value, ctx) => {
+        if (value.status === 'ran' && value.data === undefined) {
+            ctx.addIssue({ code: 'custom', message: 'A ran section needs data.' });
+        }
+        if ((value.status === 'not_run' || value.status === 'failed') && (value.reason === undefined || value.data !== undefined)) {
+            ctx.addIssue({ code: 'custom', message: 'A not_run or failed section needs a reason and no data.' });
+        }
+        if (value.status === 'partial' && (value.reason === undefined || value.data === undefined)) {
+            ctx.addIssue({ code: 'custom', message: 'A partial section needs a reason and data.' });
+        }
+    });
+}
+const notRunSchema = z.object({
+    status: z.enum(['not_run', 'failed']),
+    reason: z.string().min(1),
+}).strict();
+export const AuditReportSchema = z.object({
+    schemaVersion: z.literal(AUDIT_REPORT_SCHEMA_VERSION),
+    generatedAt: z.string().min(1),
+    tool: z.object({ name: z.literal('mcp-lint'), version: z.string().min(1) }).strict(),
+    scope: z.object({
+        source: z.string().min(1),
+        mode: z.literal('offline-tools'),
+        liveServer: z.literal(false),
+        toolsInvoked: z.literal(false),
+    }).strict(),
+    tools: z.array(auditToolSchema),
+    duplicateToolNames: z.array(z.string()),
+    findings: sectionSchema(z.array(findingSchema)),
+    severity: sectionSchema(z.object({
+        error: z.number().int().nonnegative(),
+        warning: z.number().int().nonnegative(),
+        info: z.number().int().nonnegative(),
+    }).strict()),
+    compatibility: notRunSchema,
+    tokenBudget: sectionSchema(tokenBudgetSchema),
+    quality: sectionSchema(qualitySchema),
+    recovery: notRunSchema,
+    preflight: notRunSchema,
+    recommendations: z.array(z.string()),
+    coverage: z.object({
+        ran: z.array(z.string()),
+        notRun: z.array(z.string()),
+        confidence: z.enum(['low', 'medium', 'high']),
+    }).strict(),
+}).strict();
+function notRun(reason) {
+    return { status: 'not_run', reason };
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function requireTools(value) {
+    if (!Array.isArray(value)) {
+        throw new AuditInputError('tools must be an array.');
+    }
+    return value.map((tool, index) => {
+        if (!isRecord(tool))
+            throw new AuditInputError(`tools[${index}] must be an object.`);
+        if (typeof tool.name !== 'string' || tool.name.trim() === '') {
+            throw new AuditInputError(`tools[${index}].name must be a non-empty string.`);
+        }
+        if (tool.description !== undefined && typeof tool.description !== 'string') {
+            throw new AuditInputError(`tools[${index}].description must be a string.`);
+        }
+        if (tool.inputSchema !== undefined && !isRecord(tool.inputSchema)) {
+            throw new AuditInputError(`tools[${index}].inputSchema must be an object.`);
+        }
+        if (tool.outputSchema !== undefined && !isRecord(tool.outputSchema)) {
+            throw new AuditInputError(`tools[${index}].outputSchema must be an object.`);
+        }
+        return tool;
+    });
+}
+function duplicateNames(tools) {
+    const counts = new Map();
+    for (const tool of tools) {
+        const name = tool.name;
+        counts.set(name, (counts.get(name) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([name]) => name)
+        .sort((a, b) => a.localeCompare(b));
+}
+function findingsFrom(diagnostics) {
+    return diagnostics
+        .map((diagnostic) => ({
+        ruleId: diagnostic.ruleId,
+        severity: diagnostic.severity,
+        message: diagnostic.message,
+        toolName: diagnostic.toolName,
+        path: diagnostic.path,
+        clients: [...diagnostic.clients].sort((a, b) => a.localeCompare(b)),
+        fixable: diagnostic.fix != null,
+    }))
+        .sort((a, b) => a.toolName.localeCompare(b.toolName)
+        || a.path.localeCompare(b.path)
+        || a.ruleId.localeCompare(b.ruleId)
+        || a.message.localeCompare(b.message));
+}
+function recommendations(input) {
+    const lines = [];
+    if (!input.findingsRan) {
+        lines.push('Schema lint did not run. A missing finding list is not a pass.');
+    }
+    else if ((input.counts?.error ?? 0) > 0) {
+        lines.push('Fix error findings before shipping this tools list.');
+    }
+    if (input.duplicates.length > 0) {
+        lines.push(`Rename duplicate tool names: ${input.duplicates.join(', ')}.`);
+    }
+    if (input.missingDescriptions > 0) {
+        lines.push('Add a description to every tool. Clients use it to choose a call.');
+    }
+    if (input.missingSchemas > 0) {
+        lines.push('Add inputSchema to every tool. An absent schema was not scored as valid.');
+    }
+    if (input.tokenLevel === 'over' || input.tokenLevel === 'warn') {
+        lines.push('The approximate token estimate is at or above a configured threshold.');
+    }
+    if (input.repeated > 0) {
+        lines.push('Repeated descriptions hide which tool the agent should call.');
+    }
+    if (input.toolCount === 0) {
+        lines.push('No tools were supplied, so the quality score was withheld.');
+    }
+    else if (input.findingsRan && (input.counts?.error ?? 0) === 0 && lines.length === 0) {
+        lines.push('No schema errors in this run. Recovery, preflight, and live inspection were not measured.');
+    }
+    return lines;
+}
+export function buildAuditReport(input) {
+    if (input.source.trim() === '')
+        throw new AuditInputError('source must be a non-empty string.');
+    const tools = requireTools(input.tools);
+    const inventory = tools.map((tool) => ({
+        name: tool.name,
+        hasDescription: typeof tool.description === 'string' && tool.description.trim() !== '',
+        hasInputSchema: isRecord(tool.inputSchema),
+        hasOutputSchema: isRecord(tool.outputSchema),
+    }));
+    const duplicates = duplicateNames(tools);
+    const findingsRan = input.diagnostics !== undefined;
+    const findings = findingsRan ? findingsFrom(input.diagnostics ?? []) : undefined;
+    const counts = findings
+        ? {
+            error: findings.filter((finding) => finding.severity === 'error').length,
+            warning: findings.filter((finding) => finding.severity === 'warning').length,
+            info: findings.filter((finding) => finding.severity === 'info').length,
+        }
+        : undefined;
+    let tokenSection;
+    try {
+        tokenSection = {
+            status: 'ran',
+            data: buildTokenBudget(tools, input.thresholds ?? DEFAULT_TOKEN_THRESHOLDS),
+        };
+    }
+    catch (err) {
+        tokenSection = {
+            status: 'failed',
+            reason: err instanceof Error ? err.message : 'Token estimate failed.',
+        };
+    }
+    let quality;
+    if (!findingsRan) {
+        quality = notRun('Schema lint did not run, so the quality score was withheld.');
+    }
+    else if (tools.length === 0) {
+        quality = notRun('No tools were supplied, so the quality score was withheld.');
+    }
+    else {
+        const scored = computeQualityReport(tools, input.diagnostics ?? []);
+        quality = {
+            status: 'ran',
+            data: {
+                algorithm: QUALITY_ALGORITHM,
+                overall: scored.overall,
+                grade: scored.grade,
+                weights: scored.weights,
+                coverage: scored.coverage,
+                confidence: scored.confidence,
+                note: 'quality-v2 adds points only for a description, an input schema, an output schema, and a clean lint. Missing fields add nothing. This is not a security guarantee.',
+            },
+        };
+    }
+    const tokenLevel = tokenSection.status === 'ran' ? tokenSection.data.level : undefined;
+    const lines = recommendations({
+        findingsRan,
+        counts,
+        duplicates,
+        missingDescriptions: inventory.filter((tool) => !tool.hasDescription).length,
+        missingSchemas: inventory.filter((tool) => !tool.hasInputSchema).length,
+        toolCount: tools.length,
+        tokenLevel,
+        repeated: tokenSection.status === 'ran' ? tokenSection.data.repeatedDescriptions.length : 0,
+    });
+    const ran = ['tools'];
+    if (tokenSection.status === 'ran')
+        ran.push('tokenBudget');
+    if (findingsRan)
+        ran.push('findings', 'severity');
+    if (quality.status === 'ran')
+        ran.push('quality');
+    const notRunNames = ['compatibility', 'recovery', 'preflight'];
+    if (!findingsRan)
+        notRunNames.push('findings', 'severity');
+    if (quality.status !== 'ran')
+        notRunNames.push('quality');
+    if (tokenSection.status !== 'ran')
+        notRunNames.push('tokenBudget');
+    const confidence = tools.length === 0 || !findingsRan
+        ? 'low'
+        : quality.status === 'ran' && tokenSection.status === 'ran'
+            ? 'medium'
+            : 'low';
+    return {
+        schemaVersion: AUDIT_REPORT_SCHEMA_VERSION,
+        generatedAt: input.generatedAt ?? new Date().toISOString(),
+        tool: { name: 'mcp-lint', version: input.version ?? VERSION },
+        scope: {
+            source: input.source,
+            mode: 'offline-tools',
+            liveServer: false,
+            toolsInvoked: false,
+        },
+        tools: inventory,
+        duplicateToolNames: duplicates,
+        findings: findings ? { status: 'ran', data: findings } : notRun('Schema lint did not run.'),
+        severity: counts ? { status: 'ran', data: counts } : notRun('Schema lint did not run.'),
+        compatibility: notRun('Client compatibility was not re-checked for this report.'),
+        tokenBudget: tokenSection,
+        quality,
+        recovery: notRun('Recovery was not scored.'),
+        preflight: notRun('Preflight was not evaluated.'),
+        recommendations: lines,
+        coverage: {
+            ran,
+            notRun: notRunNames,
+            confidence,
+        },
+    };
+}
+export function parseAuditReport(value) {
+    return AuditReportSchema.parse(value);
+}
+//# sourceMappingURL=report.js.map

package/dist/audit/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/audit/report.ts"],"names":[],"mappings":"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"}

package/dist/audit/tokens.d.ts

@@ -0,0 +1,53 @@
+export declare const TOKEN_ESTIMATE_METHOD: "chars-div-4";
+export declare class TokenEstimateError extends Error {
+    constructor(message: string);
+}
+export interface TokenEstimate {
+    method: typeof TOKEN_ESTIMATE_METHOD;
+    approximate: true;
+    chars: number;
+    tokens: number;
+}
+export interface TokenThresholds {
+    warn: number;
+    over: number;
+    schemaWarn: number;
+}
+export interface ToolTokenRank {
+    name: string;
+    chars: number;
+    tokens: number;
+    schemaTokens: number;
+    oversizedSchema: boolean;
+}
+export interface RepeatedDescription {
+    description: string;
+    tools: string[];
+}
+export interface TokenBudget {
+    method: typeof TOKEN_ESTIMATE_METHOD;
+    approximate: true;
+    chars: number;
+    tokens: number;
+    toolCount: number;
+    thresholds: TokenThresholds;
+    level: 'ok' | 'warn' | 'over';
+    tools: ToolTokenRank[];
+    repeatedDescriptions: RepeatedDescription[];
+    note: string;
+}
+export interface TokenBudgetDiff {
+    method: typeof TOKEN_ESTIMATE_METHOD;
+    approximate: true;
+    beforeTokens: number;
+    afterTokens: number;
+    deltaTokens: number;
+    addedTools: string[];
+    removedTools: string[];
+    grew: string[];
+}
+export declare const DEFAULT_TOKEN_THRESHOLDS: TokenThresholds;
+export declare function estimateTokens(value: unknown): TokenEstimate;
+export declare function assertThresholds(thresholds: TokenThresholds): void;
+export declare function buildTokenBudget(tools: ReadonlyArray<Record<string, unknown>>, thresholds?: TokenThresholds): TokenBudget;
+export declare function compareTokenBudgets(before: TokenBudget, after: TokenBudget): TokenBudgetDiff;

package/dist/audit/tokens.js

@@ -0,0 +1,131 @@
+export const TOKEN_ESTIMATE_METHOD = 'chars-div-4';
+export class TokenEstimateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TokenEstimateError';
+    }
+}
+export const DEFAULT_TOKEN_THRESHOLDS = {
+    warn: 4000,
+    over: 8000,
+    schemaWarn: 800,
+};
+const PROJECTION_KEYS = ['name', 'description', 'inputSchema', 'outputSchema'];
+export function estimateTokens(value) {
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch (err) {
+        throw new TokenEstimateError(err instanceof Error ? err.message : 'Value could not be serialized.');
+    }
+    if (typeof json !== 'string') {
+        throw new TokenEstimateError('Value could not be serialized.');
+    }
+    return {
+        method: TOKEN_ESTIMATE_METHOD,
+        approximate: true,
+        chars: json.length,
+        tokens: Math.ceil(json.length / 4),
+    };
+}
+export function assertThresholds(thresholds) {
+    for (const [key, value] of Object.entries(thresholds)) {
+        if (!Number.isInteger(value) || value < 1) {
+            throw new TokenEstimateError(`Token threshold "${key}" must be a positive integer.`);
+        }
+    }
+    if (thresholds.warn > thresholds.over) {
+        throw new TokenEstimateError('Token warn threshold cannot be above the over threshold.');
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function projectTool(tool) {
+    const projected = {};
+    for (const key of PROJECTION_KEYS) {
+        if (tool[key] !== undefined)
+            projected[key] = tool[key];
+    }
+    return projected;
+}
+function normalizeDescription(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim().replace(/\s+/g, ' ').toLowerCase();
+    return normalized.length >= 12 ? normalized : undefined;
+}
+export function buildTokenBudget(tools, thresholds = DEFAULT_TOKEN_THRESHOLDS) {
+    assertThresholds(thresholds);
+    const projected = tools.map(projectTool);
+    const total = estimateTokens(projected);
+    const ranked = tools.map((tool) => {
+        const name = typeof tool.name === 'string' ? tool.name : '';
+        const whole = estimateTokens(projectTool(tool));
+        const schema = estimateTokens(isRecord(tool.inputSchema) ? tool.inputSchema : {});
+        return {
+            name,
+            chars: whole.chars,
+            tokens: whole.tokens,
+            schemaTokens: schema.tokens,
+            oversizedSchema: schema.tokens >= thresholds.schemaWarn,
+        };
+    });
+    ranked.sort((a, b) => b.tokens - a.tokens || a.name.localeCompare(b.name));
+    const groups = new Map();
+    for (const tool of tools) {
+        if (typeof tool.description !== 'string' || typeof tool.name !== 'string')
+            continue;
+        const normalized = normalizeDescription(tool.description);
+        if (!normalized)
+            continue;
+        const group = groups.get(normalized) ?? {
+            description: tool.description.trim().replace(/\s+/g, ' '),
+            tools: [],
+        };
+        group.tools.push(tool.name);
+        groups.set(normalized, group);
+    }
+    const repeatedDescriptions = [...groups.values()]
+        .filter((group) => group.tools.length > 1)
+        .map((group) => ({ description: group.description, tools: [...group.tools].sort((a, b) => a.localeCompare(b)) }))
+        .sort((a, b) => a.description.localeCompare(b.description));
+    const level = total.tokens >= thresholds.over ? 'over' : total.tokens >= thresholds.warn ? 'warn' : 'ok';
+    const note = tools.length === 0
+        ? 'Empty tool list. Zero tokens is not a healthy server. Estimate is ceil(JSON chars / 4), not a tokenizer.'
+        : 'Estimate is ceil(JSON chars / 4) of name, description, inputSchema, and outputSchema. It is not a tokenizer count. Per-tool tokens do not sum to the total.';
+    return {
+        method: TOKEN_ESTIMATE_METHOD,
+        approximate: true,
+        chars: total.chars,
+        tokens: total.tokens,
+        toolCount: tools.length,
+        thresholds: { ...thresholds },
+        level,
+        tools: ranked,
+        repeatedDescriptions,
+        note,
+    };
+}
+export function compareTokenBudgets(before, after) {
+    const beforeNames = new Set(before.tools.map((tool) => tool.name));
+    const afterNames = new Map(after.tools.map((tool) => [tool.name, tool.tokens]));
+    const beforeTokens = new Map(before.tools.map((tool) => [tool.name, tool.tokens]));
+    const addedTools = [...afterNames.keys()].filter((name) => !beforeNames.has(name)).sort((a, b) => a.localeCompare(b));
+    const removedTools = [...beforeNames].filter((name) => !afterNames.has(name)).sort((a, b) => a.localeCompare(b));
+    const grew = [...afterNames.keys()]
+        .filter((name) => beforeTokens.has(name) && (afterNames.get(name) ?? 0) > (beforeTokens.get(name) ?? 0))
+        .sort((a, b) => a.localeCompare(b));
+    return {
+        method: TOKEN_ESTIMATE_METHOD,
+        approximate: true,
+        beforeTokens: before.tokens,
+        afterTokens: after.tokens,
+        deltaTokens: after.tokens - before.tokens,
+        addedTools,
+        removedTools,
+        grew,
+    };
+}
+//# sourceMappingURL=tokens.js.map

package/dist/audit/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/audit/tokens.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAsB,CAAC;AAE5D,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAoDD,MAAM,CAAC,MAAM,wBAAwB,GAAoB;IACvD,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,IAAI;IACV,UAAU,EAAE,GAAG;CAChB,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,CAAU,CAAC;AAExF,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,kBAAkB,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,gCAAgC,CAAC,CAAC;IACtG,CAAC;IACD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,IAAI,kBAAkB,CAAC,gCAAgC,CAAC,CAAC;IACjE,CAAC;IACD,OAAO;QACL,MAAM,EAAE,qBAAqB;QAC7B,WAAW,EAAE,IAAI;QACjB,KAAK,EAAE,IAAI,CAAC,MAAM;QAClB,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;KACnC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,UAA2B;IAC1D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAA2C,EAAE,CAAC;QAChG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,kBAAkB,CAAC,oBAAoB,GAAG,+BAA+B,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;QACtC,MAAM,IAAI,kBAAkB,CAAC,0DAA0D,CAAC,CAAC;IAC3F,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,WAAW,CAAC,IAA6B;IAChD,MAAM,SAAS,GAA4B,EAAE,CAAC;IAC9C,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IACnE,OAAO,UAAU,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,KAA6C,EAC7C,aAA8B,wBAAwB;IAEtD,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC7B,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACxC,MAAM,MAAM,GAAoB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACjD,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,MAAM,KAAK,GAAG,cAAc,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClF,OAAO;YACL,IAAI;YACJ,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,YAAY,EAAE,MAAM,CAAC,MAAM;YAC3B,eAAe,EAAE,MAAM,CAAC,MAAM,IAAI,UAAU,CAAC,UAAU;SACxD,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAE3E,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoD,CAAC;IAC3E,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,SAAS;QACpF,MAAM,UAAU,GAAG,oBAAoB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC1D,IAAI,CAAC,UAAU;YAAE,SAAS;QAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI;YACtC,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;YACzD,KAAK,EAAE,EAAE;SACV,CAAC;QACF,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;IACD,MAAM,oBAAoB,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;SAC9C,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;SACzC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;SAChH,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;IAE9D,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACzG,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,KAAK,CAAC;QAC7B,CAAC,CAAC,0GAA0G;QAC5G,CAAC,CAAC,6JAA6J,CAAC;IAElK,OAAO;QACL,MAAM,EAAE,qBAAqB;QAC7B,WAAW,EAAE,IAAI;QACjB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,SAAS,EAAE,KAAK,CAAC,MAAM;QACvB,UAAU,EAAE,EAAE,GAAG,UAAU,EAAE;QAC7B,KAAK;QACL,KAAK,EAAE,MAAM;QACb,oBAAoB;QACpB,IAAI;KACL,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAmB,EAAE,KAAkB;IACzE,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACnE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAChF,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACnF,MAAM,UAAU,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACtH,MAAM,YAAY,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACjH,MAAM,IAAI,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;SAChC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;SACvG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,OAAO;QACL,MAAM,EAAE,qBAAqB;QAC7B,WAAW,EAAE,IAAI;QACjB,YAAY,EAAE,MAAM,CAAC,MAAM;QAC3B,WAAW,EAAE,KAAK,CAAC,MAAM;QACzB,WAAW,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM;QACzC,UAAU;QACV,YAAY;QACZ,IAAI;KACL,CAAC;AACJ,CAAC"}

package/dist/cli/commands/check.js

@@ -1,5 +1,9 @@
 import { watch } from 'node:fs';
+import { stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { discoverToolFiles, missingToolsMessage } from '../../discover/files.js';
+import { formatDiscovered } from '../../discover/format.js';
 import { loadFile } from '../../loaders/file-loader.js';
 import { loadStdio } from '../../loaders/stdio-loader.js';
 import { loadRemote } from '../../loaders/remote-loader.js';
@@ -23,7 +27,7 @@ function filterBySeverity(diagnostics, min) {
 }
 export function registerCheckCommand(program) {
     program
-        .command('check [input]')
+        .command('check [input]', { isDefault: true })
         .description('Check MCP tool schemas for compatibility issues')
         .option('--format <format>', 'Output format: terminal|json|markdown', 'terminal')
         .option('--no-color', 'Disable terminal colors')
@@ -87,6 +91,7 @@ export function registerCheckCommand(program) {
                     const reports = await lintInstalledServers(collected.servers, {
                         remote: Boolean(options.remote),
                         timeoutMs,
+                        rules: config.rules,
                         lint: (found) => filterBySeverity(engine.lint(found), floor),
                     });
                     for (const problem of collected.errors) {
@@ -118,6 +123,26 @@ export function registerCheckCommand(program) {
                         throw new Error('--server http requires --url <url>');
                     tools = await loadRemote(options.url, 'http', optionalTimeout(options.timeout));
                 }
+                else if (await shouldDiscover(input)) {
+                    const dir = input ? resolve(input) : process.cwd();
+                    const files = await discoverToolFiles(dir);
+                    if (files.length === 0)
+                        throw new Error(missingToolsMessage(dir));
+                    const pluginRules = await loadPluginRules(fileConfig);
+                    const engine = new LintEngine([...allRules, ...pluginRules], config);
+                    const groups = [];
+                    const discoveredTools = [];
+                    const discoveredDiagnostics = [];
+                    for (const file of files) {
+                        const found = await loadFile(file);
+                        const foundDiagnostics = filterBySeverity(engine.lint(found), floor);
+                        discoveredTools.push(...found);
+                        discoveredDiagnostics.push(...foundDiagnostics);
+                        groups.push({ file, diagnostics: foundDiagnostics });
+                    }
+                    await emit(formatDiscovered(groups, options.format, !options.color), options, discoveredTools, discoveredDiagnostics);
+                    return discoveredDiagnostics.some((item) => item.severity === 'error');
+                }
                 else {
                     if (!input)
                         throw new Error('Specify an input file, --server stdio|sse|http, --installed, or --from <mcp.json>');
@@ -166,6 +191,18 @@ export function registerCheckCommand(program) {
         }
     });
 }
+async function shouldDiscover(input) {
+    if (!input)
+        return true;
+    try {
+        return (await stat(input)).isDirectory();
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+}
 function collectPath(value, previous) {
     previous.push(value);
     return previous;
@@ -222,6 +259,12 @@ async function emit(output, options, tools, diagnostics) {
     for (const tool of report.tools) {
         process.stdout.write(`  ${tool.toolName.padEnd(30)} ${String(tool.score).padStart(3)}/100  ${gradeColor(tool.grade)}  (${tool.errors} errors, ${tool.warnings} warnings)\n`);
     }
-    process.stdout.write(`\n  Overall: ${chalk.bold(String(report.overall))}/100  ${gradeColor(report.grade)}\n\n`);
+    const coverage = `${report.coverage.withDescription}/${report.coverage.toolCount} descriptions, ${report.coverage.withInputSchema}/${report.coverage.toolCount} input schemas, ${report.coverage.withOutputSchema}/${report.coverage.toolCount} output schemas`;
+    process.stdout.write(`\n  Overall: ${chalk.bold(String(report.overall))}/100  ${gradeColor(report.grade)}  confidence ${report.confidence}\n`);
+    process.stdout.write(`  ${coverage}\n`);
+    if (!report.measured) {
+        process.stdout.write('  No tools were scored. An empty list is not a pass.\n');
+    }
+    process.stdout.write('\n');
 }
 //# sourceMappingURL=check.js.map