@reclaimprotocol/agent 0.1.9 → 0.1.11

package/README.md

@@ -1,6 +1,8 @@
 # @reclaimprotocol/agent
 
-Chrome-CDP + zkTLS provider-authoring tools. The agent captures network traffic from a browser, synthesizes Reclaim provider definitions from it (`contains` matchers + `jsonPath` / `xPath` / `regex` redactions), runs a local replay diagnostic, and produces a verified attestor proof via `@reclaimprotocol/attestor-core`.
+Reclaim Protocol lets your app verify **data points** about its users — a follower count, an account balance, an order history. This package gives your AI coding agent the tools to **find, build, test and fix the _data verification providers_** (the recipes that verify a data point) by inspecting and replaying captured requests, checking sessions, evaluate proofs, publishing updates, and much more.
+
+Under the hood it's Chrome-CDP + zkTLS provider-authoring tooling: it captures network traffic from a browser, synthesizes provider definitions from it (`contains` matchers + `jsonPath` / `xPath` / `regex` redactions), runs a local replay diagnostic, and produces a verified attestor proof via `@reclaimprotocol/attestor-core`.
 
 This package **is** the Reclaim MCP server (bin: `reclaim-mcp-server`). It depends on `@reclaimprotocol/client` for the typed HTTP client and registers the provider-authoring tools below alongside the backend-facing tools (credentials, publishing) in a single MCP surface. A standalone entry (`src/index.ts`) re-exports the client SDK plus `buildAgentTools` for embedding.
 
@@ -18,122 +20,18 @@ npx -y --package=@reclaimprotocol/agent reclaim-mcp-server
 
 > The `--package=` (short form `-p`) flag selects the `reclaim-mcp-server` binary from the package. We use the long `--package=` form throughout because the short `-p` collides with the `-p`/`--print` flag of some agent CLIs (notably `claude mcp add`), which silently swallows the command. Prefer a global install? Run `npm i -g @reclaimprotocol/agent` and use `reclaim-mcp-server` directly as the `command` (drop the `npx` wrapper and its `args`).
 
