@reclaimprotocol/agent 0.1.32 → 0.1.34

package/lib/mcp/api/tools.d.ts

@@ -1,3 +1,11 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { ReclaimClient } from '@reclaimprotocol/client/api';
-export declare function registerTools(server: McpServer, client: ReclaimClient): void;
+import { ReclaimClient } from '@reclaimprotocol/client/api';
+/** The client for a call that presents the organization's API key. */
+export type OrgClientFactory = (orgToken: string) => ReclaimClient;
+/**
+ * Register a tool per generated operation. Calls go out with the developer's
+ * session token, except operations only an org API key (`rorg_…`) authorizes:
+ * those take an `orgToken` input (else the server's RECLAIM_ORG_SECRET) and go
+ * out through `orgClient` with that key.
+ */
+export declare function registerTools(server: McpServer, client: ReclaimClient, orgClient?: OrgClientFactory): void;

package/lib/mcp/api/tools.js

@@ -1,5 +1,10 @@
+import { unauthorized } from '@hapi/boom';
+import { ReclaimClient } from '@reclaimprotocol/client/api';
+import assert from 'node:assert';
+import { orgSecret } from "../../consts.js";
 import { remapErrorAsResponse } from "../remap_errors.js";
 import { successResponse } from "../success-response.js";
+import { savedOrgKey } from "../tools/authenticate/org-key-store.js";
 import { MCP_TOOLS } from "./operations.gen.js";
 /**
  * The generated `MCP_TOOLS` are keyed by OpenAPI `operationId` (PascalCase,
@@ -14,8 +19,27 @@ function toSnakeCase(name) {
         .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
         .toLowerCase();
 }
-export function registerTools(server, client) {
-    for (const [opId, shape] of Object.entries(MCP_TOOLS)) {
+/**
+ * Register a tool per generated operation. Calls go out with the developer's
+ * session token, except operations only an org API key (`rorg_…`) authorizes:
+ * those take an `orgToken` input (else the server's RECLAIM_ORG_SECRET) and go
+ * out through `orgClient` with that key.
+ */
+export function registerTools(server, client, orgClient = (orgToken) => new ReclaimClient({
+    baseUrl: client.baseUrl,
+    token: orgToken,
+})) {
+    for (const [opId, tool] of Object.entries(MCP_TOOLS)) {
+        const orgTokenOnly = 'orgTokenOnly' in tool && tool.orgTokenOnly === true;
+        const shape = {
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            // Generated entries gain `annotations` when the spec marks them; read
+            // it defensively so an older generated file still registers.
+            ...('annotations' in tool && tool.annotations
+                ? { annotations: tool.annotations }
+                : {}),
+        };
         if (!isOperationId(opId)) {
             throw new Error(`Generated MCP operation is not in the API client: ${opId}`);
         }
@@ -23,12 +47,19 @@ export function registerTools(server, client) {
         // a hand-written tool throws here at startup — intentional: hand-written
         // and generated names must stay disjoint (see start.ts), so a clash is a
         // bug to surface, not silently shadow.
-        server.registerTool(toSnakeCase(opId), shape, async (args) => {
+        server.registerTool(toSnakeCase(opId), shape, async (input) => {
             try {
+                if (!isRecord(input)) {
+                    throw new Error(`Invalid generated MCP arguments for ${opId}`);
+                }
+                const { orgToken, ...args } = input;
                 if (!isOperationArgs(opId, args)) {
                     throw new Error(`Invalid generated MCP arguments for ${opId}`);
                 }
-                const result = await client.call(opId, args);
+                const caller = orgTokenOnly
+                    ? orgClient(orgTokenFor(toSnakeCase(opId), orgToken, args))
+                    : client;
+                const result = await caller.call(opId, args);
                 return successResponse(result.data);
             }
             catch (err) {
@@ -56,3 +87,23 @@ function isOperationId(value) {
 function isOperationArgs(_operationId, value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The org API key a call authenticates with: its `orgToken`, else the
+ *  server's RECLAIM_ORG_SECRET, else the key `issue_org_token` saved (for the
+ *  call's `orgId` when it has one, otherwise the most recent). The session
+ *  token (the developer's sign-in) can't stand in, since these routes accept
+ *  only an org key. */
+function orgTokenFor(tool, orgToken, args) {
+    const orgId = isRecord(args) && isRecord(args.params)
+        ? args.params.orgId
+        : undefined;
+    const token = (typeof orgToken === 'string' && orgToken)
+        || orgSecret()
+        || savedOrgKey(typeof orgId === 'string' ? orgId : undefined);
+    assert(token, unauthorized(`${tool} authenticates with the organization's API key. Run `
+        + 'issue_org_token to save one, or pass orgToken, or set '
+        + 'RECLAIM_ORG_SECRET for the MCP server.'));
+    return token;
+}

package/lib/mcp/instructions.js

@@ -45,7 +45,7 @@ const BUILDER_TOPIC_FILES = {
  *  the right one without fetching several. Keyed across both modes; only the
  *  topics a mode actually has are listed back to it. */
 const TOPIC_SUMMARIES = {
-    'overview': 'Terminology, your stance, and the whole loop at a glance.',
+    'overview': 'Terminology, your stance, and the authoring checklist.',
     'contributions': 'Contributing a public provider as a volunteer: the '
         + 'candidate-and-review workflow and the extra rules it adds.',
     'auth': 'Signing in to the backend, and which token authorizes what.',
@@ -54,23 +54,23 @@ const TOPIC_SUMMARIES = {
     'browser': 'Choosing a browser source (local Chrome, the Reclaim runtime in '
         + 'Docker, a remote Builder browser, or a custom CDP endpoint), '
         + 'geolocation, live view, and launch troubleshooting.',
-    'capture': 'Tabs, login detection, driving the page, and picking an '
-        + 'authenticated request to prove.',
+    'capture': 'Tabs, sign-in detection, capturing through the navigation '
+        + 'script, and picking an authenticated request to prove.',
     'draft': 'The OPRF/privacy decision, propose_provider, and the canonical '
         + 'drafted shape.',
     'params': 'Extracted vs consumer-supplied vs secret params, the URL '
         + 'character budget, and runtime resolution.',
     'prove': 'replay_request, the mandatory auth-bound check, run_proof, and '
         + 'diagnosing failures.',
-    'publish': 'Creating/reusing a provider, versions, multi-request providers, '
-        + 'and going live.',
-    'discover': 'Finding providers, resolving them, and creating a verification '
-        + 'session.',
-    'integration': 'Set up a Builder token, callback, frontend and backend '
-        + 'over the HTTP session API; direct `api=2` API and result '
+    'publish': 'Creating a provider, provider versions, multi-request '
+        + 'providers, and going live.',
+    'discover': 'Reusing existing providers: finding, resolving, and '
+        + 'creating a verification session.',
+    'integration': 'After start_integration: org key, callback, frontend and '
+        + 'backend over the HTTP session API; `api=2` and result '
         + 'verification.',
-    'user-script': 'Authoring jsUserScripts / customInjection to drive '
-        + 'login-gated pages.',
+    'user-script': 'The navigation script (jsUserScripts): sign-in redirect, '
+        + 'multi-page walk, test_user_script with keep.',
     'interception': 'injectionType / interceptorType, live interception, the '
         + 'document-replay flag, and what to do when a site won\'t load or '
         + 'won\'t let the user sign in.',

package/lib/mcp/server.d.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type RegisteredTool } from '../tools/registry.ts';
-export { defineTool, type RegisteredTool, type ToolDefinition, } from '../tools/registry.ts';
+export { defineTool, type RegisteredTool, type ToolAnnotations, type ToolDefinition, } from '../tools/registry.ts';
 /**
  * Registers a list of RegisteredTool entries on a high-level McpServer.
  * Converts JSON Schema definitions to Zod and provides consistent

package/lib/mcp/server.js

@@ -15,6 +15,9 @@ export function registerToolList(server, tools) {
         server.registerTool(tool.definition.name, {
             description: tool.definition.description,
             inputSchema: toZod(tool.definition.inputSchema),
+            ...(tool.definition.annotations
+                ? { annotations: tool.definition.annotations }
+                : {}),
         }, async (args) => {
             try {
                 return successResponse(await tool.handler(args));

package/lib/mcp/start.js

@@ -79,7 +79,12 @@ export async function startMcpServer() {
         registerToolList(server, buildVerificationTools());
         // Add auto-generated tools with snake_case wrappers
         // for every MCP-tagged operation.
-        registerTools(server, client);
+        // Org-key-only operations go out with the call's `orgToken` instead.
+        registerTools(server, client, (orgToken) => new ReclaimClient({
+            baseUrl: apiUrl(),
+            token: orgToken,
+            headers: { 'User-Agent': `${NAME}/${VERSION}` },
+        }));
         if (agentToolsEnabled) {
             agentState = buildAgentState();
             registerToolList(server, buildAgentTools(client, client, agentState));

package/lib/mcp/success-response.js

@@ -6,7 +6,11 @@ export function successResponse(value) {
         structuredContent: structured(value),
         content: [{
                 type: 'text',
-                text: JSON.stringify(value, null, 2) ?? 'null',
+                // A string result is text written for the agent (a plan, a guide):
+                // JSON-quoting it would escape every newline.
+                text: typeof value === 'string'
+                    ? value
+                    : JSON.stringify(value, null, 2) ?? 'null',
             }],
     };
 }

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

@@ -3,10 +3,10 @@ import { defineTool } from "../../server.js";
 export function analyzeTool(captures) {
     return defineTool({
         name: 'analyze_request_constraints',
-        description: 'Flag provider-authoring concerns for one captured request — signed '
-            + 'request, CSRF dependency, bot challenge, short-lived token, '
-            + 'GraphQL. Call it on each top candidate from '
-            + 'find_requests_containing before drafting, and relay the returned '
+        description: 'Returns provider-authoring concerns for one captured request: '
+            + 'signed request, CSRF dependency, bot challenge, short-lived '
+            + 'token, or GraphQL. Call it on each top candidate from '
+            + '`find_requests_containing` before drafting, and relay the '
             + '`concerns` to the developer verbatim.',
         inputSchema: {
             type: 'object',
@@ -16,6 +16,7 @@ export function analyzeTool(captures) {
             },
             required: ['captureId', 'requestId'],
         },
+        annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ captureId, requestId }) => {
         const entry = captures.sessions.get(captureId);
         if (!entry) {

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

@@ -104,13 +104,16 @@ dependencies = {}) {
     };
     return defineTool({
         name: 'attach_browser',
-        description: 'Connects provider-authoring tools to a browser. Call without '
-            + '`mode` to receive the current options, then ask the developer to '
-            + 'choose; `builder` consumes quota and only `container` and `builder` '
-            + 'support a shareable live view. Call again once with the chosen '
-            + 'mode. Relay returned live-view URLs verbatim. For selection, '
-            + 'geolocation, and lifecycle guidance, call '
-            + 'how_it_works({ topic: "browser" }).',
+        description: 'Connects the authoring tools to a browser that loads the '
+            + 'developer\'s sign-in page and target site. `builder` and '
+            + '`container` run the browser remotely or in Docker, away from the '
+            + 'developer\'s own profile; `dedicated`, `attach`, and `custom` use a '
+            + 'local or supplied Chrome. Call without `mode` to receive the '
+            + 'options, ask the developer to choose, then call again once with '
+            + 'the chosen mode. `builder` consumes quota. Only `container` and '
+            + '`builder` support a shareable live view. Relay returned live-view '
+            + 'URLs verbatim. See how_it_works({ topic: "browser" }) for '
+            + 'selection, geolocation, and lifecycle.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -153,6 +156,7 @@ dependencies = {}) {
                 },
             },
         },
+        annotations: { openWorldHint: true, destructiveHint: false },
     }, async (parsed) => {
         const persisted = state.config.read()?.browser_agent;
         // Deliberately NOT falling back to the persisted mode: which browser

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

@@ -21,6 +21,7 @@ import { podProofTools } from "./pod-proof.js";
 import { createVersionFromCaptureTool } from "./publish.js";
 import { resetAll, sessionTools } from "./session.js";
 import { sharedAuthoringTools } from "./shared.js";
+import { startIntegrationTool } from "./start-integration.js";
 /** Exported so a mode (for example, old-devtools) that supplies its own
  *  publish tool can build the attach/capture state up front and share the SAME
  *  instance with `buildAgentTools` — letting that publish tool see the live
@@ -71,7 +72,8 @@ export function buildAgentTools(client, builderClient = client, externalState) {
         tools.push(t);
     }
     if (client) {
-        tools.push(createVersionFromCaptureTool(client, state.attach));
+        tools.push(startIntegrationTool());
+        tools.push(createVersionFromCaptureTool(client, state.attach, state.captures));
     }
     return tools;
 }

package/lib/mcp/tools/agent/capture.d.ts

@@ -1,4 +1,4 @@
-import { type DraftStore } from '../../../authoring/index.ts';
+import { type DraftStore, type KeptScriptRef } from '../../../authoring/index.ts';
 import { type CaptureSession } from '../../../cdp/capture.ts';
 import { type RegisteredTool } from '../../server.ts';
 import type { AttachState } from './attach.ts';
@@ -13,7 +13,7 @@ export interface CaptureEntry {
     tabClient: Awaited<ReturnType<AttachState['handles']['attachToTab']>>;
     drafts: DraftStore;
 }
-export interface CaptureStore {
+export interface CaptureStore extends KeptScriptRef {
     sessions: Map<string, CaptureEntry>;
     activeTab?: string;
 }

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

@@ -1,4 +1,4 @@
-import { makeDraftStore } from "../../../authoring/index.js";
+import { makeDraftStore, } from "../../../authoring/index.js";
 import { startCapture } from "../../../cdp/capture.js";
 import { defineTool } from "../../server.js";
 export async function resetCaptures(captures) {
@@ -7,6 +7,7 @@ export async function resetCaptures(captures) {
     }
     captures.sessions.clear();
     delete captures.activeTab;
+    delete captures.keptScript;
 }
 export function captureTools(attachRef, captures) {
     const requireAttached = () => {
@@ -17,14 +18,15 @@ export function captureTools(attachRef, captures) {
     };
     const startTool = defineTool({
         name: 'start_capture',
-        description: 'Begin recording network requests on the specified tab. '
-            + 'Returns a captureId — the session handle the authoring tools '
-            + '(navigate, propose_provider, run_proof, …) all take.',
+        description: 'Starts recording network requests on a tab. Returns a captureId, '
+            + 'the session handle that the authoring tools (`navigate`, '
+            + '`propose_provider`, `run_proof`) take.',
         inputSchema: {
             type: 'object',
             properties: { tabId: { type: 'string' } },
             required: ['tabId'],
         },
+        annotations: { openWorldHint: true },
     }, async ({ tabId }) => {
         const attached = requireAttached();
         const tabClient = await attached.handles.attachToTab(tabId);
@@ -37,13 +39,14 @@ export function captureTools(attachRef, captures) {
     });
     const stopTool = defineTool({
         name: 'stop_capture',
-        description: 'Stop recording on the given capture. '
-            + 'Captured data remains queryable until reset_session.',
+        description: 'Stops recording on a capture. Captured requests stay queryable '
+            + 'until `reset_session`.',
         inputSchema: {
             type: 'object',
             properties: { captureId: { type: 'string' } },
             required: ['captureId'],
         },
+        annotations: { openWorldHint: false, idempotentHint: true },
     }, async ({ captureId }) => {
         const entry = captures.sessions.get(captureId);
         if (!entry) {
@@ -54,11 +57,11 @@ export function captureTools(attachRef, captures) {
     });
     const getTool = defineTool({
         name: 'get_request',
-        description: 'Return the full headers and bodies of one captured request. Use it '
-            + 'to inspect a candidate that find_requests_containing ranked. '
-            + 'Unlike every other tool here, the headers are RAW — cookie and '
-            + 'authorization values are visible. Read them; never repeat them to '
-            + 'the developer or write them to a file.',
+        description: 'Returns the full headers and bodies of one captured request, to '
+            + 'inspect a candidate that `find_requests_containing` ranked. Unlike '
+            + 'the other tools, headers are raw: cookie and authorization values '
+            + 'are visible. Read them for diagnosis; do not repeat them to the '
+            + 'developer or write them to a file.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -67,6 +70,7 @@ export function captureTools(attachRef, captures) {
             },
             required: ['captureId', 'requestId'],
         },
+        annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ captureId, requestId }) => {
         const entry = captures.sessions.get(captureId);
         if (!entry) {

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

@@ -5,10 +5,11 @@ import { defineTool } from "../../server.js";
 export function listTabsTool(attachRef) {
     return defineTool({
         name: 'list_tabs',
-        description: 'List the open tabs in the attached browser, with their tabId, title '
-            + 'and URL. Call it after attach_browser to pick the tabId to pass to '
-            + 'start_capture.',
+        description: 'Returns the open tabs of the attached browser, each with its tabId, '
+            + 'title, and URL. Call it after `attach_browser` to pick the tabId '
+            + 'for `start_capture`.',
         inputSchema: { type: 'object', properties: {} },
+        annotations: { readOnlyHint: true, openWorldHint: true },
     }, async () => {
         if (!attachRef.current) {
             throw new Error('Not attached. Call attach_browser first.');

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

@@ -11,17 +11,16 @@ import { defineTool } from "../../../tools/registry.js";
 export function findTool(resolveBackend) {
     return defineTool({
         name: 'find_requests_containing',
-        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. Also finds SPLIT matches: when '
-            + '`value` is multi-word (for example, a full name), a response '
-            + 'that carries every word SEPARATELY (a JSON profile API with '
-            + 'first and 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.',
+        description: 'Searches captured responses for any encoding of `value` (raw, '
+            + 'URL-, JSON-, or HTML-escaped). Returns ranked candidates with the '
+            + 'matched variant, score, and a short snippet, to locate the '
+            + 'request that returns a data point. Also finds split matches: when '
+            + '`value` has several words (for example, a full name) and a '
+            + 'response carries each word in a separate field, the candidate has '
+            + '`splitMatch: true`; prove those per field (one redaction per '
+            + 'part). Response bodies stay server-side.',
         inputSchema: objectSchema({ value: { type: 'string' }, limit: { type: 'number' } }, ['value']),
+        annotations: { readOnlyHint: true, openWorldHint: false },
     }, async (args) => {
         const backend = resolveBackend(args);
         const value = String(args.value);

package/lib/mcp/tools/agent/how-it-works.js

@@ -16,6 +16,7 @@ export function howItWorksTool(oldMode) {
             + 'backend. Call without a topic for the overview and index. Before an '
             + 'unfamiliar or sensitive step, request that topic. Prefer one topic; '
             + '`all` returns the much larger complete guide.',
+        annotations: { readOnlyHint: true, openWorldHint: false },
         inputSchema: {
             type: 'object',
             properties: {

package/lib/mcp/tools/agent/live-view.js

@@ -21,13 +21,15 @@ export function liveViewTools(attachRef) {
     return [
         defineTool({
             name: 'share_browser_view',
-            description: 'Shares an attached `container` browser with someone who is not at '
-                + 'this machine. Step 1: call with no arguments to get the local '
-                + 'viewer URL and the `cloudflared` command to run yourself (this '
-                + 'server does not run it). Step 2: after cloudflared prints its '
-                + '`https://*.trycloudflare.com` URL, call again with it as '
-                + '`publicUrl` to get the link to relay. Treat the link as a '
-                + 'credential. For `builder`, use the `liveViewUrl` from '
+            description: 'Returns a link that lets someone who is not at this machine watch '
+                + 'and drive the attached `container` browser, for example to sign '
+                + 'in. This server opens no tunnel itself. Step 1: call with no '
+                + 'arguments to get the local viewer URL and the `cloudflared` '
+                + 'command for the developer to run. Step 2: after cloudflared '
+                + 'prints its `https://*.trycloudflare.com` URL, call again with it '
+                + 'as `publicUrl` to get the link to relay. The link grants access '
+                + 'to that browser session only, so share it only with the person '
+                + 'who needs it. For `builder`, use the `liveViewUrl` from '
                 + '`attach_browser`.',
             inputSchema: {
                 type: 'object',
@@ -39,6 +41,7 @@ export function liveViewTools(attachRef) {
                     },
                 },
             },
+            annotations: { openWorldHint: true, idempotentHint: true },
         }, async (parsed) => {
             const attached = attachRef.current;
             assert(attached, badRequest('No browser attached. Call attach_browser first.'));

package/lib/mcp/tools/agent/pod-proof.js

@@ -22,17 +22,12 @@ import { shapeRichProofResult } from "./proof.js";
 export function podProofTools(attachRef, captures) {
     const tool = defineTool({
         name: 'run_proof_via_pod',
-        description: 'Prove the drafted recipe through the Popcorn pod\'s own TEE '
-            + '(/reclaim/prove) instead of the local attestor SDK — this is '
-            + 'the remote browser session\'s own api for creating a proof '
-            + 'from that same session. Use this instead of run_proof '
-            + 'whenever this capture\'s '
-            + 'attach mode is "builder": the pod is the same enclave that '
-            + 'held the browser\'s TLS session (and its country-routed egress, '
-            + 'if any), so '
-            + 'the proof reaches the target from the browser\'s own exit IP. '
-            + 'No ownerAddress needed — the pod signs with the attestor\'s '
-            + 'own TEE key, not a local credential.',
+        description: 'Proves the drafted recipe through the remote browser pod\'s own '
+            + 'TEE (/reclaim/prove) instead of the local attestor SDK. Use it '
+            + 'instead of `run_proof` when the attach mode is "builder": the '
+            + 'proof then reaches the target from the browser\'s own exit IP and '
+            + 'country. Needs no `ownerAddress`; the pod signs with its own TEE '
+            + 'key.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -41,6 +36,7 @@ export function podProofTools(attachRef, captures) {
             },
             required: ['captureId', 'draftId'],
         },
+        annotations: { openWorldHint: true, destructiveHint: false },
     }, async ({ captureId, draftId }) => {
         const apiUrl = attachRef.current?.apiUrl;
         assert(apiUrl, badRequest('No pod api available for this attach — run_proof_via_pod needs '

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

@@ -14,9 +14,9 @@ export function proposeTool(resolveBackend) {
     return defineTool({
         name: 'propose_provider',
         description: 'Drafts a provider from one authenticated captured request and '
-            + 'keeps captured secrets server-side. Use `targets` for every value '
-            + 'available in the same response; the result contains a `draftId` '
-            + 'and secret-free recipe. Set `shortenNames: false` to preserve an '
+            + 'keeps captured secrets server-side. Use `targets` for the data '
+            + 'points the claim needs from that response; returns a `draftId` '
+            + 'and a secret-free recipe. Set `shortenNames: false` to preserve an '
             + 'explicit parameter name, including a hidden `REQ_` or `URL_` '
             + 'prefix. For matching and naming guidance, call '
             + 'how_it_works({ topic: "draft" }) and topic `params`.',
@@ -54,6 +54,7 @@ export function proposeTool(resolveBackend) {
             target: { type: 'string' },
             hash: { type: 'string', enum: ['oprf-raw', 'oprf', 'oprf-mpc'] },
         }, ['requestId', 'name']),
+        annotations: { openWorldHint: false, destructiveHint: false },
     }, async (args) => {
         const backend = resolveBackend(args);
         const requestId = String(args.requestId);

package/lib/mcp/tools/agent/publish.d.ts

@@ -1,6 +1,7 @@
 import type { ReclaimClient } from '@reclaimprotocol/client/api';
+import type { KeptScriptRef } from '../../../authoring/index.ts';
 import { type RegisteredTool } from '../../server.ts';
 import type { AttachState } from './attach.ts';
 export declare function createVersionFromCaptureTool(client: ReclaimClient, attachRef?: {
     current?: AttachState;
-}): RegisteredTool;
+}, kept?: KeptScriptRef): RegisteredTool;

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

@@ -165,11 +165,13 @@ const BROWSER_REQUEST_ACTION_SCHEMA = {
     },
     required: ['id', 'origin', 'path', 'method'],
 };
-export function createVersionFromCaptureTool(client, attachRef) {
+export function createVersionFromCaptureTool(client, attachRef, kept) {
     return defineTool({
         name: 'create_provider_version_from_capture',
         description: 'Creates a new immutable provider version after `run_proof` succeeds. '
-            + 'Pass exactly one `provider` or `providers` value returned by '
+            + 'Publishes the navigation script kept by `test_user_script` as '
+            + '`jsUserScripts` unless `jsUserScripts` is passed. Pass exactly '
+            + 'one `provider` or `providers` value returned by '
             + '`propose_provider`; do not rebuild the recipe. The default is a '
             + 'patch bump, or use `bump` or an explicitly requested higher '
             + '`version`. The new version remains a draft until published or '
@@ -230,7 +232,9 @@ export function createVersionFromCaptureTool(client, attachRef) {
                 },
                 jsUserScripts: {
                     type: 'string',
-                    description: USER_SCRIPT_HINT +
+                    description: 'Defaults to the script kept by `test_user_script` with ' +
+                        '`keep: true`; pass it only to override. ' +
+                        USER_SCRIPT_HINT +
                         ' Stored as webSettings.jsUserScripts; the Builder ' +
                         'verification client runs it before every page load ' +
                         '(including before navigating to initialUrl), matching ' +
@@ -288,7 +292,9 @@ export function createVersionFromCaptureTool(client, attachRef) {
             },
             required: ['providerId', 'initialUrl'],
         },
+        annotations: { openWorldHint: true, destructiveHint: false },
     }, async (args) => {
+        const jsUserScripts = args.jsUserScripts ?? kept?.keptScript?.script;
         // Exactly one of `provider` / `providers` — normalize to an array.
         const hasMany = Array.isArray(args.providers) && args.providers.length > 0;
         const hasOne = !!args.provider;
@@ -306,7 +312,7 @@ export function createVersionFromCaptureTool(client, attachRef) {
             notes: args.notes,
             version: ver,
             requiredContext: args.requiredContext,
-            jsUserScripts: args.jsUserScripts,
+            jsUserScripts,
             allowedJsRequests: args.allowedJsRequests,
             browserRequestActions: args.browserRequestActions,
             interceptorOptions: args.interceptorOptions,
@@ -332,11 +338,11 @@ export function createVersionFromCaptureTool(client, attachRef) {
         const attached = attachRef?.current;
         notes.push(...postPublishBrowserNotes(attached, {
             initialUrl: args.initialUrl,
-            hasUserScript: !!args.jsUserScripts?.trim(),
+            hasUserScript: !!jsUserScripts?.trim(),
             hasInterceptor: !!args.interceptorOptions,
         }));
         // Let the developer know how and when the script runs.
-        if (args.jsUserScripts?.trim()) {
+        if (jsUserScripts?.trim()) {
             notes.push('jsUserScripts will run in the Builder verification client before ' +
                 'every page load (before navigating to initialUrl), matching ' +
                 'old-devtool customInjection. window.Reclaim is available for ' +

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

@@ -10,17 +10,20 @@ import { defineTool } from "../../../tools/registry.js";
 export function replayTool(resolveBackend) {
     return defineTool({
         name: 'replay_request',
-        description: 'Validate the drafted recipe before proving — confirm its selectors '
-            + 'extract the target value. Returns diagnostics; run before '
-            + 'proving. Set `withoutSecrets: true` for the AUTH-BOUND check: it '
-            + 're-issues the request with NO secrets/cookies (an anonymous '
-            + 'visitor). If the values still extract (valid:true), the endpoint '
-            + 'is PUBLIC and the proof would not bind to the user — reject it '
-            + 'and find an auth-bound request instead.',
+        description: 'Re-sends the drafted request from inside the attached authoring '
+            + 'browser (not from this machine) and checks that its selectors '
+            + 'extract the target data points. Captured secrets stay server-side '
+            + 'and are not returned. Returns diagnostics. Run it before '
+            + '`run_proof`. With `withoutSecrets: true`, sends the request with '
+            + 'no cookies or auth headers, like an anonymous visitor. If the '
+            + 'values still extract (`valid: true`), the endpoint is public and '
+            + 'the proof would not bind to the user: choose an auth-bound '
+            + 'request instead.',
         inputSchema: objectSchema({
             draftId: { type: 'string' },
             withoutSecrets: { type: 'boolean' },
         }, ['draftId']),
+        annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {
         const backend = resolveBackend(args);
         const draft = backend.drafts.get(String(args.draftId));