@qulib/mcp 0.3.1 → 0.4.1

package/README.md

@@ -2,6 +2,28 @@
 
 **@qulib/mcp** is an MCP server that exposes Qulib so AI clients can analyze a deployed URL for release confidence, accessibility, broken links, console noise, and prioritized gaps (CLI entry `qulib-mcp`).
 
+## Setup
+
+To enable LLM-powered scenario generation, add your Anthropic API key to the
+`env` block in your MCP host config (Claude Desktop, Claude Code, Cursor, etc.):
+
+```json
+{
+  "mcpServers": {
+    "qulib": {
+      "command": "npx",
+      "args": ["@qulib/mcp"],
+      "env": {
+        "ANTHROPIC_API_KEY": "sk-ant-..."
+      }
+    }
+  }
+}
+```
+
+Without this key, qulib still runs but uses built-in template scenarios only.
+Your key is never stored by qulib — it is read from your local config at runtime.
+
 ## What it does
 
 Tools:

package/dist/compact-analyze-payload.d.ts

@@ -3,20 +3,103 @@ export declare function buildCompactAnalyzePayload(result: AnalyzeResult, includ
     includeFullReport: boolean;
     note: string;
     detectedAuth?: {
-        type: "unknown" | "form-login" | "none" | "oauth" | "magic-link";
+        type: "unknown" | "form-login" | "oauth" | "magic-link" | "none";
         loginUrl: string | null;
-        hasAuth: boolean;
         provider: string | null;
+        hasAuth: boolean;
         observedSelectors: {
             usernameSelector: string | null;
             passwordSelector: string | null;
             submitSelector: string | null;
         } | null;
         oauthButtons: {
-            provider: string;
             text: string;
+            provider: string;
         }[];
         recommendation: string;
+        authOptions?: {
+            type: "unknown" | "form-login" | "oauth" | "oauth-unknown" | "form-multi" | "magic-link";
+            label: string;
+            id: string;
+            provider: string | null;
+            source: "built-in" | "user-local" | "heuristic";
+            automatable: boolean;
+            confidence: "high" | "medium" | "low";
+            requirements: {
+                method: "storage-state";
+                instruction: string;
+            } | {
+                method: "credentials";
+                fields: {
+                    type: "password" | "text" | "email" | "select" | "checkbox";
+                    name: string;
+                    label: string;
+                    observedOptions: string[];
+                }[];
+            } | {
+                method: "unknown";
+                instruction: string;
+            };
+        }[] | undefined;
+    } | undefined;
+    repoInventory: {
+        scannedAt: string;
+        routes: {
+            path: string;
+            method: "unknown" | "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+            file: string;
+        }[];
+        repoPath: string;
+        testFiles: {
+            type: "playwright" | "cypress-e2e" | "cypress-component" | "jest" | "vitest" | "other";
+            file: string;
+            coveredPaths: string[];
+        }[];
+        missingTestIds: string[];
+        cypressStructure: {
+            detected: boolean;
+            hasCommandsFile: boolean;
+            existingE2eFiles: string[];
+            existingComponentFiles: string[];
+            e2eFolder?: string | undefined;
+            componentFolder?: string | undefined;
+            fixturesFolder?: string | undefined;
+            supportFolder?: string | undefined;
+        };
+        framework?: {
+            confidence: "high" | "medium" | "low";
+            evidence: string[];
+            primary: "unknown" | "nextjs-app-router" | "nextjs-pages-router" | "express" | "remix" | "nuxt" | "sveltekit" | "astro" | "vite";
+            testFrameworks: ("playwright" | "cypress-e2e" | "cypress-component" | "jest" | "vitest" | "other")[];
+        } | undefined;
+        automationMaturity?: {
+            label: string;
+            level: number;
+            computedAt: string;
+            repoPath: string;
+            overallScore: number;
+            dimensions: {
+                recommendations: string[];
+                dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
+                score: number;
+                weight: number;
+                evidence: string[];
+            }[];
+            topRecommendations: string[];
+        } | undefined;
+    } | null;
+    decisionLogPreview: {
+        timestamp: string;
+        reason: string;
+        phase: "observe" | "think" | "act" | "harness";
+        decision: string;
+        metadata?: Record<string, unknown> | undefined;
+    }[];
+    automationMaturitySummary?: {
+        overallScore: number;
+        level: number;
+        label: string;
+        topRecommendations: string[];
     } | undefined;
     summary: {
         status: import("@qulib/core").AnalyzeStatus;
@@ -39,7 +122,7 @@ export declare function buildCompactAnalyzePayload(result: AnalyzeResult, includ
     topGaps: {
         path: string;
         category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage";
-        severity: "high" | "medium" | "low" | "critical";
+        severity: "critical" | "high" | "medium" | "low";
         reason: string;
     }[];
     costIntelligenceSummary: {
@@ -92,7 +175,7 @@ export declare function buildCompactAnalyzePayload(result: AnalyzeResult, includ
         gapsSample: {
             path: string;
             id: string;
-            severity: "high" | "medium" | "low" | "critical";
+            severity: "critical" | "high" | "medium" | "low";
             reason: string;
             category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage";
             recommendation?: string | undefined;
@@ -108,37 +191,5 @@ export declare function buildCompactAnalyzePayload(result: AnalyzeResult, includ
         pagesSkipped: number;
         budgetExceeded: boolean;
     };
-    repoInventory: {
-        scannedAt: string;
-        routes: {
-            path: string;
-            method: "unknown" | "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
-            file: string;
-        }[];
-        repoPath: string;
-        testFiles: {
-            type: "playwright" | "cypress-e2e" | "cypress-component" | "jest" | "vitest" | "other";
-            file: string;
-            coveredPaths: string[];
-        }[];
-        missingTestIds: string[];
-        cypressStructure: {
-            detected: boolean;
-            hasCommandsFile: boolean;
-            existingE2eFiles: string[];
-            existingComponentFiles: string[];
-            e2eFolder?: string | undefined;
-            componentFolder?: string | undefined;
-            fixturesFolder?: string | undefined;
-            supportFolder?: string | undefined;
-        };
-    } | null;
-    decisionLogPreview: {
-        timestamp: string;
-        reason: string;
-        phase: "observe" | "think" | "act" | "harness";
-        decision: string;
-        metadata?: Record<string, unknown> | undefined;
-    }[];
 };
 //# sourceMappingURL=compact-analyze-payload.d.ts.map

package/dist/compact-analyze-payload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compact-analyze-payload.d.ts","sourceRoot":"","sources":["../src/compact-analyze-payload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAqBjD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,aAAa,EAAE,iBAAiB,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BA0E0igB,CAAC;sBAA4C,CAAC;sBAA4C,CAAC;iBAAuC,CAAC;;;;;;;;;;;;;;;;;uBAAghB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAAt7e,CAAC;2BAA6C,CAAC;0BAA4C,CAAC;yBAA2C,CAAC;;;;;;;;;;EAD3+C"}
+{"version":3,"file":"compact-analyze-payload.d.ts","sourceRoot":"","sources":["../src/compact-analyze-payload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAqBjD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,aAAa,EAAE,iBAAiB,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAkFs3L,CAAC;2BAA6C,CAAC;0BAA4C,CAAC;yBAA2C,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAAkqT,CAAC;sBAA4C,CAAC;sBAA4C,CAAC;iBAAuC,CAAC;;;;;;;;;;;;;;;;;uBAAghB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;EAD/4gB"}

package/dist/compact-analyze-payload.js

@@ -78,6 +78,14 @@ export function buildCompactAnalyzePayload(result, includeFullReport) {
             pagesSkipped: result.routeInventory.pagesSkipped,
             budgetExceeded: result.routeInventory.budgetExceeded,
         },
+        ...(result.repoInventory?.automationMaturity && {
+            automationMaturitySummary: {
+                overallScore: result.repoInventory.automationMaturity.overallScore,
+                level: result.repoInventory.automationMaturity.level,
+                label: result.repoInventory.automationMaturity.label,
+                topRecommendations: result.repoInventory.automationMaturity.topRecommendations,
+            },
+        }),
         repoInventory: result.repoInventory,
         decisionLogPreview: result.decisionLog.slice(-8),
         ...(result.detectedAuth !== undefined && { detectedAuth: result.detectedAuth }),

package/dist/index.js

@@ -1,11 +1,38 @@
 #!/usr/bin/env node
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+// Naming convention: qulib_{verb}_{noun}. Existing 3 tools predate this convention and retain their names for backwards compatibility.
+//
+// TODO(@qulib/mcp): When tool count exceeds ~10, evaluate MCP resource types and
+// prompt templates as complementary surfaces. Tool explosion is an MCP anti-pattern.
+// Prefer composable tools over one-tool-per-capability.
+//
+// TODO(@qulib/mcp): Evaluate tool-level permission modeling when MCP spec stabilizes.
+// Today: all tools are equally trusted. Future: read-only tools (detect_auth, explore_auth)
+// vs. write-capable tools (analyze_app with writeArtifacts) should carry different trust levels.
+import { isAbsolute, normalize, resolve } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { analyzeApp, detectAuth, exploreAuth } from '@qulib/core';
+import { analyzeApp, detectAuth, exploreAuth, scanRepo, computeAutomationMaturity, } from '@qulib/core';
 import { z } from 'zod';
 import { buildCompactAnalyzePayload } from './compact-analyze-payload.js';
 import { log } from './logger.js';
+function toolError(code, message, detail) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ error: { code, message, detail: detail ?? null } }, null, 2),
+            },
+        ],
+    };
+}
+function stderrTelemetrySink() {
+    return {
+        emit(event) {
+            process.stderr.write(`${JSON.stringify(event)}\n`);
+        },
+    };
+}
+const telemetrySink = process.env.QULIB_TELEMETRY_STDERR === '1' ? stderrTelemetrySink() : undefined;
 const mcpProgressLog = {
     info: (message) => log.info(message),
     warn: (message) => log.warn(message),
@@ -37,115 +64,51 @@ const AnalyzeInputSchema = z.object({
     testGenerationLimit: z.number().int().positive().max(50).optional(),
     enableLlmScenarios: z.boolean().optional(),
 });
-const server = new Server({
+const ScoreAutomationInputSchema = z.object({
+    repoPath: z.string().describe('Absolute path to the automation repository on the MCP host filesystem'),
+    includeFullDimensions: z
+        .boolean()
+        .optional()
+        .describe('When true, includes all dimension detail. Default false returns top recommendations only.'),
+});
+function validateAbsoluteRepoPath(repoPath) {
+    const norm = normalize(repoPath.trim());
+    if (!norm || norm === '.' || norm.includes('..')) {
+        throw new Error('repoPath must be absolute and must not contain path traversal segments');
+    }
+    if (!isAbsolute(norm)) {
+        throw new Error('repoPath must be an absolute path on the MCP host');
+    }
+    return resolve(norm);
+}
+const mcpServer = new McpServer({
     name: 'qulib-mcp',
-    version: '0.1.0',
+    version: '0.4.1',
+    description: 'Qulib QA intelligence platform — gap analysis, auth exploration, and quality scoring for deployed web applications',
 }, {
     capabilities: {
         tools: {},
     },
 });
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [
-        {
-            name: 'explore_auth',
-            description: 'Use this BEFORE analyze_app when scanning unfamiliar apps. Returns all detected sign-in paths with per-path requirements describing what credentials or actions the agent must collect from the user before calling analyze_app. Combines built-in OAuth/SSO labels, user-local patterns from ~/.qulib/providers.json, and heuristic unknown buttons.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    url: { type: 'string', description: 'Full URL of the deployed app or login page' },
-                    timeoutMs: { type: 'number', description: 'Navigation timeout in milliseconds (default 20000)' },
-                },
-                required: ['url'],
-            },
-        },
-        {
-            name: 'analyze_app',
-            description: 'Analyze a deployed web app for quality gaps. Default response is summary-first (top gaps, cost summary, next checks). Set includeFullReport for the full gapAnalysis. Optional llmMaxOutputTokensPerCall / llmTokenBudget (legacy), testGenerationLimit, enableLlmScenarios align with @qulib/core HarnessConfig.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    url: { type: 'string', description: 'Full URL of the deployed app' },
-                    maxPagesToScan: { type: 'number', description: 'Max pages to crawl (default 10)' },
-                    timeoutMs: { type: 'number', description: 'Per-page timeout in milliseconds (default 30000)' },
-                    auth: {
-                        description: 'Optional auth: form-login credentials or path to a storage state JSON from `qulib auth init`',
-                        oneOf: [
-                            {
-                                type: 'object',
-                                properties: {
-                                    type: { type: 'string', enum: ['form-login'] },
-                                    loginUrl: { type: 'string' },
-                                    username: { type: 'string' },
-                                    password: { type: 'string' },
-                                    usernameSelector: { type: 'string' },
-                                    passwordSelector: { type: 'string' },
-                                    submitSelector: { type: 'string' },
-                                    successUrlContains: { type: 'string' },
-                                },
-                                required: [
-                                    'type',
-                                    'loginUrl',
-                                    'username',
-                                    'password',
-                                    'usernameSelector',
-                                    'passwordSelector',
-                                    'submitSelector',
-                                ],
-                            },
-                            {
-                                type: 'object',
-                                properties: {
-                                    type: { type: 'string', enum: ['storage-state'] },
-                                    path: { type: 'string', description: 'Absolute path to storage state JSON on the MCP host' },
-                                },
-                                required: ['type', 'path'],
-                            },
-                        ],
-                    },
-                    includeFullReport: {
-                        type: 'boolean',
-                        description: 'When true, returns the full analyzeApp payload including all scenarios. Default false returns a summary-first shape.',
-                    },
-                    llmTokenBudget: {
-                        type: 'number',
-                        description: 'Legacy per-completion max output tokens (same as HarnessConfig.llmTokenBudget). Prefer llmMaxOutputTokensPerCall when both are set.',
-                    },
-                    llmMaxOutputTokensPerCall: {
-                        type: 'number',
-                        description: 'Optional override for per-completion max output tokens (maps to HarnessConfig.llmMaxOutputTokensPerCall).',
-                    },
-                    testGenerationLimit: { type: 'number', description: 'Max gaps fed into scenario generation (default 5).' },
-                    enableLlmScenarios: {
-                        type: 'boolean',
-                        description: 'When false, never calls an LLM for scenarios (default true when omitted).',
-                    },
-                },
-                required: ['url'],
-            },
-        },
-        {
-            name: 'detect_auth',
-            description: 'Detect the authentication pattern used by a deployed web app. Returns the auth type (form-login, oauth, magic-link, none, or unknown) and a recommendation for how to configure qulib to scan past it.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    url: { type: 'string', description: 'Full URL of the deployed app or login page' },
-                    timeoutMs: { type: 'number', description: 'Page load timeout in milliseconds (default 15000)' },
-                },
-                required: ['url'],
-            },
-        },
-    ],
-}));
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    if (request.params.name === 'explore_auth') {
-        const { url, timeoutMs } = z
-            .object({
-            url: z.string().url(),
-            timeoutMs: z.number().int().positive().optional(),
-        })
-            .parse(request.params.arguments ?? {});
+if (!process.env.ANTHROPIC_API_KEY) {
+    process.stderr.write('[qulib] WARN  ANTHROPIC_API_KEY is not set.\n' +
+        '              LLM scenario generation will be skipped — only template scenarios will run.\n' +
+        '              Add your key to the env block in your MCP host config.\n' +
+        '              See: https://github.com/TapeshN/qulib#setup\n');
+}
+const ExploreAuthToolInputSchema = z.object({
+    url: z.string().url().describe('Full URL of the deployed app or login page'),
+    timeoutMs: z.number().int().positive().optional().describe('Navigation timeout in milliseconds (default 20000)'),
+});
+const DetectAuthToolInputSchema = z.object({
+    url: z.string().url().describe('Full URL of the deployed app or login page'),
+    timeoutMs: z.number().int().positive().optional().describe('Page load timeout in milliseconds (default 15000)'),
+});
+mcpServer.registerTool('explore_auth', {
+    description: 'Use this BEFORE analyze_app when scanning unfamiliar apps. Returns all detected sign-in paths with per-path requirements describing what credentials or actions the agent must collect from the user before calling analyze_app. Combines built-in OAuth/SSO labels, user-local patterns from ~/.qulib/providers.json, and heuristic unknown buttons.',
+    inputSchema: ExploreAuthToolInputSchema,
+}, async ({ url, timeoutMs }) => {
+    try {
         log.info(`explore_auth tool url=${url} timeoutMs=${timeoutMs ?? 20000}`);
         const result = await exploreAuth(url, timeoutMs, mcpProgressLog);
         log.info(`explore_auth tool done authRequired=${result.authRequired} paths=${result.authPaths.length}`);
@@ -153,13 +116,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         };
     }
-    if (request.params.name === 'detect_auth') {
-        const { url, timeoutMs } = z
-            .object({
-            url: z.string().url(),
-            timeoutMs: z.number().int().positive().optional(),
-        })
-            .parse(request.params.arguments ?? {});
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`explore_auth failed: ${msg}`);
+        return toolError('QULIB_AUTH_EXPLORE_FAILED', msg, err instanceof Error ? err.stack : undefined);
+    }
+});
+mcpServer.registerTool('detect_auth', {
+    description: 'Detect the authentication pattern used by a deployed web app. Returns the auth type (form-login, oauth, magic-link, none, or unknown) and a recommendation for how to configure qulib to scan past it.',
+    inputSchema: DetectAuthToolInputSchema,
+}, async ({ url, timeoutMs }) => {
+    try {
         log.info(`detect_auth tool url=${url} timeoutMs=${timeoutMs ?? 15000}`);
         const result = await detectAuth(url, timeoutMs, mcpProgressLog);
         const providerSummary = result.oauthButtons.length > 0
@@ -170,63 +137,113 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         };
     }
-    if (request.params.name !== 'analyze_app') {
-        throw new Error(`Unknown tool: ${request.params.name}`);
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`detect_auth failed: ${msg}`);
+        return toolError('QULIB_AUTH_DETECT_FAILED', msg, err instanceof Error ? err.stack : undefined);
     }