-### Claude Code
-
-**Recommended — install the plugin from the marketplace** (bundles this MCP server; no `claude mcp add` and no `-p` collision to worry about — the server's `how_it_works` tool serves the authoring guide on demand):
-
-```
-/plugin marketplace add reclaimprotocol/builder
-/plugin install reclaim@reclaim
-```
-
-This is the preferred path — prefer it over the manual `claude mcp add` below unless you have a specific reason not to (e.g. you're pinning a local build).
-
-**Advanced / fallback — add the MCP server directly** (skip if you used the plugin above):
-
-```bash
-# project scope → writes .mcp.json; add `-s user` for a global install
-claude mcp add reclaim -- npx -y --package=@reclaimprotocol/agent reclaim-mcp-server
-```
-
-…or add it to `.mcp.json` yourself:
-
-```json
-{
-  "mcpServers": {
-    "reclaim": {
-      "command": "npx",
-      "args": ["-y", "--package=@reclaimprotocol/agent", "reclaim-mcp-server"]
-    }
-  }
-}
-```
-
-### Claude Desktop (macOS / Windows app)
-
-Claude Desktop is the standalone consumer app — **separate from Claude Code**, and it does **not** support the plugin marketplace (`/plugin …` is Claude Code only). Configure the MCP server manually via its config file:
-
-- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-
-Edit it (via **Settings → Developer → Edit Config**, or open the file directly) and add:
-
-```json
-{
-  "mcpServers": {
-    "reclaim": {
-      "command": "npx",
-      "args": ["-y", "--package=@reclaimprotocol/agent", "reclaim-mcp-server"]
-    }
-  }
-}
-```
-
-Then **fully quit and reopen** Claude Desktop (a window close is not enough) so it re-reads the config and starts the server.
-
-> **Node must be on the app's PATH.** Claude Desktop launches the server as a subprocess using the environment it inherits at startup — it does **not** bundle Node. If the server shows as failed, either install Node ≥ 20 and relaunch, or set `"command"` to an **absolute path** to `npx`/`node` (find it with `which npx`), since GUI-launched apps sometimes get a minimal PATH. Chrome capture works the same as anywhere else — see [Chrome / CDP](#platform-notes).
-
-### Cursor
+### Installing into your coding agent
 
-Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+Copy-paste setup for **Claude Code** (plugin marketplace), **Claude Desktop**, **Cursor**, **opencode**, **Codex**, **Windsurf**, **VS Code**, **Cline** and other MCP clients lives in the public **[reclaimprotocol/developer-tools](https://github.com/reclaimprotocol/developer-tools)** repo — that's where the Claude Code plugin/marketplace is published.
 
-```json
-{
-  "mcpServers": {
-    "reclaim": {
-      "command": "npx",
-      "args": ["-y", "--package=@reclaimprotocol/agent", "reclaim-mcp-server"]
-    }
-  }
-}
-```
-
-### opencode
-
-Add to `opencode.json` (project) or `~/.config/opencode/opencode.json` (global):
+The quickest path, in Claude Code:
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "reclaim": {
-      "type": "local",
-      "command": ["npx", "-y", "--package=@reclaimprotocol/agent", "reclaim-mcp-server"],
-      "enabled": true
-    }
-  }
-}
-```
-
-### Codex
-
-```bash
-# writes ~/.codex/config.toml
-codex mcp add reclaim -- npx -y --package=@reclaimprotocol/agent reclaim-mcp-server
 ```
-
-…or add it to `~/.codex/config.toml` yourself (Codex uses TOML, not JSON):
-
-```toml
-[mcp_servers.reclaim]
-command = "npx"
-args = ["-y", "--package=@reclaimprotocol/agent", "reclaim-mcp-server"]
+/plugin marketplace add reclaimprotocol/developer-tools
+/plugin install reclaim@reclaim
 ```
 
-### Antigravity, Windsurf, VS Code, Cline & other MCP clients
-
-These all use the standard `mcpServers` shape — add a server through the app's MCP settings (or its `mcp`/`mcpServers` config file) with:
-
-```json
-{
-  "mcpServers": {
-    "reclaim": {
-      "command": "npx",
-      "args": ["-y", "--package=@reclaimprotocol/agent", "reclaim-mcp-server"]
-    }
-  }
-}
-```
+For any other client, point it at the stdio command above (`npx -y --package=@reclaimprotocol/agent reclaim-mcp-server`) — see the developer-tools README for per-client config and the Claude Desktop / GUI-app notes.
 
 ### Optional environment
 

package/lib/authoring/tools.js

@@ -135,6 +135,73 @@ export function authoringTools(resolveBackend) {
                 ...(c.httpOnly ? { httpOnly: true } : {}),
             }));
         }),
+        defineTool({
+            name: 'wait_for_login',
+            description: 'Wait for the user to finish logging in. Polls the browser\'s '
+                + 'REAL cookies over CDP (httpOnly INCLUDED) until a NEW session '
+                + 'cookie appears, ignoring analytics/bot cookies. The ONLY '
+                + 'correct login wait — NEVER use wait_for_page for it: page JS '
+                + 'can\'t see the httpOnly session cookie (hangs the whole '
+                + 'timeout), yet DOES see pre-login tracking cookies (a '
+                + 'length/substring check fires instantly, before the user '
+                + 'types). Snapshots the baseline itself — call right after '
+                + 'navigating to the login page. Does NOT navigate (never yanks '
+                + 'the user off login/2FA). Returns { loggedIn, newCookies }.',
+            inputSchema: objectSchema({ timeoutMs: { type: 'number' } }),
+        }, async (args) => {
+            const backend = resolveBackend(args);
+            const deadline = Date.now() + (Number(args.timeoutMs) || 180000);
+            const cookies = async () => {
+                const res = (await backend.sendCdp('Network.getCookies'));
+                return res.cookies ?? [];
+            };
+            // Analytics / bot-protection / pre-auth infra cookies appear (and
+            // rotate) without any login — never the signal, even when new.
+            const JUNK = new RegExp('^(' + [
+                '_ga', '_gid', '_gat', '_ym', '__ddg', '__gads', '__gpi', '__eoi',
+                '__utm', '_fbp', 'fbp', 'fr', 'FCCDCF', 'pinLogger',
+                'userFirstVisit', 'cf_', '_dd_', 'bcookie', 'bscookie', 'lidc',
+            ].join('|') + ')', 'i');
+            // A real session/auth cookie name. Deliberately NOT bare `token` — a
+            // challenge/CSRF token (e.g. LinkedIn `chp_token`) contains it and is
+            // set BEFORE auth completes. Any new httpOnly cookie is also a
+            // candidate (server-set session cookies are usually httpOnly).
+            const SESSION = /sess|sid|jwt|_session|auth|logged.?in|remember|li_at/i;
+            // Auth/challenge URL paths — while the page is still on one, login is
+            // NOT done (a mid-flow cookie must not count). Cross-site-stable, far
+            // more so than cookie names.
+            const AUTH_URL = new RegExp([
+                'login', 'signin', 'sign-in', 'challenge', 'checkpoint', '\\buas\\b',
+                'authorize', '\\bsso\\b', 'mfa', '2fa', 'two-factor', 'otp', 'verify',
+                'password',
+            ].join('|'), 'i');
+            const offAuthUrl = async () => {
+                const { value } = await evalInPage(backend, 'location.href');
+                const href = typeof value === 'string' ? value : '';
+                try {
+                    const u = new URL(href);
+                    return !AUTH_URL.test(u.pathname + u.search);
+                }
+                catch {
+                    return false;
+                }
+            };
+            const initial = await cookies();
+            const baseline = new Set(initial.map((c) => c.name));
+            while (Date.now() < deadline) {
+                const current = await cookies();
+                const fresh = current
+                    .filter((c) => !baseline.has(c.name) && !JUNK.test(c.name));
+                const hit = fresh.filter((c) => c.httpOnly || SESSION.test(c.name));
+                // BOTH required: a new session cookie AND the page has left the auth
+                // flow. Either alone false-positives (mid-flow token; stray nav).
+                if (hit.length && await offAuthUrl()) {
+                    return { loggedIn: true, newCookies: hit.map((c) => c.name) };
+                }
+                await sleep(1000);
+            }
+            return { loggedIn: false, newCookies: [] };
+        }),
         defineTool({
             name: 'list_requests',
             description: 'List captured network requests (method/url/status/size), newest '

package/lib/mcp/tools/agent/find.js

@@ -14,38 +14,63 @@ export function findTool(resolveBackend) {
         description: 'Search captured responses for any encoding of `value` (raw, '
             + 'URL/JSON/HTML-escaped, …). Returns a ranked candidate list with '
             + 'the matched variant, score, and a short snippet — used to locate '
-            + 'the request that returns a target. Server-side; bodies stay here.',
+            + 'the request that returns a target. Also finds SPLIT matches: when '
+            + '`value` is multi-word (e.g. a full name), a response that carries '
+            + 'every word SEPARATELY (a JSON profile API with first/last name in '
+            + 'distinct fields) is returned with `splitMatch:true` — prove those '
+            + 'per-field (a redaction per part) rather than as one string. '
+            + 'Server-side; bodies stay here.',
         inputSchema: objectSchema({ value: { type: 'string' }, limit: { type: 'number' } }, ['value']),
     }, async (args) => {
         const backend = resolveBackend(args);
-        const variants = normalizeCandidates(String(args.value));
+        const value = String(args.value);
+        const variants = normalizeCandidates(value);
+        // Name-part tokens (≥3 chars) for split-field detection — a JSON API
+        // often carries a full name as separate first/last fields, so the whole
+        // string never matches even though the value IS there.
+        const tokens = value.split(/\s+/).filter((t) => t.length >= 3);
+        const snip = (body, idx, len) => {
+            const s = Math.max(0, idx - 40);
+            return body.slice(s, Math.min(body.length, idx + len + 40));
+        };
         const ranked = [];
         for (const r of backend.capture.requests.values()) {
             if (!r.responseBody) {
                 continue;
             }
+            const body = r.responseBody;
+            // Prefer JSON responses + smaller bodies (likely API endpoints).
+            const base = (r.contentType.includes('json') ? 10 : 0)
+                + Math.max(0, 5 - Math.log10(Math.max(r.size, 1)));
             let hit;
             for (const v of variants) {
-                const idx = r.responseBody.indexOf(v);
+                const idx = body.indexOf(v);
                 if (idx >= 0) {
-                    const start = Math.max(0, idx - 40);
-                    const end = Math.min(r.responseBody.length, idx + v.length + 40);
-                    hit = { snippet: r.responseBody.slice(start, end), variant: v };
+                    hit = { snippet: snip(body, idx, v.length), variant: v };
                     break;
                 }
             }
-            if (!hit) {
+            if (hit) {
+                // Whole-value match — ranked above split matches (+5).
+                ranked.push({
+                    ...publicRequest(r),
+                    matchedVariant: hit.variant,
+                    snippet: hit.snippet,
+                    score: base + 5,
+                });
                 continue;
             }
-            // Prefer JSON responses + smaller bodies (likely API endpoints).
-            const score = (r.contentType.includes('json') ? 10 : 0)
-                + Math.max(0, 5 - Math.log10(Math.max(r.size, 1)));
-            ranked.push({
-                ...publicRequest(r),
-                matchedVariant: hit.variant,
-                snippet: hit.snippet,
-                score,
-            });
+            // Split match: every word present separately (e.g. first/last name
+            // in distinct JSON fields). Requires ≥2 tokens so it's specific.
+            if (tokens.length >= 2 && tokens.every((t) => body.includes(t))) {
+                ranked.push({
+                    ...publicRequest(r),
+                    matchedVariant: `split:${tokens.join('+')}`,
+                    splitMatch: true,
+                    snippet: snip(body, body.indexOf(tokens[0]), tokens[0].length),
+                    score: base,
+                });
+            }
         }
         ranked.sort((a, b) => b.score - a.score);
         const limit = Number(args.limit) || 10;

package/lib/mcp/tools/agent/propose.js

@@ -71,11 +71,11 @@ export function proposeTool(resolveBackend) {
                 + '`targets` array');
         }
         for (const t of targets) {
-            if ((t.hash ?? defaultHash) !== undefined
-                && t.value.length > OPRF_MAX_BYTES) {
+            const bytes = Buffer.byteLength(t.value, 'utf8');
+            if ((t.hash ?? defaultHash) !== undefined && bytes > OPRF_MAX_BYTES) {
                 throw new Error(`OPRF caps hashed values at ${OPRF_MAX_BYTES} bytes; got `
-                    + `${t.value.length}-byte "${t.value}". Use a tighter `
-                    + 'target or drop `hash`.');
+                    + `${bytes}-byte "${t.value}". Use a tighter target or drop `
+                    + '`hash`.');
             }
         }
         const captured = backend.capture.requests.get(requestId);

package/lib/old/client.d.ts

@@ -99,11 +99,6 @@ export declare class ReclaimOldClient {
     registerProvider(body: RegisterProviderBody): Promise<unknown>;
     updateProviderConfig(providerId: string, body: UpdateProviderConfigBody): Promise<unknown>;
     listVersions(providerId: string): Promise<unknown>;
-    /** Full `providerConfig` (loginUrl, customInjection, requestData, ...) for
-     *  one version — the latest when `version` is omitted. Readable for ANY
-     *  non-archived provider (not owner-restricted), same as the dashboard's
-     *  edit-form prefill fetch. */
-    getProviderConfig(providerId: string, version?: string): Promise<unknown>;
     /** Partial update on the PROVIDER document itself — name/description/
      *  providerType/tags/isActive, after creation. The backend 403s if you
      *  don't own the provider (and aren't admin); other providerConfig-style

package/lib/old/client.js

@@ -60,16 +60,6 @@ export class ReclaimOldClient {
     listVersions(providerId) {
         return __classPrivateFieldGet(this, _ReclaimOldClient_instances, "m", _ReclaimOldClient_request).call(this, 'GET', `/providers/${encodeURIComponent(providerId)}/versions`, { auth: true });
     }
-    /** Full `providerConfig` (loginUrl, customInjection, requestData, ...) for
-     *  one version — the latest when `version` is omitted. Readable for ANY
-     *  non-archived provider (not owner-restricted), same as the dashboard's
-     *  edit-form prefill fetch. */
-    getProviderConfig(providerId, version) {
-        return __classPrivateFieldGet(this, _ReclaimOldClient_instances, "m", _ReclaimOldClient_request).call(this, 'GET', `/providers/${encodeURIComponent(providerId)}/config`, {
-            auth: true,
-            query: version ? { versionNumber: version } : undefined,
-        });
-    }
     /** Partial update on the PROVIDER document itself — name/description/
      *  providerType/tags/isActive, after creation. The backend 403s if you
      *  don't own the provider (and aren't admin); other providerConfig-style

package/lib/old/to-register.d.ts

@@ -83,6 +83,8 @@ interface OldRequestData {
 export interface OldInjectedRequestData extends OldRequestData {
     required?: boolean;
     multiple?: boolean;
+    templateParams?: string[];
+    templateParamsMode?: 'separate' | 'merge';
 }
 /** Translate fresh `allowedInjectedRequestData` drafts (the author's input
  *  shape, `AllowedJsRequest[]` — same shape the builder translator uses for

package/lib/old/to-register.js

@@ -89,11 +89,15 @@ function requestDataFrom(providers) {
  *  this shape and should be passed straight through instead — don't run it
  *  through this a second time. */
 export function injectedRequestDataFrom(requests) {
-    return requests.map((req) => ({
-        ...requestDataFromProvider(req),
-        required: req.required ?? true,
-        multiple: req.multiple ?? true,
-    }));
+    return requests.map((req) => {
+        return {
+            ...requestDataFromProvider(req),
+            required: req.required ?? true,
+            multiple: req.multiple ?? true,
+            templateParams: req.templateParams,
+            templateParamsMode: req.templateParamsMode,
+        };
+    });
 }
 /** Body for `POST /api/providers/register` — new provider + v1.0.0. Every
  *  drafted request becomes a `requestData` entry; provider-level fields (name)

package/lib/old/tools/build.js

@@ -1,6 +1,5 @@
 import { authenticateTool } from "./authenticate.js";
 import { getProviderInfoTool } from "./get-provider-info.js";
-import { getProviderVersionConfigTool } from "./get-version-config.js";
 import { getMeProvidersTool } from "./me-providers.js";
 import { createVersionFromCaptureTool } from "./publish.js";
 import { sessionAnalyticsLogsTool } from "./session-analytics-logs.js";
@@ -20,7 +19,6 @@ export function buildOldBackendTools(client, sdkClient) {
         authenticateTool(client),
         createVersionFromCaptureTool(client),
         getMeProvidersTool(client),
-        getProviderVersionConfigTool(client),
         getProviderInfoTool(sdkClient),
         updateProviderMetadataTool(client),
         sessionAnalyticsLogsTool(client),

package/lib/old/tools/get-provider-info.d.ts

@@ -1,14 +1,17 @@
 import { type RegisteredTool } from '../../mcp/server.ts';
 import type { ReclaimSdkClient } from '../sdk-client.ts';
 /**
- * Read provider info from the PUBLIC production SDK backend
- * (`api.reclaimprotocol.org`) — the service the verification SDK/attestor
- * itself calls at runtime, NOT the old-devtools dashboard backend
- * (`get_provider_version_config`, `devapi.reclaimprotocol.org`, requires
- * auth). Both underlying reads are unauthenticated.
+ * The single provider-read tool for old-devtools mode. Reads from the PUBLIC
+ * production SDK backend (`api.reclaimprotocol.org`) — the service the
+ * verification SDK/attestor itself calls at runtime. No auth required, works
+ * for ANY provider.
  *
- * Fetches BOTH shapes in one call, since they're complementary:
- *   - `provider`: full provider + providerConfig, `customInjection` included.
+ * Fetches BOTH shapes in one call, since they're complementary and together
+ * cover everything a caller needs before re-publishing a new version:
+ *   - `provider`: the full provider + providerConfig — `customInjection`,
+ *     `userAgent`, `allowedInjectedRequestData`, `requestData`, everything.
+ *     This is what you read before create_provider_version_from_capture so
+ *     you can pass the whole config back (that tool carries nothing forward).
  *   - `configs`: the trimmed runtime recipe the attestor actually consumes —
  *     `customInjection` deliberately omitted, `isScriptRequestingClaim`
  *     computed instead.

package/lib/old/tools/get-provider-info.js

@@ -13,14 +13,17 @@ async function attempt(label, call) {
     }
 }
 /**
- * Read provider info from the PUBLIC production SDK backend
- * (`api.reclaimprotocol.org`) — the service the verification SDK/attestor
- * itself calls at runtime, NOT the old-devtools dashboard backend
- * (`get_provider_version_config`, `devapi.reclaimprotocol.org`, requires
- * auth). Both underlying reads are unauthenticated.
+ * The single provider-read tool for old-devtools mode. Reads from the PUBLIC
+ * production SDK backend (`api.reclaimprotocol.org`) — the service the
+ * verification SDK/attestor itself calls at runtime. No auth required, works
+ * for ANY provider.
  *
- * Fetches BOTH shapes in one call, since they're complementary:
- *   - `provider`: full provider + providerConfig, `customInjection` included.
+ * Fetches BOTH shapes in one call, since they're complementary and together
+ * cover everything a caller needs before re-publishing a new version:
+ *   - `provider`: the full provider + providerConfig — `customInjection`,
+ *     `userAgent`, `allowedInjectedRequestData`, `requestData`, everything.
+ *     This is what you read before create_provider_version_from_capture so
+ *     you can pass the whole config back (that tool carries nothing forward).
  *   - `configs`: the trimmed runtime recipe the attestor actually consumes —
  *     `customInjection` deliberately omitted, `isScriptRequestingClaim`
  *     computed instead.
@@ -31,15 +34,18 @@ export function getProviderInfoTool(client) {
         description: 'Read a PUBLISHED provider from the public production SDK backend ' +
             '(api.reclaimprotocol.org — what the verification SDK/attestor ' +
             'itself fetches at runtime), for ANY provider, no auth required. ' +
-            'Different from get_provider_version_config, which reads the old ' +
-            'devtools DASHBOARD backend and requires auth. \n\n' +
+            'This is the provider-read tool for old-devtools mode. \n\n' +
             'Returns two complementary reads for the given version (latest ' +
-            'when `versionNumber` is omitted): `provider` (the full provider ' +
-            '+ providerConfig, including `customInjection`) and `configs` (the ' +
-            'trimmed recipe the attestor actually consumes — `customInjection` ' +
-            'is deliberately OMITTED there, replaced by a computed ' +
-            '`isScriptRequestingClaim` flag). One endpoint failing (e.g. an ' +
-            'invalid `versionNumber`) is reported under `errors` without ' +
+            'when `versionNumber` is omitted): `provider` (the FULL provider ' +
+            '+ providerConfig — `customInjection`, `userAgent`, ' +
+            '`allowedInjectedRequestData`, `requestData`, everything) and ' +
+            '`configs` (the trimmed recipe the attestor actually consumes — ' +
+            '`customInjection` is deliberately OMITTED there, replaced by a ' +
+            'computed `isScriptRequestingClaim` flag). Read `provider` here ' +
+            'BEFORE create_provider_version_from_capture so you can pass the ' +
+            'whole existing config back — that tool always creates a new ' +
+            'version and carries nothing forward. One endpoint failing (e.g. ' +
+            'an invalid `versionNumber`) is reported under `errors` without ' +
             'hiding a result the other endpoint did return.',
         inputSchema: {
             type: 'object',