@reclaimprotocol/agent 0.1.31 → 0.1.33

package/src/mcp/api/tools.ts

@@ -1,9 +1,12 @@
+import { unauthorized } from '@hapi/boom'
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import type { ReclaimClient } from '@reclaimprotocol/client/api'
+import { ReclaimClient } from '@reclaimprotocol/client/api'
 import type {
 	IOperationArgs,
 	IOperationId
 } from '@reclaimprotocol/client/openapi'
+import assert from 'node:assert'
+import { orgSecret } from '../../consts.ts'
 import { remapErrorAsResponse } from '../remap_errors.ts'
 import { successResponse } from '../success-response.ts'
 import { MCP_TOOLS } from './operations.gen.ts'
@@ -22,8 +25,29 @@ function toSnakeCase(name: string): string {
 		.toLowerCase()
 }
 
-export function registerTools(server: McpServer, client: ReclaimClient) {
-	for(const [opId, shape] of Object.entries(MCP_TOOLS)) {
+/** 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 function registerTools(
+	server: McpServer,
+	client: ReclaimClient,
+	orgClient: OrgClientFactory = (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,
+		}
 		if(!isOperationId(opId)) {
 			throw new Error(
 				`Generated MCP operation is not in the API client: ${opId}`,
@@ -37,13 +61,21 @@ export function registerTools(server: McpServer, client: ReclaimClient) {
 		server.registerTool(
 			toSnakeCase(opId),
 			shape,
-			async(args: unknown) => {
+			async(input: unknown) => {
 				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(
+					const caller = orgTokenOnly
+						? orgClient(orgTokenFor(toSnakeCase(opId), orgToken))
+						: client
+					const result = await caller.call(
 						opId,
 						args,
 					)
@@ -79,3 +111,23 @@ function isOperationArgs<T extends IOperationId>(
 ): value is IOperationArgs<T> {
 	return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	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. The session token (the developer's sign-in)
+ *  can't stand in, since these routes accept only an org key. */
+function orgTokenFor(tool: string, orgToken: unknown) {
+	const token = (typeof orgToken === 'string' && orgToken) || orgSecret()
+	assert(
+		token,
+		unauthorized(
+			`${tool} authenticates with the organization's API key. Pass `
+			+ 'orgToken: one from issue_org_token, or the app\'s '
+			+ 'RECLAIM_ORG_SECRET. Or set RECLAIM_ORG_SECRET for the MCP server.',
+		),
+	)
+	return token
+}

package/src/mcp/instructions.ts

@@ -78,7 +78,7 @@ const TOPIC_SUMMARIES: Record<string, string> = {
 	'discover': 'Finding providers, resolving them, and creating a verification '
 		+ 'session.',
 	'integration': 'Set up a Builder token, callback, frontend and backend '
-		+ 'with @reclaimprotocol/client; direct `api=2` API and result '
+		+ 'over the HTTP session API; direct `api=2` API and result '
 		+ 'verification.',
 	'user-script': 'Authoring jsUserScripts / customInjection to drive '
 		+ 'login-gated pages.',

package/src/mcp/start.ts

@@ -116,7 +116,12 @@ export async function startMcpServer() {
 
 		// 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()

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

@@ -17,19 +17,29 @@ const TERMINAL = new Set([
 	'expired',
 ])
 
+/** Events whose delivery is a signed result; the rest are plaintext event
+ *  notifications. Mirrors `verification_result_events()`. */
+const RESULT_EVENTS = new Set([
+	'verification_success',
+	'verification_rejected',
+	'verification_error',
+	'verification_cancelled',
+])
+
 /**
  * Resolve the org secret used to authenticate verification reads. Auth is a
- * single per-org bearer secret (`rorg_…`), not an eth signature — read it from
- * `RECLAIM_ORG_SECRET`.
+ * single per-org bearer secret (`rorg_…`), not an eth signature: the call's
+ * `orgToken`, else `RECLAIM_ORG_SECRET`.
  */
-function resolveOrgSecret(): string {
-	const secret = orgSecret()?.trim()
+function resolveOrgSecret(orgToken?: string): string {
+	const secret = orgToken?.trim() || orgSecret()?.trim()
 	assert(
 		secret,
 		new Error(
-			'RECLAIM_ORG_SECRET is not set. Verification reads authenticate with ' +
-				'the org secret (rorg_…) — issue one from the dashboard ' +
-				'(POST /orgs/{orgId}/token) and export it as RECLAIM_ORG_SECRET.',
+			'No organization API key. Verification reads authenticate with the org '
+				+ 'secret (rorg_…): pass orgToken (from issue_org_token, or the '
+				+ 'app\'s RECLAIM_ORG_SECRET), or export RECLAIM_ORG_SECRET for the '
+				+ 'MCP server.',
 		),
 	)
 	return secret
@@ -46,12 +56,15 @@ function resolveOrgSecret(): string {
  * Decryption, when needed, happens here.
  */
 export function verificationResultTool(): RegisteredTool {
-	return defineTool<{ reclaimSessionId: string }>(
+	return defineTool<{ reclaimSessionId: string, orgToken?: string }>(
 		{
 			name: 'get_verification_result',
 			description:
-				'Fetches and verifies a terminal Builder result for one session. '
-				+ 'Requires `RECLAIM_ORG_SECRET`; encrypted deliveries also require '
+				'Fetches and verifies a terminal Builder result for one session, '
+				+ 'while Builder still holds it: until its callback is delivered, or '
+				+ '7 days undelivered. The callback is the normal way to get results. '
+				+ 'Authenticates with the org API key: `orgToken`, else '
+				+ '`RECLAIM_ORG_SECRET`. Encrypted deliveries also require '
 				+ 'the matching ETH decryption key. Returns `ready: false` until a '
 				+ 'payload is available. Invalid results fail verification and are not '
 				+ 'returned. Use `list_verification_events` to diagnose '
@@ -65,11 +78,20 @@ export function verificationResultTool(): RegisteredTool {
 						description:
 							'The verification session id from create_verification_session.',
 					},
+					orgToken: {
+						type: 'string',
+						pattern: '^rorg_',
+						maxLength: 200,
+						description: 'The organization API key (`rorg_…`): from '
+							+ '`issue_org_token`, or the app\'s RECLAIM_ORG_SECRET. '
+							+ 'Defaults to the MCP server\'s RECLAIM_ORG_SECRET. Never echo '
+							+ 'it back to the user.',
+					},
 				},
 			},
 		},
 		async(args) => {
-			const secret = resolveOrgSecret()
+			const secret = resolveOrgSecret(args.orgToken)
 			// Optional eth decryption key — absent ⇒ plaintext-only.
 			const decryptionKey: DecryptionKey | undefined =
 				await resolveDecryptionKey()
@@ -91,14 +113,34 @@ export function verificationResultTool(): RegisteredTool {
 			const resultRes = await reclaim.api('GetVerificationResult', {
 				params: { sessionId: args.reclaimSessionId },
 			})
-			const { items } = resultRes.data
+			const signed = resultRes.data.items
+				.filter((item) => RESULT_EVENTS.has(item.event))
+			if(!signed.length) {
+				return {
+					reclaimSessionId: args.reclaimSessionId,
+					status,
+					ready: false,
+					note: 'Session is terminal but no result is stored: none submitted '
+						+ 'yet, or no callback subscription covers its ending event.',
+				}
+			}
 
+			// Builder keeps a result (which can carry proofs) only until its
+			// callback is delivered, or 7 days undelivered.
+			const items = signed.flatMap((item) => (
+				item.payload === null ? [] : [{ ...item, payload: item.payload }]
+			))
 			if(!items.length) {
 				return {
 					reclaimSessionId: args.reclaimSessionId,
 					status,
 					ready: false,
-					note: 'Session is terminal but no result has been submitted yet.',
+					delivered: signed.some((item) => (
+						item.deliveryStatus === 'delivered'
+					)),
+					note: 'Builder no longer holds this result: it was delivered to '
+						+ 'the callback (read it there), or went undelivered for 7 days. '
+						+ 'See list_verification_deliveries.',
 				}
 			}
 

package/src/old/tools/get-provider-info.ts

@@ -41,7 +41,9 @@ export function getProviderInfoTool(client: ReclaimSdkClient): RegisteredTool {
 				'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. ' +
-				'This is the provider-read tool for old-devtools mode. \n\n' +
+				'This is the provider-read tool for old-devtools mode. A ' +
+				'published provider is usable as-is: don\'t re-verify it ' +
+				'(capture/replay/proof) unless the user asks to test it.\n\n' +
 				'Returns two complementary reads for the given version (latest ' +
 				'when `versionNumber` is omitted): `provider` (the FULL provider ' +
 				'+ providerConfig — `customInjection`, `userAgent`, ' +