@qulib/mcp 0.4.1 → 0.4.3

package/README.md

@@ -31,6 +31,7 @@ Tools:
 - **`explore_auth(url, timeoutMs?)`** — list all sign-in paths (OAuth, unknown SSO heuristics, forms, magic link) and what the agent must collect before `analyze_app`. Prefer this on unfamiliar apps.
 - **`analyze_app`** — quality scan (optional form-login or storage-state auth). **Default payload is summary-first:** `summary`, `topGaps`, `costIntelligenceSummary`, `nextDeterministicChecks`, small previews. Set **`includeFullReport: true`** for the full `analyzeApp` result (all scenarios). Optional harness overrides: **`llmMaxOutputTokensPerCall`**, **`llmTokenBudget`** (legacy), **`testGenerationLimit`**, **`enableLlmScenarios`** (default true when omitted).
 - **`detect_auth(url, timeoutMs?)`** — single-pattern auth guess with a short recommendation (lighter than `explore_auth`).
+- **`qulib_score_automation(repoPath, includeFullDimensions?)`** — score a local automation repo across six dimensions (test coverage breadth, framework adoption, test-id hygiene, CI integration, auth test coverage, component test ratio). Returns an overall 0–100 score, maturity level (L1–L5), and top recommendations. Each dimension carries an **`applicability`** field (`applicable` / `not_applicable` / `unknown`); the overall score normalizes across applicable dimensions only so absent capabilities never get silent partial credit. **`repoPath`** must be an absolute path on the MCP host. Pass **`includeFullDimensions: true`** for per-dimension evidence and reasons.
 
 Returns from `analyze_app`:
 
@@ -87,9 +88,11 @@ When the model sees **`unrecognizedButtons`**, it can ask the user to register a
 
 | | Default (`includeFullReport` omitted or false) | `includeFullReport: true` |
 |--|--|--|
-| Size | Small: top gaps, cost summary, next checks | Full `gapAnalysis` with every scenario |
+| Size | Small: top gaps, cost summary, next checks, `repoInventorySummary` (counts only) | Full `gapAnalysis` (all scenarios) and full `repoInventory` (test files, missing test IDs) |
 | When to use | Routine agent turns, chat context limits | Deep dives, exporting full scenario JSON |
 
