mcptrustchecker 1.0.0

package/dist/scoring/index.js

@@ -0,0 +1,96 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Deterministic scorer. Turns a set of findings into an auditable Trust Score:
+ * additive penalties from 100, diminishing returns per rule, per-category caps,
+ * then weakest-link hard gates. Same methodology version + same findings ⇒
+ * identical score, and every point is reconstructable from `vector`.
+ */
+import { METHODOLOGY_VERSION } from '../version.js';
+import { ALL_CATEGORIES, bandForScore, CATEGORY_CAP, CONFIDENCE_MULT, DIMINISHING, isCapabilityRule, SEVERITY_WEIGHT, stricterGrade, } from './model.js';
+const CONFIDENCE_ORDER = { confirmed: 0, strong: 1, heuristic: 2, speculative: 3 };
+const SEVERITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/** Compute the Trust Score for a set of findings (capability rules excluded). */
+export function computeScore(findings) {
+    // The grade reflects TRUST only: capability/blast-radius findings raise the
+    // capability level (computed elsewhere) but never lower the grade.
+    const threat = findings.filter((f) => !isCapabilityRule(f.ruleId));
+    // Deterministic order: strongest confidence, then highest severity first, so
+    // the full-weight slot in each rule goes to the most-certain finding.
+    const scored = threat
+        .filter((f) => f.severity !== 'info')
+        .slice()
+        .sort((a, b) => {
+        if (a.ruleId !== b.ruleId)
+            return a.ruleId < b.ruleId ? -1 : 1;
+        // The full-weight (rank-0) slot must go to the HIGHEST-penalty finding, so
+        // that adding a lower-penalty finding can never raise the score (monotonicity).
+        const pa = SEVERITY_WEIGHT[a.severity] * CONFIDENCE_MULT[a.confidence];
+        const pb = SEVERITY_WEIGHT[b.severity] * CONFIDENCE_MULT[b.confidence];
+        if (pa !== pb)
+            return pb - pa;
+        if (CONFIDENCE_ORDER[a.confidence] !== CONFIDENCE_ORDER[b.confidence])
+            return CONFIDENCE_ORDER[a.confidence] - CONFIDENCE_ORDER[b.confidence];
+        return SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+    });
+    const rankByRule = new Map();
+    const vector = [];
+    const categoryRaw = Object.fromEntries(ALL_CATEGORIES.map((c) => [c, 0]));
+    for (const f of scored) {
+        const rank = rankByRule.get(f.ruleId) ?? 0;
+        rankByRule.set(f.ruleId, rank + 1);
+        const rawWeight = SEVERITY_WEIGHT[f.severity];
+        const confidenceMult = CONFIDENCE_MULT[f.confidence];
+        const diminishingFactor = DIMINISHING[Math.min(rank, DIMINISHING.length - 1)];
+        const appliedPenalty = round2(rawWeight * confidenceMult * diminishingFactor);
+        categoryRaw[f.category] += appliedPenalty;
+        vector.push({
+            ruleId: f.ruleId,
+            category: f.category,
+            severity: f.severity,
+            confidence: f.confidence,
+            rawWeight,
+            confidenceMult,
+            diminishingFactor,
+            appliedPenalty,
+        });
+    }
+    const categorySubtotals = Object.fromEntries(ALL_CATEGORIES.map((c) => [c, round2(Math.min(CATEGORY_CAP[c], categoryRaw[c]))]));
+    const totalPenalty = ALL_CATEGORIES.reduce((sum, c) => sum + categorySubtotals[c], 0);
+    const score = Math.max(0, Math.min(100, Math.round(100 - totalPenalty)));
+    const band = bandForScore(score);
+    // Hard gates. Most gates fire only on `confirmed` findings so a guess can't
+    // force a cap — but ANY critical (regardless of confidence) floors the grade
+    // at D, so a critical-severity issue can never be graded A/B.
+    const confirmed = threat.filter((f) => f.confidence === 'confirmed');
+    const confirmedCritical = confirmed.filter((f) => f.severity === 'critical').length;
+    const confirmedHigh = confirmed.filter((f) => f.severity === 'high').length;
+    const anyCritical = threat.some((f) => f.severity === 'critical');
+    const gatesFired = [];
+    let gateCap;
+    const applyCap = (cap, reason) => {
+        gateCap = gateCap ? stricterGrade(gateCap, cap) : cap;
+        gatesFired.push(reason);
+    };
+    if (confirmedCritical > 0)
+        applyCap('F', `${confirmedCritical} confirmed critical finding(s) → grade capped at F`);
+    else if (anyCritical)
+        applyCap('D', `a critical finding is present → grade capped at D`);
+    if (confirmedHigh >= 2)
+        applyCap('D', `${confirmedHigh} confirmed high findings → grade capped at D`);
+    else if (confirmedHigh === 1)
+        applyCap('C', `1 confirmed high finding → grade capped at C`);
+    const grade = gateCap ? stricterGrade(band, gateCap) : band;
+    return {
+        score,
+        grade,
+        band,
+        gateCap,
+        categorySubtotals,
+        vector,
+        gatesFired,
+        methodologyVersion: METHODOLOGY_VERSION,
+    };
+}

