@qulib/mcp 0.9.0 → 0.10.0

package/README.md

@@ -47,13 +47,16 @@ For verbose server-side stderr logs while troubleshooting host wiring, add:
 
 | Tool | Purpose |
 |---|---|
-| **`qulib_score_confidence`** | **Flagship.** Fuses evidence from `analyze_app`, `qulib_score_automation`, and `qulib_score_api` into one verdict: **ship / caution / hold / block** with a 0–100 confidence score, L1–L5 level, per-source contributions, honesty notes, and recommended next checks. Pass `url` and/or `repoPath`. |
-| `analyze_app` | Live-app quality scan: release confidence (0–100), axe-core a11y, broken links, console errors, prioritized gaps. Default payload is summary-first; pass `includeFullReport: true` for all scenarios. Optional form-login / storage-state auth. |
+| **`qulib_score_confidence`** | **Flagship.** Fuses evidence from `qulib_analyze_app`, `qulib_score_automation`, and `qulib_score_api` into one verdict: **ship / caution / hold / block** with a 0–100 confidence score, L1–L5 level, per-source contributions, honesty notes, and recommended next checks. Pass `url` and/or `repoPath`. |
+| `qulib_analyze_app` | Live-app quality scan: release confidence (0–100), axe-core a11y, broken links, console errors, prioritized gaps. Default payload is summary-first; pass `includeFullReport: true` for all scenarios. Optional form-login / storage-state auth. *(Canonical form; legacy alias `analyze_app` kept for backwards compatibility.)* |
 | `qulib_score_automation` | Score a local repo's test-automation maturity across six dimensions (test coverage breadth, framework adoption, test-id hygiene, CI integration, auth test coverage, component test ratio) — plus a conditional 7th dimension (API coverage) when API endpoints are detected. Returns overall 0–100, level (L1–L5), and top recommendations. Each dimension carries `applicability`; score normalizes over applicable dimensions only. |
 | `qulib_score_api` | Discover API endpoints in a repo and score their test coverage. Tier1=OpenAPI specs, Tier2=framework routes (Next.js, Express, Fastify, NestJS), Tier3=heuristic opt-in (tRPC). Returns an api-test-coverage dimension score with per-endpoint evidence. |
-| `qulib_scaffold_tests` | Generate a ready-to-run test scaffold (Cypress or Playwright config + spec files) by crawling a deployed URL. Returns `generatedTests` and `projectConfig` so an agent can write files directly. Pass `recipes` (e.g. `["auth","a11y"]`) to append proven test patterns. |
-| `explore_auth` | List all sign-in paths (OAuth, SSO, forms, magic link) and what the agent must collect before `analyze_app`. Prefer on unfamiliar apps. |
-| `detect_auth` | Single-pass auth pattern guess with a recommendation. Lighter than `explore_auth`. |
+| `qulib_scaffold_tests` | Generate a ready-to-run test scaffold (Cypress config + spec files) by crawling a deployed URL. Returns `generatedTests` and `projectConfig` so an agent can write files directly. Pass `recipes` (e.g. `["auth","a11y"]`) to append proven test patterns. Supported framework: `cypress-e2e` (default); `playwright` is not yet implemented. |
+| `qulib_explore_auth` | List all sign-in paths (OAuth, SSO, forms, magic link) and what the agent must collect before `qulib_analyze_app`. Prefer on unfamiliar apps. *(Canonical form; legacy alias `explore_auth` kept for backwards compatibility.)* |
+| `qulib_detect_auth` | Single-pass auth pattern guess with a recommendation. Lighter than `qulib_explore_auth`. *(Canonical form; legacy alias `detect_auth` kept for backwards compatibility.)* |
+| `analyze_app` | Legacy alias for `qulib_analyze_app`. Identical behavior; kept for backwards compatibility through v1.0. |
+| `explore_auth` | Legacy alias for `qulib_explore_auth`. Identical behavior; kept for backwards compatibility through v1.0. |
+| `detect_auth` | Legacy alias for `qulib_detect_auth`. Identical behavior; kept for backwards compatibility through v1.0. |
 
 **Example — flagship confidence call:**
 
@@ -136,8 +139,6 @@ When the model sees **`unrecognizedButtons`**, it can ask the user to register a
 | 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/index.js

@@ -43,6 +43,18 @@ const mcpProgressLog = {
     error: (message) => log.error(message),
     debug: (message) => log.debug(message),
 };
