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

package/build/lib/assessment-runner.js

@@ -0,0 +1,746 @@
+/**
+ * Assessment Runner Module
+ *
+ * Handles MCP server connection, assessment orchestration, and configuration
+ * for the mcp-assess-full CLI tool.
+ *
+ * Extracted from assess-full.ts as part of Issue #90 modularization.
+ *
+ * @module cli/lib/assessment-runner
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+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";
+import { AssessmentOrchestrator, } from "../../../client/lib/services/assessment/AssessmentOrchestrator.js";
+import { DEFAULT_ASSESSMENT_CONFIG, getAllModulesConfig, } from "../../../client/lib/lib/assessmentTypes.js";
+import { FULL_CLAUDE_CODE_CONFIG } from "../../../client/lib/services/assessment/lib/claudeCodeBridge.js";
+import { loadPerformanceConfig } from "../../../client/lib/services/assessment/config/performanceConfig.js";
+import { AssessmentStateManager } from "../assessmentState.js";
+import { emitServerConnected, emitToolDiscovered, emitToolsDiscoveryComplete, emitAssessmentComplete, emitTestBatch, emitVulnerabilityFound, emitAnnotationMissing, emitAnnotationMisaligned, emitAnnotationReviewRecommended, emitAnnotationAligned, emitModulesConfigured, } from "./jsonl-events.js";
+import { getProfileModules, resolveModuleNames, modulesToLegacyConfig, } from "../profiles.js";
+// ============================================================================
+// Server Configuration
+// ============================================================================
+/**
+ * Load server configuration from Claude Code's MCP settings
+ *
+ * @param serverName - Name of the server to look up
+ * @param configPath - Optional explicit config path
+ * @returns Server configuration object
+ */
+export function loadServerConfig(serverName, configPath) {
+    const possiblePaths = [
+        configPath,
+        path.join(os.homedir(), ".config", "mcp", "servers", `${serverName}.json`),
+        path.join(os.homedir(), ".config", "claude", "claude_desktop_config.json"),
+    ].filter(Boolean);
+    for (const tryPath of possiblePaths) {
+        if (!fs.existsSync(tryPath))
+            continue;
+        const config = JSON.parse(fs.readFileSync(tryPath, "utf-8"));
+        if (config.mcpServers && config.mcpServers[serverName]) {
+            const serverConfig = config.mcpServers[serverName];
+            // Check if serverConfig specifies http/sse transport
+            if (serverConfig.url ||
+                serverConfig.transport === "http" ||
+                serverConfig.transport === "sse") {
+                if (!serverConfig.url) {
+                    throw new Error(`Invalid server config: transport is '${serverConfig.transport}' but 'url' is missing`);
+                }
+                return {
+                    transport: serverConfig.transport || "http",
+                    url: serverConfig.url,
+                };
+            }
+            // Default to stdio transport
+            return {
+                transport: "stdio",
+                command: serverConfig.command,
+                args: serverConfig.args || [],
+                env: serverConfig.env || {},
+                cwd: serverConfig.cwd,
+            };
+        }
+        if (config.url ||
+            config.transport === "http" ||
+            config.transport === "sse") {
+            if (!config.url) {
+                throw new Error(`Invalid server config: transport is '${config.transport}' but 'url' is missing`);
+            }
+            return {
+                transport: config.transport || "http",
+                url: config.url,
+            };
+        }
+        if (config.command) {
+            return {
+                transport: "stdio",
+                command: config.command,
+                args: config.args || [],
+                env: config.env || {},
+            };
+        }
+    }
+    throw new Error(`Server config not found for: ${serverName}\nTried: ${possiblePaths.join(", ")}`);
+}
+// ============================================================================
+// Source File Loading
+// ============================================================================
+/**
+ * Load optional files from source code path
+ *
+ * @param sourcePath - Path to source code directory
+ * @returns Object containing loaded source files
+ */
+export function loadSourceFiles(sourcePath) {
+    const result = {};
+    // Search for README in source directory and parent directories (up to 3 levels)
+    // This handles cases where --source points to a subdirectory but README is at repo root
+    const readmePaths = ["README.md", "readme.md", "Readme.md"];
+    let readmeFound = false;
+    // First try the source directory itself
+    for (const readmePath of readmePaths) {
+        const fullPath = path.join(sourcePath, readmePath);
+        if (fs.existsSync(fullPath)) {
+            result.readmeContent = fs.readFileSync(fullPath, "utf-8");
+            readmeFound = true;
+            break;
+        }
+    }
+    // If not found, search parent directories (up to 3 levels)
+    if (!readmeFound) {
+        let currentDir = sourcePath;
+        for (let i = 0; i < 3; i++) {
+            const parentDir = path.dirname(currentDir);
+            if (parentDir === currentDir)
+                break; // Reached filesystem root
+            for (const readmePath of readmePaths) {
+                const fullPath = path.join(parentDir, readmePath);
+                if (fs.existsSync(fullPath)) {
+                    result.readmeContent = fs.readFileSync(fullPath, "utf-8");
+                    readmeFound = true;
+                    break;
+                }
+            }
+            if (readmeFound)
+                break;
+            currentDir = parentDir;
+        }
+    }
+    const packagePath = path.join(sourcePath, "package.json");
+    if (fs.existsSync(packagePath)) {
+        result.packageJson = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+    }
+    const manifestPath = path.join(sourcePath, "manifest.json");
+    if (fs.existsSync(manifestPath)) {
+        result.manifestRaw = fs.readFileSync(manifestPath, "utf-8");
+        try {
+            result.manifestJson = JSON.parse(result.manifestRaw);
+        }
+        catch {
+            console.warn("[Assessment] Failed to parse manifest.json");
+        }
+    }
+    result.sourceCodeFiles = new Map();
+    // Include config files for portability analysis
+    const sourceExtensions = [
+        ".ts",
+        ".js",
+        ".py",
+        ".go",
+        ".rs",
+        ".json",
+        ".sh",
+        ".yaml",
+        ".yml",
+    ];
+    // Parse .gitignore patterns
+    const gitignorePatterns = [];
+    const gitignorePath = path.join(sourcePath, ".gitignore");
+    if (fs.existsSync(gitignorePath)) {
+        const gitignoreContent = fs.readFileSync(gitignorePath, "utf-8");
+        for (const line of gitignoreContent.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            // Convert gitignore pattern to regex
+            const pattern = trimmed
+                .replace(/\./g, "\\.")
+                .replace(/\*\*/g, ".*")
+                .replace(/\*/g, "[^/]*")
+                .replace(/\?/g, ".");
+            try {
+                gitignorePatterns.push(new RegExp(pattern));
+            }
+            catch {
+                // Skip invalid patterns
+            }
+        }
+    }
+    const isGitignored = (relativePath) => {
+        return gitignorePatterns.some((pattern) => pattern.test(relativePath));
+    };
+    const loadSourceDir = (dir, prefix = "") => {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            const fullPath = path.join(dir, entry.name);
+            const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            // Skip gitignored files
+            if (isGitignored(relativePath))
+                continue;
+            if (entry.isDirectory()) {
+                loadSourceDir(fullPath, relativePath);
+            }
+            else if (sourceExtensions.some((ext) => entry.name.endsWith(ext))) {
+                try {
+                    const content = fs.readFileSync(fullPath, "utf-8");
+                    if (content.length < 100000) {
+                        result.sourceCodeFiles.set(relativePath, content);
+                    }
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+        }
+    };
+    try {
+        loadSourceDir(sourcePath);
+    }
+    catch (e) {
+        console.warn("[Assessment] Could not load source files:", e);
+    }
+    return result;
+}
+// ============================================================================
+// Server Connection
+// ============================================================================
+/**
+ * Connect to MCP server via configured transport
+ *
+ * @param config - Server configuration
+ * @returns Connected MCP client
+ */
+export async function connectToServer(config) {
+    let transport;
+    let stderrData = ""; // Capture stderr for error reporting
+    switch (config.transport) {
+        case "http":
+            if (!config.url)
+                throw new Error("URL required for HTTP transport");
+            transport = new StreamableHTTPClientTransport(new URL(config.url));
+            break;
+        case "sse":
+            if (!config.url)
+                throw new Error("URL required for SSE transport");
+            transport = new SSEClientTransport(new URL(config.url));
+            break;
+        case "stdio":
+        default:
+            if (!config.command)
+                throw new Error("Command required for stdio transport");
+            transport = new StdioClientTransport({
+                command: config.command,
+                args: config.args,
+                env: {
+                    ...Object.fromEntries(Object.entries(process.env).filter(([, v]) => v !== undefined)),
+                    ...config.env,
+                },
+                cwd: config.cwd,
+                stderr: "pipe",
+            });
+            // Capture stderr BEFORE connecting - critical for error context
+            // The MCP SDK creates a PassThrough stream immediately when stderr: "pipe"
+            // is set, allowing us to attach listeners before start() is called
+            const stderrStream = transport.stderr;
+            if (stderrStream) {
+                stderrStream.on("data", (data) => {
+                    stderrData += data.toString();
+                });
+            }
+            break;
+    }
+    const client = new Client({
+        name: "mcp-assess-full",
+        version: "1.0.0",
+    }, {
+        capabilities: {},
+    });
+    try {
+        await client.connect(transport);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Provide helpful context when connection fails
+        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`);
+        }
+        throw new Error(`Failed to connect to MCP server: ${errorMessage}`);
+    }
+    return client;
+}
+// ============================================================================
+// Tool Call Wrapper
+// ============================================================================
+/**
+ * Create callTool wrapper for assessment context
+ *
+ * @param client - Connected MCP client
+ * @returns Wrapped callTool function
+ */
+export function createCallToolWrapper(client) {
+    return async (name, params) => {
+        try {
+            const response = await client.callTool({
+                name,
+                arguments: params,
+            });
+            return {
+                content: response.content,
+                isError: response.isError || false,
+                structuredContent: response
+                    .structuredContent,
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    };
+}
+// ============================================================================
+// Configuration Building
+// ============================================================================
+/**
+ * Build assessment configuration from CLI options
+ *
+ * @param options - CLI assessment options
+ * @returns Assessment configuration
+ */
+export function buildConfig(options) {
+    const config = {
+        ...DEFAULT_ASSESSMENT_CONFIG,
+        enableExtendedAssessment: options.fullAssessment !== false,
+        parallelTesting: true,
+        testTimeout: 30000,
+        enableSourceCodeAnalysis: Boolean(options.sourceCodePath),
+    };
+    if (options.fullAssessment !== false) {
+        // Priority: --profile > --only-modules > --skip-modules > default (all)
+        if (options.profile) {
+            // Use profile-based module selection
+            const profileModules = getProfileModules(options.profile, {
+                hasSourceCode: Boolean(options.sourceCodePath),
+                skipTemporal: options.skipTemporal,
+            });
+            // Convert new-style module list to legacy config format
+            // (until orchestrator is updated to use new naming)
+            config.assessmentCategories = modulesToLegacyConfig(profileModules);
+        }
+        else {
+            // Derive module config from ASSESSMENT_CATEGORY_METADATA (single source of truth)
+            const allModules = getAllModulesConfig({
+                sourceCodePath: Boolean(options.sourceCodePath),
+                skipTemporal: options.skipTemporal,
+            });
+            // Apply --only-modules filter (whitelist mode)
+            if (options.onlyModules?.length) {
+                // Resolve any deprecated module names
+                const resolved = resolveModuleNames(options.onlyModules);
+                for (const key of Object.keys(allModules)) {
+                    // Disable all modules except those in the whitelist
+                    allModules[key] = resolved.includes(key);
+                }
+            }
+            // Apply --skip-modules filter (blacklist mode)
+            if (options.skipModules?.length) {
+                // Resolve any deprecated module names
+                const resolved = resolveModuleNames(options.skipModules);
+                for (const module of resolved) {
+                    if (module in allModules) {
+                        allModules[module] = false;
+                    }
+                }
+            }
+            config.assessmentCategories =
+                allModules;
+        }
+    }
+    // Temporal/rug pull detection configuration
+    if (options.temporalInvocations) {
+        config.temporalInvocations = options.temporalInvocations;
+    }
+    if (options.claudeEnabled) {
+        // Check for HTTP transport via --claude-http flag or environment variables
+        const useHttpTransport = options.claudeHttp || process.env.INSPECTOR_CLAUDE === "true";
+        const auditorUrl = options.mcpAuditorUrl ||
+            process.env.INSPECTOR_MCP_AUDITOR_URL ||
+            "http://localhost:8085";
+        config.claudeCode = {
+            enabled: true,
+            timeout: FULL_CLAUDE_CODE_CONFIG.timeout || 60000,
+            maxRetries: FULL_CLAUDE_CODE_CONFIG.maxRetries || 2,
+            // Use HTTP transport when --claude-http flag or INSPECTOR_CLAUDE env is set
+            ...(useHttpTransport && {
+                transport: "http",
+                httpConfig: {
+                    baseUrl: auditorUrl,
+                },
+            }),
+            features: {
+                intelligentTestGeneration: true,
+                aupSemanticAnalysis: true,
+                annotationInference: true,
+                documentationQuality: true,
+            },
+        };
+        if (useHttpTransport) {
+            console.log(`🔗 Claude Bridge HTTP transport: ${auditorUrl}`);
+        }
+    }
+    // Pass custom annotation pattern config path
+    if (options.patternConfigPath) {
+        config.patternConfigPath = options.patternConfigPath;
+    }
+    // Load custom performance config if provided (Issue #37)
+    // Note: Currently, modules use DEFAULT_PERFORMANCE_CONFIG directly.
+    // This validates the config file but doesn't override runtime values yet.
+    // Future enhancement: Pass performanceConfig through AssessmentContext.
+    if (options.performanceConfigPath) {
+        try {
+            const performanceConfig = loadPerformanceConfig(options.performanceConfigPath);
+            console.log(`📊 Performance config loaded from: ${options.performanceConfigPath}`);
+            console.log(`   Batch interval: ${performanceConfig.batchFlushIntervalMs}ms, ` +
+                `Security batch: ${performanceConfig.securityBatchSize}, ` +
+                `Functionality batch: ${performanceConfig.functionalityBatchSize}`);
+            // TODO: Wire performanceConfig through AssessmentContext to modules
+        }
+        catch (error) {
+            console.error(`❌ Failed to load performance config: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
+        }
+    }
+    // Logging configuration
+    // Precedence: CLI flags > LOG_LEVEL env var > default (info)
+    const envLogLevel = process.env.LOG_LEVEL;
+    const logLevel = options.logLevel ?? envLogLevel ?? "info";
+    config.logging = { level: logLevel };
+    return config;
+}
+// ============================================================================
+// Full Assessment Orchestration
+// ============================================================================
+/**
+ * Run full assessment against an MCP server
+ *
+ * @param options - CLI assessment options
+ * @returns Assessment results
+ */
+export async function runFullAssessment(options) {
+    if (!options.jsonOnly) {
+        console.log(`\n🔍 Starting full assessment for: ${options.serverName}`);
+    }
+    const serverConfig = loadServerConfig(options.serverName, options.serverConfigPath);
+    if (!options.jsonOnly) {
+        console.log("✅ Server config loaded");
+    }
+    const client = await connectToServer(serverConfig);
+    emitServerConnected(options.serverName, serverConfig.transport || "stdio");
+    if (!options.jsonOnly) {
+        console.log("✅ Connected to MCP server");
+    }
+    // Capture server info from initialization for protocol conformance checks
+    // Apply defensive null checks for protocol conformance validation
+    const rawServerInfo = client.getServerVersion();
+    const rawServerCapabilities = client.getServerCapabilities();
+    // Build serverInfo with safe fallbacks
+    const serverInfo = rawServerInfo
+        ? {
+            name: rawServerInfo.name || "unknown",
+            version: rawServerInfo.version,
+            metadata: rawServerInfo.metadata,
+        }
+        : undefined;
+    // ServerCapabilities can be undefined - that's valid per MCP spec
+    const serverCapabilities = rawServerCapabilities ?? undefined;
+    // Log warning if server didn't provide initialization info
+    if (!serverInfo && !options.jsonOnly) {
+        console.log("⚠️  Server did not provide serverInfo during initialization");
+    }
+    const response = await client.listTools();
+    const tools = response.tools || [];
+    // Emit JSONL tool discovery events for audit-worker parsing
+    for (const tool of tools) {
+        emitToolDiscovered(tool);
+    }
+    emitToolsDiscoveryComplete(tools.length);
+    if (!options.jsonOnly) {
+        console.log(`🔧 Found ${tools.length} tool${tools.length !== 1 ? "s" : ""}`);
+    }
+    // Fetch resources for new capability assessments
+    let resources = [];
+    let resourceTemplates = [];
+    try {
+        const resourcesResponse = await client.listResources();
+        resources = (resourcesResponse.resources || []).map((r) => ({
+            uri: r.uri,
+            name: r.name,
+            description: r.description,
+            mimeType: r.mimeType,
+        }));
+        // resourceTemplates may be typed as unknown in some SDK versions
+        const templates = resourcesResponse.resourceTemplates;
+        if (templates) {
+            resourceTemplates = templates.map((rt) => ({
+                uriTemplate: rt.uriTemplate,
+                name: rt.name,
+                description: rt.description,
+                mimeType: rt.mimeType,
+            }));
+        }
+        if (!options.jsonOnly &&
+            (resources.length > 0 || resourceTemplates.length > 0)) {
+            console.log(`📦 Found ${resources.length} resource(s) and ${resourceTemplates.length} resource template(s)`);
+        }
+    }
+    catch {
+        // Server may not support resources - that's okay
+        if (!options.jsonOnly) {
+            console.log("📦 Resources not supported by server");
+        }
+    }
+    // Fetch prompts for new capability assessments
+    let prompts = [];
+    try {
+        const promptsResponse = await client.listPrompts();
+        prompts = (promptsResponse.prompts || []).map((p) => ({
+            name: p.name,
+            description: p.description,
+            arguments: p.arguments?.map((a) => ({
+                name: a.name,
+                description: a.description,
+                required: a.required,
+            })),
+        }));
+        if (!options.jsonOnly && prompts.length > 0) {
+            console.log(`💬 Found ${prompts.length} prompt(s)`);
+        }
+    }
+    catch {
+        // Server may not support prompts - that's okay
+        if (!options.jsonOnly) {
+            console.log("💬 Prompts not supported by server");
+        }
+    }
+    // State management for resumable assessments
+    const stateManager = new AssessmentStateManager(options.serverName);
+    if (stateManager.exists() && !options.noResume) {
+        const summary = stateManager.getSummary();
+        if (summary) {
+            if (!options.jsonOnly) {
+                console.log(`\n📋 Found interrupted session from ${summary.startedAt}`);
+                console.log(`   Completed modules: ${summary.completedModules.length > 0 ? summary.completedModules.join(", ") : "none"}`);
+            }
+            if (options.resume) {
+                if (!options.jsonOnly) {
+                    console.log("   Resuming from previous state...");
+                }
+                // Will use partial results later
+            }
+            else if (!options.jsonOnly) {
+                console.log("   Use --resume to continue or --no-resume to start fresh");
+                // Clear state and start fresh by default
+                stateManager.clear();
+            }
+        }
+    }
+    else if (options.noResume && stateManager.exists()) {
+        stateManager.clear();
+        if (!options.jsonOnly) {
+            console.log("🗑️  Cleared previous assessment state");
+        }
+    }
+    // Pre-flight validation checks
+    if (options.preflightOnly) {
+        const preflightResult = {
+            passed: true,
+            toolCount: tools.length,
+            errors: [],
+        };
+        // Check 1: Tools exist
+        if (tools.length === 0) {
+            preflightResult.passed = false;
+            preflightResult.errors.push("No tools discovered from server");
+        }
+        // Check 2: Manifest valid (if source path provided)
+        if (options.sourceCodePath) {
+            const manifestPath = path.join(options.sourceCodePath, "manifest.json");
+            if (fs.existsSync(manifestPath)) {
+                try {
+                    JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+                    preflightResult.manifestValid = true;
+                }
+                catch {
+                    preflightResult.passed = false;
+                    preflightResult.manifestValid = false;
+                    preflightResult.errors.push("Invalid manifest.json (JSON parse error)");
+                }
+            }
+        }
+        // Check 3: First tool responds (basic connectivity)
+        if (tools.length > 0) {
+            try {
+                const callTool = createCallToolWrapper(client);
+                const firstToolResult = await callTool(tools[0].name, {});
+                preflightResult.serverResponsive = !firstToolResult.isError;
+                if (firstToolResult.isError) {
+                    preflightResult.errors.push(`First tool (${tools[0].name}) returned error - server may not be fully functional`);
+                }
+            }
+            catch (e) {
+                preflightResult.serverResponsive = false;
+                preflightResult.errors.push(`First tool call failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        await client.close();
+        // Output pre-flight result
+        console.log(JSON.stringify(preflightResult, null, 2));
+        setTimeout(() => process.exit(preflightResult.passed ? 0 : 1), 10);
+        // Return empty result (won't be used due to process.exit)
+        return {};
+    }
+    const config = buildConfig(options);
+    // Emit modules_configured event for consumer progress tracking
+    if (config.assessmentCategories) {
+        const enabled = [];
+        const skipped = [];
+        for (const [key, value] of Object.entries(config.assessmentCategories)) {
+            if (value) {
+                enabled.push(key);
+            }
+            else {
+                skipped.push(key);
+            }
+        }
+        const reason = options.onlyModules?.length
+            ? "only-modules"
+            : options.skipModules?.length
+                ? "skip-modules"
+                : "default";
+        emitModulesConfigured(enabled, skipped, reason);
+    }
+    const orchestrator = new AssessmentOrchestrator(config);
+    if (!options.jsonOnly) {
+        if (orchestrator.isClaudeEnabled()) {
+            console.log("🤖 Claude Code integration enabled");
+        }
+        else if (options.claudeEnabled) {
+            console.log("⚠️  Claude Code requested but not available");
+        }
+    }
+    let sourceFiles = {};
+    if (options.sourceCodePath && fs.existsSync(options.sourceCodePath)) {
+        sourceFiles = loadSourceFiles(options.sourceCodePath);
+        if (!options.jsonOnly) {
+            console.log(`📁 Loaded source files from: ${options.sourceCodePath}`);
+        }
+    }
+    // Create readResource wrapper for ResourceAssessor
+    const readResource = async (uri) => {
+        const response = await client.readResource({ uri });
+        // Extract text content from response
+        if (response.contents && response.contents.length > 0) {
+            const content = response.contents[0];
+            if ("text" in content && content.text) {
+                return content.text;
+            }
+            if ("blob" in content && content.blob) {
+                // Return base64 blob as string
+                return content.blob;
+            }
+        }
+        return "";
+    };
+    // Create getPrompt wrapper for PromptAssessor
+    const getPrompt = async (name, args) => {
+        const response = await client.getPrompt({ name, arguments: args });
+        return {
+            messages: (response.messages || []).map((m) => ({
+                role: m.role,
+                content: typeof m.content === "string" ? m.content : JSON.stringify(m.content),
+            })),
+        };
+    };
+    // Progress callback to emit JSONL events for real-time monitoring
+    const onProgress = (event) => {
+        if (event.type === "test_batch") {
+            emitTestBatch(event.module, event.completed, event.total, event.batchSize, event.elapsed);
+        }
+        else if (event.type === "vulnerability_found") {
+            emitVulnerabilityFound(event.tool, event.pattern, event.confidence, event.evidence, event.riskLevel, event.requiresReview, event.payload);
+        }
+        else if (event.type === "annotation_missing") {
+            emitAnnotationMissing(event.tool, event.title, event.description, event.parameters, event.inferredBehavior);
+        }
+        else if (event.type === "annotation_misaligned") {
+            emitAnnotationMisaligned(event.tool, event.title, event.description, event.parameters, event.field, event.actual, event.expected, event.confidence, event.reason);
+        }
+        else if (event.type === "annotation_review_recommended") {
+            emitAnnotationReviewRecommended(event.tool, event.title, event.description, event.parameters, event.field, event.actual, event.inferred, event.confidence, event.isAmbiguous, event.reason);
+        }
+        else if (event.type === "annotation_aligned") {
+            emitAnnotationAligned(event.tool, event.confidence, event.annotations);
+        }
+        // module_started and module_complete are handled by orchestrator directly
+    };
+    const context = {
+        serverName: options.serverName,
+        tools,
+        callTool: createCallToolWrapper(client),
+        listTools: async () => {
+            const response = await client.listTools();
+            return response.tools;
+        },
+        config,
+        sourceCodePath: options.sourceCodePath,
+        onProgress,
+        ...sourceFiles,
+        // New capability assessment data
+        resources,
+        resourceTemplates,
+        prompts,
+        readResource,
+        getPrompt,
+        // Server info for protocol conformance checks
+        serverInfo,
+        serverCapabilities: serverCapabilities,
+    };
+    if (!options.jsonOnly) {
+        console.log(`\n🏃 Running assessment with ${Object.keys(config.assessmentCategories || {}).length} modules...`);
+        console.log("");
+    }
+    const results = await orchestrator.runFullAssessment(context);
+    // Emit assessment complete event
+    const defaultOutputPath = `/tmp/inspector-full-assessment-${options.serverName}.json`;
+    emitAssessmentComplete(results.overallStatus, results.totalTestsRun, results.executionTime, options.outputPath || defaultOutputPath);
+    await client.close();
+    return results;
+}

package/build/lib/cli-parser.js

@@ -0,0 +1,419 @@
+/**
+ * CLI Parser Module
+ *
+ * Handles command-line argument parsing, validation, and help text for
+ * the mcp-assess-full CLI tool.
+ *
+ * Extracted from assess-full.ts as part of Issue #90 modularization.
+ *
+ * @module cli/lib/cli-parser
+ */
+import { ASSESSMENT_CATEGORY_METADATA, } from "../../../client/lib/lib/assessmentTypes.js";
+import { ASSESSMENT_PROFILES, isValidProfileName, getProfileHelpText, } from "../profiles.js";
+// ============================================================================
+// Constants
+// ============================================================================
+// Valid module names derived from ASSESSMENT_CATEGORY_METADATA
+const VALID_MODULE_NAMES = Object.keys(ASSESSMENT_CATEGORY_METADATA);
+// ============================================================================
+// Validation Functions
+// ============================================================================
+/**
+ * Validate module names from CLI input
+ *
+ * @param input - Comma-separated module names
+ * @param flagName - Flag name for error messages (e.g., "--skip-modules")
+ * @returns Array of validated module names, or empty array if invalid
+ */
+export function validateModuleNames(input, flagName) {
+    const names = input
+        .split(",")
+        .map((n) => n.trim())
+        .filter(Boolean);
+    const invalid = names.filter((n) => !VALID_MODULE_NAMES.includes(n));
+    if (invalid.length > 0) {
+        console.error(`Error: Invalid module name(s) for ${flagName}: ${invalid.join(", ")}`);
+        console.error(`Valid modules: ${VALID_MODULE_NAMES.join(", ")}`);
+        setTimeout(() => process.exit(1), 10);
+        return [];
+    }
+    return names;
+}
+/**
+ * Validate parsed options for consistency and requirements
+ *
+ * @param options - Partial assessment options to validate
+ * @returns Validation result with any errors
+ */
+export function validateArgs(options) {
+    const errors = [];
+    // Server name is required
+    if (!options.serverName) {
+        errors.push("--server is required");
+    }
+    // Validate mutual exclusivity of --profile, --skip-modules, and --only-modules
+    if (options.profile &&
+        (options.skipModules?.length || options.onlyModules?.length)) {
+        errors.push("--profile cannot be used with --skip-modules or --only-modules");
+    }
+    if (options.skipModules?.length && options.onlyModules?.length) {
+        errors.push("--skip-modules and --only-modules are mutually exclusive");
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+// ============================================================================
+// Argument Parsing
+// ============================================================================
+/**
+ * Parse command-line arguments
+ *
+ * @param argv - Command-line arguments (defaults to process.argv.slice(2))
+ * @returns Parsed assessment options
+ */
+export function parseArgs(argv) {
+    const args = argv ?? process.argv.slice(2);
+    const options = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg)
+            continue;
+        switch (arg) {
+            case "--server":
+            case "-s":
+                options.serverName = args[++i];
+                break;
+            case "--config":
+            case "-c":
+                options.serverConfigPath = args[++i];
+                break;
+            case "--output":
+            case "-o":
+                options.outputPath = args[++i];
+                break;
+            case "--source":
+                options.sourceCodePath = args[++i];
+                break;
+            case "--pattern-config":
+            case "-p":
+                options.patternConfigPath = args[++i];
+                break;
+            case "--performance-config":
+                options.performanceConfigPath = args[++i];
+                break;
+            case "--claude-enabled":
+                options.claudeEnabled = true;
+                break;
+            case "--claude-http":
+                // Enable Claude Bridge with HTTP transport (connects to mcp-auditor)
+                options.claudeEnabled = true;
+                options.claudeHttp = true;
+                break;
+            case "--mcp-auditor-url": {
+                const urlValue = args[++i];
+                if (!urlValue || urlValue.startsWith("-")) {
+                    console.error("Error: --mcp-auditor-url requires a URL argument");
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                try {
+                    new URL(urlValue); // Validate URL format
+                    options.mcpAuditorUrl = urlValue;
+                }
+                catch {
+                    console.error(`Error: Invalid URL for --mcp-auditor-url: ${urlValue}`);
+                    console.error("  Expected format: http://hostname:port or https://hostname:port");
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                break;
+            }
+            case "--full":
+                options.fullAssessment = true;
+                break;
+            case "--verbose":
+            case "-v":
+                options.verbose = true;
+                options.logLevel = "debug";
+                break;
+            case "--silent":
+                options.logLevel = "silent";
+                break;
+            case "--log-level": {
+                const levelValue = args[++i];
+                const validLevels = [
+                    "silent",
+                    "error",
+                    "warn",
+                    "info",
+                    "debug",
+                ];
+                if (!validLevels.includes(levelValue)) {
+                    console.error(`Invalid log level: ${levelValue}. Valid options: ${validLevels.join(", ")}`);
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                options.logLevel = levelValue;
+                break;
+            }
+            case "--json":
+                options.jsonOnly = true;
+                break;
+            case "--format":
+            case "-f": {
+                const formatValue = args[++i];
+                if (formatValue !== "json" && formatValue !== "markdown") {
+                    console.error(`Invalid format: ${formatValue}. Valid options: json, markdown`);
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                options.format = formatValue;
+                break;
+            }
+            case "--include-policy":
+                options.includePolicy = true;
+                break;
+            case "--preflight":
+                options.preflightOnly = true;
+                break;
+            case "--compare":
+                options.comparePath = args[++i];
+                break;
+            case "--diff-only":
+                options.diffOnly = true;
+                break;
+            case "--resume":
+                options.resume = true;
+                break;
+            case "--no-resume":
+                options.noResume = true;
+                break;
+            case "--temporal-invocations":
+                options.temporalInvocations = parseInt(args[++i], 10);
+                break;
+            case "--skip-temporal":
+                options.skipTemporal = true;
+                break;
+            case "--profile": {
+                const profileValue = args[++i];
+                if (!profileValue) {
+                    console.error("Error: --profile requires a profile name");
+                    console.error(`Valid profiles: ${Object.keys(ASSESSMENT_PROFILES).join(", ")}`);
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                if (!isValidProfileName(profileValue)) {
+                    console.error(`Error: Invalid profile name: ${profileValue}`);
+                    console.error(`Valid profiles: ${Object.keys(ASSESSMENT_PROFILES).join(", ")}`);
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                options.profile = profileValue;
+                break;
+            }
+            case "--skip-modules": {
+                const skipValue = args[++i];
+                if (!skipValue) {
+                    console.error("Error: --skip-modules requires a comma-separated list");
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                options.skipModules = validateModuleNames(skipValue, "--skip-modules");
+                if (options.skipModules.length === 0 && skipValue) {
+                    options.helpRequested = true;
+                    return options;
+                }
+                break;
+            }
+            case "--only-modules": {
+                const onlyValue = args[++i];
+                if (!onlyValue) {
+                    console.error("Error: --only-modules requires a comma-separated list");
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+                options.onlyModules = validateModuleNames(onlyValue, "--only-modules");
+                if (options.onlyModules.length === 0 && onlyValue) {
+                    options.helpRequested = true;
+                    return options;
+                }
+                break;
+            }
+            case "--help":
+            case "-h":
+                printHelp();
+                options.helpRequested = true;
+                return options;
+            default:
+                if (!arg.startsWith("-")) {
+                    if (!options.serverName) {
+                        options.serverName = arg;
+                    }
+                }
+                else {
+                    console.error(`Unknown argument: ${arg}`);
+                    printHelp();
+                    setTimeout(() => process.exit(1), 10);
+                    options.helpRequested = true;
+                    return options;
+                }
+        }
+    }
+    // Validate mutual exclusivity of --profile, --skip-modules, and --only-modules
+    if (options.profile &&
+        (options.skipModules?.length || options.onlyModules?.length)) {
+        console.error("Error: --profile cannot be used with --skip-modules or --only-modules");
+        setTimeout(() => process.exit(1), 10);
+        options.helpRequested = true;
+        return options;
+    }
+    if (options.skipModules?.length && options.onlyModules?.length) {
+        console.error("Error: --skip-modules and --only-modules are mutually exclusive");
+        setTimeout(() => process.exit(1), 10);
+        options.helpRequested = true;
+        return options;
+    }
+    if (!options.serverName) {
+        console.error("Error: --server is required");
+        printHelp();
+        setTimeout(() => process.exit(1), 10);
+        options.helpRequested = true;
+        return options;
+    }
+    // Environment variable fallbacks (matches run-security-assessment.ts behavior)
+    // INSPECTOR_CLAUDE=true enables Claude with HTTP transport
+    if (process.env.INSPECTOR_CLAUDE === "true" && !options.claudeEnabled) {
+        options.claudeEnabled = true;
+        options.claudeHttp = true; // HTTP transport when enabled via env var
+    }
+    // INSPECTOR_MCP_AUDITOR_URL overrides default URL (only if not set via CLI)
+    if (process.env.INSPECTOR_MCP_AUDITOR_URL && !options.mcpAuditorUrl) {
+        const envUrl = process.env.INSPECTOR_MCP_AUDITOR_URL;
+        try {
+            new URL(envUrl);
+            options.mcpAuditorUrl = envUrl;
+        }
+        catch {
+            console.warn(`Warning: Invalid INSPECTOR_MCP_AUDITOR_URL: ${envUrl}, using default`);
+        }
+    }
+    return options;
+}
+// ============================================================================
+// Help Text
+// ============================================================================
+/**
+ * Print help message to console
+ */
+export function printHelp() {
+    console.log(`
+Usage: mcp-assess-full [options] [server-name]
+
+Run comprehensive MCP server assessment with 16 assessor modules organized in 4 tiers.
+
+Options:
+  --server, -s <name>    Server name (required, or pass as first positional arg)
+  --config, -c <path>    Path to server config JSON
+  --output, -o <path>    Output path (default: /tmp/inspector-full-assessment-<server>.<ext>)
+  --source <path>        Source code path for deep analysis (AUP, portability, etc.)
+  --pattern-config, -p <path>  Path to custom annotation pattern JSON
+  --performance-config <path>  Path to performance tuning JSON (batch sizes, timeouts, etc.)
+  --format, -f <type>    Output format: json (default) or markdown
+  --include-policy       Include policy compliance mapping in report (30 requirements)
+  --preflight            Run quick validation only (tools exist, manifest valid, server responds)
+  --compare <path>       Compare current assessment against baseline JSON file
+  --diff-only            Output only the comparison diff (requires --compare)
+  --resume               Resume from previous interrupted assessment
+  --no-resume            Force fresh start, clear any existing state
+  --claude-enabled       Enable Claude Code integration (CLI transport: requires 'claude' binary)
+  --claude-http          Enable Claude Code via HTTP transport (connects to mcp-auditor proxy)
+  --mcp-auditor-url <url>  mcp-auditor URL for HTTP transport (default: http://localhost:8085)
+  --full                 Enable all assessment modules (default)
+  --profile <name>       Use predefined module profile (quick, security, compliance, full)
+  --temporal-invocations <n>  Number of invocations per tool for rug pull detection (default: 25)
+  --skip-temporal        Skip temporal/rug pull testing (faster assessment)
+  --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)
+  --verbose, -v          Enable verbose logging (same as --log-level debug)
+  --silent               Suppress all diagnostic logging
+  --log-level <level>    Set log level: silent, error, warn, info (default), debug
+                         Also supports LOG_LEVEL environment variable
+  --help, -h             Show this help message
+
+Environment Variables:
+  INSPECTOR_CLAUDE=true         Enable Claude with HTTP transport (same as --claude-http)
+  INSPECTOR_MCP_AUDITOR_URL     Override default mcp-auditor URL (default: http://localhost:8085)
+  LOG_LEVEL                     Set log level (overridden by --log-level flag)
+
+${getProfileHelpText()}
+Module Selection:
+  --profile, --skip-modules, and --only-modules are mutually exclusive.
+  Use --profile for common assessment scenarios.
+  Use --skip-modules for custom runs by disabling expensive modules.
+  Use --only-modules to focus on specific areas (e.g., tool annotation PRs).
+
+  Valid module names (new naming):
+    functionality, security, errorHandling, protocolCompliance, aupCompliance,
+    toolAnnotations, prohibitedLibraries, manifestValidation, authentication,
+    temporal, resources, prompts, crossCapability, developerExperience,
+    portability, externalAPIScanner
+
+  Legacy module names (deprecated, will map to new names):
+    documentation -> developerExperience
+    usability -> developerExperience
+    mcpSpecCompliance -> protocolCompliance
+    protocolConformance -> protocolCompliance
+
+Module Tiers (16 total):
+  Tier 1 - Core Security (Always Run):
+    • Functionality      - Tests all tools work correctly
+    • Security           - Prompt injection & vulnerability testing
+    • Error Handling     - Validates error responses
+    • Protocol Compliance - MCP protocol + JSON-RPC validation
+    • AUP Compliance     - Acceptable Use Policy checks
+    • Temporal           - Rug pull/temporal behavior change detection
+
+  Tier 2 - Compliance (MCP Directory):
+    • Tool Annotations   - readOnlyHint/destructiveHint validation
+    • Prohibited Libs    - Dependency security checks
+    • Manifest           - MCPB manifest.json validation
+    • Authentication     - OAuth/auth evaluation
+
+  Tier 3 - Capability-Based (Conditional):
+    • Resources          - Resource capability assessment
+    • Prompts            - Prompt capability assessment
+    • Cross-Capability   - Chained vulnerability detection
+
+  Tier 4 - Extended (Optional):
+    • Developer Experience - Documentation + usability assessment
+    • Portability        - Cross-platform compatibility
+    • External API       - External service detection
+
+Examples:
+  # Profile-based (recommended):
+  mcp-assess-full my-server --profile quick         # CI/CD fast check (~30s)
+  mcp-assess-full my-server --profile security      # Security audit (~2-3min)
+  mcp-assess-full my-server --profile compliance    # Directory submission (~5min)
+  mcp-assess-full my-server --profile full          # Comprehensive audit (~10-15min)
+
+  # Custom module selection:
+  mcp-assess-full my-server --skip-modules temporal,resources  # Skip expensive modules
+  mcp-assess-full my-server --only-modules functionality,toolAnnotations  # Annotation PR review
+
+  # Advanced options:
+  mcp-assess-full --server my-server --source ./my-server --output ./results.json
+  mcp-assess-full --server my-server --format markdown --include-policy
+  mcp-assess-full --server my-server --compare ./baseline.json --diff-only
+  `);
+}

package/package.json

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