@unfragile/mcp-server 0.5.0 → 0.6.0

package/README.md

@@ -57,8 +57,30 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 }
 ```
 
+## Verify before you install (CLI guard)
+
+Don't add an MCP server blind. Verify it first — identity, known security incidents, data-access risk, and cross-vendor reputation, in one signed verdict:
+
+```bash
+# Check a target before installing
+npx -y @unfragile/mcp-server verify mcp:@modelcontextprotocol/server-postgres
+
+# Guard a real install — runs the command only if the target isn't FLAGGED
+npx -y @unfragile/mcp-server guard -- claude mcp add pg -- npx -y @scope/pg-mcp
+```
+
+The `guard` wrapper extracts the install target from your `claude mcp add` / `cursor mcp add` / `npx` command, verifies it, and **blocks on a `flagged` verdict** (known-bad package, exfiltration, typosquat) unless you pass `--force`. Every verdict is Ed25519-signed and audit-logged — defensible evidence for compliance (EU AI Act Annex III logging/oversight).
+
+Verdicts: `trusted` · `caution` · `unverified` · `flagged`.
+
 ## Tools
 
+### Verify (the trust resolver)
+
+| Tool | Description |
+|------|-------------|
+| `unfragile_verify` | **Call BEFORE invoking or installing any tool/MCP server.** Returns a signed verdict (`trusted`/`caution`/`unverified`/`flagged`) from identity + typosquat checks, the MCP CVE/incident registry, structural data-access risk, and cross-vendor match-graph reputation. Do not invoke anything that comes back `flagged`. |
+
 ### Resolve (the headline call)
 
 | Tool | Description |

package/dist/guard.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/guard.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// ─────────────────────────────────────────────────────────────
+// `unfragile` — verify-before-invoke CLI guard.
+//
+// The viral dev hook: verify an MCP server / package BEFORE you install it.
+//
+//   npx -y @unfragile/mcp-server verify mcp:@scope/server
+//   npx -y @unfragile/mcp-server guard -- claude mcp add pg -- npx -y @scope/pg-mcp
+//
+// `verify <target>`  → prints the signed verdict; exit 1 if flagged.
+// `guard -- <cmd…>`  → extracts the install target from a `claude mcp add`
+//                      (or any `npx …`) command, verifies it, BLOCKS on
+//                      `flagged` (unless --force), then runs the real command.
+// ─────────────────────────────────────────────────────────────
+import { spawn } from "node:child_process";
+const API_BASE = process.env.UNFRAGILE_API_URL || "https://unfragile.ai";
+const API_KEY = process.env.UNFRAGILE_API_KEY || "";
+const C = {
+    reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m",
+    green: "\x1b[32m", yellow: "\x1b[33m", red: "\x1b[31m", gray: "\x1b[90m",
+};
+const isTTY = process.stdout.isTTY;
+const paint = (s, ...codes) => (isTTY ? codes.join("") + s + C.reset : s);
+/** Pull the most likely install target out of a wrapped command's args. */
+function extractTarget(args) {
+    const joined = args.join(" ");
+    // npx [-y] <pkg>   (the common MCP-add shape)
+    const npx = joined.match(/npx\s+(?:-y\s+|--yes\s+)?(@?[\w./-]+)/);
+    if (npx)
+        return `npm:${npx[1]}`;
+    // uvx / pipx <pkg>
+    const uvx = joined.match(/\b(?:uvx|pipx run)\s+(@?[\w./-]+)/);
+    if (uvx)
+        return `pypi:${uvx[1]}`;
+    // an explicit prefixed ref or URL anywhere in the args
+    const ref = args.find((a) => /^(mcp|npm|pypi|github|gh):/.test(a) || /^https?:\/\//.test(a));
+    if (ref)
+        return ref;
+    return null;
+}
+async function callVerify(target, intent, action) {
+    const res = await fetch(`${API_BASE}/api/v1/verify`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...(API_KEY ? { "X-API-Key": API_KEY } : {}) },
+        body: JSON.stringify({ target, intent, action }),
+        signal: AbortSignal.timeout(15000),
+    });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    return (await res.json());
+}
+function printVerdict(target, v) {
+    const verdict = (v.verdict || "unverified");
+    const badge = verdict === "trusted" ? paint(" TRUSTED ", C.bold, C.green)
+        : verdict === "caution" ? paint(" CAUTION ", C.bold, C.yellow)
+            : verdict === "flagged" ? paint(" FLAGGED ", C.bold, C.red)
+                : paint(" UNVERIFIED ", C.bold, C.gray);
+    console.error("");
+    console.error(`  ${badge}  ${paint(target, C.bold)}`);
+    if (v.summary)
+        console.error(`  ${paint(v.summary, C.dim)}`);
+    const s = v.safety || {};
+    if (s.score != null)
+        console.error(`  ${paint("safety", C.gray)}  ${s.score}/100 · ${s.dataAccessRisk || "?"} data-access risk`);
+    if (s.flags?.length)
+        console.error(`  ${paint("flags", C.gray)}   ${paint(s.flags.join(", "), C.yellow)}`);
+    const id = v.identity || {};
+    if (id.typosquatRisk)
+        console.error(`  ${paint("⚠ resembles '" + id.typosquatRisk + "' — possible typosquat", C.yellow)}`);
+    const r = v.reputation || {};
+    if (r.timesInvoked)
+        console.error(`  ${paint("rep", C.gray)}     ${r.timesInvoked} invocations${r.successRate != null ? `, ${Math.round(r.successRate * 100)}% success` : ""} · rank ${r.unfragileRank ?? 0}/100`);
+    if (v.signature)
+        console.error(`  ${paint("signed by " + (v.signedBy || "unfragile.ai") + " (Ed25519)", C.gray)}`);
+    if (v.compliance?.evidenceUrl)
+        console.error(`  ${paint("audit  " + v.compliance.evidenceUrl, C.gray)}`);
+    console.error("");
+    return verdict;
+}
+function help() {
+    console.error(`unfragile — verify-before-invoke guard
+
+USAGE
+  unfragile verify <target> [--intent "..."] [--action read|write|execute]
+  unfragile guard [--force] -- <command...>
+
+EXAMPLES
+  unfragile verify mcp:@modelcontextprotocol/server-postgres
+  unfragile verify npm:postmark-mcp
+  unfragile guard -- claude mcp add pg -- npx -y @scope/pg-mcp
+  unfragile guard -- cursor mcp add ...
+
+BEHAVIOR
+  Prints a signed verdict (trusted | caution | unverified | flagged).
+  'guard' runs your command only if the target is not FLAGGED.
+  Use --force to override a flagged target (logged). Exit 1 on flagged/block.
+
+ENV
+  UNFRAGILE_API_URL  (default https://unfragile.ai)
+  UNFRAGILE_API_KEY  (optional — higher rate limits)`);
+}
+function getFlag(args, name) {
+    const i = args.indexOf(name);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const cmd = argv[0];
+    if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
+        help();
+        process.exit(cmd ? 0 : 1);
+    }
+    if (cmd === "verify") {
+        const target = argv[1];
+        if (!target || target.startsWith("-")) {
+            console.error("error: `unfragile verify <target>` requires a target.");
+            process.exit(1);
+        }
+        const intent = getFlag(argv, "--intent");
+        const action = getFlag(argv, "--action");
+        try {
+            const v = await callVerify(target, intent, action);
+            const verdict = printVerdict(target, v);
+            process.exit(verdict === "flagged" ? 1 : 0);
+        }
+        catch (err) {
+            console.error(paint(`  verify unavailable (${err instanceof Error ? err.message : String(err)}) — treat as UNVERIFIED.`, C.yellow));
+            process.exit(2);
+        }
+    }
+    if (cmd === "guard") {
+        const force = argv.includes("--force");
+        const sep = argv.indexOf("--");
+        if (sep < 0 || sep + 1 >= argv.length) {
+            console.error("error: `unfragile guard -- <command...>` requires a command after `--`.");
+            process.exit(1);
+        }
+        const wrapped = argv.slice(sep + 1);
+        const target = extractTarget(wrapped);
+        if (!target) {
+            console.error(paint("  no install target detected in command — running unguarded.", C.gray));
+        }
+        else {
+            try {
+                const v = await callVerify(target, undefined, "execute");
+                const verdict = printVerdict(target, v);
+                if (verdict === "flagged" && !force) {
+                    console.error(paint("  ✗ BLOCKED — this target is flagged. Re-run with --force to override (logged).", C.bold + C.red));
+                    process.exit(1);
+                }
+                if (verdict === "flagged" && force) {
+                    console.error(paint("  ⚠ proceeding despite FLAGGED verdict (--force).", C.yellow));
+                }
+            }
+            catch (err) {
+                console.error(paint(`  verify unavailable (${err instanceof Error ? err.message : String(err)}) — proceeding unguarded.`, C.yellow));
+            }
+        }
+        // Pass through to the real command.
+        const child = spawn(wrapped[0], wrapped.slice(1), { stdio: "inherit", shell: false });
+        child.on("exit", (code) => process.exit(code ?? 0));
+        child.on("error", (e) => {
+            console.error(`error running command: ${e.message}`);
+            process.exit(1);
+        });
+        return;
+    }
+    console.error(`unknown command '${cmd}'.\n`);
+    help();
+    process.exit(1);
+}
+main();

package/dist/index.js

@@ -489,6 +489,56 @@ server.tool("trust_passport", "Get the machine-readable trust passport for an AI
         return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
     }
 });
+// Tool 5b: Verify-before-invoke — the trust resolver
+server.tool("unfragile_verify", "Verify a tool / MCP server / package BEFORE invoking or installing it. Returns a signed verdict: trusted | caution | unverified | flagged. Pass the install target (e.g. 'mcp:@scope/server', 'npm:pkg', a GitHub/URL, or an `npx ...` command). Checks identity + typosquats, known security incidents/CVEs, data-access risk, and cross-vendor reputation. ALWAYS call this before adding an MCP server or running an unfamiliar tool; do NOT invoke anything that comes back 'flagged'.", {
+    target: z.string().min(1).max(500).describe("What you're about to invoke/install: 'mcp:@scope/server', 'npm:pkg', 'pypi:pkg', 'github:owner/repo', an https URL, an `npx -y @scope/pkg` command, or a bare slug."),
+    intent: z.string().max(300).optional().describe("What you want to do with it (e.g. 'query postgres read-only') — enables fit scoring."),
+    action: z.enum(["read", "write", "execute"]).optional().describe("The kind of access you intend to grant — raises the risk bar for write/execute."),
+}, async ({ target, intent, action }) => {
+    log("unfragile_verify", target);
+    try {
+        const res = await fetch(`${API_BASE}/api/v1/verify`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...(API_KEY ? { "X-API-Key": API_KEY } : {}),
+            },
+            body: JSON.stringify({ target, intent, action }),
+            signal: AbortSignal.timeout(15000),
+        });
+        if (!res.ok) {
+            return { content: [{ type: "text", text: `Verify failed (HTTP ${res.status}). Treat '${target}' as UNVERIFIED — do not invoke without manual review.` }], isError: true };
+        }
+        const v = await res.json();
+        const icon = v.verdict === "trusted" ? "✅" : v.verdict === "caution" ? "⚠️" : v.verdict === "flagged" ? "🛑" : "❓";
+        const lines = [];
+        lines.push(`${icon} VERDICT: ${String(v.verdict || "unverified").toUpperCase()}`);
+        lines.push(v.summary || "");
+        const id = v.identity || {};
+        lines.push(`\nIdentity: ${id.matched ? `matched → ${id.canonical}` : "not found in graph"}${id.verifiedBuilder ? " (verified builder)" : ""}${id.typosquatRisk ? ` ⚠️ resembles '${id.typosquatRisk}' — possible typosquat` : ""}`);
+        const s = v.safety || {};
+        lines.push(`Safety: ${s.score ?? "?"}/100 · ${s.dataAccessRisk || "?"} data-access risk · permissions: ${(s.permissions || []).join(", ") || "unknown"}`);
+        if (s.flags && s.flags.length)
+            lines.push(`Flags: ${s.flags.join(", ")}`);
+        const r = v.reputation || {};
+        if (r.timesInvoked)
+            lines.push(`Reputation: ${r.timesInvoked} invocations${r.successRate != null ? `, ${Math.round(r.successRate * 100)}% success` : " (no rated history yet)"} · rank ${r.unfragileRank ?? 0}/100`);
+        if (v.verdict === "flagged")
+            lines.push(`\n🛑 DO NOT INVOKE. ${s.flags?.includes("known-exfiltration") ? "Known data-exfiltration incident." : "Known security issue."} Verify the publisher and pin a known-good version first.`);
+        else if (v.verdict === "unverified")
+            lines.push(`\n❓ Not attested by Unfragile. No identity/outcome history. Proceed only with manual review.`);
+        else if (v.verdict === "caution")
+            lines.push(`\n⚠️ Usable but unproven or write/exec-capable. Review permissions before granting access.`);
+        if (v.signature)
+            lines.push(`\nSigned by ${v.signedBy || "unfragile.ai"} (Ed25519, offline-verifiable). Verify key: ${v._links?.verify_key || `${API_BASE}/api/v1/trust-passport-public-key`}`);
+        if (v.compliance?.evidenceUrl)
+            lines.push(`Audit evidence: ${v.compliance.evidenceUrl}`);
+        return { content: [{ type: "text", text: lines.filter(Boolean).join("\n") }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Verify error: ${err instanceof Error ? err.message : String(err)}. Treat '${target}' as UNVERIFIED — do not invoke without manual review.` }], isError: true };
+    }
+});
 // Tool 6: Compare artifacts
 server.tool("compare", "Compare two AI artifacts side-by-side. Shows capabilities, pricing, rank, and graph signals for each. Uses search-based lookup (best-effort name matching). Use this when deciding between alternatives.", {
     artifact_a: z.string().min(1).max(200).describe("First artifact name (e.g., 'cursor')"),
@@ -622,7 +672,10 @@ server.tool("feedback", "Report whether a recommended tool worked or not. This c
             headers["X-API-Key"] = API_KEY;
         const body = {
             matchRecordId,
-            outcome: outcome === "success" ? "success" : "failure",
+            // Canonical outcome values are "success" | "fail" (see MatchOutcome in
+            // the schema). The tool exposes "failure" to agents for clarity, but we
+            // MUST send "fail" — otherwise the route can't lower successRate.
+            outcome: outcome === "success" ? "success" : "fail",
             clickedThrough: true,
             source: SOURCE,
         };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@unfragile/mcp-server",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "mcpName": "io.github.Savirinc/unfragile",
-  "description": "Unfragile MCP Server — agent-native discovery, trust, and routing for AI artifacts. Implements the Unfragile Capability Protocol v1.",
+  "description": "Unfragile MCP Server — verify-before-invoke trust resolver + agent-native discovery and routing for AI artifacts. Implements the Unfragile Capability Protocol v1.",
   "keywords": [
     "mcp",
     "ai",
@@ -26,13 +26,14 @@
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "unfragile-mcp": "dist/index.js"
+    "unfragile-mcp": "dist/index.js",
+    "unfragile": "dist/guard.js"
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsc && chmod +x dist/index.js",
+    "build": "tsc && chmod +x dist/index.js dist/guard.js",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "prepublishOnly": "npm run build"