mcptrustchecker 1.2.0 → 1.3.0

package/README.md

@@ -9,10 +9,11 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A520-3c873a.svg)](package.json)
 [![Methodology](https://img.shields.io/badge/methodology-mcptrustchecker--1.0-6f42c1.svg)](docs/methodology.md)
-[![Tests](https://img.shields.io/badge/tests-294%20passing-brightgreen.svg)](test)
+[![Tests](https://img.shields.io/badge/tests-304%20passing-brightgreen.svg)](test)
 [![Rules](https://img.shields.io/badge/rules-78-orange.svg)](docs/rules.md)
 [![No account](https://img.shields.io/badge/account-not%20required-brightgreen.svg)](#why-this-is-different)
 [![Offline](https://img.shields.io/badge/runs-100%25%20offline-brightgreen.svg)](#why-this-is-different)
+[![Free hosted API](https://img.shields.io/badge/hosted%20API-free-c4f542.svg)](https://mcptrustchecker.com/api)
 
 <br/>
 
@@ -24,6 +25,8 @@
 npx mcptrustchecker                # 🔍 scan every MCP server you already have installed — zero config
 ```
 
+**Zero install?** Run the same deterministic engine as a **free public web API → [mcptrustchecker.com/api](https://mcptrustchecker.com/api)**
+
 <sub>· offline · deterministic · no account · OAuth browser login for protected servers · reads the real published npm/PyPI source · <a href="#the-algorithm-the-capability-flow-trust-model">one novel core</a> ·</sub>
 
 </div>
@@ -148,6 +151,8 @@ mcptrustchecker scan ./tools.json --min-grade B             # exit 1 below a gra
 
 The terminal report is **detailed by default** — every finding prints its full description (**what** the problem is and **why** it matters), the exact location, the offending **evidence**, a **fix**, and its OWASP mapping, grouped most-severe-first. Add `--details` for external references, or `--quiet` for just the grade line.
 
+**No install? Use the free hosted API.** A hosted version of the exact same deterministic engine runs at **[mcptrustchecker.com/api](https://mcptrustchecker.com/api)** — POST a `tools.json` manifest or a published npm/PyPI package name over a single HTTPS request and get the same auditable A–F Trust Score back as JSON. It is **completely free** (grab a key in seconds, no card, no account), and it's the quickest way to try the scanner without installing anything. The CLI and library stay 100% offline — the hosted API is an optional convenience.
+
 ---
 
 ## The algorithm: the Capability-Flow Trust Model
@@ -242,20 +247,22 @@ Full list: **[docs/rules.md](docs/rules.md)** · run `mcptrustchecker rules`.
 
 ---
 
-## Two axes: Trust (grade) and Capability (blast radius)
+## Three axes: Trust (grade), Capability (blast radius), Coverage (depth)
 
-A single number can't answer "should I use this server?" — because **"powerful" and "malicious" are different questions.** A web scraper legitimately needs to fetch untrusted pages and act on them; that's a large *blast radius*, not evidence it's a bad actor. So MCP Trust Checker reports two independent things:
+A single number can't answer "should I use this server?" — because **"powerful" and "malicious" are different questions**, and a clean grade means nothing if the scan barely saw the server. So MCP Trust Checker reports three independent things:
 
 - **Trust — the A–F grade.** Driven by *threat* signals: prompt-injection with concealment, embedded secrets, Unicode smuggling, typosquatting, known CVEs, rug-pull drift, annotation lies, a single tool built as an exfiltration primitive. Answers **"any sign this server is malicious or negligent?"**
 - **Capability — a level (Minimal → Critical).** Driven by what the server *can do*: code execution, filesystem writes, network egress, the cross-tool toxic-flow surface. Answers **"how much damage if the model driving it is manipulated?"** — a fact to size access against, **not** a mark against the server.
+- **Coverage — a level (Live → Source → Manifest → Metadata → Empty).** How much the scan could actually inspect. A Grade A from a `metadata`-only scan (no tools enumerated, no code read) is **not** the assurance of a Grade A from a `live` scan that saw the real runtime tools. Coverage never changes the score — it states the score's reach, so a shallow scan is never mistaken for a clean bill of health. When coverage is partial, the report says exactly what it could not see.
 
 ```
-firecrawl   Trust B (81/100)   Capability CRITICAL   → trustworthy, but huge blast radius — grant carefully
-poisoned    Trust F            Capability HIGH        → actual malice signals — avoid
-memory      Trust A (100)      Capability MINIMAL     → safe and low-power
+firecrawl   Trust B (81/100)   Capability CRITICAL   Coverage LIVE     → trustworthy, but huge blast radius — grant carefully
+poisoned    Trust F            Capability HIGH        Coverage LIVE     → actual malice signals — avoid
+memory      Trust A (100)      Capability MINIMAL     Coverage LIVE     → safe and low-power
+some-pkg    Trust A (98)       Capability MINIMAL     Coverage METADATA → clean *so far* — 0 tools seen; scan the live server
 ```
 
-This is why MCP Trust Checker doesn't collapse every capable server into "F" (which would make the grade useless). Popularity is never an input — popular packages get compromised — but a legitimate powerful server keeps a high Trust grade while its Capability is surfaced honestly.
+This is why MCP Trust Checker doesn't collapse every capable server into "F" (which would make the grade useless). Popularity is never an input — popular packages get compromised — but a legitimate powerful server keeps a high Trust grade while its Capability and the scan's Coverage are surfaced honestly.
 
 ## The Trust grade is auditable by construction
 

package/dist/engine.js

@@ -14,6 +14,7 @@ import { checkIntegrity } from './lockfile.js';
 import { surfaceDigest } from './util/hash.js';
 import { computeScore } from './scoring/index.js';
 import { computeCapabilityProfile } from './scoring/capability.js';
+import { computeCoverage } from './scoring/coverage.js';
 import { METHODOLOGY_VERSION, TOOL_NAME, TOOL_VERSION } from './version.js';
 const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
 const SEVERITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
@@ -146,6 +147,7 @@ export async function scanSurface(rawSurface, options = {}) {
         score,
         capabilities,
         capabilityProfile: computeCapabilityProfile(capabilities, flows),
+        coverage: computeCoverage(surface),
         toxicFlows: flows,
         integrity,
         surfaceDigest: surfaceDigest(surface),

package/dist/report/markdown.js

@@ -3,6 +3,8 @@
  * Markdown report — for PR comments, job summaries, and README embeds.
  */
 import { ALL_CATEGORIES } from '../scoring/model.js';
+import { coverageLabel } from '../scoring/coverage.js';
+const COVERAGE_EMOJI = { live: '🟢', source: '🟢', manifest: '🟡', metadata: '🟡', empty: '🔴' };
 const SEV_EMOJI = {
     critical: '🟥',
     high: '🟧',
@@ -29,6 +31,16 @@ export function renderMarkdown(report) {
         `**Surface:** ${report.stats.tools} tools, ${report.stats.prompts} prompts, ${report.stats.resources} resources · ` +
         `**Methodology:** \`${s.methodologyVersion}\``);
     md.push('');
+    const cov = report.coverage;
+    md.push(`**Coverage:** ${COVERAGE_EMOJI[cov.level] ?? '⚪'} ${cov.level.toUpperCase()} — ${coverageLabel(cov.level)}`);
+    if (cov.caveats.length) {
+        md.push('');
+        md.push('> [!NOTE]');
+        md.push('> This grade reflects only what was inspected:');
+        for (const note of cov.caveats)
+            md.push(`> - ${mdInline(note)}`);
+    }
+    md.push('');
     const bs = report.stats.findingsBySeverity;
     md.push(`**Findings:** ${bs.critical} critical · ${bs.high} high · ${bs.medium} medium · ${bs.low} low · ${bs.info} info`);
     md.push('');

package/dist/report/sarif.js

@@ -95,6 +95,8 @@ export function renderSarif(report) {
                     trustScore: report.score.score,
                     grade: report.score.grade,
                     capabilityLevel: report.capabilityProfile.level,
+                    coverageLevel: report.coverage.level,
+                    coverageCaveats: report.coverage.caveats,
                     methodologyVersion: report.score.methodologyVersion,
                     surfaceDigest: report.surfaceDigest,
                 },

package/dist/report/terminal.js

@@ -3,6 +3,7 @@
  * Human-facing terminal report. Zero-dependency ANSI, degrades to plain text
  * when piped or under NO_COLOR.
  */
+import { coverageLabel } from '../scoring/coverage.js';
 import { c, padVisible } from '../util/ansi.js';
 import { ALL_CATEGORIES, isCapabilityRule } from '../scoring/model.js';
 const SEV_LABEL = {
@@ -45,6 +46,14 @@ function capColor(level, s) {
             return c.bold(c.red(s));
     }
 }
+/** A deep scan (live/source) reads normal; a shallow one (manifest/metadata/empty) is a caution. */
+function coverageColor(level, s) {
+    if (level === 'live' || level === 'source')
+        return c.green(s);
+    if (level === 'empty')
+        return c.red(s);
+    return c.yellow(s);
+}
 /** Usable terminal width (clamped), for wrapping detailed descriptions. */
 const TERM = Math.max(64, Math.min(process.stdout.columns || 100, 118));
 function line(char = '─', width = Math.min(TERM, 72)) {
@@ -97,6 +106,10 @@ export function renderTerminal(report, opts = {}) {
     out.push(`   ${gradeColor(score.grade, `╭${'─'.repeat(badge.length)}╮`)}`);
     out.push(`   ${gradeColor(score.grade, `│${badge}│`)}   ${c.bold(`Trust Score ${score.score}/100`)}   ${c.gray('(malice/negligence signals)')}`);
     out.push(`   ${gradeColor(score.grade, `╰${'─'.repeat(badge.length)}╯`)}   ${capColor(cap.level, `Capability ${cap.level.toUpperCase()}`)}   ${c.gray('(blast radius)')}`);
+    const cov = report.coverage;
+    // Align under "Capability": 3 leading spaces + the 2 box borders + badge width + 3-space gap.
+    const pad = ' '.repeat(badge.length + 8);
+    out.push(`${pad}${coverageColor(cov.level, `Coverage ${cov.level.toUpperCase()}`)}   ${c.gray('(' + coverageLabel(cov.level) + ')')}`);
     if (cap.reasons.length) {
         out.push(`   ${c.gray('methodology ' + score.methodologyVersion)} · ${c.gray(cap.reasons.slice(0, 2).join('; '))}`);
     }
@@ -114,6 +127,16 @@ export function renderTerminal(report, opts = {}) {
         .join(c.gray(' · '));
     out.push(`${c.gray('Threats   ')} ${counts || c.green('none')}`);
     out.push(`${c.gray('Capability')} ${capColor(cap.level, cap.level)} ${c.gray(`(${capabilityFindings.length} observation${capabilityFindings.length === 1 ? '' : 's'})`)}`);
+    // Coverage caveats — what the scan could NOT see, so a clean grade on a shallow
+    // scan is never read as a thorough all-clear.
+    if (cov.caveats.length) {
+        out.push('');
+        out.push(`${coverageColor(cov.level, '⚑')} ${c.gray('Coverage — this grade reflects only what was inspected:')}`);
+        for (const note of cov.caveats) {
+            for (const wl of wrap(note, TERM - 4))
+                out.push(`  ${c.gray(wl)}`);
+        }
+    }
     // Category penalties.
     const cats = ALL_CATEGORIES.filter((cat) => score.categorySubtotals[cat] > 0);
     if (cats.length) {

package/dist/scoring/coverage.d.ts

@@ -0,0 +1,14 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Coverage — a third, honest axis alongside Trust (grade) and Capability (blast
+ * radius). It states how much of the target the scan could actually inspect, so
+ * a clean grade from a shallow scan is never mistaken for a thorough one.
+ *
+ * Purely descriptive and deterministic: derived only from what the acquired
+ * surface contains. It never changes the score — it explains the score's reach.
+ */
+import type { Coverage, CoverageLevel, ServerSurface } from '../types.js';
+/** Derive the coverage descriptor from an acquired surface. */
+export declare function computeCoverage(surface: ServerSurface): Coverage;
+/** A short human label for a coverage level (terminal/markdown headline). */
+export declare function coverageLabel(level: CoverageLevel): string;

package/dist/scoring/coverage.js

@@ -0,0 +1,62 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Coverage — a third, honest axis alongside Trust (grade) and Capability (blast
+ * radius). It states how much of the target the scan could actually inspect, so
+ * a clean grade from a shallow scan is never mistaken for a thorough one.
+ *
+ * Purely descriptive and deterministic: derived only from what the acquired
+ * surface contains. It never changes the score — it explains the score's reach.
+ */
+/** Derive the coverage descriptor from an acquired surface. */
+export function computeCoverage(surface) {
+    const toolSurface = (Array.isArray(surface.tools) && surface.tools.length > 0) ||
+        (Array.isArray(surface.prompts) && surface.prompts.length > 0) ||
+        (Array.isArray(surface.resources) && surface.resources.length > 0);
+    const implementationSource = Array.isArray(surface.sourceFiles) && surface.sourceFiles.length > 0;
+    const m = surface.packageMeta;
+    const packageMetadata = Boolean(m && (m.name || m.version || (Array.isArray(m.dependencies) && m.dependencies.length > 0) || m.tarballSha256));
+    const liveTransport = surface.source?.kind === 'stdio' || surface.source?.kind === 'http';
+    // Richest signal wins for the headline label; `inputs` keeps the full detail.
+    let level;
+    if (liveTransport)
+        level = 'live';
+    else if (implementationSource)
+        level = 'source';
+    else if (toolSurface)
+        level = 'manifest';
+    else if (packageMetadata)
+        level = 'metadata';
+    else
+        level = 'empty';
+    const caveats = [];
+    if (level === 'empty') {
+        caveats.push('Nothing scannable was found on this target — an empty surface is not a clean bill of health.');
+    }
+    else {
+        if (!toolSurface) {
+            caveats.push('No tools were enumerated, so prompt-injection, capability and toxic-flow analysis had no tool surface to inspect. ' +
+                'To grade a package’s real runtime tools, scan the running server: --command "npx -y <package>".');
+        }
+        if (!implementationSource && !liveTransport) {
+            caveats.push(packageMetadata
+                ? 'The implementation source was not read — this reflects registry metadata only. Add --online to fetch and analyze the published package source.'
+                : 'The implementation source was not read — this reflects the declared tool metadata only.');
+        }
+    }
+    return { level, inputs: { toolSurface, implementationSource, packageMetadata, liveTransport }, caveats };
+}
+/** A short human label for a coverage level (terminal/markdown headline). */
+export function coverageLabel(level) {
+    switch (level) {
+        case 'live':
+            return 'running server — real runtime tools';
+        case 'source':
+            return 'published/local source read';
+        case 'manifest':
+            return 'static tool list only — no source';
+        case 'metadata':
+            return 'registry metadata only — no tools, no source';
+        case 'empty':
+            return 'nothing inspected';
+    }
+}

package/dist/types.d.ts

@@ -208,6 +208,29 @@ export interface CapabilityProfile {
     /** The union of capability tags observed across the server's tools. */
     tags: CapabilityTag[];
 }
+/**
+ * The depth of what the scan actually observed. A Trust grade is only ever as
+ * meaningful as its coverage: a clean grade from a metadata-only scan (no tools
+ * enumerated, no source read) is NOT the same assurance as a clean grade from a
+ * live scan that saw the real runtime tools and read the code.
+ */
+export type CoverageLevel = 'live' | 'source' | 'manifest' | 'metadata' | 'empty';
+export interface Coverage {
+    level: CoverageLevel;
+    /** Which analysis inputs had signal — drives which detectors could contribute. */
+    inputs: {
+        /** Tool/prompt/resource surface enumerated (injection, capability, toxic-flow). */
+        toolSurface: boolean;
+        /** Implementation source analyzed (MTC-SRC sinks). */
+        implementationSource: boolean;
+        /** Package/provenance metadata present (supply-chain). */
+        packageMetadata: boolean;
+        /** Spoke to a running server (live stdio/HTTP), so the tools are runtime-real. */
+        liveTransport: boolean;
+    };
+    /** Honest notes on what the scan could NOT see; empty when coverage is complete. */
+    caveats: string[];
+}
 export interface ToxicFlow {
     id: string;
     severity: Severity;
@@ -291,6 +314,8 @@ export interface ScanReport {
     capabilities: ToolCapability[];
     /** The server's blast-radius rating (independent of the trust grade). */
     capabilityProfile: CapabilityProfile;
+    /** How much of the target the scan actually inspected (a grade's depth). */
+    coverage: Coverage;
     toxicFlows: ToxicFlow[];
     integrity?: IntegrityResult;
     /** SHA-256 of the canonicalized surface — the rug-pull fingerprint. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcptrustchecker",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Local-first, deterministic security scanner for Model Context Protocol (MCP) servers. Cross-tool toxic-flow analysis, Unicode-smuggling decode, prompt-injection & supply-chain detection, with an auditable 0–100 Trust Score.",
   "type": "module",
   "license": "MIT",