@reclaimprotocol/agent 0.1.27 → 0.1.29

package/src/mcp/api/tools.ts

@@ -1,5 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import type { ReclaimClient } from '@reclaimprotocol/client'
+import type { ReclaimClient } from '@reclaimprotocol/client/api'
 import type {
 	IOperationArgs,
 	IOperationId

package/src/mcp/instructions.ts

@@ -70,11 +70,13 @@ const SHARED_TOPIC_FILES: Record<string, string> = {
  *  topics a mode actually has are listed back to it. */
 const TOPIC_SUMMARIES: Record<string, string> = {
 	'overview': 'Terminology, your stance, and the whole loop at a glance.',
+	'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.',
 	'devtools-migration': 'Importing a public legacy provider with the same '
 		+ 'UUID.',
 	'browser': 'Choosing a browser source (local Chrome, the Reclaim runtime in '
-		+ 'Docker, a remote Popcorn browser, or a custom CDP endpoint), '
+		+ '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.',
@@ -86,8 +88,10 @@ const TOPIC_SUMMARIES: Record<string, string> = {
 		+ 'diagnosing failures.',
 	'publish': 'Creating/reusing a provider, versions, multi-request providers, '
 		+ 'and going live.',
-	'discover': 'Finding the right providers for a dev\'s app and creating a '
-		+ 'verification session.',
+	'discover': 'Finding providers, resolving them, and creating a verification '
+		+ 'session.',
+	'integration': 'Builder Verification Client integration: the `api=2` bridge, '
+		+ 'result verification, and optional TEE binding.',
 	'user-script': 'Authoring jsUserScripts / customInjection to drive '
 		+ 'login-gated pages.',
 	'interception': 'injectionType / interceptorType, live interception, the '

package/src/mcp/remap_errors.ts

@@ -1,7 +1,6 @@
-import type { Boom } from '@hapi/boom'
 import { isBoom } from '@hapi/boom'
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
-import type { ProblemDetails } from '../index.ts'
+import { isProblemDetails, isProblemError } from '@reclaimprotocol/client/api'
 import { errorAsToolText } from '../tools/registry.ts'
 
 // One error shape for every MCP tool. The text comes from errorAsToolText
@@ -11,19 +10,22 @@ export const remapErrorAsResponse = (
 ): CallToolResult => {
 	const text = errorAsToolText(err)
 
-	// The client throws a Boom-style ProblemError, so the status lives on
-	// `output.statusCode` / `problem.status`, not `status`.
-	if(!isBoom(err) || !err.output?.statusCode) {
+	const data = isProblemError(err)
+		? err.data
+		: isBoom(err) && err.output?.statusCode
+			&& isProblemDetails(err.data)
+			? err.data
+			: undefined
+	if(!data) {
 		return {
 			isError: true as const,
 			content: [{ type: 'text' as const, text }],
 		}
 	}
 
-	const data = (err as Boom<ProblemDetails>).data
 	return {
 		isError: true as const,
-		...(data ? { structuredContent: data } : {}),
+		structuredContent: data,
 		content: [{ type: 'text' as const, text }],
 	}
 }

package/src/mcp/start.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { ReclaimClient } from '@reclaimprotocol/client'
+import { ReclaimClient } from '@reclaimprotocol/client/api'
 import { ConfigStore } from '../config/store.ts'
 import {
 	agentDisabled,

package/src/mcp/tools/agent/attach.ts

@@ -1,5 +1,5 @@
 import { badRequest } from '@hapi/boom'
-import type { ReclaimClient } from '@reclaimprotocol/client'
+import type { ReclaimClient } from '@reclaimprotocol/client/api'
 import assert from 'node:assert'
 import {
 	type CdpHandles,
@@ -20,6 +20,7 @@ import {
 import type { ConfigStore } from '../../../config/store.ts'
 import { defaultConfigPath } from '../../../config/store.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
+import { ensureLiveViewUrl } from './live-view-url.ts'
 
 export type BrowserMode =
 	| 'dedicated'
@@ -45,7 +46,7 @@ export interface AttachState {
 	liveViewUrl?: string
 	browserSessionId?: string
 	orgId?: string
-	/** The Popcorn pod's own TEE api base (builder mode only) — lets
+	/** The hosted Builder browser's TEE API base — lets
 	 *  `run_proof_via_pod` prove through the SAME enclave that holds the
 	 *  browser's TLS session (and its country-routed egress), instead of the
 	 *  local in-process attestor SDK. */
@@ -420,6 +421,9 @@ export function attachTool(
 			const next = await connect(
 				mode, { ...parsed, orgId }, persisted, builderClient, deps,
 			)
+			next.liveViewUrl = next.liveViewUrl
+				? ensureLiveViewUrl(next.liveViewUrl)
+				: undefined
 			try {
 				await beforeReplace?.()
 				await disposeAttached(state)

package/src/mcp/tools/agent/build.ts

@@ -10,7 +10,7 @@
  * session for the shared authoring tools.
  */
 
-import type { ReclaimClient } from '@reclaimprotocol/client'
+import type { ReclaimClient } from '@reclaimprotocol/client/api'
 import { ConfigStore } from '../../../config/store.ts'
 import { ensureAttestorCrypto } from '../../../proof/proof-core.ts'
 import { type RegisteredTool } from '../../server.ts'

package/src/mcp/tools/agent/live-view-url.ts

@@ -0,0 +1,13 @@
+const LIVE_VIEW_PATH = 'liveview.html'
+
+/** Add the browser runtime's viewer route and magnification when absent. */
+export function ensureLiveViewUrl(value: string): string {
+	const url = new URL(value)
+	const pathname = url.pathname.replace(/\/+$/, '')
+	if(!pathname.toLowerCase().endsWith(`/${LIVE_VIEW_PATH}`)) {
+		url.pathname = `${pathname}/${LIVE_VIEW_PATH}`
+	}
+
+	url.searchParams.set('magnify', '1')
+	return url.toString()
+}

package/src/mcp/tools/agent/live-view.ts

@@ -1,13 +1,11 @@
 /**
- * `share_browser_view` / `stop_browser_view` — put the LOCAL attached tab
- * behind a public URL so someone who is not at this machine can watch it, and
- * optionally drive it.
+ * `share_browser_view` / `stop_browser_view` — put the attached container
+ * browser's built-in viewer behind a public URL so someone who is not at this
+ * machine can watch it and optionally drive it.
  *
- * Scoped to the CDP-attached modes (`dedicated`, `attach`, `custom`) on
- * purpose. A `builder`-mode browser is a Popcorn pod that already ships its
- * own hosted live view on `attach_browser`'s `liveViewUrl`; tunnelling a
- * second one would duplicate it and burn a share URL for nothing, so this
- * refuses and points at the one that exists.
+ * Scoped to `container` mode on purpose. A `builder`-mode browser already has
+ * a hosted live view at `attach_browser`'s `liveViewUrl`; tunnelling a second
+ * one would duplicate it, so this refuses and points at the existing URL.
  *
  * The share is deliberately explicit and single-instance: one live view per
  * attached browser, started only when asked for, and torn down by
@@ -19,6 +17,7 @@ import { startTunnel, type Tunnel } from '../../../live/tunnel.ts'
 import { LOGGER } from '../../../logger.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import { type AttachState, SHAREABLE_MODES } from './attach.ts'
+import { ensureLiveViewUrl } from './live-view-url.ts'
 
 export interface LiveShare {
 	tunnel: Tunnel
@@ -30,6 +29,8 @@ export interface LiveShareRef {
 	current?: LiveShare
 }
 
+type TunnelStarter = typeof startTunnel
+
 /** Tear down whatever share is running. Safe when none is. Exported so the
  *  session tools can call it from `dispose_browser` / `reset_session`. */
 export async function stopLiveShare(ref: LiveShareRef): Promise<boolean> {
@@ -50,47 +51,41 @@ export async function stopLiveShare(ref: LiveShareRef): Promise<boolean> {
 export function liveViewTools(
 	attachRef: { current?: AttachState },
 	shareRef: LiveShareRef,
+	openTunnel: TunnelStarter = startTunnel,
 ): RegisteredTool[] {
 	return [
 		defineTool<Record<string, never>>(
 			{
 				name: 'share_browser_view',
 				description:
-					'Put the attached browser\'s live view behind a PUBLIC HTTPS URL (a '
-					+ 'cloudflared quick tunnel) so someone elsewhere can watch it and '
-					+ 'act in it. Use it to hand a login or a 2FA step to the person '
-					+ 'who holds the credentials, or to let a colleague watch a '
-					+ 'capture. Returns the URL — relay it to the developer VERBATIM, '
+					'Opens a public HTTPS tunnel to the attached `container` browser '
+					+ 'viewer. Use it when someone else must sign in or control it. '
+					+ 'Returns `url` with `liveview.html?magnify=1`; relay it verbatim '
 					+ 'on its own line. '
-					+ 'ONLY for `container` mode, whose browser runs its own viewer. '
-					+ 'A `builder` browser already has a hosted live view: use the '
-					+ '`liveViewUrl` attach_browser returned. A local browser '
-					+ '(`dedicated`, `attach`, `custom`) cannot be shared at all — no '
-					+ 'tunnel can fix that, because there is no viewer behind it. Tell '
-					+ 'them so, and offer to re-attach: `container` is free and needs '
-					+ 'Docker, `builder` needs no install but is chargeable. '
-					+ 'THE URL IS THE ONLY CREDENTIAL: the random hostname is the whole '
-					+ 'secret, with no token or login behind it, so anyone who learns '
-					+ 'it can see and drive this browser as the signed-in user. Share '
-					+ 'it only with the person who needs it, and call stop_browser_view '
-					+ 'the moment they are done. '
-					+ 'Needs cloudflared: an existing install on PATH is used as-is, '
-					+ 'otherwise it is downloaded once to ~/.reclaim/bin on first '
-					+ 'share (never at install time). Set RECLAIM_CLOUDFLARED_PATH to '
-					+ 'point at your own copy instead.',
+					+ 'Only `container` supports this. For `builder`, relay '
+					+ 'the `liveViewUrl` from attach_browser; local modes '
+					+ '(`dedicated`, `attach`, `custom`) '
+					+ 'cannot be shared. The URL is a credential: anyone with it can '
+					+ 'control the signed-in browser. Share it only with the intended '
+					+ 'person and call stop_browser_view when done. `propagating: true` '
+					+ 'means the tunnel remains live while the Cloudflare edge starts; '
+					+ 'reuse the URL and reload after a few seconds rather than creating '
+					+ 'another tunnel.',
 				inputSchema: { type: 'object', properties: {} },
 			},
 			async() => {
-
 				const attached = attachRef.current
 				assert(attached, badRequest(
 					'No browser attached. Call attach_browser first.',
 				))
+				const hostedViewUrl = attached.liveViewUrl
+					? ensureLiveViewUrl(attached.liveViewUrl)
+					: undefined
 				assert(SHAREABLE_MODES.has(attached.mode), badRequest(
 					`share_browser_view does not apply to \`${attached.mode}\` mode. `
-					+ (attached.liveViewUrl
+					+ (hostedViewUrl
 						? 'That browser already has a hosted live view — use the '
-							+ `\`liveViewUrl\` from attach_browser: ${attached.liveViewUrl}`
+							+ `\`liveViewUrl\` from attach_browser: ${hostedViewUrl}`
 						: 'That browser has no live view to put behind a URL. To let '
 							+ 'someone else in, re-attach with mode "container" (the '
 							+ 'Reclaim runtime in Docker — free, needs Docker) or '
@@ -113,12 +108,12 @@ export function liveViewTools(
 					+ '"container".',
 				))
 
-				const tunnel = await startTunnel(viewerPort, {
+				const tunnel = await openTunnel(viewerPort, {
 					probePath: '/liveview.html?magnify=1',
 				})
 				// The path is the runtime's own viewer page; `magnify=1` is what makes
 				// it lay out for the device that opens it.
-				const url = `${tunnel.url}/liveview.html?magnify=1`
+				const url = ensureLiveViewUrl(tunnel.url)
 				const share: LiveShare = {
 					tunnel, url,
 				}
@@ -127,6 +122,12 @@ export function liveViewTools(
 
 				return {
 					url,
+					...(share.tunnel.ready
+						? {}
+						: {
+							propagating: true,
+							cloudflaredLog: share.tunnel.cloudflaredLog,
+						}),
 					...(share.tunnel.binary.source === 'downloaded'
 						? { cloudflaredInstalled: true }
 						: {}),
@@ -135,6 +136,11 @@ export function liveViewTools(
 							? ['cloudflared was not installed, so it was downloaded once '
 								+ 'to ~/.reclaim/bin. Mention that; later shares reuse it.']
 							: []),
+						...(share.tunnel.ready
+							? []
+							: ['The tunnel hostname exists but the public viewer is still '
+								+ 'propagating. Relay the URL now; if it errors, wait a few '
+								+ 'seconds and reload. Do not start a second tunnel.']),
 						'Relay `url` to the developer verbatim, on its own line.',
 						'The URL is a credential: it needs no login, and anyone with it '
 						+ 'can see this browser and act in it as the signed-in user.',
@@ -152,11 +158,10 @@ export function liveViewTools(
 			{
 				name: 'stop_browser_view',
 				description:
-					'Close the public URL opened by share_browser_view: shuts the '
-					+ 'tunnel down, so the URL stops resolving for whoever still has '
-					+ 'it. Call it as soon as the person you shared with is finished. '
-					+ 'Nothing else changes — the browser stays attached, its own live '
-					+ 'view keeps serving locally, and any capture keeps running.',
+					'Stops the public tunnel opened by share_browser_view; the URL stops '
+					+ 'resolving. Call it when the viewer is done. The browser stays '
+					+ 'attached, its local viewer keeps serving, and capture continues. '
+					+ 'Returns `stopped: false` when no public share is active.',
 				inputSchema: { type: 'object', properties: {} },
 			},
 			async() => ({ stopped: await stopLiveShare(shareRef) }),

package/src/mcp/tools/agent/propose.ts

@@ -34,7 +34,12 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 				+ 'identifier (letters/digits/underscore, not starting with a '
 				+ 'digit); we recommend lower_snake_case (for example, '
 				+ '"employer_name"), '
-				+ 'but you choose the exact name.',
+				+ 'but you choose the exact name. For a parameter used only to build a '
+				+ 'later claim request, preserve a `REQ_` prefix (body, header, or '
+				+ 'intermediate value) or `URL_` prefix (path or query value) by '
+				+ 'setting `shortenNames: false`. The prefix hides that internal '
+				+ 'parameter from the data-point UI; it remains available to named '
+				+ 'regexes and `{{param}}` substitutions.',
 			inputSchema: objectSchema(
 				{
 					requestId: { type: 'string' },
@@ -56,9 +61,10 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 								name: {
 									type: 'string',
 									description:
-										'The param key, or the source of one — see '
-										+ '`shortenNames`. Must stay distinct from other targets\' '
-										+ 'names after whichever treatment applies.',
+										'Parameter key. See `shortenNames`. Keep it unique. '
+										+ 'For hidden internal values, use `REQ_` or `URL_`. Set '
+										+ '`shortenNames: false`. The prefix hides it from the '
+										+ 'data-point UI but preserves substitution.',
 								},
 								hash: {
 									type: 'string',

package/src/mcp/tools/agent/publish.ts

@@ -1,18 +1,28 @@
-import type { ReclaimClient } from '@reclaimprotocol/client'
+import { badRequest } from '@hapi/boom'
+import type { ReclaimClient } from '@reclaimprotocol/client/api'
+import type {
+	CreateProviderVersionRequest
+} from '@reclaimprotocol/client/openapi'
+import assert from 'node:assert'
 import type { JSONSchema } from 'zod/v4/core'
 import {
 	ALLOWED_REQUESTS_HINT,
+	COOKIE_ATTACHMENT_HINT,
 	USER_SCRIPT_HINT,
 } from '../../../provider/injection-doc.ts'
 import {
 	countsFor,
 	matchRedactionWarnings,
 } from '../../../provider/match-redaction-warning.ts'
+import {
+	postPublishBrowserNotes
+} from '../../../provider/post-publish-browser.ts'
 import type { ReclaimProvider } from '../../../provider/schema.ts'
 import type { AllowedJsRequest } from '../../../provider/to-version.ts'
 import {
-	nextVersion,
 	providerToCreateVersionRequest,
+	resolveNewVersion,
+	type VersionBump,
 } from '../../../provider/to-version.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import type { AttachState } from './attach.ts'
@@ -136,6 +146,8 @@ interface PublishArgs {
 	initialUrl: string
 	notes?: string
 	version?: { major: number, minor: number, patch: number }
+	bump?: VersionBump
+	requiredContext?: CreateProviderVersionRequest['requiredContext']
 	jsUserScripts?: string
 	allowedJsRequests?: AllowedJsRequest[]
 	interceptorOptions?: {
@@ -159,8 +171,11 @@ export function createVersionFromCaptureTool(
 				'(requests[], webSettings, …) for you; do NOT hand-construct that ' +
 				'shape or call create_provider_version directly. Exactly one of ' +
 				'`provider` (one request) or `providers` (a multi-request provider — ' +
-				'every entry is required at verification time). Omit `version` to ' +
-				'auto-bump past the highest existing one. The version lands on the ' +
+				'every entry is required at verification time). This tool always ' +
+				'creates a new immutable version; never edit an existing version. ' +
+				'Omit `version` and `bump` for a patch bump, pass `bump` for a ' +
+				'major/minor/patch bump, or pass the exact higher `version` the user ' +
+				'directed. The version lands on the ' +
 				'draft branch: call `publish_provider_version` (PRIVATE) or ' +
 				'`submit_provider_version_for_review` (PUBLIC) to go live. ' +
 				'`requiredContext` is derived from any {{context.<name>}} ' +
@@ -202,15 +217,31 @@ export function createVersionFromCaptureTool(
 					version: {
 						type: 'object',
 						description:
-							'Semver to publish as. Omit to auto-pick the next ' +
-							'version above the highest existing one.',
+							'Exact new semver requested by the user. It must be higher ' +
+							'than the current highest version. Do not pass with `bump`.',
 						properties: {
-							major: { type: 'number', minimum: 0 },
-							minor: { type: 'number', minimum: 0 },
-							patch: { type: 'number', minimum: 0 },
+							major: { type: 'integer', minimum: 0 },
+							minor: { type: 'integer', minimum: 0 },
+							patch: { type: 'integer', minimum: 0 },
 						},
 						required: ['major', 'minor', 'patch'],
 					},
+					bump: {
+						type: 'string',
+						enum: ['major', 'minor', 'patch'],
+						description:
+							'Semantic increment from the highest version. Defaults to ' +
+							'`patch`. Do not pass with an exact `version`.',
+					},
+					requiredContext: {
+						type: 'object',
+						description:
+							'Complete JSON Schema for consumer-supplied session context. ' +
+							'Omit to derive string properties from {{context.<name>}} ' +
+							'placeholders. Pass refinements while creating this new ' +
+							'version; never update the created version in place.',
+						additionalProperties: true,
+					},
 					jsUserScripts: {
 						type: 'string',
 						description:
@@ -218,8 +249,9 @@ export function createVersionFromCaptureTool(
 							' Stored as webSettings.jsUserScripts; the Builder ' +
 							'verification client runs it before every page load ' +
 							'(including before navigating to initialUrl), matching ' +
-							'old-devtools customInjection. window.Reclaim is not exposed ' +
-							'there yet, so prefer plain browser JS.',
+							'old-devtools customInjection. window.Reclaim is available ' +
+							'for supported bridge actions; prefer plain browser JS for ' +
+							'navigation and interaction.',
 					},
 					allowedJsRequests: {
 						type: 'array',
@@ -238,7 +270,8 @@ export function createVersionFromCaptureTool(
 							'In-app interception settings, stored as ' +
 							'webSettings.clientOptions.inapp.interceptorOptions — only ' +
 							'needed for a genuine live-interception provider (a real ' +
-							'HAWKEYE/MSWJS script, not the standard capture→replay flow).',
+							'HAWKEYE/MSWJS script, not the standard capture→replay flow). ' +
+							COOKIE_ATTACHMENT_HINT,
 						properties: {
 							interceptorType: {
 								type: 'string',
@@ -280,12 +313,19 @@ export function createVersionFromCaptureTool(
 
 			const providers = hasMany ? args.providers! : [args.provider!]
 
-			// Auto-pick the next version if not explicit
-			const ver = args.version ?? (await nextVersion(client, args.providerId))
+			assert(
+				!(args.version && args.bump),
+				badRequest('Pass either `version` or `bump`, not both.'),
+			)
+			const ver = await resolveNewVersion(client, args.providerId, {
+				version: args.version,
+				bump: args.bump,
+			})
 
 			const body = providerToCreateVersionRequest(providers, args.initialUrl, {
 				notes: args.notes,
 				version: ver,
+				requiredContext: args.requiredContext,
 				jsUserScripts: args.jsUserScripts,
 				allowedJsRequests: args.allowedJsRequests,
 				interceptorOptions: args.interceptorOptions,
@@ -315,25 +355,20 @@ export function createVersionFromCaptureTool(
 			// before closing it (a builder-mode session is quota-accounted and
 			// otherwise just sits until its TTL expires).
 			const attached = attachRef?.current
-			if(attached) {
-				notes.push(
-					`A "${attached.mode}" browser session is still attached` +
-					(attached.browserSessionId
-						? ` (browserSessionId: ${attached.browserSessionId})`
-						: '') +
-					'. Ask the developer whether they want to keep it open for ' +
-					'further edits — only call dispose_browser once they confirm ' +
-					'they\'re done with it.',
-				)
-			}
+			notes.push(...postPublishBrowserNotes(attached, {
+				initialUrl: args.initialUrl,
+				hasUserScript: !!args.jsUserScripts?.trim(),
+				hasInterceptor: !!args.interceptorOptions,
+			}))
 
-			// Let the dev know how/when the script runs (and the window.Reclaim gap).
+			// Let the developer know how and when the script runs.
 			if(args.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 not yet exposed ' +
-					'there, so prefer plain browser JS for navigation/interaction.',
+					'old-devtool customInjection. window.Reclaim is available for ' +
+					'supported bridge actions; prefer plain browser JS for navigation ' +
+					'and interaction.',
 				)
 			}
 

package/src/mcp/tools/agent/shared.ts

@@ -7,6 +7,7 @@
  * `start_capture`, since one capture bundles the tab, its requests, and its
  * drafts) and the rich, credential-aware `run_proof` schema.
  */
+import type { JSONSchema } from 'zod/v4/core'
 import {
 	type AuthoringBackend,
 	authoringTools,
@@ -151,6 +152,10 @@ const RUN_PROOF_EXTRAS = {
 		attestorUrl: { type: 'string' },
 	},
 	required: ['ownerAddress'],
+} satisfies {
+	description: string
+	properties: JSONSchema.ObjectSchema['properties']
+	required: string[]
 }
 
 /** The shared authoring tools mapped to the MCP's shape: resolve each call's

package/src/mcp/tools/authenticate/authenticate.ts

@@ -1,4 +1,4 @@
-import type { ReclaimClient } from '@reclaimprotocol/client'
+import type { ReclaimClient } from '@reclaimprotocol/client/api'
 import { spawn } from 'node:child_process'
 import { createServer } from 'node:http'
 import * as oauth from 'openid-client'

package/src/mcp/tools/authenticate/build.ts

@@ -1,4 +1,4 @@
-import type { ReclaimClient } from '@reclaimprotocol/client'
+import type { ReclaimClient } from '@reclaimprotocol/client/api'
 import type { RegisteredTool } from '../../server.ts'
 import { authenticateTool } from './authenticate.ts'
 import { importTool } from './import.ts'

package/src/mcp/tools/authenticate/builder-access.ts

@@ -1,4 +1,4 @@
-import type { ReclaimClient } from '@reclaimprotocol/client'
+import type { ReclaimClient } from '@reclaimprotocol/client/api'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import { authenticateTool } from './authenticate.ts'
 

package/src/mcp/tools/verification/result.ts

@@ -2,7 +2,6 @@ import {
 	createReclaim,
 	decryptCallback,
 	type DecryptionKey,
-	verifyResultFull,
 } from '@reclaimprotocol/client'
 import assert from 'node:assert'
 import { apiUrl, orgSecret } from '../../../consts.ts'
@@ -45,16 +44,15 @@ export function verificationResultTool(): RegisteredTool {
 		{
 			name: 'get_verification_result',
 			description:
-				'Check a verification session and return its result when ready. ' +
-				'Authenticates with the org secret (RECLAIM_ORG_SECRET). Fetches the ' +
-				'session status; if it is terminal and a result has been submitted, ' +
-				'pulls the stored result(s) and verifies them locally. Encrypted ' +
-				'deliveries (ECIES over secp256k1) are decrypted with your optional ' +
-				'eth key (RECLAIM_DECRYPT_KEY or reclaim-decrypt.key); plaintext ' +
-				'deliveries are read directly. Returns ' +
-				'`ready: false` while the session is still pending or no result has ' +
-				'been delivered yet. Use list_verification_events for the full ' +
-				'lifecycle log.',
+				'Reads a verification session and locally checks each submitted ' +
+				'result. Requires RECLAIM_ORG_SECRET. Encrypted ECIES deliveries ' +
+				'also require the matching optional eth key ' +
+				'(RECLAIM_DECRYPT_KEY or reclaim-decrypt.key); plaintext deliveries ' +
+				'are read directly. Returns `ready: false` until the session is ' +
+				'terminal and at least one payload is readable. When `ready: true`, ' +
+				'act only on result entries where `valid` is true; `ready` means a ' +
+				'payload was read, not that verification succeeded. Use ' +
+				'list_verification_events to diagnose an unfinished session.',
 			inputSchema: {
 				type: 'object',
 				required: ['sessionId'],
@@ -101,7 +99,7 @@ export function verificationResultTool(): RegisteredTool {
 				}
 			}
 
-			// Each item's `payload` is a compact JWE (encrypted to the org's
+			// Each item's `payload` is an ECIES ciphertext (encrypted to the org's
 			// credential) or the plaintext signed JWS, as raw text. `decryptCallback`
 			// branches on the body shape; an encrypted delivery with no key throws
 			// a clear error, which we surface per-subscription rather than skip.
@@ -117,7 +115,7 @@ export function verificationResultTool(): RegisteredTool {
 					continue
 				}
 
-				const outcome = await verifyResultFull(jws, {
+				const outcome = await reclaim.results.verify(jws, {
 					expectedReclaimSessionId: args.sessionId,
 				})
 				results.push({