package/dist/scoring/model.d.ts

@@ -0,0 +1,50 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * The scoring model — every constant that can move a Trust Score lives here so
+ * the methodology is auditable in one place. A plain weighted average is
+ * gameable, so we use additive penalties from 100 with diminishing returns,
+ * per-category caps, and weakest-link gates — severity is kept distinct from
+ * risk, and the result is fully deterministic.
+ */
+import type { Category, Confidence, Grade, Severity } from '../types.js';
+/** Points for the FIRST finding of a severity, before modifiers. */
+export declare const SEVERITY_WEIGHT: Record<Severity, number>;
+/** Confidence multiplier — a guess must not carry a confirmed finding's weight. */
+export declare const CONFIDENCE_MULT: Record<Confidence, number>;
+/** Diminishing returns for the Nth finding of the same rule (index clamped to last). */
+export declare const DIMINISHING: number[];
+/** Maximum points any single category may subtract. */
+export declare const CATEGORY_CAP: Record<Category, number>;
+export declare const ALL_CATEGORIES: Category[];
+/** Higher score = safer. Bands are fixed and published. */
+export declare const GRADE_BANDS: {
+    grade: Grade;
+    min: number;
+}[];
+/** Strictness ordering: F is worst (0), A is best (4). */
+export declare const GRADE_RANK: Record<Grade, number>;
+export declare function bandForScore(score: number): Grade;
+/** Return the stricter (worse) of two grades. */
+export declare function stricterGrade(a: Grade, b: Grade): Grade;
+/**
+ * MCP Trust Checker scores two independent axes:
+ *
+ *  - TRUST (the A–F grade): does anything suggest the server is malicious or
+ *    negligent? Driven by *threat* findings (poisoning, secrets, unicode
+ *    smuggling, typosquat, CVEs, rug-pull, annotation lies, a single tool built
+ *    as an exfiltration primitive).
+ *  - CAPABILITY (a level): how much could this server do if the model driving
+ *    it were manipulated? Driven by *capability* findings (code execution,
+ *    filesystem writes, network egress, the cross-tool toxic-flow surface).
+ *
+ * A legitimate but powerful server (a scraper, a browser, a filesystem tool) is
+ * high-CAPABILITY but should still be high-TRUST — it isn't a bad actor, it just
+ * has a large blast radius. Keeping the axes separate is what stops the grade
+ * from collapsing every capable server into "F".
+ *
+ * These rules describe *capability* and therefore do NOT lower the trust grade;
+ * they raise the capability level and are shown as "capability observations".
+ */
+export declare const CAPABILITY_RULES: Set<string>;
+/** True if a rule describes capability/blast-radius rather than a trust threat. */
+export declare function isCapabilityRule(ruleId: string): boolean;

