@apitella/scan 0.1.0

package/README.md

@@ -0,0 +1,146 @@
+# @apitella/scan
+
+Check an MCP server's tool surface for the gaps that bite agents in production —
+missing safety annotations, descriptions that contradict their own hints, credential
+strings and prompt-injection phrasing in tool text — at **build time**, in **CI**, or
+against a **live URL**.
+
+Same checks as the free scanner at [apitella.com/scan](https://apitella.com/scan),
+runnable where you build the server.
+
+```
+npx @apitella/scan http://localhost:3000/mcp
+```
+
+```
+Apitella scan  my-warehouse-mcp v1.4.0
+6 tools · 2 resources
+
+  ▲ create_shipment  [no-safety-hints]
+    Neither readOnlyHint nor destructiveHint is declared — an agent can't tell
+    whether this is safe to auto-approve.
+  ▲ delete_record  [destructive-hint-mismatch]
+    Description reads as destructive, but destructiveHint isn't set to true — an
+    agent skipping confirmation has no signal this is dangerous.
+  · server  [no-version-signal]
+    No changelog or version signal on this server — if any of this changes,
+    nothing tells you unless it's being monitored.
+
+  2 warnings — see above.
+```
+
+## Usage
+
+|                                         |                                                                                     |
+| --------------------------------------- | ----------------------------------------------------------------------------------- |
+| `npx @apitella/scan <url>`              | Connect (Streamable HTTP, falling back to SSE) and scan. Works against `localhost`. |
+| `npx @apitella/scan --input tools.json` | Scan a saved `tools/list` dump — no running server needed.                          |
+| `-H, --header "X-API-Key: ..."`         | Extra request header. Repeatable.                                                   |
+| `--token <t>`                           | Bearer token shorthand.                                                             |
+| `--baseline [file]`                     | Diff the scan against a committed snapshot (default `.apitella/baseline.json`).     |
+| `--update-baseline`                     | Write the current surface to the baseline file and exit 0.                          |
+| `--json`                                | Machine-readable output (includes the baseline diff when `--baseline` is set).      |
+| `--fail-on <error\|warning>`            | Non-zero exit threshold (default: `warning`). Ignored with `--baseline`.            |
+| `--no-fail`                             | Always exit 0 unless the scan itself failed.                                        |
+
+### Exit codes
+
+| Code | Meaning                                                                  |
+| ---- | ------------------------------------------------------------------------ |
+| `0`  | Clean, below `--fail-on`, no regression vs. `--baseline`, or `--no-fail` |
+| `1`  | Findings at or above `--fail-on`, or a regression vs. `--baseline`       |
+| `2`  | Usage error, or couldn't reach / parse the target                        |
+
+## Baseline: make schema changes show up in code review
+
+Commit a snapshot of your server's surface, then fail a PR only when the change makes
+it **worse** — a tool removed, a tool that lost its `readOnlyHint` / `destructiveHint`,
+or a new error/warning. Pre-existing findings you've decided to live with don't fail
+the build.
+
+```
+# once, checked in:
+npx @apitella/scan http://localhost:3000/mcp --update-baseline
+git add .apitella/baseline.json
+
+# on every PR:
+npx @apitella/scan http://localhost:3000/mcp --baseline
+```
+
+```
+vs. baseline  .apitella/baseline.json
+  − removed  get_user
+  + added    delete_user
+  ! delete_user lost its safety hint — it declared destructiveHint in the baseline and now declares neither.
+  ▲ new      delete_user  [no-safety-hints]
+
+  This change makes the MCP surface worse than the baseline.
+```
+
+When a change is intentional, re-run `--update-baseline` and commit the new snapshot —
+the diff lands in the PR alongside the code.
+
+## In CI
+
+### GitHub Action
+
+```yaml
+# .github/workflows/mcp-scan.yml
+- uses: actions/checkout@v4
+- uses: actions/setup-node@v4
+  with: { node-version: 20 }
+- run: |
+    npm ci && npm run build
+    node dist/server.js &
+    npx --yes wait-on http://localhost:3000/mcp
+- uses: dodogeny/apitella-saas/cli@v1
+  with:
+    url: http://localhost:3000/mcp
+    baseline: .apitella/baseline.json
+```
+
+Action inputs: `url` **or** `input` (a `tools/list` dump), `baseline`, `fail-on`,
+`headers` (newline-separated `Name: value`), `package-version`. A full example is in
+[`examples/mcp-scan.yml`](./examples/mcp-scan.yml).
+
+### Plain npx
+
+```yaml
+- run: npx @apitella/scan --input tools.json --fail-on error
+```
+
+## What it checks
+
+- **`no-safety-hints`** — a tool declares neither `readOnlyHint` nor `destructiveHint`.
+- **`destructive-hint-mismatch`** — the description reads as destructive ("deletes…",
+  "wipes…") but `destructiveHint` isn't `true`.
+- **`readonly-hint-contradicted`** — `readOnlyHint: true` on a tool that takes a
+  `content` / `body` / `payload` / `data` parameter.
+- **`instruction-injection`** — tool or parameter text contains instruction-override
+  phrasing or invisible characters aimed at the model reading it.
+- **`credential-exposed`** — an AWS key, GitHub/Slack token, or private-key block in
+  tool text.
+- **`insecure-transport`** — the server URL is plain `http://`.
+
+The CVE lookup and the LLM-backed semantic injection scan that
+[apitella.com](https://apitella.com) runs are not in this CLI — it stays offline and
+fast. Continuous monitoring of a deployed server (and of servers you depend on) is the
+hosted product.
+
+## What it does not do
+
+It does not send your schema anywhere. Everything runs locally.
+
+## Development
+
+```
+npm install
+npm run build
+npm test
+npm run dev -- http://localhost:3000/mcp   # run from source
+```
+
+The rule logic in `src/analyze.ts` is a port of the transport-free checks in the
+Apitella API (`api/src/lib/scanAnalysis.ts` and the synchronous half of
+`api/src/lib/securityChecks.ts`). The two are kept in sync by hand for now; the tests
+in `test/` lock the CLI's behaviour so a divergence is caught.

package/dist/analyze.js

@@ -0,0 +1,134 @@
+// Narrow, low-false-positive credential shapes — same approach gitleaks/trufflehog take.
+const CREDENTIAL_PATTERNS = [
+    { name: "AWS access key ID", pattern: /\bAKIA[0-9A-Z]{16}\b/ },
+    { name: "GitHub token", pattern: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/ },
+    { name: "Slack token", pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+    {
+        name: "private key block",
+        pattern: /-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----/,
+    },
+];
+// Override / injection phrasing aimed at whatever model reads the description, not at a
+// human skimming a tool list. Clear imperative overrides only — "ignore" alone shows up in
+// plenty of legitimate text ("ignores trailing whitespace").
+const INJECTION_PATTERNS = [
+    /ignore (all |any |previous |prior |the above )+instructions?/i,
+    /disregard (all |any |previous |prior |the above )+instructions?/i,
+    /you (must|should|will) always\b/i,
+    /do not (tell|inform|mention|notify) the user/i,
+    /\bsystem prompt\s*:/i,
+    /\bnew instructions?\s*:/i,
+    // Zero-width / invisible-formatting characters — hides text from a human reviewer while
+    // a model still reads it.
+    /[​‌‍⁠]/,
+];
+const DESTRUCTIVE_VERBS = /\b(delete|deletes|deleted|deleting|remove|removes|removed|removing|drop|drops|dropped|dropping|wipe|wipes|wiped|wiping|purge|purges|purged|purging|destroy|destroys|destroyed|destroying|erase|erases|erased|erasing)\b/i;
+// Exact param-name match — catch a payload param named exactly "content" without
+// false-positiving on "contentType" or "dataSource".
+const WRITE_SHAPED_PARAM_NAMES = new Set([
+    "content",
+    "body",
+    "payload",
+    "data",
+]);
+function scanText(text, operationId, location, findings) {
+    if (!text)
+        return;
+    const where = location ? `Parameter "${location}"` : "Description";
+    for (const { name, pattern } of CREDENTIAL_PATTERNS) {
+        if (pattern.test(text)) {
+            findings.push({
+                severity: "error",
+                rule: "credential-exposed",
+                operation: operationId,
+                message: `${where} contains what looks like a ${name}.`,
+            });
+        }
+    }
+    for (const pattern of INJECTION_PATTERNS) {
+        if (pattern.test(text)) {
+            findings.push({
+                severity: "error",
+                rule: "instruction-injection",
+                operation: operationId,
+                message: `${where} contains text that reads as an instruction override rather than documentation.`,
+            });
+            break;
+        }
+    }
+}
+export function analyze(schema, url) {
+    const findings = [];
+    const toolOps = schema.operations.filter((op) => !op.category);
+    const resourceCount = schema.operations.filter((op) => op.category === "resource").length;
+    const resourceTemplateCount = schema.operations.filter((op) => op.category === "resource_template").length;
+    const promptCount = schema.operations.filter((op) => op.category === "prompt").length;
+    if (url && url.startsWith("http://")) {
+        findings.push({
+            severity: "warning",
+            rule: "insecure-transport",
+            operation: null,
+            message: `${url} is served over plain HTTP, not HTTPS — everything in the exchange crosses the wire readable.`,
+        });
+    }
+    for (const op of schema.operations) {
+        scanText(op.description, op.id, null, findings);
+        for (const param of op.params) {
+            scanText(param.description, op.id, param.name, findings);
+        }
+        // Safety hints are a tool-only concept — resources/prompts carry a category, tools
+        // never do.
+        if (op.category)
+            continue;
+        const readOnlyHint = op.annotations?.readOnlyHint;
+        const destructiveHint = op.annotations?.destructiveHint;
+        if (op.description &&
+            DESTRUCTIVE_VERBS.test(op.description) &&
+            destructiveHint !== true) {
+            findings.push({
+                severity: "warning",
+                rule: "destructive-hint-mismatch",
+                operation: op.id,
+                message: "Description reads as destructive, but destructiveHint isn't set to true — an agent skipping confirmation has no signal this is dangerous.",
+            });
+        }
+        if (readOnlyHint === true) {
+            const writeParam = op.params.find((p) => WRITE_SHAPED_PARAM_NAMES.has(p.name.toLowerCase()));
+            if (writeParam) {
+                findings.push({
+                    severity: "warning",
+                    rule: "readonly-hint-contradicted",
+                    operation: op.id,
+                    message: `Declared readOnlyHint, but takes a "${writeParam.name}" parameter — that's what a write payload looks like, not a read.`,
+                });
+            }
+        }
+        if (readOnlyHint === undefined && destructiveHint === undefined) {
+            findings.push({
+                severity: "warning",
+                rule: "no-safety-hints",
+                operation: op.id,
+                message: "Neither readOnlyHint nor destructiveHint is declared — an agent can't tell whether this is safe to auto-approve.",
+            });
+        }
+    }
+    findings.push({
+        severity: "note",
+        rule: "no-version-signal",
+        operation: null,
+        message: "No changelog or version signal on this server — if any of this changes, nothing tells you unless it's being monitored.",
+    });
+    const counts = {
+        error: findings.filter((f) => f.severity === "error").length,
+        warning: findings.filter((f) => f.severity === "warning").length,
+        note: findings.filter((f) => f.severity === "note").length,
+    };
+    return {
+        toolCount: toolOps.length,
+        resourceCount,
+        resourceTemplateCount,
+        promptCount,
+        findings,
+        counts,
+    };
+}

package/dist/fetch.js

@@ -0,0 +1,162 @@
+import { readFile } from "node:fs/promises";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+const CONNECT_TIMEOUT_MS = 15_000;
+function resolveType(prop) {
+    if (prop.type)
+        return prop.type;
+    const variants = prop.anyOf ?? prop.oneOf;
+    if (variants && variants.length > 0) {
+        return [...new Set(variants.map(resolveType))].join(" | ");
+    }
+    return "unknown";
+}
+function paramsFromInputSchema(inputSchema) {
+    if (!inputSchema || typeof inputSchema !== "object")
+        return [];
+    const schema = inputSchema;
+    const properties = schema.properties ?? {};
+    const required = new Set(schema.required ?? []);
+    return Object.entries(properties).map(([name, prop]) => ({
+        name,
+        required: required.has(name),
+        type: resolveType(prop),
+        enumValues: prop.enum,
+        description: prop.description,
+    }));
+}
+function normalize(input) {
+    const toolOps = input.tools.map((tool) => ({
+        id: tool.name,
+        description: tool.description,
+        params: paramsFromInputSchema(tool.inputSchema),
+        annotations: tool.annotations,
+    }));
+    const resourceOps = (input.resources ?? []).map((r) => ({
+        id: `resource:${r.uri}`,
+        description: r.description,
+        params: [],
+        category: "resource",
+        mimeType: r.mimeType,
+    }));
+    const resourceTemplateOps = (input.resourceTemplates ?? []).map((t) => ({
+        id: `resource_template:${t.uriTemplate}`,
+        description: t.description,
+        params: [],
+        category: "resource_template",
+        mimeType: t.mimeType,
+    }));
+    const promptOps = (input.prompts ?? []).map((p) => ({
+        id: `prompt:${p.name}`,
+        description: p.description,
+        params: (p.arguments ?? []).map((arg) => ({
+            name: arg.name,
+            required: arg.required ?? false,
+            type: "string",
+            description: arg.description,
+        })),
+        category: "prompt",
+    }));
+    return {
+        operations: [
+            ...toolOps,
+            ...resourceOps,
+            ...resourceTemplateOps,
+            ...promptOps,
+        ],
+    };
+}
+async function connectWithTimeout(client, transport) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("Connection timed out")), CONNECT_TIMEOUT_MS);
+    });
+    try {
+        await Promise.race([client.connect(transport), timeout]);
+    }
+    catch (err) {
+        await client.close().catch(() => { });
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// Try Streamable HTTP first, fall back to SSE — same order the MCP SDK docs recommend for
+// the migration period. A fresh Client per attempt.
+async function connect(url, headers) {
+    const requestInit = Object.keys(headers).length > 0 ? { headers } : undefined;
+    try {
+        const client = new Client({ name: "apitella-scan", version: "0.1.0" });
+        await connectWithTimeout(client, new StreamableHTTPClientTransport(new URL(url), { requestInit }));
+        return client;
+    }
+    catch {
+        const client = new Client({ name: "apitella-scan", version: "0.1.0" });
+        await connectWithTimeout(client, new SSEClientTransport(new URL(url), { requestInit }));
+        return client;
+    }
+}
+export async function fetchFromUrl(url, headers) {
+    const client = await connect(url, headers);
+    try {
+        const info = client.getServerVersion();
+        const capabilities = client.getServerCapabilities() ?? {};
+        const [tools, resources, resourceTemplates, prompts] = await Promise.all([
+            client.listTools().then((r) => r.tools),
+            capabilities.resources
+                ? client.listResources().then((r) => r.resources)
+                : Promise.resolve([]),
+            capabilities.resources
+                ? client.listResourceTemplates().then((r) => r.resourceTemplates)
+                : Promise.resolve([]),
+            capabilities.prompts
+                ? client.listPrompts().then((r) => r.prompts)
+                : Promise.resolve([]),
+        ]);
+        return {
+            schema: normalize({
+                tools: tools,
+                resources: resources,
+                resourceTemplates: resourceTemplates,
+                prompts: prompts,
+            }),
+            meta: {
+                serverName: info?.name ?? null,
+                serverVersion: info?.version ?? null,
+            },
+        };
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+// Accepts a saved `tools/list` result, an object with tools/resources/prompts keys, or a
+// bare array of tools — whatever a build step can dump without booting the server.
+export async function fetchFromFile(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`Couldn't read ${path} as JSON: ${err.message}`);
+    }
+    if (Array.isArray(parsed)) {
+        return normalize({ tools: parsed });
+    }
+    if (parsed && typeof parsed === "object") {
+        const obj = parsed;
+        // Unwrap a JSON-RPC envelope ({ jsonrpc, id, result: { tools } }) if that's what got saved.
+        const source = (obj.result && typeof obj.result === "object" ? obj.result : obj);
+        if (Array.isArray(source.tools)) {
+            return normalize({
+                tools: source.tools,
+                resources: source.resources,
+                resourceTemplates: source.resourceTemplates,
+                prompts: source.prompts,
+            });
+        }
+    }
+    throw new Error(`${path} doesn't look like a tools/list dump — expected an array of tools or an object with a "tools" array.`);
+}

package/dist/index.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { analyze } from "./analyze.js";
+import { diffSnapshots, makeSnapshot, readSnapshot, writeSnapshot, } from "./baseline.js";
+import { fetchFromFile, fetchFromUrl } from "./fetch.js";
+import { renderBaselineDiff, renderJson, renderText } from "./report.js";
+const VERSION = "0.1.0";
+const DEFAULT_BASELINE = ".apitella/baseline.json";
+const HELP = `
+apitella-scan — check an MCP server's tool surface for safety-annotation gaps
+                and prompt-injection risks.
+
+USAGE
+  npx @apitella/scan <url> [options]
+  npx @apitella/scan --input tools.json [options]
+
+ARGUMENTS
+  <url>                    MCP server URL (Streamable HTTP or SSE). Works against
+                          localhost — point it at your dev server.
+
+OPTIONS
+  -i, --input <file>      Scan a saved tools/list dump instead of connecting.
+                          Accepts a bare array of tools, a { "tools": [...] }
+                          object, or a JSON-RPC response envelope.
+  -H, --header <h>        Extra request header, "Name: value". Repeatable.
+      --token <t>         Bearer token — shorthand for -H "Authorization: Bearer <t>".
+      --baseline [file]   Compare the scan to a committed snapshot and report what
+                          changed (default file: ${DEFAULT_BASELINE}). Exits non-zero
+                          only on a regression — a removed tool, a tool that lost its
+                          safety hint, or a new error/warning.
+      --update-baseline   Write the current surface to the baseline file and exit 0.
+                          Run this to accept the current state as the new reference.
+      --json              Emit JSON instead of the formatted report.
+      --fail-on <lvl>     Without --baseline: exit non-zero when findings reach this
+                          level, "error" or "warning" (default: warning).
+      --no-fail           Always exit 0 unless the scan itself failed.
+  -h, --help              Show this help.
+  -v, --version           Show version.
+
+EXIT CODES
+  0   clean / below threshold / no regression / --no-fail
+  1   findings at or above --fail-on, or a regression vs. --baseline
+  2   usage error, or couldn't reach / parse the target
+
+Part of Apitella — https://apitella.com/scan
+`;
+class UsageError extends Error {
+}
+function parseHeaders(raw, token) {
+    const headers = {};
+    for (const entry of raw ?? []) {
+        const idx = entry.indexOf(":");
+        if (idx === -1) {
+            throw new UsageError(`Bad --header "${entry}" — expected "Name: value".`);
+        }
+        headers[entry.slice(0, idx).trim()] = entry.slice(idx + 1).trim();
+    }
+    if (token)
+        headers["Authorization"] = `Bearer ${token}`;
+    return headers;
+}
+async function main() {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            allowPositionals: true,
+            options: {
+                input: { type: "string", short: "i" },
+                header: { type: "string", short: "H", multiple: true },
+                token: { type: "string" },
+                baseline: { type: "string" },
+                "update-baseline": { type: "boolean", default: false },
+                json: { type: "boolean", default: false },
+                "fail-on": { type: "string", default: "warning" },
+                "no-fail": { type: "boolean", default: false },
+                help: { type: "boolean", short: "h", default: false },
+                version: { type: "boolean", short: "v", default: false },
+            },
+        });
+    }
+    catch (err) {
+        throw new UsageError(err.message);
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (values.version) {
+        process.stdout.write(`${VERSION}\n`);
+        return 0;
+    }
+    const failOn = values["fail-on"];
+    if (failOn !== "error" && failOn !== "warning") {
+        throw new UsageError(`--fail-on must be "error" or "warning", got "${failOn}".`);
+    }
+    const url = positionals[0];
+    if (!url && !values.input) {
+        throw new UsageError("Pass an MCP server URL or --input <file>. See --help.");
+    }
+    if (url && values.input) {
+        throw new UsageError("Pass a URL or --input, not both.");
+    }
+    // `--baseline` with no value falls through parseArgs as undefined; treat its presence via
+    // the raw argv so `--baseline` alone means "use the default path".
+    const baselineFlagPresent = process.argv.includes("--baseline");
+    const baselinePath = values.baseline ??
+        (baselineFlagPresent || values["update-baseline"]
+            ? DEFAULT_BASELINE
+            : null);
+    const target = values.input ? values.input : url;
+    let meta = null;
+    let schema;
+    if (values.input) {
+        schema = await fetchFromFile(values.input);
+    }
+    else {
+        try {
+            const res = await fetchFromUrl(url, parseHeaders(values.header, values.token));
+            meta = res.meta;
+            schema = res.schema;
+        }
+        catch (err) {
+            throw new UsageError(`Couldn't scan ${url}: ${err.message}`);
+        }
+    }
+    const report = analyze(schema, values.input ? null : url);
+    if (values["update-baseline"]) {
+        const path = baselinePath ?? DEFAULT_BASELINE;
+        await writeSnapshot(path, makeSnapshot(schema, target, report.findings));
+        process.stdout.write(`Baseline written to ${path} — ${report.toolCount} tool${report.toolCount === 1 ? "" : "s"}, ${report.findings.length} finding${report.findings.length === 1 ? "" : "s"} recorded.\n`);
+        return 0;
+    }
+    const diff = baselinePath
+        ? diffSnapshots(await readSnapshot(baselinePath), {
+            schema,
+            findings: report.findings,
+        })
+        : null;
+    if (values.json) {
+        process.stdout.write(`${renderJson(report, target, meta, diff)}\n`);
+    }
+    else {
+        process.stdout.write(renderText(report, target, meta));
+        if (diff && baselinePath) {
+            process.stdout.write(renderBaselineDiff(diff, baselinePath));
+        }
+    }
+    if (values["no-fail"])
+        return 0;
+    if (diff)
+        return diff.regressed ? 1 : 0;
+    const threshold = failOn;
+    const hit = report.counts.error > 0 ||
+        (threshold === "warning" && report.counts.warning > 0);
+    return hit ? 1 : 0;
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    if (err instanceof UsageError) {
+        process.stderr.write(`${err.message}\n`);
+        process.exit(2);
+    }
+    process.stderr.write(`Unexpected error: ${err.stack ?? err}\n`);
+    process.exit(2);
+});

