looking-glass-mcp 3.0.0 → 3.1.0

package/README.md

@@ -6,7 +6,21 @@
 
 <p align="center">
   <strong>The AI-native browser for agents.</strong><br/>
-  72 MCP tools. Self-healing interactions. Semantic change detection. Structured extraction. Credential vault. Enterprise-grade security. Deploy anywhere.
+  71 MCP tools. Self-healing interactions. Semantic change detection. Structured extraction. Credential vault. Enterprise-grade security. Deploy anywhere.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/looking-glass-mcp"><img src="https://img.shields.io/npm/v/looking-glass-mcp?color=blue&label=npm" alt="npm" /></a>
+  <a href="https://www.npmjs.com/package/looking-glass-mcp"><img src="https://img.shields.io/npm/dm/looking-glass-mcp?color=orange&label=downloads" alt="downloads" /></a>
+  <a href="https://registry.modelcontextprotocol.io/servers/io.github.Sahib-Sawhney-WH/looking-glass-mcp"><img src="https://img.shields.io/badge/MCP_Registry-listed-brightgreen" alt="MCP Registry" /></a>
+  <a href="https://github.com/Sahib-Sawhney-WH/LookingGlass/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Sahib-Sawhney-WH/LookingGlass/ci.yml?label=CI" alt="CI" /></a>
+  <a href="https://github.com/Sahib-Sawhney-WH/LookingGlass/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Sahib-Sawhney-WH/LookingGlass?color=purple" alt="MIT License" /></a>
+  <a href="https://github.com/Sahib-Sawhney-WH/LookingGlass"><img src="https://img.shields.io/github/stars/Sahib-Sawhney-WH/LookingGlass?style=social" alt="GitHub Stars" /></a>
+  <img src="https://img.shields.io/badge/tools-71-ff69b4" alt="71 tools" />
+  <img src="https://img.shields.io/badge/tests-79-success" alt="79 tests" />
+  <img src="https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white" alt="Node 20+" />
+  <img src="https://img.shields.io/badge/Playwright-1.50+-2EAD33?logo=playwright&logoColor=white" alt="Playwright" />
+  <img src="https://img.shields.io/badge/Azure-ready-0078D4?logo=microsoftazure&logoColor=white" alt="Azure Ready" />
 </p>
 
 <p align="center">
@@ -18,10 +32,6 @@
   <a href="#configuration">Configuration</a>
 </p>
 
-<p align="center">
-  <a href="https://portal.azure.com/#create/Microsoft.Template"><img src="https://aka.ms/deploytoazurebutton" alt="Deploy to Azure" /></a>
-</p>
-
 ---
 
 ## What's New in v3.0
@@ -46,9 +56,22 @@ Looking Glass v3.0 transforms from a browser automation tool into an **AI-native
 **Claude Code:**
 
 ```bash
+# Basic (headless, uses local-dev profile by default for stdio)
 claude mcp add looking-glass -- npx looking-glass-mcp
+
+# With visible browser window
+claude mcp add looking-glass -e BROWSER_HEADLESS=false -- npx looking-glass-mcp
+
+# With all options
+claude mcp add looking-glass \
+  -e BROWSER_HEADLESS=false \
+  -e BROWSER_SECURITY_PROFILE=local-dev \
+  -e VAULT_ENCRYPTION_KEY=your-passphrase-at-least-32-characters \
+  -- npx looking-glass-mcp
 ```
 
+> **Tip:** After changing env vars, restart Claude Code (new conversation) for the changes to take effect.
+
 **GitHub Copilot / VS Code:**
 
 Add to `.vscode/mcp.json`:
@@ -189,16 +212,17 @@ Looking Glass ships with **72 tools** across 10 categories.
 | `browser_wait_for` | **NEW** Semantic condition waiting ("results loaded") |
 | `browser_workflow` | **NEW** On-demand workflow context |
 
-### Credential Vault (5 tools)
+### Credential Vault (4 tools)
 
 | Tool | Description |
 |------|-------------|