package/dist/scoring/model.js

@@ -0,0 +1,101 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * The scoring model — every constant that can move a Trust Score lives here so
+ * the methodology is auditable in one place. A plain weighted average is
+ * gameable, so we use additive penalties from 100 with diminishing returns,
+ * per-category caps, and weakest-link gates — severity is kept distinct from
+ * risk, and the result is fully deterministic.
+ */
+/** Points for the FIRST finding of a severity, before modifiers. */
+export const SEVERITY_WEIGHT = {
+    critical: 45,
+    high: 22,
+    medium: 9,
+    low: 3,
+    info: 0,
+};
+/** Confidence multiplier — a guess must not carry a confirmed finding's weight. */
+export const CONFIDENCE_MULT = {
+    confirmed: 1.0,
+    strong: 0.7,
+    heuristic: 0.4,
+    speculative: 0.2,
+};
+/** Diminishing returns for the Nth finding of the same rule (index clamped to last). */
+export const DIMINISHING = [1.0, 0.5, 0.25, 0.1];
+/** Maximum points any single category may subtract. */
+export const CATEGORY_CAP = {
+    injection: 50,
+    exfiltration: 50,
+    permissions: 35,
+    'supply-chain': 30,
+    network: 25,
+    hygiene: 10,
+};
+export const ALL_CATEGORIES = [
+    'injection',
+    'exfiltration',
+    'permissions',
+    'supply-chain',
+    'network',
+    'hygiene',
+];
+/** Higher score = safer. Bands are fixed and published. */
+export const GRADE_BANDS = [
+    { grade: 'A', min: 90 },
+    { grade: 'B', min: 80 },
+    { grade: 'C', min: 70 },
+    { grade: 'D', min: 60 },
+    { grade: 'F', min: 0 },
+];
+/** Strictness ordering: F is worst (0), A is best (4). */
+export const GRADE_RANK = { F: 0, D: 1, C: 2, B: 3, A: 4 };
+export function bandForScore(score) {
+    for (const b of GRADE_BANDS)
+        if (score >= b.min)
+            return b.grade;
+    return 'F';
+}
+/** Return the stricter (worse) of two grades. */
+export function stricterGrade(a, b) {
+    return GRADE_RANK[a] <= GRADE_RANK[b] ? a : b;
+}
+/**
+ * MCP Trust Checker scores two independent axes:
+ *
+ *  - TRUST (the A–F grade): does anything suggest the server is malicious or
+ *    negligent? Driven by *threat* findings (poisoning, secrets, unicode
+ *    smuggling, typosquat, CVEs, rug-pull, annotation lies, a single tool built
+ *    as an exfiltration primitive).
+ *  - CAPABILITY (a level): how much could this server do if the model driving
+ *    it were manipulated? Driven by *capability* findings (code execution,
+ *    filesystem writes, network egress, the cross-tool toxic-flow surface).
+ *
+ * A legitimate but powerful server (a scraper, a browser, a filesystem tool) is
+ * high-CAPABILITY but should still be high-TRUST — it isn't a bad actor, it just
+ * has a large blast radius. Keeping the axes separate is what stops the grade
+ * from collapsing every capable server into "F".
+ *
+ * These rules describe *capability* and therefore do NOT lower the trust grade;
+ * they raise the capability level and are shown as "capability observations".
+ */
+export const CAPABILITY_RULES = new Set([
+    'MTC-CAP-001', // command/code execution
+    'MTC-CAP-002', // filesystem mutation
+    'MTC-CAP-004', // open-world + sensitive read
+    'MTC-CAP-005', // missing destructiveHint
+    'MTC-CAP-006', // unconstrained command param
+    'MTC-CAP-007', // unconstrained URL/host param
+    'MTC-CAP-008', // unconstrained path param
+    'MTC-CAP-009', // declared sampling capability
+    'MTC-CAP-010', // declared elicitation capability (the secret-seeking variant is MTC-CAP-011, a threat)
+    'MTC-FLOW-002', // cross-tool trifecta (capability co-presence, not malice)
+    'MTC-FLOW-003', // read + egress in one tool
+    'MTC-FLOW-004', // source + sink co-exist
+    'MTC-FLOW-005', // untrusted input reaches an action
+    'MTC-NET-005', // remote endpoint (informational)
+]);
+/** True if a rule describes capability/blast-radius rather than a trust threat. */
+export function isCapabilityRule(ruleId) {
+    return CAPABILITY_RULES.has(ruleId);
+}