-    const input = AnalyzeInputSchema.parse(request.params.arguments ?? {});
-    const successIndicator = input.auth?.type === 'form-login' &&
-        input.auth.successUrlContains !== undefined &&
-        input.auth.successUrlContains !== ''
-        ? { urlContains: input.auth.successUrlContains }
-        : {};
-    const authConfig = input.auth?.type === 'form-login'
-        ? {
-            type: 'form-login',
-            loginUrl: input.auth.loginUrl,
-            credentials: { username: input.auth.username, password: input.auth.password },
-            selectors: {
-                username: input.auth.usernameSelector,
-                password: input.auth.passwordSelector,
-                submit: input.auth.submitSelector,
-            },
-            successIndicator,
+});
+mcpServer.registerTool('analyze_app', {
+    description: 'Analyze a deployed web app for quality gaps. Default response is summary-first (top gaps, cost summary, next checks). Set includeFullReport for the full gapAnalysis. Optional llmMaxOutputTokensPerCall / llmTokenBudget (legacy), testGenerationLimit, enableLlmScenarios align with @qulib/core HarnessConfig.',
+    inputSchema: AnalyzeInputSchema,
+}, async (input) => {
+    try {
+        const successIndicator = input.auth?.type === 'form-login' &&
+            input.auth.successUrlContains !== undefined &&
+            input.auth.successUrlContains !== ''
+            ? { urlContains: input.auth.successUrlContains }
+            : {};
+        const authConfig = input.auth?.type === 'form-login'
+            ? {
+                type: 'form-login',
+                loginUrl: input.auth.loginUrl,
+                credentials: { username: input.auth.username, password: input.auth.password },
+                selectors: {
+                    username: input.auth.usernameSelector,
+                    password: input.auth.passwordSelector,
+                    submit: input.auth.submitSelector,
+                },
+                successIndicator,
+            }
+            : input.auth?.type === 'storage-state'
+                ? { type: 'storage-state', path: input.auth.path }
+                : undefined;
+        const harnessConfig = {
+            maxPagesToScan: input.maxPagesToScan ?? 10,
+            maxDepth: 3,
+            minPagesForConfidence: 3,
+            timeoutMs: input.timeoutMs ?? 30000,
+            retryCount: 0,
+            llmTokenBudget: input.llmTokenBudget ?? input.llmMaxOutputTokensPerCall ?? 4096,
+            llmMaxOutputTokensPerCall: input.llmMaxOutputTokensPerCall,
+            testGenerationLimit: input.testGenerationLimit ?? 5,
+            enableLlmScenarios: input.enableLlmScenarios !== false,
+            readOnlyMode: true,
+            requireHumanReview: false,
+            failOnConsoleError: false,
+            explorer: 'playwright',
+            defaultAdapter: 'playwright',
+            adapters: ['playwright'],
+            ...(authConfig && { auth: authConfig }),
+        };
+        const result = await analyzeApp({
+            url: input.url,
+            writeArtifacts: false,
+            config: harnessConfig,
+            progressLog: mcpProgressLog,
+            telemetry: telemetrySink,
+        });
+        const payload = buildCompactAnalyzePayload(result, input.includeFullReport === true);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(payload, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`analyze_app failed: ${msg}`);
+        return toolError('QULIB_SCAN_FAILED', msg, err instanceof Error ? err.stack : undefined);
+    }
+});
+mcpServer.registerTool('qulib_score_automation', {
+    description: 'Score an automation repository for QA maturity across six dimensions: test coverage breadth, framework adoption, test-id hygiene, CI integration, auth test coverage, and component test ratio. Returns an overall score (0–100), maturity level (L1–L5), and prioritized recommendations.',
+    inputSchema: ScoreAutomationInputSchema,
+}, async ({ repoPath, includeFullDimensions }) => {
+    try {
+        // Security: repoPath is an absolute path on the MCP host. We validate it is absolute
+        // and does not contain path traversal sequences. The MCP host is responsible for ensuring
+        // the path is within an allowed directory. We do not enforce a sandbox here — that is a
+        // host-level concern.
+        const abs = validateAbsoluteRepoPath(repoPath);
+        log.info(`qulib_score_automation repoPath=${abs}`);
+        const repo = await scanRepo(abs);
+        const maturity = computeAutomationMaturity(repo);
+        const payload = includeFullDimensions === true
+            ? maturity
+            : {
+                overallScore: maturity.overallScore,
+                level: maturity.level,
+                label: maturity.label,
+                topRecommendations: maturity.topRecommendations,
+                repoPath: maturity.repoPath,
+                computedAt: maturity.computedAt,
+            };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('repoPath must')) {
+            return toolError('QULIB_INPUT_INVALID', msg, undefined);
         }
-        : input.auth?.type === 'storage-state'
-            ? { type: 'storage-state', path: input.auth.path }
-            : undefined;
-    const harnessConfig = {
-        maxPagesToScan: input.maxPagesToScan ?? 10,
-        maxDepth: 3,
-        minPagesForConfidence: 3,
-        timeoutMs: input.timeoutMs ?? 30000,
-        retryCount: 0,
-        llmTokenBudget: input.llmTokenBudget ?? input.llmMaxOutputTokensPerCall ?? 4096,
-        llmMaxOutputTokensPerCall: input.llmMaxOutputTokensPerCall,
-        testGenerationLimit: input.testGenerationLimit ?? 5,
-        enableLlmScenarios: input.enableLlmScenarios !== false,
-        readOnlyMode: true,
-        requireHumanReview: false,
-        failOnConsoleError: false,
-        explorer: 'playwright',
-        defaultAdapter: 'playwright',
-        adapters: ['playwright'],
-        ...(authConfig && { auth: authConfig }),
-    };
-    const result = await analyzeApp({
-        url: input.url,
-        writeArtifacts: false,
-        config: harnessConfig,
-        progressLog: mcpProgressLog,
-    });
-    const payload = buildCompactAnalyzePayload(result, input.includeFullReport === true);
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify(payload, null, 2),
-            },
-        ],
-    };
+        log.error(`qulib_score_automation failed: ${msg}`);
+        return toolError('QULIB_REPO_SCORE_FAILED', msg, err instanceof Error ? err.stack : undefined);
+    }
 });
 const transport = new StdioServerTransport();
-await server.connect(transport);
+await mcpServer.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qulib/mcp",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "MCP server for Qulib — AI-callable QA gap analysis",
   "license": "MIT",
   "author": "Tapesh Nagarwal",
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@qulib/core": "0.3.1",
+    "@qulib/core": "0.4.1",
     "zod": "^3.23.0"
   },
   "devDependencies": {