+// ---------------------------------------------------------------------------
+// Naming convergence — 0.10 (non-breaking aliases)
+//
+// Three legacy tools predate the qulib_ prefix convention:
+//   explore_auth → qulib_explore_auth (alias)
+//   detect_auth  → qulib_detect_auth  (alias)
+//   analyze_app  → qulib_analyze_app  (alias)
+//
+// The legacy names keep working unchanged. New integrations should prefer the
+// qulib_ forms. Both will coexist through 1.0; the legacy names are marked
+// "alias" in their descriptions. Removal is planned for 1.0.
+// ---------------------------------------------------------------------------
 // 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: { ... }`)
@@ -118,14 +130,11 @@ 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 }) => {
+async function handleExploreAuth({ url, timeoutMs, }) {
     try {
-        log.info(`explore_auth tool url=${url} timeoutMs=${timeoutMs ?? 20000}`);
+        log.info(`explore_auth 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}`);
+        log.info(`explore_auth done authRequired=${result.authRequired} paths=${result.authPaths.length}`);
         return {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         };
@@ -135,18 +144,24 @@ mcpServer.registerTool('explore_auth', {
         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 }) => {
+}
+const 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.';
+mcpServer.registerTool('explore_auth', {
+    description: `${EXPLORE_AUTH_DESCRIPTION} (Alias for new integrations: qulib_explore_auth)`,
+    inputSchema: ExploreAuthToolInputSchema,
+}, handleExploreAuth);
+mcpServer.registerTool('qulib_explore_auth', {
+    description: `${EXPLORE_AUTH_DESCRIPTION} (Canonical qulib_ form; explore_auth is the legacy alias kept for backwards compatibility.)`,
+    inputSchema: ExploreAuthToolInputSchema,
+}, handleExploreAuth);
+async function handleDetectAuth({ url, timeoutMs, }) {
     try {
-        log.info(`detect_auth tool url=${url} timeoutMs=${timeoutMs ?? 15000}`);
+        log.info(`detect_auth url=${url} timeoutMs=${timeoutMs ?? 15000}`);
         const result = await detectAuth(url, timeoutMs, mcpProgressLog);
         const providerSummary = result.oauthButtons.length > 0
             ? result.oauthButtons.map((b) => b.provider).join(', ')
             : result.provider ?? 'none';
-        log.info(`detect_auth tool done type=${result.type} providers=${providerSummary} automatable=${result.type === 'form-login'}`);
+        log.info(`detect_auth done type=${result.type} providers=${providerSummary} automatable=${result.type === 'form-login'}`);
         return {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         };
@@ -156,11 +171,17 @@ mcpServer.registerTool('detect_auth', {
         log.error(`detect_auth failed: ${msg}`);
         return toolError('QULIB_AUTH_DETECT_FAILED', msg, err instanceof Error ? err.stack : undefined);
     }
-});
-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. Set agentSummary for the compact gate-decision payload (pass/warn/fail with honesty notes) — use this when calling from a CI gate or orchestrator. Optional llmMaxOutputTokensPerCall / llmTokenBudget (legacy), testGenerationLimit, enableLlmScenarios align with @qulib/core HarnessConfig.',
-    inputSchema: AnalyzeInputSchema,
-}, async (input) => {
+}
+const 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.';
+mcpServer.registerTool('detect_auth', {
+    description: `${DETECT_AUTH_DESCRIPTION} (Alias for new integrations: qulib_detect_auth)`,
+    inputSchema: DetectAuthToolInputSchema,
+}, handleDetectAuth);
+mcpServer.registerTool('qulib_detect_auth', {
+    description: `${DETECT_AUTH_DESCRIPTION} (Canonical qulib_ form; detect_auth is the legacy alias kept for backwards compatibility.)`,
+    inputSchema: DetectAuthToolInputSchema,
+}, handleDetectAuth);
+async function handleAnalyzeApp(input) {
     try {
         const successIndicator = input.auth?.type === 'form-login' &&
             input.auth.successUrlContains !== undefined &&
@@ -225,7 +246,16 @@ mcpServer.registerTool('analyze_app', {
         log.error(`analyze_app failed: ${msg}`);
         return toolError('QULIB_SCAN_FAILED', msg, err instanceof Error ? err.stack : undefined);
     }
-});
+}
+const 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. Set agentSummary for the compact gate-decision payload (pass/warn/fail with honesty notes) — use this when calling from a CI gate or orchestrator. Optional llmMaxOutputTokensPerCall / llmTokenBudget (legacy), testGenerationLimit, enableLlmScenarios align with @qulib/core HarnessConfig.';
+mcpServer.registerTool('analyze_app', {
+    description: `${ANALYZE_APP_DESCRIPTION} (Alias for new integrations: qulib_analyze_app)`,
+    inputSchema: AnalyzeInputSchema,
+}, handleAnalyzeApp);
+mcpServer.registerTool('qulib_analyze_app', {
+    description: `${ANALYZE_APP_DESCRIPTION} (Canonical qulib_ form; analyze_app is the legacy alias kept for backwards compatibility.)`,
+    inputSchema: AnalyzeInputSchema,
+}, handleAnalyzeApp);
 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,
@@ -267,7 +297,7 @@ const ScaffoldTestsInputSchema = z.object({
     framework: z
         .enum(['cypress-e2e', 'playwright'])
         .optional()
-        .describe('Test framework to generate. Default: cypress-e2e'),
+        .describe('Test framework to generate. Default and recommended: cypress-e2e. playwright is accepted but not yet implemented (returns an error).'),
     maxPagesToScan: z
         .number()
         .int()
@@ -288,7 +318,7 @@ const ScaffoldTestsInputSchema = z.object({
         'Example: ["auth", "a11y"] adds 6 ready-to-run test scenarios.'),
 });
 mcpServer.registerTool('qulib_scaffold_tests', {
-    description: 'Generate a ready-to-run test scaffold for a deployed web app. Crawls the URL, identifies quality gaps and user flows, then produces framework-specific test files (Cypress or Playwright) plus the project config (cypress.config.ts or playwright.config.ts) and package.json deps. Returns generatedTests (array of {filename, code, outputPath}) and projectConfig so an agent can write the files directly to a repo without any manual test-writing. Optionally pass recipes (e.g. ["auth","a11y"]) to append proven NQ-2/CaseLoom-derived test patterns for common flows — auth adds login/logout/protected-route tests, a11y adds heading/landmark/title checks, nav adds deep-link/404 tests, seed adds state-reset helpers.',
+    description: 'Generate a ready-to-run test scaffold for a deployed web app. Crawls the URL, identifies quality gaps and user flows, then produces framework-specific test files plus the project config and package.json deps. Returns generatedTests (array of {filename, code, outputPath}) and projectConfig so an agent can write the files directly to a repo without any manual test-writing. Supported framework: cypress-e2e (default). playwright scaffold is experimental and not yet implemented. Optionally pass recipes (e.g. ["auth","a11y"]) to append proven NQ-2/CaseLoom-derived test patterns for common flows — auth adds login/logout/protected-route tests, a11y adds heading/landmark/title checks, nav adds deep-link/404 tests, seed adds state-reset helpers.',
     inputSchema: ScaffoldTestsInputSchema,
 }, async ({ url, framework, maxPagesToScan, recipes }) => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qulib/mcp",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "MCP server for Qulib — AI-callable release confidence. Seven tools: fused verdict, live-app scan, automation maturity, API coverage, test scaffold, and auth tools.",
   "license": "MIT",
   "author": "Tapesh Nagarwal",
@@ -30,16 +30,16 @@
     "build": "npm --prefix ../.. run build -w @qulib/core && tsc && chmod +x dist/index.js",
     "prepublishOnly": "npm run build",
     "dev": "tsx src/index.ts",
-    "test": "node --import tsx/esm --test src/__tests__/summarize-analyze-result.test.ts src/__tests__/analyze-app-mcp-payload.test.ts src/__tests__/score-confidence-mcp.test.ts"
+    "test": "node --import tsx/esm --test src/__tests__/summarize-analyze-result.test.ts src/__tests__/analyze-app-mcp-payload.test.ts src/__tests__/score-confidence-mcp.test.ts src/__tests__/naming-aliases.test.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@qulib/core": "0.9.0",
+    "@qulib/core": "0.10.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "tsx": "^4.11.0",
+    "tsx": "^4.22.4",
     "typescript": "^5.4.0"
   },
   "keywords": [
@@ -50,6 +50,9 @@
     "ship-verdict",
     "automation-maturity",
     "accessibility",
-    "ai"
+    "ai",
+    "ci-gate",
+    "playwright",
+    "web-quality"
   ]
 }