@mcp-guardian/cli 4.1.2

package/dist/tui/data-fetcher.d.ts

@@ -0,0 +1,144 @@
+export interface TuiData {
+    overview: OverviewData;
+    security: SecurityData;
+    cost: CostData;
+    health: HealthData;
+    ai: AiData;
+    audit: AuditData;
+    policy: PolicyData;
+    instances: InstanceData[];
+}
+export interface OverviewData {
+    totalInstances: number;
+    activeInstances: number;
+    totalRequests: number;
+    blockedRequests: number;
+    passRate: number;
+    totalCostUsd: number;
+    burnRatePerHour: number;
+    avgLatencyMs: number;
+    activeServers: number;
+    lastUpdated: string;
+}
+export interface SecurityData {
+    servers: {
+        name: string;
+        score: number;
+        cves: number;
+        critical: number;
+        auth: boolean;
+    }[];
+    overallScore: number;
+    worstOffenders: string[];
+    activeThreats: number;
+    lastScan: string;
+}
+export interface CostData {
+    servers: {
+        name: string;
+        tokens: number;
+        cost: number;
+        trend: string;
+    }[];
+    totalCost: number;
+    projectedMonthly: number;
+    budgetAlerts: string[];
+    pricingModel: string;
+}
+export interface HealthData {
+    servers: {
+        name: string;
+        latency: number;
+        successRate: number;
+        tools: number;
+        circuitBreaker: string;
+    }[];
+    atRisk: string[];
+    avgLatency: number;
+    totalTools: number;
+}
+export interface AiData {
+    suggestions: any[];
+    baselines: any[];
+    learningState: {
+        adaptiveThreshold: number;
+        truePositiveRate: number;
+        falsePositiveRate: number;
+        moduleWeights: Record<string, number>;
+    };
+    threats: any[];
+    report: any;
+}
+export interface AuditData {
+    events: any[];
+    total: number;
+    blocked: number;
+    passed: number;
+    flagged: number;
+}
+export interface PolicyData {
+    mode: string;
+    activeRules: number;
+    autoGeneratedRules: string[];
+    rules: any[];
+}
+export interface InstanceData {
+    instanceId: string;
+    instanceName: string;
+    status: string;
+    hostname: string;
+    version: string;
+    lastHeartbeat: string;
+    totalRequests: number;
+    blockedRequests: number;
+    totalCostUsd: number;
+    avgLatencyMs: number;
+}
+export declare class DataFetcher {
+    private dashboardUrl;
+    private ws;
+    private wsUrl;
+    private cache;
+    private listeners;
+    private wsConnected;
+    private reconnectTimer;
+    constructor(dashboardUrl?: string);
+    /** Get current cached data */
+    getData(): TuiData | null;
+    /** Subscribe to data updates */
+    onChange(callback: () => void): () => void;
+    /** Notify all listeners */
+    private notify;
+    /** Connect WebSocket for real-time updates */
+    connectWebSocket(): void;
+    /** Fall back to HTTP polling when WebSocket is unavailable */
+    private fallbackToHttp;
+    /** Schedule WebSocket reconnection */
+    private scheduleReconnect;
+    /** Handle incoming WebSocket messages */
+    private handleWsMessage;
+    /** Fetch all data from HTTP API */
+    fetchAll(): Promise<TuiData>;
+    /** Fetch JSON from an API endpoint */
+    private fetchJson;
+    /** Start periodic HTTP polling fallback */
+    startPolling(intervalMs?: number): ReturnType<typeof setInterval>;
+    /** Parse overview data */
+    private parseOverview;
+    /** Parse security data */
+    private parseSecurity;
+    /** Parse cost data */
+    private parseCost;
+    /** Parse health data */
+    private parseHealth;
+    /** Parse AI data */
+    private parseAi;
+    /** Parse audit data */
+    private parseAudit;
+    /** Parse policy data */
+    private parsePolicy;
+    /** Parse instances data */
+    private parseInstances;
+    /** Stop and clean up */
+    stop(): void;
+}

package/dist/tui/data-fetcher.js