+> **0.4.2 note:** The compact response now ships `repoInventorySummary` (route/test/missing-id counts plus framework verdict) instead of the full `repoInventory`. Agents that need the raw `testFiles` or `missingTestIds` arrays should pass `includeFullReport: true`.
+
 Example (full):
 
 ```json

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

@@ -42,51 +42,20 @@ export declare function buildCompactAnalyzePayload(result: AnalyzeResult, includ
             };
         }[] | 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;
-        };
+    repoInventorySummary: {
         framework?: {
-            confidence: "high" | "medium" | "low";
-            evidence: string[];
             primary: "unknown" | "nextjs-app-router" | "nextjs-pages-router" | "express" | "remix" | "nuxt" | "sveltekit" | "astro" | "vite";
+            confidence: "high" | "medium" | "low";
             testFrameworks: ("playwright" | "cypress-e2e" | "cypress-component" | "jest" | "vitest" | "other")[];
+            evidenceCount: number;
         } | 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;
+        repoPath: string;
+        scannedAt: string;
+        routeCount: number;
+        testFileCount: number;
+        missingTestIdCount: number;
+        interactiveTsxFilesScanned: number | null;
+        cypressDetected: boolean;
     } | null;
     decisionLogPreview: {
         timestamp: string;

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAkFs3L,CAAC;2BAA6C,CAAC;0BAA4C,CAAC;yBAA2C,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAAkqT,CAAC;sBAA4C,CAAC;sBAA4C,CAAC;iBAAuC,CAAC;;;;;;;;;;;;;;;;;uBAAghB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;EAD/4gB"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAuG+9d,CAAC;sBAA4C,CAAC;sBAA4C,CAAC;iBAAuC,CAAC;;;;;;;;;;;;;;;;;uBAAghB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;EAD9sf"}

package/dist/compact-analyze-payload.js

@@ -33,6 +33,26 @@ export function buildCompactAnalyzePayload(result, includeFullReport) {
         }
         : null;
     const ps = result.publicSurface;
+    const repo = result.repoInventory;
+    const repoInventorySummary = repo
+        ? {
+            repoPath: repo.repoPath,
+            scannedAt: repo.scannedAt,
+            routeCount: repo.routes.length,
+            testFileCount: repo.testFiles.length,
+            missingTestIdCount: repo.missingTestIds.length,
+            interactiveTsxFilesScanned: repo.interactiveTsxFilesScanned ?? null,
+            cypressDetected: repo.cypressStructure.detected,
+            ...(repo.framework && {
+                framework: {
+                    primary: repo.framework.primary,
+                    confidence: repo.framework.confidence,
+                    testFrameworks: repo.framework.testFrameworks,
+                    evidenceCount: repo.framework.evidence.length,
+                },
+            }),
+        }
+        : null;
     return {
         summary: {
             status: result.status,
@@ -78,18 +98,18 @@ export function buildCompactAnalyzePayload(result, includeFullReport) {
             pagesSkipped: result.routeInventory.pagesSkipped,
             budgetExceeded: result.routeInventory.budgetExceeded,
         },
-        ...(result.repoInventory?.automationMaturity && {
+        ...(repo?.automationMaturity && {
             automationMaturitySummary: {
-                overallScore: result.repoInventory.automationMaturity.overallScore,
-                level: result.repoInventory.automationMaturity.level,
-                label: result.repoInventory.automationMaturity.label,
-                topRecommendations: result.repoInventory.automationMaturity.topRecommendations,
+                overallScore: repo.automationMaturity.overallScore,
+                level: repo.automationMaturity.level,
+                label: repo.automationMaturity.label,
+                topRecommendations: repo.automationMaturity.topRecommendations,
             },
         }),
-        repoInventory: result.repoInventory,
+        repoInventorySummary,
         decisionLogPreview: result.decisionLog.slice(-8),
         ...(result.detectedAuth !== undefined && { detectedAuth: result.detectedAuth }),
         includeFullReport: false,
-        note: 'Summary-first payload. Pass includeFullReport: true for full gapAnalysis (all scenarios and generatedTests).',
+        note: 'Summary-first payload. Pass includeFullReport: true for the full gapAnalysis (all scenarios, generated tests) and the full repoInventory (test files, missing test IDs).',
     };
 }

package/dist/index.js

@@ -8,12 +8,15 @@
 // 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 { createRequire } from 'node:module';
 import { isAbsolute, normalize, resolve } from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+const requirePkg = createRequire(import.meta.url);
+const pkg = requirePkg('../package.json');
 import { analyzeApp, detectAuth, exploreAuth, scanRepo, computeAutomationMaturity, } from '@qulib/core';
 import { z } from 'zod';
-import { buildCompactAnalyzePayload } from './compact-analyze-payload.js';
+import { summarizeAnalyzeResult } from './summarize-analyze-result.js';
 import { log } from './logger.js';
 function toolError(code, message, detail) {
     return {
@@ -39,6 +42,12 @@ const mcpProgressLog = {
     error: (message) => log.error(message),
     debug: (message) => log.debug(message),
 };
+// NOTE: MCP `auth` shape intentionally flattens the core `AuthConfigSchema` so an LLM
+// can populate it without nested objects. We translate it back into core's nested
+// `AuthConfig` (with `credentials: { username, password }` and `selectors: { ... }`)
+// before passing it to `analyzeApp` below. If core's `AuthConfigSchema` changes, mirror
+// the change here. Drift is allowed because the surfaces serve different consumers
+// (LLM tool input vs internal harness contract), but the translation must stay 1:1.
 const FormLoginMcpAuthSchema = z.object({
     type: z.literal('form-login'),
     loginUrl: z.string().url(),
@@ -83,7 +92,7 @@ function validateAbsoluteRepoPath(repoPath) {
 }
 const mcpServer = new McpServer({
     name: 'qulib-mcp',
-    version: '0.4.1',
+    version: pkg.version,
     description: 'Qulib QA intelligence platform — gap analysis, auth exploration, and quality scoring for deployed web applications',
 }, {
     capabilities: {
@@ -193,7 +202,7 @@ mcpServer.registerTool('analyze_app', {
             progressLog: mcpProgressLog,
             telemetry: telemetrySink,
         });
-        const payload = buildCompactAnalyzePayload(result, input.includeFullReport === true);
+        const payload = summarizeAnalyzeResult(result, input.includeFullReport === true);
         return {
             content: [
                 {

package/dist/summarize-analyze-result.d.ts

@@ -0,0 +1,164 @@
+import type { AnalyzeResult } from '@qulib/core';
+export declare function summarizeAnalyzeResult(result: AnalyzeResult, includeFullReport: boolean): AnalyzeResult | {
+    includeFullReport: boolean;
+    note: string;
+    detectedAuth?: {
+        type: "unknown" | "form-login" | "oauth" | "magic-link" | "none";
+        loginUrl: string | null;
+        provider: string | null;
+        hasAuth: boolean;
+        observedSelectors: {
+            usernameSelector: string | null;
+            passwordSelector: string | null;
+            submitSelector: string | null;
+        } | null;
+        oauthButtons: {
+            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;
+    repoInventorySummary: {
+        framework?: {
+            primary: "unknown" | "nextjs-app-router" | "nextjs-pages-router" | "express" | "remix" | "nuxt" | "sveltekit" | "astro" | "vite";
+            confidence: "high" | "medium" | "low";
+            testFrameworks: ("playwright" | "cypress-e2e" | "cypress-component" | "jest" | "vitest" | "other")[];
+            evidenceCount: number;
+        } | undefined;
+        repoPath: string;
+        scannedAt: string;
+        routeCount: number;
+        testFileCount: number;
+        missingTestIdCount: number;
+        interactiveTsxFilesScanned: number | null;
+        cypressDetected: boolean;
+    } | 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;
+        coverageScore: number | null;
+        releaseConfidence: number | null;
+        mode: "url-only" | "url-repo" | "auth-required";
+        coveragePagesScanned: number;
+        coverageBudgetExceeded: boolean;
+        coverageWarning: "auth-required" | "budget-exceeded" | "low-coverage" | "navigation-failures" | null;
+        gapCount: number;
+        scenarioCount: number;
+        generatedTestCount: number;
+        publicSurface: {
+            pageCount: number;
+            gapCount: number;
+            accessibilityViolationCount: number;
+            brokenLinkCount: number;
+        } | null;
+    };
+    topGaps: {
+        path: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage";
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+    }[];
+    costIntelligenceSummary: {
+        maxOutputTokensPerLlmCall: number;
+        usageDataQuality: "none" | "actual" | "estimated" | "mixed";
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        budgetWarningCount: number;
+        maturityLevel: number;
+        maturityLabel: string;
+    } | null;
+    costIntelligence: {
+        maxOutputTokensPerLlmCall: number;
+        budgetRole: "max-output-tokens-per-llm-call";
+        records: {
+            provider: string;
+            model: string;
+            inputTokens: number;
+            outputTokens: number;
+            operationType: "scenario-generation";
+            timestamp: string;
+            dataQuality: "none" | "actual" | "estimated" | "mixed";
+            estimatedCostUsd?: number | undefined;
+            promptHash?: string | undefined;
+            resultHash?: string | undefined;
+            notes?: string | undefined;
+        }[];
+        budgetWarnings: string[];
+        usageSummary: {
+            dataQuality: "none" | "actual" | "estimated" | "mixed";
+            totalInputTokens: number;
+            totalOutputTokens: number;
+        };
+        repeatedOperations: {
+            recommendation: string;
+            promptHash: string;
+            count: number;
+        }[];
+        deterministicMaturity: {
+            label: string;
+            level: number;
+            rationale: string;
+            ceilingNote?: string | undefined;
+        };
+        conversionRecommendations: string[];
+    } | null;
+    nextDeterministicChecks: string[];
+    gapAnalysisPreview: {
+        analyzedAt: string;
+        gapsSample: {
+            path: string;
+            id: string;
+            severity: "critical" | "high" | "medium" | "low";
+            reason: string;
+            category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage";
+            recommendation?: string | undefined;
+            description?: string | undefined;
+        }[];
+        scenariosOmitted: number;
+        generatedTestsOmitted: number;
+    };
+    routeInventorySummary: {
+        scannedAt: string;
+        baseUrl: string;
+        routeCount: number;
+        pagesSkipped: number;
+        budgetExceeded: boolean;
+    };
+};
+//# sourceMappingURL=summarize-analyze-result.d.ts.map

package/dist/summarize-analyze-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarize-analyze-result.d.ts","sourceRoot":"","sources":["../src/summarize-analyze-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAqBjD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,EAAE,iBAAiB,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAuGu+d,CAAC;sBAA4C,CAAC;sBAA4C,CAAC;iBAAuC,CAAC;;;;;;;;;;;;;;;;;uBAAghB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;EADltf"}

package/dist/summarize-analyze-result.js

@@ -0,0 +1,115 @@
+const severityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+function topGapsBySeverity(gaps, limit) {
+    return [...gaps].sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]).slice(0, limit);
+}
+function nextDeterministicChecks(gaps, conversion) {
+    const out = [];
+    const byCat = new Map();
+    for (const g of gaps) {
+        byCat.set(g.category, (byCat.get(g.category) ?? 0) + 1);
+    }
+    for (const [cat, n] of [...byCat.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3)) {
+        out.push(`Add or tighten deterministic coverage for **${cat}** (${n} gap(s) in this scan).`);
+    }
+    out.push(...conversion.slice(0, 2));
+    return out.slice(0, 5);
+}
+export function summarizeAnalyzeResult(result, includeFullReport) {
+    if (includeFullReport) {
+        return result;
+    }
+    const g = result.gapAnalysis;
+    const ci = g.costIntelligence;
+    const top = topGapsBySeverity(result.gaps, 5);
+    const costSummary = ci
+        ? {
+            maxOutputTokensPerLlmCall: ci.maxOutputTokensPerLlmCall,
+            usageDataQuality: ci.usageSummary.dataQuality,
+            totalInputTokens: ci.usageSummary.totalInputTokens,
+            totalOutputTokens: ci.usageSummary.totalOutputTokens,
+            budgetWarningCount: ci.budgetWarnings.length,
+            maturityLevel: ci.deterministicMaturity.level,
+            maturityLabel: ci.deterministicMaturity.label,
+        }
+        : null;
+    const ps = result.publicSurface;
+    const repo = result.repoInventory;
+    const repoInventorySummary = repo
+        ? {
+            repoPath: repo.repoPath,
+            scannedAt: repo.scannedAt,
+            routeCount: repo.routes.length,
+            testFileCount: repo.testFiles.length,
+            missingTestIdCount: repo.missingTestIds.length,
+            interactiveTsxFilesScanned: repo.interactiveTsxFilesScanned ?? null,
+            cypressDetected: repo.cypressStructure.detected,
+            ...(repo.framework && {
+                framework: {
+                    primary: repo.framework.primary,
+                    confidence: repo.framework.confidence,
+                    testFrameworks: repo.framework.testFrameworks,
+                    evidenceCount: repo.framework.evidence.length,
+                },
+            }),
+        }
+        : null;
+    return {
+        summary: {
+            status: result.status,
+            coverageScore: result.coverageScore,
+            releaseConfidence: g.releaseConfidence,
+            mode: g.mode,
+            coveragePagesScanned: g.coveragePagesScanned,
+            coverageBudgetExceeded: g.coverageBudgetExceeded,
+            coverageWarning: g.coverageWarning ?? null,
+            gapCount: g.gaps.length,
+            scenarioCount: g.scenarios.length,
+            generatedTestCount: g.generatedTests.length,
+            publicSurface: ps === null
+                ? null
+                : {
+                    pageCount: ps.pages.length,
+                    gapCount: ps.gaps.length,
+                    accessibilityViolationCount: ps.accessibilityViolations.length,
+                    brokenLinkCount: ps.brokenLinks.length,
+                },
+        },
+        topGaps: top.map((x) => ({
+            path: x.path,
+            category: x.category,
+            severity: x.severity,
+            reason: x.reason,
+        })),
+        costIntelligenceSummary: costSummary,
+        costIntelligence: ci ?? null,
+        nextDeterministicChecks: ci
+            ? nextDeterministicChecks(result.gaps, ci.conversionRecommendations)
+            : nextDeterministicChecks(result.gaps, []),
+        gapAnalysisPreview: {
+            analyzedAt: g.analyzedAt,
+            gapsSample: g.gaps.slice(0, 8),
+            scenariosOmitted: g.scenarios.length,
+            generatedTestsOmitted: g.generatedTests.length,
+        },
+        routeInventorySummary: {
+            scannedAt: result.routeInventory.scannedAt,
+            baseUrl: result.routeInventory.baseUrl,
+            routeCount: result.routeInventory.routes.length,
+            pagesSkipped: result.routeInventory.pagesSkipped,
+            budgetExceeded: result.routeInventory.budgetExceeded,
+        },
+        ...(repo?.automationMaturity && {
+            automationMaturitySummary: {
+                overallScore: repo.automationMaturity.overallScore,
+                level: repo.automationMaturity.level,
+                label: repo.automationMaturity.label,
+                topRecommendations: repo.automationMaturity.topRecommendations,
+            },
+        }),
+        repoInventorySummary,
+        decisionLogPreview: result.decisionLog.slice(-8),
+        ...(result.detectedAuth !== undefined && { detectedAuth: result.detectedAuth }),
+        includeFullReport: false,
+        note: 'Summary-first payload. Pass includeFullReport: true for the full gapAnalysis (all scenarios, generated tests) and the full repoInventory (test files, missing test IDs).',
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qulib/mcp",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "MCP server for Qulib — AI-callable QA gap analysis",
   "license": "MIT",
   "author": "Tapesh Nagarwal",
@@ -29,11 +29,11 @@
   "scripts": {
     "build": "npm --prefix ../.. run build -w @qulib/core && tsc && chmod +x dist/index.js",
     "dev": "tsx src/index.ts",
-    "test": "node --import tsx/esm --test src/compact-analyze-payload.test.ts"
+    "test": "node --import tsx/esm --test src/__tests__/summarize-analyze-result.test.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@qulib/core": "0.4.1",
+    "@qulib/core": "0.4.3",
     "zod": "^3.23.0"
   },
   "devDependencies": {