@bryan-thompson/inspector-assessment-cli 1.43.1 → 1.43.3

package/build/lib/assessment-runner/server-connection.js

@@ -9,6 +9,37 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+/**
+ * Returns minimal environment variables for spawned MCP servers.
+ * Using a curated set prevents unintended behavior from inherited env vars
+ * (e.g., native module loading triggered by unexpected env conditions).
+ *
+ * @see https://github.com/triepod-ai/inspector-assessment/issues/211
+ */
+function getMinimalEnv() {
+    const minimal = {};
+    // Essential system paths
+    if (process.env.PATH)
+        minimal.PATH = process.env.PATH;
+    if (process.env.HOME)
+        minimal.HOME = process.env.HOME;
+    if (process.env.TMPDIR)
+        minimal.TMPDIR = process.env.TMPDIR;
+    if (process.env.TMP)
+        minimal.TMP = process.env.TMP;
+    if (process.env.TEMP)
+        minimal.TEMP = process.env.TEMP;
+    // Node.js environment
+    minimal.NODE_ENV = process.env.NODE_ENV || "production";
+    // Platform-specific essentials
+    if (process.env.USER)
+        minimal.USER = process.env.USER;
+    if (process.env.SHELL)
+        minimal.SHELL = process.env.SHELL;
+    if (process.env.LANG)
+        minimal.LANG = process.env.LANG;
+    return minimal;
+}
 /**
  * Connect to MCP server via configured transport
  *
@@ -37,8 +68,8 @@ export async function connectToServer(config) {
                 command: config.command,
                 args: config.args,
                 env: {
-                    ...Object.fromEntries(Object.entries(process.env).filter(([, v]) => v !== undefined)),
-                    ...config.env,
+                    ...getMinimalEnv(),
+                    ...config.env, // Explicit config overrides take priority
                 },
                 cwd: config.cwd,
                 stderr: "pipe",
@@ -65,16 +96,32 @@ export async function connectToServer(config) {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
+        // Issue #212: Detect SIGKILL (exit code 137) which may indicate Gatekeeper blocking
+        const isSigkill = errorMessage.includes("exit code 137") ||
+            errorMessage.includes("SIGKILL") ||
+            errorMessage.toLowerCase().includes("killed");
         // Provide helpful context when connection fails
+        let contextualHelp = `Failed to connect to MCP server: ${errorMessage}\n\n`;
         if (stderrData.trim()) {
-            throw new Error(`Failed to connect to MCP server: ${errorMessage}\n\n` +
-                `Server stderr:\n${stderrData.trim()}\n\n` +
-                `Common causes:\n` +
-                `  - Missing environment variables (check .env file)\n` +
-                `  - Required external services not running\n` +
-                `  - Missing API credentials`);
+            contextualHelp += `Server stderr:\n${stderrData.trim()}\n\n`;
+        }
+        contextualHelp += `Common causes:\n`;
+        contextualHelp += `  - Missing environment variables (check .env file)\n`;
+        contextualHelp += `  - Required external services not running\n`;
+        contextualHelp += `  - Missing API credentials\n`;
+        // Issue #212: Add native module specific help for SIGKILL/timeout
+        if (isSigkill) {
+            contextualHelp += `\n\u{1F534} Exit code 137 (SIGKILL) detected - possible causes:\n`;
+            contextualHelp += `  - macOS Gatekeeper blocked unsigned native binaries\n`;
+            contextualHelp += `  - Native module (canvas, sharp, better-sqlite3) killed by security policy\n`;
+            contextualHelp += `  - Out of memory during native module initialization\n`;
+            contextualHelp += `\nSuggested actions:\n`;
+            contextualHelp += `  - Check pre-flight warnings above for detected native modules\n`;
+            contextualHelp += `  - Try: xattr -d com.apple.quarantine /path/to/binary\n`;
+            contextualHelp += `  - Open System Preferences > Security & Privacy to allow blocked apps\n`;
+            contextualHelp += `  - Consider pure JavaScript alternatives (e.g., jimp instead of sharp)\n`;
         }
-        throw new Error(`Failed to connect to MCP server: ${errorMessage}`);
+        throw new Error(contextualHelp);
     }
     return client;
 }

package/build/lib/cli-parser.js

@@ -316,6 +316,14 @@ export function parseArgs(argv) {
                 // Issue #137: Stage B enrichment for Claude semantic analysis
                 options.stageBVerbose = true;
                 break;
+            case "--static-only":
+                // Issue #213: Static-only assessment without server connection
+                options.staticOnly = true;
+                break;
+            case "--fallback-static":
+                // Issue #213: Try runtime, fall back to static on failure
+                options.fallbackStatic = true;
+                break;
             case "--profile": {
                 const profileValue = args[++i];
                 if (!profileValue) {
@@ -435,6 +443,37 @@ export function parseArgs(argv) {
         options.helpRequested = true;
         return options;
     }
+    // Issue #213: Validate --static-only and --fallback-static options
+    if (options.staticOnly && options.fallbackStatic) {
+        console.error("Error: --static-only and --fallback-static are mutually exclusive");
+        console.error("  Use --static-only for static analysis only");
+        console.error("  Use --fallback-static to try runtime first, then fall back to static");
+        setTimeout(() => process.exit(1), 10);
+        options.helpRequested = true;
+        return options;
+    }
+    if (options.staticOnly && !options.sourceCodePath) {
+        console.error("Error: --static-only requires --source <path>");
+        console.error("  Provide the path to source code for static analysis");
+        setTimeout(() => process.exit(1), 10);
+        options.helpRequested = true;
+        return options;
+    }
+    if (options.staticOnly &&
+        (options.httpUrl || options.sseUrl || options.serverConfigPath)) {
+        console.error("Error: --static-only cannot be used with --http, --sse, or --config");
+        console.error("  Static-only mode does not connect to a server");
+        setTimeout(() => process.exit(1), 10);
+        options.helpRequested = true;
+        return options;
+    }
+    if (options.staticOnly && options.singleModule) {
+        console.error("Error: --static-only cannot be used with --module");
+        console.error("  Static mode runs all static-capable modules automatically");
+        setTimeout(() => process.exit(1), 10);
+        options.helpRequested = true;
+        return options;
+    }
     if (!options.serverName) {
         console.error("Error: --server is required");
         printHelp();
@@ -522,6 +561,10 @@ Options:
                          breakdowns to tiered output (Tier 2 + Tier 3)
   --module, -m <name>    Run single module directly (bypasses orchestrator for faster execution)
                          Mutually exclusive with --skip-modules, --only-modules, --profile
+  --static-only          Run static analysis only (no server connection required)
+                         Requires --source path. Validates manifest, docs, code quality.
+  --fallback-static      Try runtime assessment, fall back to static on failure
+                         Use when server may have startup issues.
   --skip-modules <list>  Skip specific modules (comma-separated)
   --only-modules <list>  Run only specific modules (comma-separated)
   --json                 Output only JSON path (no console summary)
@@ -585,6 +628,23 @@ Module Tiers (13 standard + 4 opt-in):
     • File Modularization - Code quality metrics (not security)
     • External API       - External service detection (informational)
 
+Static Analysis (--static-only):
+  When a server won't start, use --static-only with --source to validate:
+    • Manifest           - Schema compliance, required fields
+    • Developer Experience - README quality, documentation
+    • Prohibited Libs    - Banned dependency detection
+    • Portability        - Platform-specific patterns
+    • External API       - External service detection
+    • Tool Annotations   - Annotation presence in source
+    • Authentication     - Credential patterns
+    • AUP Compliance     - Policy keyword analysis
+    • File Modularization - Code structure metrics
+    • Conformance        - Code quality checks
+
+  Modules skipped in static mode (require runtime):
+    • Functionality, Security, Temporal, Protocol Compliance
+    • Resources, Prompts, Cross-Capability
+
 Transport Options:
   --config, --http, and --sse are mutually exclusive.
   Use --http or --sse for quick testing without a config file.
@@ -612,6 +672,13 @@ Examples:
   mcp-assess-full my-server --skip-modules temporal,resources  # Skip expensive modules
   mcp-assess-full my-server --only-modules functionality,toolAnnotations  # Annotation PR review
 
+  # Static analysis (when server won't start):
+  mcp-assess-full my-server --source ./my-server --static-only
+  mcp-assess-full my-server --source ./my-server --static-only --only-modules manifestValidation,prohibitedLibraries
+
+  # Fallback mode (try runtime, fall back to static on failure):
+  mcp-assess-full my-server --http http://localhost:10900/mcp --source ./my-server --fallback-static
+
   # Advanced options:
   mcp-assess-full --server my-server --source ./my-server --output ./results.json
   mcp-assess-full --server my-server --format markdown --include-policy

package/build/lib/cli-parserSchemas.js

@@ -133,6 +133,9 @@ export const AssessmentOptionsSchema = z
     outputFormat: OutputFormatSchema.optional(),
     autoTier: z.boolean().optional(),
     stageBVerbose: z.boolean().optional(),
+    // Issue #213: Static analysis mode options
+    staticOnly: z.boolean().optional(),
+    fallbackStatic: z.boolean().optional(),
 })
     .refine((data) => !(data.profile && (data.skipModules?.length || data.onlyModules?.length)), {
     message: "--profile cannot be used with --skip-modules or --only-modules",
@@ -141,6 +144,15 @@ export const AssessmentOptionsSchema = z
     .refine((data) => !(data.skipModules?.length && data.onlyModules?.length), {
     message: "--skip-modules and --only-modules are mutually exclusive",
     path: ["skipModules"],
+})
+    // Issue #213: Static mode validations
+    .refine((data) => !(data.staticOnly && data.fallbackStatic), {
+    message: "--static-only and --fallback-static are mutually exclusive",
+    path: ["staticOnly"],
+})
+    .refine((data) => !(data.staticOnly && !data.sourceCodePath), {
+    message: "--static-only requires --source <path>",
+    path: ["staticOnly"],
 });
 /**
  * Schema for validation result.

package/build/lib/jsonl-events.js

@@ -427,3 +427,32 @@ export function emitTieredOutput(outputDir, outputFormat, tiers) {
         tiers,
     });
 }
+// ============================================================================
+// Native Module Warning Events - Issue #212
+// ============================================================================
+/**
+ * Emit native_module_warning event when native modules detected in package.json.
+ * This is a pre-flight warning that doesn't block assessment, but alerts
+ * users to potential issues with native binaries being blocked by Gatekeeper.
+ *
+ * @param moduleName - Name of the detected native module (e.g., "canvas")
+ * @param category - Module category (image, database, graphics, system, crypto)
+ * @param severity - Impact severity (HIGH or MEDIUM)
+ * @param warningMessage - Human-readable warning about potential issues
+ * @param dependencyType - Where found (dependencies, devDependencies, optionalDependencies)
+ * @param version - Version specifier from package.json
+ * @param suggestedEnvVars - Optional environment variables to mitigate issues
+ */
+export function emitNativeModuleWarning(moduleName, category, severity, warningMessage, dependencyType, version, suggestedEnvVars) {
+    emitJSONL({
+        event: "native_module_warning",
+        moduleName,
+        category,
+        severity,
+        warningMessage,
+        dependencyType,
+        moduleVersion: version, // Renamed to avoid collision with package version
+        ...(suggestedEnvVars &&
+            Object.keys(suggestedEnvVars).length > 0 && { suggestedEnvVars }),
+    });
+}