-| `vault_store` | Store encrypted credential profile (AES-256-GCM + PBKDF2) |
 | `vault_list` | List profile names and timestamps (no values) |
 | `vault_delete` | Delete a credential profile |
 | `vault_login` | Login using a vault profile (blind injection) |
 | `vault_inject` | Fill form fields from vault without submitting |
 
+> Credentials are stored via the CLI (`looking-glass vault store`), not through the agent. See [Credential Vault](#credential-vault) below.
+
 ### Observation & Debugging (10 tools)
 
 `browser_screenshot`, `browser_snapshot`, `browser_evaluate`, `browser_console_messages`, `browser_network_requests`, `browser_diagnose`, `browser_error_report`, `browser_snapshot_state` / `browser_diff_state`, `browser_action_history`
@@ -291,12 +315,20 @@ See [SECURITY.md](SECURITY.md) for the full security model.
 
 ### Security Profiles
 
-| Profile | URL Access | JS Execution | Tool Access | Rate Limit |
-|---------|-----------|--------------|-------------|------------|
-| `restricted` (default) | localhost only | Blocked | Observation only | 30/min |
-| `local-dev` | All HTTP/HTTPS | Allowed | All tools | 60/min |
-| `open` | Everything | Allowed | All tools | 120/min |
-| `sandbox` | Blocked | Blocked | Observation only | 10/min |
+The default profile depends on transport mode:
+- **stdio** (local agent): defaults to `local-dev` (full access)
+- **http** (cloud deployment): defaults to `restricted` (observation only)
+
+Override with `BROWSER_SECURITY_PROFILE` if needed.
+
+| Profile | URL Access | JS Execution | Tool Access | Rate Limit | Use Case |
+|---------|-----------|--------------|-------------|------------|----------|
+| `local-dev` | All HTTP/HTTPS | Allowed | All tools | 60/min | Local development and testing |
+| `restricted` | localhost only | Blocked | Observation only | 30/min | Production monitoring — agent can screenshot, audit, and inspect but cannot click, type, or navigate |
+| `open` | Everything | Allowed | All tools | 120/min | Trusted cloud environments |
+| `sandbox` | Blocked | Blocked | Observation only | 10/min | Maximum lockdown — blocks all URLs by default |
+
+> **Note:** If you're using Looking Glass locally via stdio and the agent can't interact with pages, check that your profile is set to `local-dev`. The `restricted` profile is designed for read-only monitoring where the agent should never modify page state.
 
 ### HTTP Transport Security
 
@@ -307,10 +339,56 @@ See [SECURITY.md](SECURITY.md) for the full security model.
 
 ### Credential Vault
 
+Credentials are stored via the CLI — the agent never sees your passwords.
+
+**Setup:**
+
+1. Set your vault encryption key (add to your shell profile or MCP config):
+
+   ```bash
+   export VAULT_ENCRYPTION_KEY="your-passphrase-at-least-32-characters-long"
+   ```
+
+2. Store a credential profile (interactive — passwords are masked):
+
+   ```bash
+   npx looking-glass-mcp vault store linkedin
+   ```
+
+   You'll be prompted for field name/value pairs:
+
+   ```
+   Storing credential profile: linkedin
+   Field name (empty to finish): email
+   Value for "email": user@example.com
+   Field name (empty to finish): password
+   Value for "password": ********
+   Field name (empty to finish):
+   ✓ Stored profile "linkedin" with 2 fields
+   ```
+
+3. Use the profile in your agent conversation:
+
+   ```
+   "Log in to LinkedIn with vault profile linkedin"
+   ```
+
+   The agent calls `vault_login` which decrypts and injects credentials directly into the page — the agent never sees the plaintext values.
+
+**CLI commands:**
+
+| Command | Description |
+|---------|-------------|
+| `npx looking-glass-mcp vault store <profile>` | Store credentials interactively (masked input) |
+| `npx looking-glass-mcp vault list` | List stored profiles and timestamps |
+| `npx looking-glass-mcp vault delete <profile>` | Delete a stored profile |
+
+**Security properties:**
+
 - AES-256-GCM encryption with PBKDF2 key derivation (100k iterations, SHA-512)
 - Field names and values encrypted together (no metadata leakage)
 - Vault file permissions restricted to owner (`0600`)
-- Agent never sees plaintext credentials -- blind injection only
+- Credential storage happens exclusively through the CLI — never through the agent channel
 - `createdAt` and `lastUsedAt` tracking per profile
 
 ### Audit Trail
@@ -426,12 +504,12 @@ MCP Client (Claude, Copilot, etc.)
 |  - Audit Logging (deep redaction)         |
 |  - RBAC Policy Enforcement                |
 |                                           |
-|  72 Tools                                 |
+|  71 Tools                                 |
 |  - Intelligence (extract, go, wait_for)   |
 |  - Interaction (click, type, hover)       |
 |  - Observation (screenshot, snapshot)     |
 |  - Testing (scenarios, assertions)        |
-|  - Vault (store, inject, login)           |
+|  - Vault (inject, login, list, delete)    |
 |                                           |
 |  Browser Manager                          |
 |  - Playwright (Chromium/Firefox/WebKit)   |

package/bin/looking-glass-mcp.mjs

@@ -1,2 +1,8 @@
 #!/usr/bin/env node
-import '../build/index.js';
+
+// Route "vault" subcommand to the vault CLI
+if (process.argv[2] === 'vault') {
+  await import('../build/vault-cli.js');
+} else {
+  await import('../build/index.js');
+}

package/bin/looking-glass-vault.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../build/vault-cli.js';

package/build/index.js

@@ -22641,7 +22641,9 @@ var SECURITY_PROFILES = {
   }
 };
 function getConfig() {
-  const profile = process.env.BROWSER_SECURITY_PROFILE || "restricted";
+  const transport = process.env.MCP_TRANSPORT || "stdio";
+  const defaultProfile = transport === "http" ? "restricted" : "local-dev";
+  const profile = process.env.BROWSER_SECURITY_PROFILE || defaultProfile;
   return {
     headless: process.env.BROWSER_HEADLESS === "true",
     sessionsDir: resolve(process.env.BROWSER_SESSIONS_DIR || ".browser-sessions"),
@@ -23891,6 +23893,7 @@ function formatJournal(entries) {
 // src/middleware/toolWrapper.ts
 init_manager();
 var _middlewares = [];
+var _hasPreSnapshot = false;
 var _captureSnapshot = null;
 var _detectChanges = null;
 var _captureWorkflow = null;
@@ -23930,7 +23933,7 @@ function wrapToolRegistration(server) {
       const errorCountBefore = getConsoleMessages().filter((m) => m.type === "error").length;
       const failureCountBefore = getNetworkRequests().filter((r) => r.status && r.status >= 400).length;
       let preSnapshot = null;
-      if (isInteraction && _captureSnapshot) {
+      if (isInteraction && _captureSnapshot && _hasPreSnapshot) {
         try {
           preSnapshot = await _captureSnapshot();
         } catch {
@@ -23986,6 +23989,7 @@ function wrapToolRegistration(server) {
             workflow = await _captureWorkflow();
           }
           setPendingIntelligence({ changes, workflow });
+          _hasPreSnapshot = true;
         } catch {
         }
       }
@@ -27404,7 +27408,6 @@ var INTELLIGENCE_TOOLS = /* @__PURE__ */ new Set([
   "browser_wait_for"
 ]);
 var VAULT_WRITE_TOOLS = /* @__PURE__ */ new Set([
-  "vault_store",
   "vault_delete",
   "vault_login",
   "vault_inject"
@@ -28927,15 +28930,6 @@ async function saveVault(vault) {
   } catch {
   }
 }
-function encrypt(data) {
-  const key = requireKey();
-  const iv = randomBytes(12);
-  const cipher = createCipheriv("aes-256-gcm", key, iv);
-  let encrypted = cipher.update(data, "utf-8", "hex");
-  encrypted += cipher.final("hex");
-  const tag = cipher.getAuthTag().toString("hex");
-  return { iv: iv.toString("hex"), encrypted, tag };
-}
 function decrypt(iv, encrypted, tag) {
   const key = requireKey();
   const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(iv, "hex"));
@@ -28944,18 +28938,6 @@ function decrypt(iv, encrypted, tag) {
   decrypted += decipher.final("utf-8");
   return decrypted;
 }
-async function storeCredential(profile, fields) {
-  const vault = await loadVault();
-  const payload = JSON.stringify({ fieldNames: Object.keys(fields), fields });
-  const { iv, encrypted, tag } = encrypt(payload);
-  vault.profiles[profile] = {
-    iv,
-    encrypted,
-    tag,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  await saveVault(vault);
-}
 async function listProfiles() {
   const vault = await loadVault();
   return Object.entries(vault.profiles).map(([name, p]) => ({
@@ -29208,26 +29190,6 @@ ${JSON.stringify(ctx, null, 2)}` }
       }
     }
   );
-  server.tool(
-    "vault_store",
-    {
-      profile: external_exports.string().describe('Profile name (e.g. "staging-admin", "bank-login")'),
-      fields: external_exports.record(external_exports.string()).describe('Credential fields (e.g. { email: "user@example.com", password: "..." })')
-    },
-    async ({ profile, fields }) => {
-      if (!isVaultConfigured()) {
-        return { content: [{ type: "text", text: "Vault not configured. Set VAULT_ENCRYPTION_KEY env var." }], isError: true };
-      }
-      try {
-        await storeCredential(profile, fields);
-        return {
-          content: [{ type: "text", text: `Vault: stored profile "${profile}" with fields: ${Object.keys(fields).join(", ")}` }]
-        };
-      } catch (err) {
-        return { content: [{ type: "text", text: `Vault store failed: ${err.message}` }], isError: true };
-      }
-    }
-  );
   server.tool(
     "vault_list",
     {},
@@ -29316,7 +29278,7 @@ ${lines.join("\n")}` }] };
 }
 
 // src/index.ts
-var VERSION = "3.0.0";
+var VERSION = "3.0.1";
 var _browserReady = false;
 function createServer(config2) {
   const server = new McpServer({

package/build/vault-cli.js

@@ -0,0 +1,261 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+
+// src/cli/vault.ts
+import { createInterface } from "node:readline";
+import { resolve } from "node:path";
+
+// src/security/vault.ts
+import { createCipheriv, createDecipheriv, randomBytes, pbkdf2Sync } from "node:crypto";
+import { readFile, writeFile, mkdir, chmod } from "node:fs/promises";
+import { dirname } from "node:path";
+
+// src/browser/manager.ts
+import { chromium, firefox, webkit } from "playwright-core";
+var _readyResolve = null;
+var _readyPromise = new Promise((r) => {
+  _readyResolve = r;
+});
+
+// src/security/vault.ts
+var PBKDF2_ITERATIONS = 1e5;
+var PBKDF2_KEY_LEN = 32;
+var PBKDF2_DIGEST = "sha512";
+var _vaultFile = "";
+var _rawKey = null;
+var _derivedKey = null;
+var _vaultSalt = null;
+function initVault(sessionsDir, encryptionKey) {
+  _vaultFile = `${sessionsDir}/vault.enc`;
+  if (encryptionKey && encryptionKey.length >= 32) {
+    _rawKey = encryptionKey;
+  }
+}
+function isVaultConfigured() {
+  return _rawKey !== null;
+}
+function requireKey() {
+  if (!_rawKey) {
+    throw new Error("Vault not configured. Set VAULT_ENCRYPTION_KEY environment variable (32+ chars).");
+  }
+  if (!_derivedKey) {
+    throw new Error("Vault key not derived. Call loadVault() first to initialize.");
+  }
+  return _derivedKey;
+}
+async function loadVault() {
+  try {
+    const data = await readFile(_vaultFile, "utf-8");
+    const vault = JSON.parse(data);
+    if (vault.salt && _rawKey) {
+      _vaultSalt = Buffer.from(vault.salt, "hex");
+      _derivedKey = pbkdf2Sync(_rawKey, _vaultSalt, PBKDF2_ITERATIONS, PBKDF2_KEY_LEN, PBKDF2_DIGEST);
+    }
+    return vault;
+  } catch {
+    if (_rawKey) {
+      _vaultSalt = randomBytes(32);
+      _derivedKey = pbkdf2Sync(_rawKey, _vaultSalt, PBKDF2_ITERATIONS, PBKDF2_KEY_LEN, PBKDF2_DIGEST);
+    }
+    return { version: 2, salt: _vaultSalt?.toString("hex") || "", profiles: {} };
+  }
+}
+async function saveVault(vault) {
+  await mkdir(dirname(_vaultFile), { recursive: true });
+  await writeFile(_vaultFile, JSON.stringify(vault, null, 2), "utf-8");
+  try {
+    await chmod(_vaultFile, 384);
+  } catch {
+  }
+}
+function encrypt(data) {
+  const key = requireKey();
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  let encrypted = cipher.update(data, "utf-8", "hex");
+  encrypted += cipher.final("hex");
+  const tag = cipher.getAuthTag().toString("hex");
+  return { iv: iv.toString("hex"), encrypted, tag };
+}
+async function storeCredential(profile, fields) {
+  const vault = await loadVault();
+  const payload = JSON.stringify({ fieldNames: Object.keys(fields), fields });
+  const { iv, encrypted, tag } = encrypt(payload);
+  vault.profiles[profile] = {
+    iv,
+    encrypted,
+    tag,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await saveVault(vault);
+}
+async function listProfiles() {
+  const vault = await loadVault();
+  return Object.entries(vault.profiles).map(([name, p]) => ({
+    name,
+    createdAt: p.createdAt,
+    lastUsedAt: p.lastUsedAt
+  }));
+}
+async function deleteProfile(profile) {
+  const vault = await loadVault();
+  delete vault.profiles[profile];
+  await saveVault(vault);
+}
+
+// src/cli/vault.ts
+var USAGE = `
+Usage: looking-glass vault <command> [options]
+
+Commands:
+  store <profile>    Store credentials interactively (passwords masked)
+  list               List stored profiles and timestamps
+  delete <profile>   Delete a stored profile
+
+Environment:
+  VAULT_ENCRYPTION_KEY   Passphrase for encryption (32+ chars, required)
+  BROWSER_SESSIONS_DIR   Sessions directory (default: .browser-sessions)
+
+Examples:
+  npx looking-glass-mcp vault store linkedin
+  npx looking-glass-mcp vault list
+  npx looking-glass-mcp vault delete linkedin
+`.trim();
+function die(msg) {
+  console.error(`Error: ${msg}`);
+  process.exit(1);
+}
+function initFromEnv() {
+  const sessionsDir = resolve(process.env.BROWSER_SESSIONS_DIR || ".browser-sessions");
+  const key = process.env.VAULT_ENCRYPTION_KEY;
+  initVault(sessionsDir, key);
+  if (!isVaultConfigured()) {
+    die("VAULT_ENCRYPTION_KEY is not set or is shorter than 32 characters.");
+  }
+}
+function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve2) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve2(answer.trim());
+    });
+  });
+}
+function promptMasked(question) {
+  return new Promise((resolve2) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    process.stdout.write(question);
+    const stdin = process.stdin;
+    const wasRaw = stdin.isRaw;
+    if (stdin.isTTY && stdin.setRawMode) {
+      stdin.setRawMode(true);
+    }
+    let value = "";
+    const onData = (ch) => {
+      const c = ch.toString("utf-8");
+      if (c === "\n" || c === "\r" || c === "") {
+        if (stdin.isTTY && stdin.setRawMode) {
+          stdin.setRawMode(wasRaw ?? false);
+        }
+        stdin.removeListener("data", onData);
+        rl.close();
+        process.stdout.write("\n");
+        resolve2(value);
+      } else if (c === "") {
+        process.stdout.write("\n");
+        process.exit(1);
+      } else if (c === "\x7F" || c === "\b") {
+        if (value.length > 0) {
+          value = value.slice(0, -1);
+          process.stdout.write("\b \b");
+        }
+      } else {
+        value += c;
+        process.stdout.write("*");
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+function isSensitiveField(name) {
+  const lower = name.toLowerCase();
+  return ["password", "passwd", "pwd", "pass", "secret", "token", "key", "pin", "otp"].some(
+    (p) => lower.includes(p)
+  );
+}
+async function cmdStore(profileName) {
+  const profile = profileName || await prompt("Profile name: ");
+  if (!profile) die("Profile name is required.");
+  console.log(`
+Storing credential profile: ${profile}`);
+  console.log("Enter field name/value pairs. Leave field name empty to finish.\n");
+  const fields = {};
+  while (true) {
+    const fieldName = await prompt("Field name (empty to finish): ");
+    if (!fieldName) break;
+    const sensitive = isSensitiveField(fieldName);
+    const value = sensitive ? await promptMasked(`Value for "${fieldName}": `) : await prompt(`Value for "${fieldName}": `);
+    if (!value) {
+      console.log(`  Skipping empty field "${fieldName}"`);
+      continue;
+    }
+    fields[fieldName] = value;
+  }
+  if (Object.keys(fields).length === 0) {
+    die("No fields provided. Nothing stored.");
+  }
+  await storeCredential(profile, fields);
+  console.log(`
+\u2713 Stored profile "${profile}" with ${Object.keys(fields).length} field(s)`);
+}
+async function cmdList() {
+  const profiles = await listProfiles();
+  if (profiles.length === 0) {
+    console.log("No profiles stored.");
+    return;
+  }
+  console.log("Vault Profiles:\n");
+  for (const p of profiles) {
+    const lastUsed = p.lastUsedAt ? `, last used: ${p.lastUsedAt}` : "";
+    console.log(`  \u2022 ${p.name}  (created: ${p.createdAt}${lastUsed})`);
+  }
+}
+async function cmdDelete(profileName) {
+  const profile = profileName || await prompt("Profile name to delete: ");
+  if (!profile) die("Profile name is required.");
+  await deleteProfile(profile);
+  console.log(`\u2713 Deleted profile "${profile}"`);
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args[0] === "vault") args.shift();
+  const command = args[0];
+  const target = args[1];
+  if (!command || command === "--help" || command === "-h") {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  initFromEnv();
+  switch (command) {
+    case "store":
+      await cmdStore(target);
+      break;
+    case "list":
+      await cmdList();
+      break;
+    case "delete":
+      await cmdDelete(target);
+      break;
+    default:
+      console.error(`Unknown command: ${command}
+`);
+      console.log(USAGE);
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error(`Fatal: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "looking-glass-mcp",
-  "version": "3.0.0",
+  "version": "3.1.0",
+  "mcpName": "io.github.Sahib-Sawhney-WH/looking-glass-mcp",
   "description": "AI-native browser for agents — semantic change detection, self-healing interactions, structured extraction, credential vault, and enterprise Azure deployment",
   "main": "build/index.js",
   "type": "module",
   "bin": {
     "looking-glass-mcp": "bin/looking-glass-mcp.mjs",
-    "looking-glass": "bin/looking-glass-mcp.mjs"
+    "looking-glass": "bin/looking-glass-mcp.mjs",
+    "looking-glass-vault": "bin/looking-glass-vault.mjs"
   },
   "scripts": {
     "build": "node esbuild.config.js",