package/dist/types.d.ts

@@ -0,0 +1,361 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * MCP Trust Checker core type model.
+ *
+ * Everything in the engine is expressed against a single normalized, transport-
+ * agnostic view of a server — the {@link ServerSurface}. Acquisition adapters
+ * (stdio / HTTP / static JSON / client config) all produce a `ServerSurface`;
+ * every detector consumes one and emits {@link Finding}s; the scorer turns
+ * findings into an auditable {@link Score}. Keeping this model small and pure is
+ * what makes the whole tool deterministic and offline-capable.
+ */
+/** Where a surface was acquired from (drives which detectors have signal). */
+export type SurfaceSourceKind = 'stdio' | 'http' | 'manifest' | 'client-config' | 'package';
+export interface SurfaceSource {
+    kind: SurfaceSourceKind;
+    /** Human-readable origin: a path, URL, or package spec. */
+    origin: string;
+}
+/** A JSON-Schema-ish object as advertised by a tool's `inputSchema`. */
+export interface JsonSchema {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema | JsonSchema[];
+    required?: string[];
+    enum?: unknown[];
+    description?: string;
+    title?: string;
+    format?: string;
+    [k: string]: unknown;
+}
+/**
+ * Tool behavior hints as advertised by the server.
+ *
+ * SECURITY NOTE: these are attacker-controllable and MUST NOT be trusted for
+ * security decisions. MCP Trust Checker reads them only to flag when they *contradict*
+ * a tool's derived capabilities (annotation-vs-behavior mismatch).
+ */
+export interface ToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+    [k: string]: unknown;
+}
+export interface ToolDef {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+    outputSchema?: JsonSchema;
+    annotations?: ToolAnnotations;
+}
+export interface PromptArgument {
+    name: string;
+    description?: string;
+    required?: boolean;
+}
+export interface PromptDef {
+    name: string;
+    title?: string;
+    description?: string;
+    arguments?: PromptArgument[];
+}
+export interface ResourceDef {
+    uri?: string;
+    uriTemplate?: string;
+    name?: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+}
+export interface TransportInfo {
+    kind: 'stdio' | 'http' | 'sse' | 'unknown';
+    /** For HTTP/SSE transports. */
+    url?: string;
+    /** For stdio transports. */
+    command?: string;
+    args?: string[];
+    /**
+     * True when the spawned `command`/`args` originate from untrusted metadata
+     * without an executable allowlist — the systemic stdio-RCE class.
+     */
+    userControlledCommand?: boolean;
+    /** Execution-hijacking env vars that were stripped before spawning, if any. */
+    droppedEnv?: string[];
+}
+/** Package/provenance metadata, if the target maps to a known package. */
+export interface PackageMeta {
+    registry?: 'npm' | 'pypi' | 'unknown';
+    name?: string;
+    version?: string;
+    /** Raw install/lifecycle scripts, if known. */
+    scripts?: Record<string, string>;
+    dependencies?: string[];
+    repositoryUrl?: string | null;
+    license?: string | null;
+    weeklyDownloads?: number | null;
+    /** ISO 8601 publish timestamp of the resolved version, if known. */
+    publishedAt?: string | null;
+    /** Whether the install spec pins an exact version (false = @latest/floating). */
+    pinned?: boolean;
+    /** The raw version token from the install spec, if any (e.g. "latest", "^1.2.0"). */
+    requestedSpec?: string;
+}
+/** The single normalized object every detector operates on. */
+export interface ServerSurface {
+    /** Stable identity used for lockfile pinning (package spec, url, or path). */
+    id: string;
+    source: SurfaceSource;
+    server: {
+        name?: string;
+        version?: string;
+        title?: string;
+        /** Free-text server instructions — a first-class line-jumping surface. */
+        instructions?: string;
+        protocolVersion?: string;
+        capabilities?: Record<string, unknown>;
+    };
+    tools: ToolDef[];
+    prompts: PromptDef[];
+    resources: ResourceDef[];
+    transport?: TransportInfo;
+    packageMeta?: PackageMeta;
+    /**
+     * Server implementation source, when available (a local package directory or
+     * an extracted tarball). Enables implementation-level analysis — reading what
+     * the code *does*, not only what the tool metadata *claims*.
+     */
+    sourceFiles?: SourceFile[];
+}
+export interface SourceFile {
+    /** Path relative to the package root. */
+    path: string;
+    content: string;
+}
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+/**
+ * How sure we are — the "severity ≠ risk" split: a heuristic
+ * keyword hit and a decoded hidden-instruction payload can share a severity
+ * but must not carry the same weight — and only `confirmed` findings can fire
+ * a hard grade gate.
+ */
+export type Confidence = 'confirmed' | 'strong' | 'heuristic' | 'speculative';
+export type Category = 'injection' | 'exfiltration' | 'permissions' | 'supply-chain' | 'network' | 'hygiene';
+export interface FindingLocation {
+    kind: 'tool' | 'prompt' | 'resource' | 'server' | 'package' | 'transport' | 'flow';
+    /** Name of the tool/prompt/resource, when applicable. */
+    name?: string;
+    /** Field within the object, e.g. `description` or `inputSchema.properties.path.description`. */
+    field?: string;
+}
+export interface Finding {
+    /** Stable rule id, e.g. `MTC-UNI-001`. Used for docs, baselines and SARIF. */
+    ruleId: string;
+    title: string;
+    category: Category;
+    severity: Severity;
+    confidence: Confidence;
+    /** What was found and why it matters. */
+    description: string;
+    remediation?: string;
+    location?: FindingLocation;
+    /** Concrete evidence: a decoded payload, matched snippet, offending name, etc. */
+    evidence?: string;
+    /** External references (OWASP, CVE, blog posts, spec sections). */
+    references?: string[];
+    /** OWASP MCP Top 10 / LLM Top 10 mapping id, when available. */
+    owasp?: string;
+    /** Structured extras for machine consumers. */
+    data?: Record<string, unknown>;
+}
+export type CapabilityTag = 'untrusted-input' | 'sensitive-source' | 'external-sink' | 'code-exec' | 'file-write';
+export interface ToolCapability {
+    tool: string;
+    tags: CapabilityTag[];
+    /** Why each tag was assigned (keyword/schema evidence), for explainability. */
+    reasons: Partial<Record<CapabilityTag, string[]>>;
+}
+/** How much a server could do if the model driving it were manipulated. */
+export type CapabilityLevel = 'minimal' | 'moderate' | 'high' | 'critical';
+export interface CapabilityProfile {
+    level: CapabilityLevel;
+    /** Human-readable reasons the level was assigned. */
+    reasons: string[];
+    /** The union of capability tags observed across the server's tools. */
+    tags: CapabilityTag[];
+}
+export interface ToxicFlow {
+    id: string;
+    severity: Severity;
+    confidence: Confidence;
+    /** Tool(s) that supply the untrusted input, if any. */
+    untrustedInput: string[];
+    /** Tool(s) that read sensitive data, if any. */
+    sensitiveSource: string[];
+    /** Tool(s) that can exfiltrate / act externally. */
+    externalSink: string[];
+    /** True when a single tool holds more than one role (self-contained primitive). */
+    selfContained: boolean;
+    /** The concrete attack chain of tools (e.g. ["fetch_url","read_file","http_request"]). */
+    path?: string[];
+    /** True when at least one leg of the path is a direct schema wire (higher plausibility). */
+    pathWired?: boolean;
+    description: string;
+}
+export type Grade = 'A' | 'B' | 'C' | 'D' | 'F';
+export interface ScoreVectorItem {
+    ruleId: string;
+    category: Category;
+    severity: Severity;
+    confidence: Confidence;
+    /** Base weight for the severity. */
+    rawWeight: number;
+    confidenceMult: number;
+    /** Diminishing-returns multiplier for the Nth finding of this rule. */
+    diminishingFactor: number;
+    /** rawWeight × confidenceMult × diminishingFactor, rounded to 2dp. */
+    appliedPenalty: number;
+}
+export interface Score {
+    /** 0–100, higher is safer. */
+    score: number;
+    /** Final grade after gates. */
+    grade: Grade;
+    /** Grade implied by the raw number, before hard gates. */
+    band: Grade;
+    /** Strictest grade cap forced by a hard gate, if any. */
+    gateCap?: Grade;
+    /** Points subtracted per category (after per-category caps). */
+    categorySubtotals: Record<Category, number>;
+    /** Fully itemized, reconstructable penalty vector. */
+    vector: ScoreVectorItem[];
+    /** Human-readable descriptions of every gate that fired. */
+    gatesFired: string[];
+    methodologyVersion: string;
+}
+export type IntegrityStatus = 'first-seen' | 'unchanged' | 'drift';
+export interface SurfaceChange {
+    kind: 'tool-added' | 'tool-removed' | 'tool-changed' | 'instructions-changed';
+    name?: string;
+    detail: string;
+}
+export interface IntegrityResult {
+    status: IntegrityStatus;
+    currentDigest: string;
+    previousDigest?: string;
+    /** Populated when status is `drift`. */
+    changes?: SurfaceChange[];
+}
+export interface ScanReport {
+    tool: {
+        name: string;
+        version: string;
+        methodologyVersion: string;
+    };
+    target: {
+        id: string;
+        source: SurfaceSource;
+        server?: {
+            name?: string;
+            version?: string;
+        };
+    };
+    /** ISO timestamp. Omitted for reproducible (deterministic) reports. */
+    scannedAt?: string;
+    findings: Finding[];
+    score: Score;
+    capabilities: ToolCapability[];
+    /** The server's blast-radius rating (independent of the trust grade). */
+    capabilityProfile: CapabilityProfile;
+    toxicFlows: ToxicFlow[];
+    integrity?: IntegrityResult;
+    /** SHA-256 of the canonicalized surface — the rug-pull fingerprint. */
+    surfaceDigest: string;
+    stats: {
+        tools: number;
+        prompts: number;
+        resources: number;
+        findingsBySeverity: Record<Severity, number>;
+    };
+}
+export interface DetectorContext {
+    surface: ServerSurface;
+    config: ResolvedConfig;
+    /** Per-tool capability tags, computed once by the engine and shared. */
+    capabilities: ToolCapability[];
+    /**
+     * Tool names exposed by OTHER servers in the same scan, for cross-server
+     * name-collision / shadowing detection. Empty when scanning a single target.
+     */
+    siblingTools?: {
+        server: string;
+        name: string;
+    }[];
+}
+export interface Detector {
+    id: string;
+    /** Pipeline stage number (see docs/architecture.md). */
+    stage: number;
+    title: string;
+    run(ctx: DetectorContext): Finding[] | Promise<Finding[]>;
+}
+export interface McpTrustCheckerConfig {
+    /** Rule ids to disable entirely. */
+    disabledRules?: string[];
+    /** Rule ids whose findings are allowed (suppressed) — an explicit waiver list. */
+    allowlist?: string[];
+    /** Fail CI when the score is below this threshold (0–100). */
+    failUnder?: number;
+    /** Fail CI when the grade is worse than this (e.g. "B"). */
+    minGrade?: Grade;
+    /** Path to the integrity lockfile. */
+    lockfile?: string;
+    /**
+     * When true, the toxic-flow graph assumes the client also exposes generic
+     * built-in tools (web-fetch as untrusted input, file/network as sinks), which
+     * can complete a trifecta on their own.
+     */
+    includeBuiltins?: boolean;
+    /** Additional package names to hard-protect against typosquatting. */
+    protectedPackages?: string[];
+    /** Zero-width character count above which a string is treated as an encoded payload. */
+    invisibleCharThreshold?: number;
+    /**
+     * Location-scoped waivers (a baseline). Unlike `allowlist` (which silences a
+     * whole rule everywhere), each entry silences a specific finding on a specific
+     * tool/field — with a justification that stays in the config for audit.
+     * Also loadable from a standalone `.mtcignore` JSON file next to the config.
+     */
+    suppress?: Suppression[];
+    /** Organisational policy the scan is gated against (see {@link Policy}). */
+    policy?: Policy;
+}
+/** A single baseline waiver. `rule` is required; the rest narrow the match. */
+export interface Suppression {
+    rule: string;
+    /** Only suppress on this tool/prompt/resource name (location.name). */
+    tool?: string;
+    /** Only suppress on this field (location.field). */
+    field?: string;
+    /** Why the waiver is safe — kept for audit, never affects matching. */
+    reason?: string;
+}
+/** Policy-as-code: declarative rules a server must satisfy, gated in CI. */
+export interface Policy {
+    /** Fail if the Trust grade is worse than this. */
+    minGrade?: Grade;
+    /** Fail if the Capability blast-radius exceeds this level. */
+    maxCapability?: CapabilityLevel;
+    /** Fail if any of these rule ids fired. */
+    denyRules?: string[];
+    /** Fail if the server exposes any of these capability tags. */
+    denyCapabilities?: CapabilityTag[];
+}
+/** Config with all defaults resolved — what detectors actually see. */
+export interface ResolvedConfig extends Required<Omit<McpTrustCheckerConfig, 'minGrade' | 'lockfile' | 'policy'>> {
+    minGrade?: Grade;
+    lockfile?: string;
+    policy?: Policy;
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * MCP Trust Checker core type model.
+ *
+ * Everything in the engine is expressed against a single normalized, transport-
+ * agnostic view of a server — the {@link ServerSurface}. Acquisition adapters
+ * (stdio / HTTP / static JSON / client config) all produce a `ServerSurface`;
+ * every detector consumes one and emits {@link Finding}s; the scorer turns
+ * findings into an auditable {@link Score}. Keeping this model small and pure is
+ * what makes the whole tool deterministic and offline-capable.
+ */
+export {};

package/dist/util/ansi.d.ts

@@ -0,0 +1,26 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Tiny zero-dependency ANSI helper. Respects NO_COLOR and non-TTY output.
+ * A security tool should not pull a coloring library into its dependency tree.
+ */
+export declare const c: {
+    enabled: boolean;
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    underline: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    magenta: (s: string) => string;
+    cyan: (s: string) => string;
+    gray: (s: string) => string;
+    white: (s: string) => string;
+    bgRed: (s: string) => string;
+    bgGreen: (s: string) => string;
+    bgYellow: (s: string) => string;
+};
+/** Visible length of a string, ignoring ANSI escapes. */
+export declare function visibleLength(s: string): number;
+/** Pad a (possibly colored) string to a visible width. */
+export declare function padVisible(s: string, width: number): string;