package/build/lib/static-modules.js

@@ -0,0 +1,103 @@
+/**
+ * Static Analysis Module Definitions
+ *
+ * Defines which assessment modules can run without a server connection.
+ * These modules analyze source code, manifest, package.json, and documentation
+ * without requiring tool execution or server interaction.
+ *
+ * @module cli/lib/static-modules
+ * @see Issue #213
+ */
+/**
+ * Modules that can run in static-only mode (no server connection required).
+ *
+ * These modules have `contextRequirements.needsCallTool: false` and operate on:
+ * - Source code files (sourceCodeFiles)
+ * - Package metadata (packageJson, manifestJson)
+ * - Documentation (readmeContent)
+ * - Tool schemas (tools - extracted from manifest if available)
+ */
+export const STATIC_MODULES = [
+    "manifestValidation", // MCPB manifest.json schema validation
+    "documentation", // Documentation quality (legacy name for DeveloperExperience)
+    "usability", // Usability assessment (legacy name for DeveloperExperience)
+    "prohibitedLibraries", // Banned dependency detection
+    "portability", // Platform-specific pattern detection
+    "externalAPIScanner", // External API dependency detection
+    "fileModularization", // Code structure metrics
+    "conformance", // Code quality checks
+    "toolAnnotations", // Annotation presence in source
+    "authentication", // Credential pattern detection
+    "aupCompliance", // AUP keyword analysis
+];
+/**
+ * Modules that require a running server (cannot run in static mode).
+ *
+ * These modules have `contextRequirements.needsCallTool: true` and require:
+ * - Active tool execution (callTool function)
+ * - Server connection and response validation
+ * - Real-time behavior testing
+ */
+export const RUNTIME_MODULES = [
+    "functionality", // Tests actual tool execution
+    "security", // Tests security vulnerabilities via tool calls
+    "temporal", // Tests for rug pulls (baseline + post-call comparison)
+    "protocolCompliance", // Tests protocol compliance via tool calls
+    "resources", // Tests resource accessibility
+    "prompts", // Tests prompt behavior and injection
+    "crossCapability", // Tests tool chaining attacks
+    "errorHandling", // Tests error response handling (legacy, merged into protocolCompliance)
+    "dependencyVulnerability", // npm/yarn/pnpm audit (requires live server)
+];
+/**
+ * Check if a module can run in static-only mode
+ *
+ * @param moduleName - Name of the assessment module
+ * @returns true if the module can run without server connection
+ */
+export function isStaticModule(moduleName) {
+    return STATIC_MODULES.includes(moduleName);
+}
+/**
+ * Check if a module requires a running server
+ *
+ * @param moduleName - Name of the assessment module
+ * @returns true if the module requires server connection
+ */
+export function isRuntimeModule(moduleName) {
+    return RUNTIME_MODULES.includes(moduleName);
+}
+/**
+ * Get all static module names as an array
+ *
+ * @returns Array of static module names
+ */
+export function getStaticModules() {
+    return STATIC_MODULES;
+}
+/**
+ * Get all runtime module names as an array
+ *
+ * @returns Array of runtime module names
+ */
+export function getRuntimeModules() {
+    return RUNTIME_MODULES;
+}
+/**
+ * Filter a list of module names to only include static-capable modules
+ *
+ * @param modules - Array of module names to filter
+ * @returns Array of modules that can run in static mode
+ */
+export function filterToStaticModules(modules) {
+    return modules.filter(isStaticModule);
+}
+/**
+ * Filter a list of module names to only include runtime-required modules
+ *
+ * @param modules - Array of module names to filter
+ * @returns Array of modules that require server connection
+ */
+export function filterToRuntimeModules(modules) {
+    return modules.filter(isRuntimeModule);
+}

