mcp-lint 0.8.0 → 0.9.0

package/README.md

@@ -13,6 +13,8 @@ Proof page, with a live bench: [mcp-lint-alpha.vercel.app](https://mcp-lint-alph
 
 MCP servers expose tool schemas consumed by **Claude**, **Cursor**, **Gemini**, **VS Code Copilot**, **Windsurf**, **Cline**, **OpenAI Agents SDK**, and **Continue.dev**. Each client has different JSON Schema support and quirks — a schema that works in Claude may silently break in Cursor or OpenAI. `mcp-lint` catches these issues before your users do.
 
+This repository is **0.9.0**. npm `latest` is still 0.8.0 until that release is published, so `npx mcp-lint` does not include `report` yet. Design notes: [PRODUCT.md](PRODUCT.md), [ROADMAP.md](ROADMAP.md), [ARCHITECTURE.md](ARCHITECTURE.md), [SECURITY.md](SECURITY.md), [RELEASE.md](RELEASE.md). Those files describe the current code and the 1.0 plan. They are not extra commands.
+
 ```
 $ npx mcp-lint check tools.json
 
@@ -184,6 +186,19 @@ mcp-lint check --server sse --url http://localhost:3000/sse
 | `1` | One or more errors found |
 | `2` | Invalid input or configuration error |
 
+### `mcp-lint report <file>`
+
+Writes the versioned audit report for one tools file. `check --format json` still prints the diagnostic array. `report --format json` prints `MCPAuditReport`.
+
+```bash
+mcp-lint report tools.json
+mcp-lint report tools.json --format sarif --output results.sarif
+mcp-lint report tools.json --format html --output report.html
+mcp-lint report tools.json --format markdown
+```
+
+Formats are `terminal`, `json`, `markdown`, `sarif`, and `html`. The HTML file has inline CSS and no script. Token totals are a local `chars / 4` estimate. Recovery, preflight, and live inspection stay marked as not run. Exit `1` when the report contains an error, or when the file cannot be read.
+
 ---
 
 ### `mcp-lint diff <before> <after>`
@@ -216,10 +231,10 @@ Looked-up files:
 |--------|------|
 | Cursor | `~/.cursor/mcp.json` and `./.cursor/mcp.json` |
 | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
-| Claude Code | `~/.claude.json`, `~/.claude/settings.json`, and `./.mcp.json` |
+| Claude Code | `~/.claude.json`, `~/.claude/settings.json`, and `./.mcp.json`. `~/.claude.json` also contributes each `projects.<path>.mcpServers` entry. |
 | VS Code | `~/Library/Application Support/Code/User/mcp.json` and `./.vscode/mcp.json` |
 
-`--strict` also exits 1 when a configured server fails to start. Without it, a start failure is printed and the exit code follows the schema errors.
+`--strict` also exits 1 when a configured server fails to start. Without it, a start failure is printed and the exit code follows the schema errors. If two started servers expose the same tool name, both reports include `tool-name/server-collision`.
 
 ---
 
@@ -237,7 +252,7 @@ mcp-lint diff tools.json tools.next.json
 
 ### `mcp-lint fix [input]`
 
-Auto-fixes issues that are safe to fix automatically (no semantic changes).
+Writes fixes marked `safe`. `review` and `manual` fixes are printed by `--dry-run` and left in the file. mcp-lint does not invent titles, descriptions, or hints.
 
 ```bash
 mcp-lint fix tools.json                            # fixed output to stdout
@@ -280,6 +295,8 @@ mcp-lint init --force  # overwrite existing
 | Rule | Severity | Fixable | Description |
 |------|----------|---------|-------------|
 | `tool-name/client-safe` | 🔴 error, 🟡 warning | ❌ | Names must match `^[A-Za-z0-9_-]{1,64}$`. A leading digit is a warning because Gemini rejects it. |
+| `tool-name/duplicate` | 🔴 error | ❌ | The same name appears twice in one tools list. |
+| `tool-name/server-collision` | 🔴 error | ❌ | The same name is exposed by two servers during `check --installed` or `--from`. |
 
 OpenAI and Azure use that pattern. A space, slash, or dot makes the tool disappear. See `examples/names/unsafe.json`.
 
@@ -393,7 +410,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: robert19001-cmyk/mcp-lint@v0.8.0
+      - uses: robert19001-cmyk/mcp-lint@v0.9.0
+        # Tag v0.9.0. The action installs npm latest.
         with:
           input: tools.json
           severity: warning
@@ -411,6 +429,9 @@ jobs:
 | `clients` | all | Comma-separated client filter |
 | `fail_on` | `error` | Fail CI when issues at this severity found |
 | `score` | `false` | Show quality score |
+| `sarif` | `false` | Upload SARIF when this `mcp-lint` release includes `report`. The workflow needs `security-events: write`. |
+
+The action in this repository writes a `::error`, `::warning`, or `::notice` annotation from `check --format json`. With an empty `input` it also looks one directory down, skipping `node_modules` and dot directories. `sarif: true` uploads SARIF when the installed CLI has `report`. The action installs npm `latest`. That is still 0.8.0, so the input warns and skips the upload until 0.9.0 is published.
 
 ### Manual workflow
 
@@ -726,7 +747,7 @@ The repository includes `glama.json` and a production Dockerfile so MCP director
 
 ## Site
 
-The proof page is in `site/`. It runs the same recovery scorer as the CLI.
+The proof page is in `site/`. Version 0.9.0. It runs the same recovery scorer as the CLI and explains every command in plain language. The pictures are generated stills, not screenshots of the tool.
 
 ```bash
 npm run site

package/dist/audit/format.d.ts

@@ -0,0 +1,5 @@
+import type { MCPAuditReport } from './report.js';
+export declare const AUDIT_FORMATS: readonly ["terminal", "json", "markdown", "sarif", "html"];
+export type AuditFormat = (typeof AUDIT_FORMATS)[number];
+export declare function formatAuditReport(report: MCPAuditReport, format: string, noColor?: boolean): string;
+export declare function escapeHtml(value: string): string;

package/dist/audit/format.js

@@ -0,0 +1,246 @@
+import chalk from 'chalk';
+export const AUDIT_FORMATS = ['terminal', 'json', 'markdown', 'sarif', 'html'];
+const SITE = 'https://mcp-lint-alpha.vercel.app/';
+export function formatAuditReport(report, format, noColor = false) {
+    switch (format) {
+        case 'json':
+            return JSON.stringify(report, null, 2) + '\n';
+        case 'markdown':
+            return formatMarkdownReport(report);
+        case 'terminal':
+            return formatTerminalReport(report, noColor);
+        case 'sarif':
+            return formatSarif(report);
+        case 'html':
+            return formatHtml(report);
+        default:
+            throw new Error(`Unknown format "${format}". Use ${AUDIT_FORMATS.join(', ')}.`);
+    }
+}
+export function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function findingRows(findings) {
+    return findings.map((finding) => {
+        const cells = [finding.severity, finding.toolName, finding.ruleId, finding.path, finding.message]
+            .map((cell) => cell.replace(/\|/g, '\\|').replace(/\n/g, ' '));
+        return `| ${cells.join(' | ')} |`;
+    }).join('\n');
+}
+function formatMarkdownReport(report) {
+    const counts = report.severity.status === 'ran'
+        ? `${report.severity.data.error} errors, ${report.severity.data.warning} warnings, ${report.severity.data.info} info`
+        : report.severity.reason;
+    const findings = report.findings.status === 'ran'
+        ? (report.findings.data.length === 0
+            ? 'No schema findings in this run.\n'
+            : [
+                '| Severity | Tool | Rule | Path | Message |',
+                '| --- | --- | --- | --- | --- |',
+                findingRows(report.findings.data),
+                '',
+            ].join('\n'))
+        : `${report.findings.reason}\n`;
+    const tokens = report.tokenBudget.status === 'ran'
+        ? [
+            `Approximate \`chars / 4\` estimate: **${report.tokenBudget.data.tokens}** tokens (${report.tokenBudget.data.chars} chars), level \`${report.tokenBudget.data.level}\`.`,
+            report.tokenBudget.data.note,
+            '',
+        ].join('\n')
+        : `${report.tokenBudget.status === 'partial' ? report.tokenBudget.reason : report.tokenBudget.reason}\n`;
+    const notRun = report.coverage.notRun.map((name) => `- ${name}`).join('\n');
+    const recommendations = report.recommendations.map((line) => `- ${line}`).join('\n');
+    return [
+        `# mcp-lint report`,
+        '',
+        `Source: \`${report.scope.source}\``,
+        `Generated: ${report.generatedAt}`,
+        `Tool: mcp-lint ${report.tool.version}`,
+        `Schema: ${report.schemaVersion}`,
+        '',
+        '## Summary',
+        '',
+        counts,
+        `Confidence: ${report.coverage.confidence}. A section marked not run is not a pass.`,
+        '',
+        '## Findings',
+        '',
+        findings.trimEnd(),
+        '',
+        '## Token estimate',
+        '',
+        tokens.trimEnd(),
+        '',
+        '## Not measured',
+        '',
+        notRun || '- none',
+        '',
+        '## Recommendations',
+        '',
+        recommendations || '- none',
+        '',
+    ].join('\n');
+}
+function formatTerminalReport(report, noColor) {
+    const tone = (severity, text) => {
+        if (noColor)
+            return text;
+        if (severity === 'error')
+            return chalk.red(text);
+        if (severity === 'warning')
+            return chalk.yellow(text);
+        return chalk.blue(text);
+    };
+    const lines = [
+        `${noColor ? '' : chalk.bold('')}mcp-lint report  ${report.scope.source}`.trim(),
+        report.severity.status === 'ran'
+            ? `${report.severity.data.error} errors, ${report.severity.data.warning} warnings, ${report.severity.data.info} info`
+            : report.severity.reason,
+    ];
+    if (report.findings.status === 'ran') {
+        for (const finding of report.findings.data) {
+            lines.push(tone(finding.severity, `${finding.severity}  ${finding.toolName}  ${finding.message}`));
+            lines.push(`  ${finding.path}  [${finding.ruleId}]`);
+        }
+        if (report.findings.data.length === 0)
+            lines.push('No schema findings in this run.');
+    }
+    else {
+        lines.push(report.findings.reason);
+    }
+    if (report.tokenBudget.status === 'ran') {
+        lines.push(`Token estimate (chars/4, approximate): ${report.tokenBudget.data.tokens}  level ${report.tokenBudget.data.level}`);
+    }
+    for (const line of report.recommendations)
+        lines.push(line);
+    lines.push(`Not measured: ${report.coverage.notRun.join(', ')}`);
+    return lines.join('\n') + '\n';
+}
+function formatSarif(report) {
+    const findings = report.findings.status === 'ran' ? report.findings.data : [];
+    const ruleIds = [...new Set(findings.map((finding) => finding.ruleId))].sort((a, b) => a.localeCompare(b));
+    const ruleIndex = new Map(ruleIds.map((id, index) => [id, index]));
+    const notifications = report.coverage.notRun.map((name) => ({
+        message: { text: `${name} did not run. An empty result is not a pass for that section.` },
+        level: 'note',
+    }));
+    const sarif = {
+        $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'mcp-lint',
+                        version: report.tool.version,
+                        informationUri: SITE,
+                        rules: ruleIds.map((id) => ({
+                            id,
+                            shortDescription: { text: id },
+                        })),
+                    },
+                },
+                invocations: [
+                    {
+                        executionSuccessful: true,
+                        toolExecutionNotifications: notifications,
+                    },
+                ],
+                results: findings.map((finding) => ({
+                    ruleId: finding.ruleId,
+                    ruleIndex: ruleIndex.get(finding.ruleId),
+                    level: finding.severity === 'error' ? 'error' : finding.severity === 'warning' ? 'warning' : 'note',
+                    message: { text: finding.message },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: { uri: encodeURI(report.scope.source) },
+                            },
+                            logicalLocations: [
+                                {
+                                    name: finding.toolName,
+                                    fullyQualifiedName: `${finding.toolName}.${finding.path}`,
+                                },
+                            ],
+                        },
+                    ],
+                    partialFingerprints: {
+                        'mcpLint/v1': `${finding.toolName}/${finding.ruleId}/${finding.path}`,
+                    },
+                    properties: {
+                        clients: finding.clients,
+                        fixable: finding.fixable,
+                    },
+                })),
+            },
+        ],
+    };
+    return JSON.stringify(sarif, null, 2) + '\n';
+}
+function formatHtml(report) {
+    const findings = report.findings.status === 'ran'
+        ? (report.findings.data.length === 0
+            ? '<p>No schema findings in this run.</p>'
+            : `<table>
+<thead><tr><th>Severity</th><th>Tool</th><th>Rule</th><th>Path</th><th>Message</th></tr></thead>
+<tbody>
+${report.findings.data.map((finding) => `<tr>
+<td>${escapeHtml(finding.severity)}</td>
+<td>${escapeHtml(finding.toolName)}</td>
+<td><code>${escapeHtml(finding.ruleId)}</code></td>
+<td><code>${escapeHtml(finding.path)}</code></td>
+<td>${escapeHtml(finding.message)}</td>
+</tr>`).join('\n')}
+</tbody>
+</table>`)
+        : `<p>${escapeHtml(report.findings.reason)}</p>`;
+    const tokens = report.tokenBudget.status === 'ran'
+        ? `<p>Approximate chars/4 estimate: <strong>${report.tokenBudget.data.tokens}</strong> tokens, level ${escapeHtml(report.tokenBudget.data.level)}.</p><p>${escapeHtml(report.tokenBudget.data.note)}</p>`
+        : `<p>${escapeHtml(report.tokenBudget.reason)}</p>`;
+    const counts = report.severity.status === 'ran'
+        ? `${report.severity.data.error} errors, ${report.severity.data.warning} warnings, ${report.severity.data.info} info`
+        : report.severity.reason;
+    const notRun = report.coverage.notRun.map((name) => `<li>${escapeHtml(name)}</li>`).join('');
+    const recommendations = report.recommendations.map((line) => `<li>${escapeHtml(line)}</li>`).join('');
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>mcp-lint report: ${escapeHtml(report.scope.source)}</title>
+<style>
+  body { margin: 0; background: #f3efe4; color: #1c1916; font: 16px/1.5 ui-sans-serif, system-ui, sans-serif; }
+  main { max-width: 880px; margin: 0 auto; padding: 32px 20px 64px; }
+  h1 { font-size: 32px; line-height: 1.15; margin-bottom: 8px; }
+  h2 { font-size: 18px; margin-top: 32px; }
+  p, li { max-width: 68ch; }
+  table { width: 100%; border-collapse: collapse; }
+  th, td { text-align: left; vertical-align: top; border-bottom: 1px solid #d9d2c5; padding: 8px; }
+  code { font-family: ui-monospace, monospace; }
+  .meta { color: #5c564e; }
+</style>
+</head>
+<body>
+<main>
+<p class="meta">mcp-lint ${escapeHtml(report.tool.version)} · schema ${report.schemaVersion} · ${escapeHtml(report.generatedAt)}</p>
+<h1>${escapeHtml(report.scope.source)}</h1>
+<p>${escapeHtml(counts)}. Confidence ${escapeHtml(report.coverage.confidence)}. A section that did not run is not a pass.</p>
+<h2>Findings</h2>
+${findings}
+<h2>Token estimate</h2>
+${tokens}
+<h2>Not measured</h2>
+<ul>${notRun}</ul>
+<h2>Recommendations</h2>
+<ul>${recommendations}</ul>
+</main>
+</body>
+</html>
+`;
+}
+//# sourceMappingURL=format.js.map

package/dist/audit/format.js.map

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

package/dist/audit/index.d.ts

@@ -0,0 +1,6 @@
+export { AUDIT_REPORT_SCHEMA_VERSION, QUALITY_ALGORITHM, AuditInputError, AuditReportSchema, buildAuditReport, parseAuditReport, } from './report.js';
+export type { AuditFinding, AuditTool, BuildAuditReportInput, MCPAuditReport, QualitySectionData, Section, SectionStatus, SeverityCounts, } from './report.js';
+export { AUDIT_FORMATS, escapeHtml, formatAuditReport } from './format.js';
+export type { AuditFormat } from './format.js';
+export { DEFAULT_TOKEN_THRESHOLDS, TOKEN_ESTIMATE_METHOD, TokenEstimateError, assertThresholds, buildTokenBudget, compareTokenBudgets, estimateTokens, } from './tokens.js';
+export type { RepeatedDescription, TokenBudget, TokenBudgetDiff, TokenEstimate, TokenThresholds, ToolTokenRank, } from './tokens.js';

package/dist/audit/index.js

@@ -0,0 +1,4 @@
+export { AUDIT_REPORT_SCHEMA_VERSION, QUALITY_ALGORITHM, AuditInputError, AuditReportSchema, buildAuditReport, parseAuditReport, } from './report.js';
+export { AUDIT_FORMATS, escapeHtml, formatAuditReport } from './format.js';
+export { DEFAULT_TOKEN_THRESHOLDS, TOKEN_ESTIMATE_METHOD, TokenEstimateError, assertThresholds, buildTokenBudget, compareTokenBudgets, estimateTokens, } from './tokens.js';
+//# sourceMappingURL=index.js.map

package/dist/audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAWrB,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE3E,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,GACf,MAAM,aAAa,CAAC"}

package/dist/audit/report.d.ts

@@ -0,0 +1,268 @@
+import { z } from 'zod';
+import type { Diagnostic } from '../core/diagnostic.js';
+import { type TokenBudget, type TokenThresholds } from './tokens.js';
+export declare const AUDIT_REPORT_SCHEMA_VERSION: 1;
+export declare const QUALITY_ALGORITHM: "quality-v2";
+export declare class AuditInputError extends Error {
+    constructor(message: string);
+}
+export type SectionStatus = 'ran' | 'not_run' | 'partial' | 'failed';
+export interface RanSection<T> {
+    status: 'ran';
+    data: T;
+}
+export interface NotRunSection {
+    status: 'not_run' | 'failed';
+    reason: string;
+}
+export interface PartialSection<T> {
+    status: 'partial';
+    reason: string;
+    data: T;
+}
+export type Section<T> = RanSection<T> | NotRunSection | PartialSection<T>;
+export interface AuditFinding {
+    ruleId: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    toolName: string;
+    path: string;
+    clients: string[];
+    fixable: boolean;
+}
+export interface AuditTool {
+    name: string;
+    hasDescription: boolean;
+    hasInputSchema: boolean;
+    hasOutputSchema: boolean;
+}
+export interface QualitySectionData {
+    algorithm: typeof QUALITY_ALGORITHM;
+    overall: number;
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+    weights: {
+        description: number;
+        inputSchema: number;
+        outputSchema: number;
+        lintClean: number;
+        error: number;
+        warning: number;
+    };
+    coverage: {
+        toolCount: number;
+        withDescription: number;
+        withInputSchema: number;
+        withOutputSchema: number;
+    };
+    confidence: 'low' | 'medium';
+    note: string;
+}
+export interface SeverityCounts {
+    error: number;
+    warning: number;
+    info: number;
+}
+export interface MCPAuditReport {
+    schemaVersion: typeof AUDIT_REPORT_SCHEMA_VERSION;
+    generatedAt: string;
+    tool: {
+        name: 'mcp-lint';
+        version: string;
+    };
+    scope: {
+        source: string;
+        mode: 'offline-tools';
+        liveServer: false;
+        toolsInvoked: false;
+    };
+    tools: AuditTool[];
+    duplicateToolNames: string[];
+    findings: Section<AuditFinding[]>;
+    severity: Section<SeverityCounts>;
+    compatibility: NotRunSection;
+    tokenBudget: Section<TokenBudget>;
+    quality: Section<QualitySectionData>;
+    recovery: NotRunSection;
+    preflight: NotRunSection;
+    recommendations: string[];
+    coverage: {
+        ran: string[];
+        notRun: string[];
+        confidence: 'low' | 'medium' | 'high';
+    };
+}
+export interface BuildAuditReportInput {
+    source: string;
+    tools: unknown;
+    diagnostics?: Diagnostic[];
+    version?: string;
+    generatedAt?: string;
+    thresholds?: TokenThresholds;
+}
+export declare const AuditReportSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    generatedAt: z.ZodString;
+    tool: z.ZodObject<{
+        name: z.ZodLiteral<"mcp-lint">;
+        version: z.ZodString;
+    }, z.core.$strict>;
+    scope: z.ZodObject<{
+        source: z.ZodString;
+        mode: z.ZodLiteral<"offline-tools">;
+        liveServer: z.ZodLiteral<false>;
+        toolsInvoked: z.ZodLiteral<false>;
+    }, z.core.$strict>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        hasDescription: z.ZodBoolean;
+        hasInputSchema: z.ZodBoolean;
+        hasOutputSchema: z.ZodBoolean;
+    }, z.core.$strict>>;
+    duplicateToolNames: z.ZodArray<z.ZodString>;
+    findings: z.ZodObject<{
+        status: z.ZodEnum<{
+            failed: "failed";
+            ran: "ran";
+            not_run: "not_run";
+            partial: "partial";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            ruleId: z.ZodString;
+            severity: z.ZodEnum<{
+                error: "error";
+                warning: "warning";
+                info: "info";
+            }>;
+            message: z.ZodString;
+            toolName: z.ZodString;
+            path: z.ZodString;
+            clients: z.ZodArray<z.ZodString>;
+            fixable: z.ZodBoolean;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+    severity: z.ZodObject<{
+        status: z.ZodEnum<{
+            failed: "failed";
+            ran: "ran";
+            not_run: "not_run";
+            partial: "partial";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodObject<{
+            error: z.ZodNumber;
+            warning: z.ZodNumber;
+            info: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    compatibility: z.ZodObject<{
+        status: z.ZodEnum<{
+            failed: "failed";
+            not_run: "not_run";
+        }>;
+        reason: z.ZodString;
+    }, z.core.$strict>;
+    tokenBudget: z.ZodObject<{
+        status: z.ZodEnum<{
+            failed: "failed";
+            ran: "ran";
+            not_run: "not_run";
+            partial: "partial";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodObject<{
+            method: z.ZodLiteral<"chars-div-4">;
+            approximate: z.ZodLiteral<true>;
+            chars: z.ZodNumber;
+            tokens: z.ZodNumber;
+            toolCount: z.ZodNumber;
+            thresholds: z.ZodObject<{
+                warn: z.ZodNumber;
+                over: z.ZodNumber;
+                schemaWarn: z.ZodNumber;
+            }, z.core.$strict>;
+            level: z.ZodEnum<{
+                ok: "ok";
+                warn: "warn";
+                over: "over";
+            }>;
+            tools: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                chars: z.ZodNumber;
+                tokens: z.ZodNumber;
+                schemaTokens: z.ZodNumber;
+                oversizedSchema: z.ZodBoolean;
+            }, z.core.$strict>>;
+            repeatedDescriptions: z.ZodArray<z.ZodObject<{
+                description: z.ZodString;
+                tools: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+            note: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    quality: z.ZodObject<{
+        status: z.ZodEnum<{
+            failed: "failed";
+            ran: "ran";
+            not_run: "not_run";
+            partial: "partial";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodObject<{
+            algorithm: z.ZodLiteral<"quality-v2">;
+            overall: z.ZodNumber;
+            grade: z.ZodEnum<{
+                A: "A";
+                B: "B";
+                C: "C";
+                D: "D";
+                F: "F";
+            }>;
+            weights: z.ZodObject<{
+                description: z.ZodLiteral<25>;
+                inputSchema: z.ZodLiteral<25>;
+                outputSchema: z.ZodLiteral<10>;
+                lintClean: z.ZodLiteral<40>;
+                error: z.ZodLiteral<15>;
+                warning: z.ZodLiteral<5>;
+            }, z.core.$strict>;
+            coverage: z.ZodObject<{
+                toolCount: z.ZodNumber;
+                withDescription: z.ZodNumber;
+                withInputSchema: z.ZodNumber;
+                withOutputSchema: z.ZodNumber;
+            }, z.core.$strict>;
+            confidence: z.ZodEnum<{
+                low: "low";
+                medium: "medium";
+            }>;
+            note: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    recovery: z.ZodObject<{
+        status: z.ZodEnum<{
+            failed: "failed";
+            not_run: "not_run";
+        }>;
+        reason: z.ZodString;
+    }, z.core.$strict>;
+    preflight: z.ZodObject<{
+        status: z.ZodEnum<{
+            failed: "failed";
+            not_run: "not_run";
+        }>;
+        reason: z.ZodString;
+    }, z.core.$strict>;
+    recommendations: z.ZodArray<z.ZodString>;
+    coverage: z.ZodObject<{
+        ran: z.ZodArray<z.ZodString>;
+        notRun: z.ZodArray<z.ZodString>;
+        confidence: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare function buildAuditReport(input: BuildAuditReportInput): MCPAuditReport;
+export declare function parseAuditReport(value: unknown): MCPAuditReport;