package/dist/report.js

@@ -0,0 +1,126 @@
+// No color dependency — a tiny ANSI helper that no-ops when stdout isn't a TTY or NO_COLOR
+// is set, so CI logs stay clean.
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code, s) => useColor ? `\x1b[${code}m${s}\x1b[0m` : s;
+const c = {
+    bold: (s) => paint("1", s),
+    dim: (s) => paint("2", s),
+    red: (s) => paint("31", s),
+    yellow: (s) => paint("33", s),
+    green: (s) => paint("32", s),
+    cyan: (s) => paint("36", s),
+};
+const MARK = {
+    error: c.red("✖"),
+    warning: c.yellow("▲"),
+    note: c.dim("·"),
+};
+const LABEL = {
+    error: c.red,
+    warning: c.yellow,
+    note: c.dim,
+};
+function countsLine(report) {
+    const parts = [
+        `${report.toolCount} tool${report.toolCount === 1 ? "" : "s"}`,
+    ];
+    if (report.resourceCount) {
+        parts.push(`${report.resourceCount} resource${report.resourceCount === 1 ? "" : "s"}`);
+    }
+    if (report.resourceTemplateCount) {
+        parts.push(`${report.resourceTemplateCount} resource templates`);
+    }
+    if (report.promptCount) {
+        parts.push(`${report.promptCount} prompt${report.promptCount === 1 ? "" : "s"}`);
+    }
+    return parts.join(" · ");
+}
+export function renderText(report, target, meta) {
+    const lines = [];
+    const server = meta?.serverName
+        ? `${meta.serverName}${meta.serverVersion ? ` v${meta.serverVersion}` : ""}`
+        : target;
+    lines.push("");
+    lines.push(`${c.bold("Apitella scan")}  ${c.dim(server)}`);
+    lines.push(c.dim(countsLine(report)));
+    lines.push("");
+    const ordered = [
+        ...report.findings.filter((f) => f.severity === "error"),
+        ...report.findings.filter((f) => f.severity === "warning"),
+        ...report.findings.filter((f) => f.severity === "note"),
+    ];
+    for (const f of ordered) {
+        const scope = f.operation ? c.cyan(f.operation) : c.dim("server");
+        lines.push(`  ${MARK[f.severity]} ${scope}  ${LABEL[f.severity](`[${f.rule}]`)}`);
+        lines.push(`    ${f.message}`);
+    }
+    lines.push("");
+    const { error, warning } = report.counts;
+    if (error === 0 && warning === 0) {
+        lines.push(c.green("  ✔ Nothing flagged — every tool declares a safety hint and nothing contradicts itself."));
+    }
+    else {
+        const bits = [];
+        if (error)
+            bits.push(c.red(`${error} error${error === 1 ? "" : "s"}`));
+        if (warning)
+            bits.push(c.yellow(`${warning} warning${warning === 1 ? "" : "s"}`));
+        lines.push(`  ${bits.join(", ")} — see above.`);
+        lines.push(c.dim("  These are point-in-time. To catch changes like these after you ship, monitor the server free at apitella.com."));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+export function renderBaselineDiff(diff, baselinePath) {
+    const lines = [];
+    lines.push(`${c.bold("vs. baseline")}  ${c.dim(baselinePath)}`);
+    const nothing = diff.addedOps.length === 0 &&
+        diff.removedOps.length === 0 &&
+        diff.lostSafetyHint.length === 0 &&
+        diff.newFindings.length === 0 &&
+        diff.resolvedFindings.length === 0;
+    if (nothing) {
+        lines.push(c.green("  ✔ No change to the surface since the baseline."));
+        lines.push("");
+        return lines.join("\n");
+    }
+    for (const id of diff.removedOps) {
+        lines.push(`  ${c.red("−")} removed  ${c.cyan(id)}`);
+    }
+    for (const id of diff.addedOps) {
+        lines.push(`  ${c.green("+")} added    ${c.cyan(id)}`);
+    }
+    for (const id of diff.lostSafetyHint) {
+        lines.push(`  ${c.red("!")} ${c.cyan(id)} lost its safety hint — it declared readOnlyHint/destructiveHint in the baseline and now declares neither.`);
+    }
+    for (const f of diff.newFindings) {
+        const scope = f.operation ? c.cyan(f.operation) : c.dim("server");
+        lines.push(`  ${MARK[f.severity]} new      ${scope}  ${LABEL[f.severity](`[${f.rule}]`)}`);
+        lines.push(`    ${f.message}`);
+    }
+    for (const f of diff.resolvedFindings) {
+        const scope = f.operation ? c.cyan(f.operation) : c.dim("server");
+        lines.push(`  ${c.green("✓")} resolved ${scope}  ${c.dim(`[${f.rule}]`)}`);
+    }
+    lines.push("");
+    lines.push(diff.regressed
+        ? c.red("  This change makes the MCP surface worse than the baseline.")
+        : c.dim("  No regressions — update the baseline to accept these changes (--update-baseline)."));
+    lines.push("");
+    return lines.join("\n");
+}
+export function renderJson(report, target, meta, diff) {
+    return JSON.stringify({
+        target,
+        server: meta ?? null,
+        summary: {
+            toolCount: report.toolCount,
+            resourceCount: report.resourceCount,
+            resourceTemplateCount: report.resourceTemplateCount,
+            promptCount: report.promptCount,
+            ...report.counts,
+        },
+        findings: report.findings,
+        baseline: diff ?? null,
+    }, null, 2);
+}

package/dist/schema-types.js

@@ -0,0 +1,4 @@
+// Vendored, verbatim, from api/src/lib/schema-types.ts. The normalized shape the MCP
+// fetcher produces so the analysis only has to know one schema shape. Keep in sync with
+// the API copy until a shared package exists.
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@apitella/scan",
+  "version": "0.1.0",
+  "description": "Check an MCP server's tool surface for safety-annotation gaps and prompt-injection risks — at build time, in CI, or against a live URL.",
+  "type": "module",
+  "bin": {
+    "apitella-scan": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "test": "node --test --import tsx test/analyze.test.ts test/baseline.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "security",
+    "linter",
+    "ci",
+    "agents",
+    "llm"
+  ],
+  "license": "MIT",
+  "homepage": "https://apitella.com/scan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dodogeny/apitella-saas.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/dodogeny/apitella-saas/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}