@@ -0,0 +1,268 @@
+export class DataFetcher {
+    dashboardUrl;
+    ws = null;
+    wsUrl;
+    cache = null;
+    listeners = new Set();
+    wsConnected = false;
+    reconnectTimer = null;
+    constructor(dashboardUrl) {
+        this.dashboardUrl = (dashboardUrl || process.env['GUARDIAN_DASHBOARD_URL'] || 'http://localhost:4000').replace(/\/$/, '');
+        this.wsUrl = this.dashboardUrl.replace(/^http/, 'ws') + '/ws';
+    }
+    /** Get current cached data */
+    getData() {
+        return this.cache;
+    }
+    /** Subscribe to data updates */
+    onChange(callback) {
+        this.listeners.add(callback);
+        return () => this.listeners.delete(callback);
+    }
+    /** Notify all listeners */
+    notify() {
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch { /* ignore listener errors */ }
+        }
+    }
+    /** Connect WebSocket for real-time updates */
+    connectWebSocket() {
+        try {
+            // Using global WebSocket available in Node 22+
+            const WS = globalThis.WebSocket;
+            if (!WS) {
+                this.fallbackToHttp();
+                return;
+            }
+            this.ws = new WS(this.wsUrl);
+            this.ws.onopen = () => {
+                this.wsConnected = true;
+                // Subscribe to all channels
+                if (this.ws?.readyState === 1) {
+                    this.ws.send(JSON.stringify({
+                        type: 'subscribe',
+                        channels: ['ai', 'audit', 'metrics', 'logs', 'instances', 'policy', 'health', 'cost'],
+                    }));
+                }
+            };
+            this.ws.onmessage = (event) => {
+                try {
+                    const msg = JSON.parse(event.data.toString());
+                    this.handleWsMessage(msg);
+                }
+                catch { /* ignore parse errors */ }
+            };
+            this.ws.onclose = () => {
+                this.wsConnected = false;
+                this.scheduleReconnect();
+            };
+            this.ws.onerror = () => {
+                this.wsConnected = false;
+                this.fallbackToHttp();
+            };
+        }
+        catch {
+            this.fallbackToHttp();
+        }
+    }
+    /** Fall back to HTTP polling when WebSocket is unavailable */
+    fallbackToHttp() {
+        this.fetchAll().catch(() => {
+            // Will retry on next poll interval
+        });
+    }
+    /** Schedule WebSocket reconnection */
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connectWebSocket();
+        }, 5000);
+    }
+    /** Handle incoming WebSocket messages */
+    handleWsMessage(msg) {
+        const cache = this.cache;
+        if (!cache)
+            return;
+        switch (msg.type) {
+            case 'ai:suggestions':
+                cache.ai.suggestions = msg.payload?.suggestions || [];
+                break;
+            case 'ai:baselines':
+                cache.ai.baselines = msg.payload?.baselines || [];
+                break;
+            case 'ai:state':
+                cache.ai.learningState = msg.payload?.state || cache.ai.learningState;
+                break;
+            case 'ai:threats':
+                cache.ai.threats = msg.payload?.threats || [];
+                break;
+            case 'ai:report':
+                cache.ai.report = msg.payload?.report || null;
+                break;
+            case 'audit:events':
+                if (msg.payload?.events) {
+                    cache.audit.events = msg.payload.events;
+                }
+                break;
+            case 'metrics:live':
+                if (msg.payload?.instances) {
+                    cache.instances = msg.payload.instances;
+                }
+                break;
+        }
+        this.notify();
+    }
+    /** Fetch all data from HTTP API */
+    async fetchAll() {
+        const [overview, security, cost, health, ai, audit, policy, instances] = await Promise.allSettled([
+            this.fetchJson('/api/aggregate/metrics'),
+            this.fetchJson('/api/security'),
+            this.fetchJson('/api/cost'),
+            this.fetchJson('/api/health'),
+            this.fetchJson('/api/ai/report'),
+            this.fetchJson('/api/aggregate/audit'),
+            this.fetchJson('/api/policy'),
+            this.fetchJson('/api/instances'),
+        ]);
+        this.cache = {
+            overview: this.parseOverview(overview.status === 'fulfilled' ? overview.value : null),
+            security: this.parseSecurity(security.status === 'fulfilled' ? security.value : null),
+            cost: this.parseCost(cost.status === 'fulfilled' ? cost.value : null),
+            health: this.parseHealth(health.status === 'fulfilled' ? health.value : null),
+            ai: this.parseAi(ai.status === 'fulfilled' ? ai.value : null),
+            audit: this.parseAudit(audit.status === 'fulfilled' ? audit.value : null),
+            policy: this.parsePolicy(policy.status === 'fulfilled' ? policy.value : null),
+            instances: this.parseInstances(instances.status === 'fulfilled' ? instances.value : null),
+        };
+        this.notify();
+        return this.cache;
+    }
+    /** Fetch JSON from an API endpoint */
+    async fetchJson(path) {
+        try {
+            const response = await fetch(`${this.dashboardUrl}${path}`, {
+                signal: AbortSignal.timeout(5000),
+            });
+            if (!response.ok)
+                return null;
+            return response.json();
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Start periodic HTTP polling fallback */
+    startPolling(intervalMs = 3000) {
+        return setInterval(() => {
+            this.fetchAll().catch(() => { });
+        }, intervalMs);
+    }
+    /** Parse overview data */
+    parseOverview(data) {
+        return {
+            totalInstances: data?.totalInstances || 0,
+            activeInstances: data?.activeInstances || 0,
+            totalRequests: data?.totalRequests || 0,
+            blockedRequests: data?.blockedRequests || 0,
+            passRate: data?.totalRequests > 0 ? ((data.passedRequests || 0) / data.totalRequests) * 100 : 100,
+            totalCostUsd: data?.totalCost || 0,
+            burnRatePerHour: data?.burnRatePerHour || 0,
+            avgLatencyMs: data?.avgLatencyMs || 0,
+            activeServers: data?.activeServers || 0,
+            lastUpdated: data?.lastUpdated || new Date().toISOString(),
+        };
+    }
+    /** Parse security data */
+    parseSecurity(data) {
+        return {
+            servers: data?.serverReports || [],
+            overallScore: data?.overallScore || 0,
+            worstOffenders: data?.worstOffenders || [],
+            activeThreats: data?.activeThreats || 0,
+            lastScan: data?.lastScan || 'N/A',
+        };
+    }
+    /** Parse cost data */
+    parseCost(data) {
+        return {
+            servers: data?.serverReports || [],
+            totalCost: data?.totalCost || 0,
+            projectedMonthly: data?.projectedMonthly || 0,
+            budgetAlerts: data?.budgetAlerts || [],
+            pricingModel: data?.pricingModel || 'unknown',
+        };
+    }
+    /** Parse health data */
+    parseHealth(data) {
+        return {
+            servers: data?.serverReports || [],
+            atRisk: data?.atRisk || [],
+            avgLatency: data?.avgLatency || 0,
+            totalTools: data?.totalTools || 0,
+        };
+    }
+    /** Parse AI data */
+    parseAi(data) {
+        return {
+            suggestions: data?.suggestions || [],
+            baselines: data?.baselines || [],
+            learningState: data?.learningState || { adaptiveThreshold: 0.85, truePositiveRate: 0, falsePositiveRate: 0, moduleWeights: {} },
+            threats: data?.threats || [],
+            report: data?.report || null,
+        };
+    }
+    /** Parse audit data */
+    parseAudit(data) {
+        return {
+            events: data?.events || [],
+            total: data?.total || 0,
+            blocked: data?.blocked || 0,
+            passed: data?.passed || 0,
+            flagged: data?.flagged || 0,
+        };
+    }
+    /** Parse policy data */
+    parsePolicy(data) {
+        return {
+            mode: data?.mode || 'none',
+            activeRules: data?.activeRules || 0,
+            autoGeneratedRules: data?.autoGeneratedRules || [],
+            rules: data?.rules || [],
+        };
+    }
+    /** Parse instances data */
+    parseInstances(data) {
+        if (Array.isArray(data)) {
+            return data.map((inst) => ({
+                instanceId: inst.instance_id || inst.instanceId || 'unknown',
+                instanceName: inst.instance_name || inst.instanceName || 'unknown',
+                status: inst.status || 'unknown',
+                hostname: inst.hostname || inst.host_name || 'unknown',
+                version: inst.version || 'unknown',
+                lastHeartbeat: inst.last_heartbeat || inst.lastHeartbeat || 'N/A',
+                totalRequests: inst.total_requests || inst.totalRequests || 0,
+                blockedRequests: inst.blocked_requests || inst.blockedRequests || 0,
+                totalCostUsd: inst.total_cost_usd || inst.totalCostUsd || 0,
+                avgLatencyMs: inst.avg_latency_ms || inst.avgLatencyMs || 0,
+            }));
+        }
+        return [];
+    }
+    /** Stop and clean up */
+    stop() {
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.listeners.clear();
+    }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@mcp-guardian/cli",
+  "version": "4.1.2",
+  "description": "CLI binary for scanning MCP tool definitions",
+  "type": "module",
+  "bin": {
+    "mcp-guardian": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "dependencies": {
+    "@mcp-guardian/core": "^4.1.2",
+    "@mcp-guardian/server": "^4.1.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^3.2.4",
+    "@types/node": "^20.0.0"
+  },
+  "license": "MIT"
+}

package/package.json.prepack-backup

@@ -0,0 +1,28 @@
+{
+  "name": "@mcp-guardian/cli",
+  "version": "4.1.2",
+  "description": "CLI binary for scanning MCP tool definitions",
+  "type": "module",
+  "bin": {
+    "mcp-guardian": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "pnpm --dir ../server run build && tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepack": "node ../../scripts/prepack-npm-deps.mjs",
+    "postpack": "node ../../scripts/postpack-npm-deps.mjs",
+    "prepublishOnly": "pnpm run build && node ../../scripts/validate-npm-pack.mjs"
+  },
+  "dependencies": {
+    "@mcp-guardian/core": "workspace:^4.1.2",
+    "@mcp-guardian/server": "workspace:^4.1.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^3.2.4",
+    "@types/node": "^20.0.0"
+  },
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { scanServer, verifyToolDefinitions } from "@mcp-guardian/core";
+import { fetchToolsFromStdio } from "@mcp-guardian/core";
+import { fetchToolsFromHttp, fetchToolsFromSse } from "@mcp-guardian/core";
+import type { ServerScanResult, ToolScanResult } from "@mcp-guardian/core";
+
+interface ClaudeDesktopConfig {
+  mcpServers?: Record<string, {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    transport?: string;
+  }>;
+}
+
+const { values: flags, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    json: { type: "boolean", default: false },
+    "fail-on-critical": { type: "boolean", default: false },
+    "fail-on-warning": { type: "boolean", default: false },
+    "skip-semantic": { type: "boolean", default: false },
+    "skip-pinning": { type: "boolean", default: false },
+    verbose: { type: "boolean", short: "v", default: false },
+    url: { type: "string" },
+    transport: { type: "string" },
+    server: { type: "string" },
+    mcp: { type: "boolean", default: false },
+  },
+  allowPositionals: true,
+});
+
+async function resolveConfigPath(): Promise<string> {
+  if (positionals[0]) return positionals[0];
+  const candidates = [
+    join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json"),
+    join(homedir(), ".config", "Claude", "claude_desktop_config.json"),
+    join(process.env.APPDATA ?? "", "Claude", "claude_desktop_config.json"),
+  ];
+  return candidates.find(existsSync) ?? candidates[0];
+}
+
+function printReport(results: ServerScanResult[], verbose: boolean): void {
+  for (const server of results) {
+    const icon = server.status === "critical" ? "[CRIT]" :
+      server.status === "warning" ? "[WARN]" : "[OK]";
+
+    console.log(`\n${icon}  ${server.serverName} [${server.transport}]`);
+    console.log(`   ${server.summary.total} tools | ${server.summary.critical} critical | ${server.summary.warnings} warnings | ${server.summary.clean} clean`);
+
+    for (const tool of server.tools) {
+      if (tool.status === "clean" && !verbose) continue;
+      const toolIcon = tool.status === "critical" ? "  [CRIT]" : "  [WARN]";
+      console.log(`${toolIcon} ${tool.toolName}`);
+      for (const issue of tool.issues) {
+        if (issue.severity === "info") continue;
+        console.log(`       [${issue.id}] ${issue.message}`);
+        if (verbose && issue.evidence) console.log(`       evidence: "${issue.evidence}"`);
+        if (verbose && issue.confidence < 1.0) console.log(`       confidence: ${(issue.confidence * 100).toFixed(0)}%`);
+      }
+    }
+  }
+}
+
+async function main() {
+  if (flags.mcp) {
+    const { startMcpServer } = await import("@mcp-guardian/server");
+    await startMcpServer();
+    return;
+  }
+
+  const results: ServerScanResult[] = [];
+
+  // Single URL mode
+  if (flags.url) {
+    const transport = (flags.transport ?? "http") as "stdio" | "http" | "sse";
+    const fetchFn = transport === "sse" ? fetchToolsFromSse : fetchToolsFromHttp;
+    const tools = await fetchFn({ url: flags.url });
+    const scanResult = await scanServer(flags.url, tools, transport, { skipSemantic: flags["skip-semantic"] });
+
+    if (!flags["skip-pinning"]) {
+      const pinResult = verifyToolDefinitions(tools, flags.url);
+      if (pinResult.status === "changed" || pinResult.status === "tampered") {
+        scanResult.status = "critical";
+      }
+    }
+    results.push(scanResult);
+  } else {
+    // Claude Desktop config mode
+    const configPath = await resolveConfigPath();
+    if (!existsSync(configPath)) {
+      console.error(`Config not found: ${configPath}`);
+      process.exit(1);
+    }
+
+    const config: ClaudeDesktopConfig = JSON.parse(readFileSync(configPath, "utf8"));
+    const servers = config.mcpServers ?? {};
+
+    for (const [serverName, serverConfig] of Object.entries(servers)) {
+      if (flags.server && serverName !== flags.server) continue;
+
+      let tools;
+      let transport: "stdio" | "http" | "sse" = "stdio";
+
+      if (serverConfig.url) {
+        const raw = (serverConfig.transport as string | undefined) ?? "http";
+        if (raw === "sse") {
+          transport = "sse";
+          tools = await fetchToolsFromSse({ url: serverConfig.url });
+        } else {
+          transport = "http";
+          tools = await fetchToolsFromHttp({ url: serverConfig.url });
+        }
+      } else if (serverConfig.command) {
+        tools = await fetchToolsFromStdio({ command: serverConfig.command, args: serverConfig.args, env: serverConfig.env });
+      } else {
+        console.warn(`  Skipping ${serverName}: no command or URL`);
+        continue;
+      }
+
+      const scanResult = await scanServer(serverName, tools, transport, { skipSemantic: flags["skip-semantic"] });
+
+      if (!flags["skip-pinning"]) {
+        const pinResult = verifyToolDefinitions(tools, serverName);
+        if (pinResult.status === "changed") console.warn(`  Tool definitions changed in "${serverName}" since last approval`);
+        if (pinResult.status === "tampered") {
+          console.error(`  Manifest tampered for "${serverName}" - treat as critical`);
+          scanResult.status = "critical";
+        }
+      }
+      results.push(scanResult);
+    }
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    printReport(results, flags.verbose ?? false);
+  }
+
+  const hasCritical = results.some(r => r.status === "critical");
+  const hasWarning = results.some(r => r.status === "warning");
+
+  if (flags["fail-on-critical"] && hasCritical) process.exit(2);
+  if (flags["fail-on-warning"] && (hasCritical || hasWarning)) process.exit(2);
+}
+
+main().catch(err => {
+  console.error("Fatal:", err.message);
+  process.exit(1);
+});