@bryan-thompson/inspector-assessment-cli 1.26.6 → 1.27.0

package/build/lib/cli-parser.js

@@ -9,7 +9,8 @@
  * @module cli/lib/cli-parser
  */
 import { ASSESSMENT_CATEGORY_METADATA, } from "../../../client/lib/lib/assessmentTypes.js";
-import { ASSESSMENT_PROFILES, isValidProfileName, getProfileHelpText, } from "../profiles.js";
+import { ASSESSMENT_PROFILES, isValidProfileName, getProfileHelpText, TIER_1_CORE_SECURITY, TIER_2_COMPLIANCE, TIER_3_CAPABILITY, TIER_4_EXTENDED, } from "../profiles.js";
+import packageJson from "../../package.json" with { type: "json" };
 // ============================================================================
 // Constants
 // ============================================================================
@@ -249,6 +250,15 @@ export function parseArgs(argv) {
                 }
                 break;
             }
+            case "--list-modules":
+                printModules();
+                options.listModules = true;
+                return options;
+            case "--version":
+            case "-V":
+                printVersion();
+                options.versionRequested = true;
+                return options;
             case "--help":
             case "-h":
                 printHelp();
@@ -310,8 +320,20 @@ export function parseArgs(argv) {
     return options;
 }
 // ============================================================================
-// Help Text
+// Version and Help Text
 // ============================================================================
+/**
+ * Get package version from package.json
+ */
+function getPackageVersion() {
+    return packageJson.version;
+}
+/**
+ * Print version to console
+ */
+export function printVersion() {
+    console.log(`mcp-assess-full ${getPackageVersion()}`);
+}
 /**
  * Print help message to console
  */
@@ -349,6 +371,7 @@ Options:
   --silent               Suppress all diagnostic logging
   --log-level <level>    Set log level: silent, error, warn, info (default), debug
                          Also supports LOG_LEVEL environment variable
+  --version, -V          Show version number
   --help, -h             Show this help message
 
 Environment Variables:
