@qulib/mcp 0.1.1 → 0.2.1

package/README.md

@@ -4,9 +4,12 @@
 
 ## What it does
 
-One tool: `analyze_app(url, auth?)`
+Tools:
 
-Returns:
+- **`analyze_app(url, auth?)`** — full quality scan (optional form-login auth).
+- **`detect_auth(url, timeoutMs?)`** — detect whether the site uses form login, OAuth, magic link, etc., and get a plain-language recommendation (including when to use manual `qulib auth init` and storage state).
+
+Returns from `analyze_app`:
 
 - Release confidence score (0-100)
 - Accessibility violations (axe-core, WCAG 2 A/AA)
@@ -14,7 +17,7 @@ Returns:
 - Console errors and coverage warnings
 - Prioritized gaps with severity
 
-Supports optional form-login auth for scanning authenticated pages.
+Supports optional form-login auth for scanning authenticated pages. If auth is required but not configured, the scan can stop early with `mode: auth-required` and guidance in `detectedAuth` / the decision log.
 
 ## Install for Claude Code
 
@@ -37,6 +40,18 @@ Add this under `mcpServers` in `claude_desktop_config.json` (Claude Desktop) or
 }
 ```
 
+## One-time browser setup
+
+qulib uses Playwright under the hood. After your MCP host first runs the qulib server, you'll need to install Chromium:
+
+```bash
+npx playwright install chromium
+```
+
+This is a one-time step. You'll only need to do it again if Playwright's browser version is bumped in a future qulib release.
+
+If you skip this step, the first tool call will return a clear error telling you to run the command.
+
 ## Example usage
 
 Ask Claude:
@@ -47,9 +62,33 @@ Claude will call `analyze_app({ url: "https://example.com" })` and reason about
 
 ## Authenticated scanning
 
+### Form login (automated)
+
 > "Use Qulib to scan my staging app at https://staging.example.com. Log in as user@example.com with password Test123, the login form is at /login with selectors [data-testid='email'], [data-testid='password'], and [data-testid='submit']."
 
-Claude will pass auth credentials to the tool; Qulib signs in, then scans.
+Claude will pass auth credentials to `analyze_app`; Qulib signs in, then scans.
+
+### OAuth, SSO, magic link, or anything that cannot be scripted
+
+OAuth and similar flows need human consent on the provider domain; Qulib does not automate them. Use the **CLI** (same machine as the browser):
+
+```bash
+qulib auth init --base-url https://app.example.com
+```
+
+Log in manually in the opened window, press ENTER in the terminal, then reuse the saved JSON with:
+
+```bash
+qulib analyze --url https://app.example.com --auth-storage-state ./qulib-storage-state.json
+```
+
+For MCP-driven workflows, run `auth init` on the machine where the MCP server runs, then pass `auth: { type: 'storage-state', path: '/absolute/path/to/qulib-storage-state.json' }` to `analyze_app`.
+
+### Detecting auth before you configure anything
+
+> "Use qulib's `detect_auth` tool on https://app.example.com — what auth pattern does it use and what should I do next?"
+
+The tool returns `type`, `oauthButtons`, `recommendation`, and related fields so the agent can explain options honestly.
 
 ## Known limitations
 

package/dist/index.js

@@ -2,24 +2,27 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { analyzeApp } from '@qulib/core';
+import { analyzeApp, detectAuth } from '@qulib/core';
 import { z } from 'zod';
+const FormLoginMcpAuthSchema = z.object({
+    type: z.literal('form-login'),
+    loginUrl: z.string().url(),
+    username: z.string(),
+    password: z.string(),
+    usernameSelector: z.string(),
+    passwordSelector: z.string(),
+    submitSelector: z.string(),
+    successUrlContains: z.string().optional(),
+});
+const StorageStateMcpAuthSchema = z.object({
+    type: z.literal('storage-state'),
+    path: z.string().min(1),
+});
 const AnalyzeInputSchema = z.object({
     url: z.string().url(),
     maxPagesToScan: z.number().int().min(1).max(50).optional(),
     timeoutMs: z.number().int().positive().optional(),
-    auth: z
-        .object({
-        type: z.literal('form-login'),
-        loginUrl: z.string().url(),
-        username: z.string(),
-        password: z.string(),
-        usernameSelector: z.string(),
-        passwordSelector: z.string(),
-        submitSelector: z.string(),
-        successUrlContains: z.string().optional(),
-    })
-        .optional(),
+    auth: z.discriminatedUnion('type', [FormLoginMcpAuthSchema, StorageStateMcpAuthSchema]).optional(),
 });
 const server = new Server({
     name: 'qulib-mcp',
@@ -33,7 +36,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
             name: 'analyze_app',
-            description: 'Analyze a deployed web app for quality gaps. Returns a release confidence score (0-100), accessibility violations, broken links, and prioritized risks. Supports optional form-login authentication.',
+            description: 'Analyze a deployed web app for quality gaps. Returns a release confidence score (0-100), accessibility violations, broken links, and prioritized risks. Supports optional form-login or storage-state (Playwright) authentication.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -41,42 +44,95 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     maxPagesToScan: { type: 'number', description: 'Max pages to crawl (default 10)' },
                     timeoutMs: { type: 'number', description: 'Per-page timeout in milliseconds (default 30000)' },
                     auth: {
-                        type: 'object',
-                        description: 'Optional form-login auth',
-                        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',
+                        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'],
+                            },
                         ],
                     },
                 },
                 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 === 'detect_auth') {
+        const { url, timeoutMs } = z
+            .object({
+            url: z.string().url(),
+            timeoutMs: z.number().int().positive().optional(),
+        })
+            .parse(request.params.arguments ?? {});
+        const result = await detectAuth(url, timeoutMs);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    }
     if (request.params.name !== 'analyze_app') {
         throw new Error(`Unknown tool: ${request.params.name}`);
     }
     const input = AnalyzeInputSchema.parse(request.params.arguments ?? {});
-    const successIndicator = input.auth?.successUrlContains !== undefined && input.auth.successUrlContains !== ''
+    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 result = await analyzeApp({
         url: input.url,
         writeArtifacts: false,
@@ -94,19 +150,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             explorer: 'playwright',
             defaultAdapter: 'playwright',
             adapters: ['playwright'],
-            ...(input.auth && {
-                auth: {
-                    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,
-                },
-            }),
+            ...(authConfig && { auth: authConfig }),
         },
     });
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qulib/mcp",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "MCP server for Qulib — AI-callable QA gap analysis",
   "license": "MIT",
   "author": "Tapesh Nagarwal",
@@ -31,7 +31,7 @@
     "dev": "tsx src/index.ts"
   },
   "dependencies": {
-    "@qulib/core": "0.1.1",
+    "@qulib/core": "0.2.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.23.0"
   },