@qulib/mcp 0.2.0 → 0.2.2

package/README.md

@@ -6,8 +6,9 @@
 
 Tools:
 
-- **`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).
+- **`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(url, auth?)`** — full quality scan (optional form-login or storage-state auth).
+- **`detect_auth(url, timeoutMs?)`** — single-pattern auth guess with a short recommendation (lighter than `explore_auth`).
 
 Returns from `analyze_app`:
 
@@ -40,6 +41,26 @@ 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.
+
+## Agentic auth exploration (`explore_auth`)
+
+On unfamiliar apps, call **`explore_auth`** before **`analyze_app`**. The response lists each sign-in path (curated public OAuth/SSO, password forms, magic-link wording, and **heuristic** unknown buttons such as tenant-specific SSO). Each path includes **`requirements`** (e.g. storage-state vs credentials) and **`suggestedAgentBehavior`**.
+
+When the model sees **`unrecognizedButtons`**, it can ask the user to register a label on the **MCP host** with the CLI:
+
+`qulib auth providers add --id <kebab-id> --label "..." --pattern "..."` — patterns are saved under **`~/.qulib/providers.json`** and merged with the built-in list on the next `explore_auth` / `explore-auth`. Nothing is auto-written without an explicit `providers add`.
+
 ## Example usage
 
 Ask Claude:

package/dist/index.js

@@ -2,7 +2,7 @@
 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, detectAuth } from '@qulib/core';
+import { analyzeApp, detectAuth, exploreAuth } from '@qulib/core';
 import { z } from 'zod';
 const FormLoginMcpAuthSchema = z.object({
     type: z.literal('form-login'),
@@ -34,6 +34,18 @@ const server = new Server({
 });
 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. Returns a release confidence score (0-100), accessibility violations, broken links, and prioritized risks. Supports optional form-login or storage-state (Playwright) authentication.',
@@ -97,6 +109,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     ],
 }));
 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 ?? {});
+        const result = await exploreAuth(url, timeoutMs);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    }
     if (request.params.name === 'detect_auth') {
         const { url, timeoutMs } = z
             .object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qulib/mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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.2.0",
+    "@qulib/core": "0.2.2",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.23.0"
   },