@@ -417,3 +440,61 @@ Examples:
   mcp-assess-full --server my-server --compare ./baseline.json --diff-only
   `);
 }
+/**
+ * Module description mappings for printModules output.
+ * Uses human-friendly descriptions that may differ from ASSESSMENT_CATEGORY_METADATA.
+ */
+const MODULE_DESCRIPTIONS = {
+    functionality: "Tool functionality validation",
+    security: "Security vulnerability detection (23 attack patterns)",
+    temporal: "Temporal/rug pull detection",
+    errorHandling: "Error handling compliance",
+    protocolCompliance: "MCP protocol + JSON-RPC validation",
+    aupCompliance: "Acceptable use policy compliance",
+    toolAnnotations: "Tool annotation validation (readOnlyHint, destructiveHint)",
+    prohibitedLibraries: "Prohibited library detection",
+    manifestValidation: "MCPB manifest.json validation",
+    authentication: "OAuth/auth evaluation",
+    resources: "Resource path traversal + sensitive data exposure",
+    prompts: "Prompt AUP compliance + injection testing",
+    crossCapability: "Cross-capability attack chain detection",
+    developerExperience: "Documentation + usability assessment",
+    portability: "Cross-platform compatibility",
+    externalAPIScanner: "External API detection (requires --source)",
+};
+/**
+ * Print available modules organized by tier
+ */
+export function printModules() {
+    const formatModule = (name) => {
+        const desc = MODULE_DESCRIPTIONS[name] ||
+            ASSESSMENT_CATEGORY_METADATA[name]?.description ||
+            "";
+        return `  ${name.padEnd(22)} ${desc}`;
+    };
+    console.log(`
+Available Assessment Modules (16 total):
+
+Tier 1 - Core Security (${TIER_1_CORE_SECURITY.length} modules):
+${TIER_1_CORE_SECURITY.map(formatModule).join("\n")}
+
+Tier 2 - Compliance (${TIER_2_COMPLIANCE.length} modules):
+${TIER_2_COMPLIANCE.map(formatModule).join("\n")}
+
+Tier 3 - Capability-Based (${TIER_3_CAPABILITY.length} modules):
+${TIER_3_CAPABILITY.map(formatModule).join("\n")}
+
+Tier 4 - Extended (${TIER_4_EXTENDED.length} modules):
+${TIER_4_EXTENDED.map(formatModule).join("\n")}
+
+Usage:
+  --only-modules <list>   Run only specified modules (comma-separated)
+  --skip-modules <list>   Skip specified modules (comma-separated)
+  --profile <name>        Use predefined profile (quick, security, compliance, full)
+
+Examples:
+  mcp-assess-full my-server --only-modules functionality,security
+  mcp-assess-full my-server --skip-modules temporal,portability
+  mcp-assess-full my-server --profile compliance
+`);
+}

package/build/lib/comparison-handler.js

@@ -0,0 +1,84 @@
+/**
+ * Comparison Handler Module
+ *
+ * Handles assessment comparison/diff logic for comparing
+ * current results against a baseline.
+ *
+ * @module cli/lib/comparison-handler
+ */
+import * as fs from "fs";
+import { compareAssessments, } from "../../../client/lib/lib/assessmentDiffer.js";
+import { formatDiffAsMarkdown } from "../../../client/lib/lib/reportFormatters/DiffReportFormatter.js";
+// ============================================================================
+// Comparison Functions
+// ============================================================================
+/**
+ * Handle comparison mode - compare current results against a baseline.
+ *
+ * @param results - Current assessment results
+ * @param options - CLI options including comparePath and diffOnly
+ * @returns ComparisonResult if comparison was performed, null if no comparison
+ */
+export function handleComparison(results, options) {
+    if (!options.comparePath) {
+        return null;
+    }
+    if (!fs.existsSync(options.comparePath)) {
+        console.error(`Error: Baseline file not found: ${options.comparePath}`);
+        // Return null to indicate comparison failed - caller handles null returns
+        return null;
+    }
+    const baselineData = JSON.parse(fs.readFileSync(options.comparePath, "utf-8"));
+    // Validate baseline has expected structure
+    if (!baselineData.functionality || !baselineData.security) {
+        console.warn("Warning: Baseline file may be incomplete (missing functionality or security)");
+    }
+    const baseline = baselineData;
+    const diff = compareAssessments(baseline, results);
+    // Handle diff-only mode
+    if (options.diffOnly) {
+        let diffPath;
+        if (options.format === "markdown") {
+            diffPath =
+                options.outputPath || `/tmp/inspector-diff-${options.serverName}.md`;
+            fs.writeFileSync(diffPath, formatDiffAsMarkdown(diff));
+        }
+        else {
+            diffPath =
+                options.outputPath || `/tmp/inspector-diff-${options.serverName}.json`;
+            fs.writeFileSync(diffPath, JSON.stringify(diff, null, 2));
+        }
+        const exitCode = diff.summary.overallChange === "regressed" ? 1 : 0;
+        return { diff, exitCode, diffOutputPath: diffPath };
+    }
+    // Return comparison result for normal mode
+    const exitCode = diff.summary.overallChange === "regressed" ? 1 : 0;
+    return { diff, exitCode };
+}
+/**
+ * Display comparison summary to console.
+ *
+ * @param diff - Assessment diff to display
+ */
+export function displayComparisonSummary(diff) {
+    console.log("\n" + "=".repeat(70));
+    console.log("VERSION COMPARISON");
+    console.log("=".repeat(70));
+    console.log(`Baseline: ${diff.baseline.version || "N/A"} (${diff.baseline.date})`);
+    console.log(`Current:  ${diff.current.version || "N/A"} (${diff.current.date})`);
+    console.log(`Overall Change: ${diff.summary.overallChange.toUpperCase()}`);
+    console.log(`Modules Improved: ${diff.summary.modulesImproved}`);
+    console.log(`Modules Regressed: ${diff.summary.modulesRegressed}`);
+    if (diff.securityDelta.newVulnerabilities.length > 0) {
+        console.log(`\n⚠️  NEW VULNERABILITIES: ${diff.securityDelta.newVulnerabilities.length}`);
+    }
+    if (diff.securityDelta.fixedVulnerabilities.length > 0) {
+        console.log(`✅ FIXED VULNERABILITIES: ${diff.securityDelta.fixedVulnerabilities.length}`);
+    }
+    if (diff.functionalityDelta.newBrokenTools.length > 0) {
+        console.log(`❌ NEW BROKEN TOOLS: ${diff.functionalityDelta.newBrokenTools.length}`);
+    }
+    if (diff.functionalityDelta.fixedTools.length > 0) {
+        console.log(`✅ FIXED TOOLS: ${diff.functionalityDelta.fixedTools.length}`);
+    }
+}

package/build/lib/result-output.js

@@ -0,0 +1,154 @@
+/**
+ * Result Output Module
+ *
+ * Handles saving assessment results to files and displaying
+ * summaries to the console.
+ *
+ * @module cli/lib/result-output
+ */
+import * as fs from "fs";
+import { ASSESSMENT_CATEGORY_METADATA, } from "../../../client/lib/lib/assessmentTypes.js";
+import { createFormatter } from "../../../client/lib/lib/reportFormatters/index.js";
+import { generatePolicyComplianceReport } from "../../../client/lib/services/assessment/PolicyComplianceGenerator.js";
+// ============================================================================
+// Result Output
+// ============================================================================
+/**
+ * Save results to file with appropriate format
+ */
+export function saveResults(serverName, results, options) {
+    const format = options.format || "json";
+    // Generate policy compliance report if requested
+    const policyReport = options.includePolicy
+        ? generatePolicyComplianceReport(results, serverName)
+        : undefined;
+    // Create formatter with options
+    const formatter = createFormatter({
+        format,
+        includePolicyMapping: options.includePolicy,
+        policyReport,
+        serverName,
+        includeDetails: true,
+        prettyPrint: true,
+    });
+    const fileExtension = formatter.getFileExtension();
+    const defaultPath = `/tmp/inspector-full-assessment-${serverName}${fileExtension}`;
+    const finalPath = options.outputPath || defaultPath;
+    // For JSON format, add metadata wrapper
+    if (format === "json") {
+        // Filter out undefined/skipped modules from results (--skip-modules support)
+        const filteredResults = Object.fromEntries(Object.entries(results).filter(([_, v]) => v !== undefined));
+        const output = {
+            timestamp: new Date().toISOString(),
+            assessmentType: "full",
+            ...filteredResults,
+            ...(policyReport ? { policyCompliance: policyReport } : {}),
+        };
+        fs.writeFileSync(finalPath, JSON.stringify(output, null, 2));
+    }
+    else {
+        // For other formats (markdown), use the formatter
+        const content = formatter.format(results);
+        fs.writeFileSync(finalPath, content);
+    }
+    return finalPath;
+}
+// ============================================================================
+// Summary Display
+// ============================================================================
+/**
+ * Display summary to console
+ */
+export function displaySummary(results) {
+    const { overallStatus, summary, totalTestsRun, executionTime, 
+    // Destructuring order matches display order below
+    functionality, security, documentation, errorHandling, usability, mcpSpecCompliance, aupCompliance, toolAnnotations, prohibitedLibraries, manifestValidation, portability, externalAPIScanner, authentication, temporal, resources, prompts, crossCapability, } = results;
+    console.log("\n" + "=".repeat(70));
+    console.log("FULL ASSESSMENT RESULTS");
+    console.log("=".repeat(70));
+    console.log(`Server: ${results.serverName}`);
+    console.log(`Overall Status: ${overallStatus}`);
+    console.log(`Total Tests Run: ${totalTestsRun}`);
+    console.log(`Execution Time: ${executionTime}ms`);
+    console.log("-".repeat(70));
+    console.log("\n📊 MODULE STATUS:");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const modules = [
+        ["Functionality", functionality, "functionality"],
+        ["Security", security, "security"],
+        ["Documentation", documentation, "documentation"],
+        ["Error Handling", errorHandling, "errorHandling"],
+        ["Usability", usability, "usability"],
+        ["MCP Spec Compliance", mcpSpecCompliance, "mcpSpecCompliance"],
+        ["AUP Compliance", aupCompliance, "aupCompliance"],
+        ["Tool Annotations", toolAnnotations, "toolAnnotations"],
+        ["Prohibited Libraries", prohibitedLibraries, "prohibitedLibraries"],
+        ["Manifest Validation", manifestValidation, "manifestValidation"],
+        ["Portability", portability, "portability"],
+        ["External API Scanner", externalAPIScanner, "externalAPIScanner"],
+        ["Authentication", authentication, "authentication"],
+        ["Temporal", temporal, "temporal"],
+        ["Resources", resources, "resources"],
+        ["Prompts", prompts, "prompts"],
+        ["Cross-Capability", crossCapability, "crossCapability"],
+    ];
+    for (const [name, module, categoryKey] of modules) {
+        if (module) {
+            const metadata = ASSESSMENT_CATEGORY_METADATA[categoryKey];
+            const optionalMarker = metadata?.tier === "optional" ? " (optional)" : "";
+            const icon = module.status === "PASS"
+                ? "✅"
+                : module.status === "FAIL"
+                    ? "❌"
+                    : "⚠️";
+            console.log(`   ${icon} ${name}${optionalMarker}: ${module.status}`);
+        }
+    }
+    console.log("\n📋 KEY FINDINGS:");
+    console.log(`   ${summary}`);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const securityModule = security;
+    if (securityModule?.vulnerabilities?.length > 0) {
+        const vulns = securityModule.vulnerabilities;
+        console.log(`\n🔒 SECURITY VULNERABILITIES (${vulns.length}):`);
+        for (const vuln of vulns.slice(0, 5)) {
+            console.log(`   • ${vuln}`);
+        }
+        if (vulns.length > 5) {
+            console.log(`   ... and ${vulns.length - 5} more`);
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const aupModule = aupCompliance;
+    if (aupModule?.violations?.length > 0) {
+        const violations = aupModule.violations;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const critical = violations.filter((v) => v.severity === "CRITICAL");
+        console.log(`\n⚖️  AUP FINDINGS:`);
+        console.log(`   Total flagged: ${violations.length}`);
+        if (critical.length > 0) {
+            console.log(`   🚨 CRITICAL violations: ${critical.length}`);
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const annotationsModule = toolAnnotations;
+    if (annotationsModule) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const funcModule = functionality;
+        console.log(`\n🏷️  TOOL ANNOTATIONS:`);
+        console.log(`   Annotated: ${annotationsModule.annotatedCount || 0}/${funcModule?.workingTools || 0}`);
+        if (annotationsModule.missingAnnotationsCount > 0) {
+            console.log(`   Missing: ${annotationsModule.missingAnnotationsCount}`);
+        }
+        if (annotationsModule.misalignedAnnotationsCount > 0) {
+            console.log(`   ⚠️  Misalignments: ${annotationsModule.misalignedAnnotationsCount}`);
+        }
+    }
+    if (results.recommendations?.length > 0) {
+        console.log("\n💡 RECOMMENDATIONS:");
+        for (const rec of results.recommendations.slice(0, 5)) {
+            console.log(`   • ${rec}`);
+        }
+    }
+    console.log("\n" + "=".repeat(70));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bryan-thompson/inspector-assessment-cli",
-  "version": "1.26.6",
+  "version": "1.27.0",
   "description": "CLI for the Enhanced MCP Inspector with assessment capabilities",
   "license": "MIT",
   "author": "Bryan Thompson <bryan@triepod.ai>",