package/build/transport.js

@@ -2,21 +2,46 @@ import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { getDefaultEnvironment, StdioClientTransport, } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { findActualExecutable } from "spawn-rx";
+/**
+ * Returns minimal environment variables for spawned MCP servers.
+ * Using a curated set prevents unintended behavior from inherited env vars.
+ *
+ * @see https://github.com/triepod-ai/inspector-assessment/issues/211
+ */
+function getMinimalEnv() {
+    const minimal = {};
+    // Essential system paths
+    if (process.env.PATH)
+        minimal.PATH = process.env.PATH;
+    if (process.env.HOME)
+        minimal.HOME = process.env.HOME;
+    if (process.env.TMPDIR)
+        minimal.TMPDIR = process.env.TMPDIR;
+    if (process.env.TMP)
+        minimal.TMP = process.env.TMP;
+    if (process.env.TEMP)
+        minimal.TEMP = process.env.TEMP;
+    // Node.js environment
+    minimal.NODE_ENV = process.env.NODE_ENV || "production";
+    // Platform-specific essentials
+    if (process.env.USER)
+        minimal.USER = process.env.USER;
+    if (process.env.SHELL)
+        minimal.SHELL = process.env.SHELL;
+    if (process.env.LANG)
+        minimal.LANG = process.env.LANG;
+    return minimal;
+}
 function createStdioTransport(options) {
     let args = [];
     if (options.args !== undefined) {
         args = options.args;
     }
-    const processEnv = {};
-    for (const [key, value] of Object.entries(process.env)) {
-        if (value !== undefined) {
-            processEnv[key] = value;
-        }
-    }
+    // Use minimal env + SDK defaults instead of full process.env
     const defaultEnv = getDefaultEnvironment();
     const env = {
         ...defaultEnv,
-        ...processEnv,
+        ...getMinimalEnv(),
     };
     const { cmd: actualCommand, args: actualArgs } = findActualExecutable(options.command ?? "", args);
     return new StdioClientTransport({

package/package.json

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