@reclaimprotocol/agent 0.1.33 → 0.1.34

package/src/mcp/tools/agent/start-integration.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+
+interface StartIntegrationArgs {
+	goal: string
+	orgId?: string
+	providerIds?: string[]
+}
+
+/**
+ * Returns the plan a coding agent follows to add Reclaim verification to the
+ * developer's app, from sign-in to a tested Verify button. The plan lives in
+ * `skill/start-integration.md`; this tool fills in the inputs.
+ */
+export function startIntegrationTool(): RegisteredTool {
+	return defineTool<StartIntegrationArgs>(
+		{
+			name: 'start_integration',
+			description:
+				'Returns a step-by-step plan for adding Reclaim verification to the '
+				+ 'current codebase: sign in, build or choose a provider, then add the '
+				+ 'session route, callback, and Verify button. Call it first when a '
+				+ 'developer wants their users to prove something, and follow the '
+				+ 'plan to the end. Changes nothing itself.',
+			inputSchema: {
+				type: 'object',
+				required: ['goal'],
+				properties: {
+					goal: {
+						type: 'string',
+						minLength: 1,
+						maxLength: 300,
+						description:
+							'What the developer\'s users prove, for example, "they have '
+							+ 'a GitHub account with 100 followers".',
+					},
+					orgId: {
+						type: 'string',
+						format: 'uuid',
+						description: 'Organization to use. Omit to choose from the list.',
+					},
+					providerIds: {
+						type: 'array',
+						maxItems: 10,
+						items: { type: 'string' },
+						description:
+							'Existing provider IDs to use. Omit to build a new provider.',
+					},
+				},
+			},
+			annotations: { readOnlyHint: true, openWorldHint: false },
+		},
+		async(args) => renderStartIntegration(args),
+	)
+}
+
+/** Fill the plan template. Exported for tests. */
+export function renderStartIntegration(args: StartIntegrationArgs): string {
+	const providerIds = args.providerIds?.length
+		? args.providerIds.map((id) => `\`${id}\``).join(', ')
+		: undefined
+	const values: Record<string, string | undefined> = {
+		goal: args.goal,
+		orgId: args.orgId,
+		providerIds,
+	}
+	const template = readFileSync(
+		fileURLToPath(
+			new URL('../../../../skill/start-integration.md', import.meta.url),
+		),
+		'utf8',
+	)
+	return template
+		// Keep a conditional block only when its input was given (or not given).
+		.replace(
+			/<!-- (if|ifnot):(\w+) -->\n([\s\S]*?)<!-- endif -->\n/g,
+			(_, kind: string, name: string, body: string) => {
+				return (kind === 'if') === Boolean(values[name]) ? body : ''
+			},
+		)
+		.replace(/\{\{(\w+)\}\}/g, (_, name: string) => values[name] ?? '')
+}

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

@@ -25,18 +25,16 @@ export function authenticateTool(
 					+ 'get_me_providers; those need the separate old-devtools login, '
 					+ 'reclaim_authenticate. Check both with get_devtools_mode. '
 					: '')
-				+ 'Authorize the CLI / MCP to make authenticated API calls. Opens '
-				+ 'the '
-				+ 'browser to the builder sign-in page (standard OAuth 2.0 ' +
-				'authorization-code + PKCE with a localhost redirect) and waits for ' +
-				'the user to sign in and approve. On success the access token is ' +
-				'cached in ~/.reclaim/config.json and activated for this session.\n\n' +
-				'Call with no arguments. This bearer token authenticates ' +
-				'dashboard/org-management calls (for example, list_orgs, or ' +
-				'issuing an org secret). Programmatic verification calls use a ' +
-				'separate org secret ' +
-				'(rorg_…, set as RECLAIM_ORG_SECRET).',
+				+ 'Signs the developer in to Builder. Opens the Builder sign-in page '
+				+ 'in their browser (OAuth 2.0 authorization code with PKCE, '
+				+ 'redirecting to a localhost port this server opens) and waits for '
+				+ 'them to approve. Saves the access token in ~/.reclaim/config.json '
+				+ 'with mode 0600 and uses it for this session; the token is never '
+				+ 'returned. The token authorizes organization-management tools such '
+				+ 'as `list_orgs`. Programmatic verification tools use a separate '
+				+ 'organization key; see `issue_org_token`. Call with no arguments.',
 			inputSchema: { type: 'object', properties: {} },
+			annotations: { openWorldHint: true, idempotentHint: true },
 		},
 		async() => runOAuthLoopback(client),
 	)

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

@@ -3,6 +3,7 @@ import type { RegisteredTool } from '../../server.ts'
 import { authenticateTool } from './authenticate.ts'
 import { importTool } from './import.ts'
 import { issueTool } from './issue.ts'
+import { issueOrgTokenTool } from './issue-org-token.ts'
 import { resolveOwnerKeyTool } from './resolve-owner-key.ts'
 
 /**
@@ -27,6 +28,7 @@ export function buildLocalCredentialTools(): RegisteredTool[] {
 export function buildCredentialTools(client: ReclaimClient): RegisteredTool[] {
 	return [
 		authenticateTool(client),
+		issueOrgTokenTool(client),
 		...buildLocalCredentialTools(),
 	]
 }

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

@@ -35,6 +35,7 @@ export function buildBuilderOrganizationTools(
 						cursor: { type: 'string', maxLength: 500 },
 					},
 				},
+				annotations: { readOnlyHint: true, openWorldHint: true },
 			},
 			async({ cursor }) => {
 				const { data } = await client.call('ListOrgs', {

package/src/mcp/tools/authenticate/eth-key.ts

@@ -16,8 +16,20 @@
  */
 import { deriveFromPrivateKey } from '@reclaimprotocol/client'
 import assert from 'node:assert'
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { isAbsolute, join } from 'node:path'
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	writeFileSync,
+} from 'node:fs'
+import {
+	dirname,
+	isAbsolute,
+	join,
+	relative,
+	resolve
+} from 'node:path'
 import { privateKey, privateKeyFile } from '../../../consts.ts'
 import { findProjectRoot } from '../../../paths.ts'
 
@@ -124,7 +136,7 @@ export function resolveEthKey(
 }
 
 /** Append `entry` to the project `.gitignore` if not already present. */
-function ensureGitignored(projectDir: string, entry: string) {
+export function ensureGitignored(projectDir: string, entry: string) {
 	const path = join(projectDir, '.gitignore')
 	const current = existsSync(path) ? readFileSync(path, 'utf8') : ''
 	if(current.split('\n').some((l) => l.trim() === entry)) {
@@ -136,29 +148,47 @@ function ensureGitignored(projectDir: string, entry: string) {
 }
 
 /**
- * Persist a raw eth private key to the project `.env` as
- * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
- * Used by `issue_credentials` (generate) and `import_credentials` (supplied
- * hex). Returns the derived address and the `.env` path.
+ * Set `name=value` in a dotenv file, replacing an existing line or appending
+ * one. Writes with mode 0600 and adds the file to the project `.gitignore`.
+ * `envFile` is relative to `projectDir`.
  */
-export function writeEthKey(
-	privateKeyHex: string,
-	projectDir = findProjectRoot(process.cwd()),
-): { path: string, address: string } {
-	const hex = normalizeEthHex(privateKeyHex)
-	const envPath = join(projectDir, ENV_FILE)
-	const line = `${ENV_VAR}=${hex}`
+export function upsertEnvVar(
+	projectDir: string,
+	envFile: string,
+	name: string,
+	value: string,
+): string {
+	const envPath = resolve(projectDir, envFile)
+	const line = `${name}=${value}`
 	const existing = existsSync(envPath) ? readFileSync(envPath, 'utf8') : ''
-	const re = new RegExp(`^\\s*${ENV_VAR}\\s*=.*$`, 'm')
+	const re = new RegExp(`^\\s*${name}\\s*=.*$`, 'm')
 	let next: string
 	if(re.test(existing)) {
-		next = existing.replace(re, line)
+		// A function replacer keeps `$` sequences in the value literal.
+		next = existing.replace(re, () => line)
 	} else {
 		const prefix = existing && !existing.endsWith('\n') ? '\n' : ''
 		next = existing + prefix + line + '\n'
 	}
 
+	mkdirSync(dirname(envPath), { recursive: true })
 	writeFileSync(envPath, next, { mode: 0o600 })
-	ensureGitignored(projectDir, ENV_FILE)
-	return { path: envPath, address: deriveFromPrivateKey(hex).address }
+	chmodSync(envPath, 0o600)
+	ensureGitignored(projectDir, relative(projectDir, envPath))
+	return envPath
+}
+
+/**
+ * Persist a raw eth private key to the project `.env` as
+ * `RECLAIM_PRIVATE_KEY=0x…` (upsert; mode 0600; `.env` added to `.gitignore`).
+ * Used by `issue_credentials` (generate) and `import_credentials` (supplied
+ * hex). Returns the derived address and the `.env` path.
+ */
+export function writeEthKey(
+	privateKeyHex: string,
+	projectDir = findProjectRoot(process.cwd()),
+): { path: string, address: string } {
+	const hex = normalizeEthHex(privateKeyHex)
+	const path = upsertEnvVar(projectDir, ENV_FILE, ENV_VAR, hex)
+	return { path, address: deriveFromPrivateKey(hex).address }
 }

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

@@ -5,68 +5,53 @@ import { writeEthKey } from './eth-key.ts'
 
 export function importTool(): RegisteredTool {
 	return defineTool<{
-		privateKey?: string
-		keyFile?: string
+		keyFile: string
 		projectDir?: string
 	}>(
 		{
 			name: 'import_credentials',
 			description:
-				'Import an eth proof-owner key the dev already holds and persist it ' +
-				'to the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
-				'added to .gitignore). Provide EITHER `privateKey` (raw 0x-hex, 64 ' +
-				'chars) OR `keyFile` (path to a file holding the raw 0x-hex key). ' +
-				'The address is derived locally; the private key is never ' +
-				'returned. This is a local signing key only (not registered ' +
-				'with any server, ' +
-				'unrelated to org auth or encryption).',
+				'Imports an eth proof-owner key from a file the developer already '
+				+ 'holds. Reads the raw 0x-hex key from `keyFile` and writes it to '
+				+ 'the project `.env` as RECLAIM_PRIVATE_KEY (mode 0600; `.env` '
+				+ 'added to .gitignore). Returns the derived address and the `.env` '
+				+ 'path; never the key. The key is a local signing key only: it is '
+				+ 'not registered with any server and is unrelated to org auth or '
+				+ 'encryption. To create a new key instead, use `issue_credentials`.',
 			inputSchema: {
 				type: 'object',
+				required: ['keyFile'],
 				properties: {
-					privateKey: {
-						type: 'string',
-						pattern: '^0x?[0-9a-fA-F]{64}$',
-						description:
-							'Raw Ethereum private key, 0x-prefixed hex (64 hex chars).',
-					},
 					keyFile: {
 						type: 'string',
 						description:
-							'Path to a file containing the raw 0x-hex private key ' +
-							'(absolute or project-relative).',
+							'Path to a file containing the raw 0x-hex private key '
+							+ '(absolute or relative to the working directory).',
 					},
 					projectDir: {
 						type: 'string',
 						description:
-							'Project directory whose `.env` the key is written to. ' +
-							'Defaults to the closest ancestor of cwd containing .git or ' +
-							'package.json.',
+							'Project directory whose `.env` the key is written to. '
+							+ 'Defaults to the closest ancestor of cwd containing .git or '
+							+ 'package.json.',
 					},
 				},
 			},
+			annotations: { readOnlyHint: false, destructiveHint: false },
 		},
 		async(args) => {
-			if(!args.privateKey && !args.keyFile) {
-				throw new Error('Provide either `privateKey` (0x-hex) or `keyFile`.')
-			}
-
-			if(args.privateKey && args.keyFile) {
-				throw new Error('Provide only one of `privateKey` or `keyFile`.')
-			}
-
 			const projectDir = findProjectRoot(args.projectDir || process.cwd())
-			const privateKeyHex = args.keyFile
-				? readFileSync(args.keyFile, 'utf8')
-				: args.privateKey!
-			const { path, address } = writeEthKey(privateKeyHex, projectDir)
+			const { path, address } = writeEthKey(
+				readFileSync(args.keyFile, 'utf8'), projectDir,
+			)
 
 			return {
 				address,
 				path,
 				note:
-					'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY ' +
-					'(mode 0600). resolve_owner_key resolves it from .env. Keep .env ' +
-					'secret — it has been added to .gitignore.',
+					'Eth proof-owner key written to .env as RECLAIM_PRIVATE_KEY '
+					+ '(mode 0600). resolve_owner_key resolves it from .env. Keep .env '
+					+ 'secret: it has been added to .gitignore.',
 			}
 		},
 	)

package/src/mcp/tools/authenticate/issue-org-token.ts

@@ -0,0 +1,84 @@
+import type { ReclaimClient } from '@reclaimprotocol/client/api'
+import assert from 'node:assert'
+import { isAbsolute, relative, resolve } from 'node:path'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import { upsertEnvVar } from './eth-key.ts'
+import { saveOrgKey } from './org-key-store.ts'
+
+/**
+ * Issues an organization API key and stores it on disk, so the key never
+ * passes through the agent's transcript. Replaces the generated
+ * `issue_org_token` operation, which returned the key in its response.
+ */
+export function issueOrgTokenTool(client: ReclaimClient): RegisteredTool {
+	return defineTool<{
+		orgId: string
+		projectDir: string
+		envFile?: string
+		envVar?: string
+	}>(
+		{
+			name: 'issue_org_token',
+			description:
+				'Issues an organization API key (owner only) and writes it to a '
+				+ 'server env file in the project, so the app can read it at runtime. '
+				+ 'Also saves it on this machine for the org-key tools. Returns the '
+				+ 'org, file, variable, and last four characters; never the key. '
+				+ 'Replaces an existing variable of the same name in the file. '
+				+ 'Adds the file to .gitignore. Use when the app needs a key, or '
+				+ 'before `create_verification_session`.',
+			inputSchema: {
+				type: 'object',
+				required: ['orgId', 'projectDir'],
+				properties: {
+					orgId: { type: 'string', format: 'uuid' },
+					projectDir: {
+						type: 'string',
+						description: 'Absolute path of the app\'s project directory.',
+					},
+					envFile: {
+						type: 'string',
+						description:
+							'Env file to write, relative to `projectDir`. Default `.env`.',
+					},
+					envVar: {
+						type: 'string',
+						pattern: '^[A-Za-z_][A-Za-z0-9_]*$',
+						description:
+							'Variable name to set. Default `RECLAIM_ORG_SECRET`.',
+					},
+				},
+			},
+			annotations: { openWorldHint: true, destructiveHint: false },
+		},
+		async(args) => {
+			assert(
+				isAbsolute(args.projectDir),
+				new Error('`projectDir` must be an absolute path.'),
+			)
+			const envFile = args.envFile || '.env'
+			const envVar = args.envVar || 'RECLAIM_ORG_SECRET'
+			const inside = relative(
+				args.projectDir, resolve(args.projectDir, envFile),
+			)
+			assert(
+				inside && !inside.startsWith('..') && !isAbsolute(inside),
+				new Error('`envFile` must be inside `projectDir`.'),
+			)
+
+			const { data } = await client.call('IssueOrgToken', {
+				params: { orgId: args.orgId },
+			})
+			const path = upsertEnvVar(
+				args.projectDir, envFile, envVar, data.orgSecret,
+			)
+			saveOrgKey(args.orgId, data.orgSecret)
+			return {
+				orgId: args.orgId,
+				envFile: path,
+				envVar,
+				last4: data.last4,
+			}
+		},
+	)
+}

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

@@ -8,15 +8,14 @@ export function issueTool(): RegisteredTool {
 		{
 			name: 'issue_credentials',
 			description:
-				'Generate a fresh secp256k1 eth proof-owner key-pair (the key ' +
-				'that signs local claim creation) and write the raw private key to ' +
-				'the project `.env` as RECLAIM_PRIVATE_KEY=0x… (mode 0600; `.env` ' +
-				'added to .gitignore). This is a LOCAL signing key only — it is NOT ' +
-				'registered with any server and is unrelated to org auth (the org ' +
-				'secret) or encryption (the eth decrypt key). ALWAYS confirm with ' +
-				'the dev before generating a new key. After writing, run_proof picks ' +
-				'it up automatically via resolve_owner_key. The private key is never ' +
-				'returned in the response.',
+				'Generates a new secp256k1 eth proof-owner key and writes the '
+				+ 'private key to the project `.env` as RECLAIM_PRIVATE_KEY (mode '
+				+ '0600; `.env` added to .gitignore). Returns the address and the '
+				+ '`.env` path; never the key. The key is a local signing key only: '
+				+ 'it is not registered with any server and is unrelated to org auth '
+				+ 'or encryption. Confirm with the developer before replacing an '
+				+ 'existing key. `run_proof` then picks it up through '
+				+ '`resolve_owner_key`.',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -29,6 +28,7 @@ export function issueTool(): RegisteredTool {
 					},
 				},
 			},
+			annotations: { destructiveHint: false },
 		},
 		async(args) => {
 			const projectDir = findProjectRoot(args.projectDir || process.cwd())

package/src/mcp/tools/authenticate/org-key-store.ts

@@ -0,0 +1,25 @@
+import { ConfigStore } from '../../../config/store.ts'
+
+/**
+ * Save an organization API key (`rorg_…`) in the local config (mode 0600), so
+ * the org-key tools can use it without the key passing through a transcript.
+ */
+export function saveOrgKey(orgId: string, secret: string) {
+	const saved = new ConfigStore().read()?.org_keys
+	new ConfigStore().write({
+		org_keys: {
+			byOrg: { ...saved?.byOrg, [orgId]: secret },
+			recent: orgId,
+		},
+	})
+}
+
+/**
+ * The saved key for `orgId`, or the most recently saved key when no org is
+ * given. Returns `undefined` when none is saved.
+ */
+export function savedOrgKey(orgId?: string): string | undefined {
+	const saved = new ConfigStore().read()?.org_keys
+	const id = orgId || saved?.recent
+	return id ? saved?.byOrg[id] : undefined
+}

package/src/mcp/tools/authenticate/resolve-owner-key.ts

@@ -19,18 +19,16 @@ export function resolveOwnerKeyTool(): RegisteredTool {
 		{
 			name: 'resolve_owner_key',
 			description:
-				'Resolve which eth proof-owner key run_proof should sign with — ' +
-				'call this BEFORE run_proof. Checks, in order: RECLAIM_PRIVATE_KEY ' +
-				'in the MCP env, a RECLAIM_PRIVATE_KEY=0x… line in the project .env, ' +
-				'then a file at RECLAIM_PRIVATE_KEY_FILE holding the raw hex. ' +
-				'Returns { ready: true, address, source } when one is ' +
-				'available — pass `address` to run_proof as `ownerAddress`. ' +
-				'Returns { ready: false } ' +
-				'when none exists: then ask the dev to generate one ' +
-				'(issue_credentials) or import one they already hold ' +
-				'(import_credentials, accepts 0x-hex or a key-file path), and call ' +
-				'resolve_owner_key again. Never exposes the private key.',
+				'Finds the eth proof-owner key `run_proof` signs with. Call it '
+				+ 'before `run_proof`. Checks RECLAIM_PRIVATE_KEY in the MCP env, a '
+				+ 'RECLAIM_PRIVATE_KEY line in the project .env, then the file at '
+				+ 'RECLAIM_PRIVATE_KEY_FILE. Returns { ready: true, address, source '
+				+ '}: pass `address` to `run_proof` as `ownerAddress`. Returns { '
+				+ 'ready: false } when none exists: ask the developer to create one '
+				+ 'with `issue_credentials` or import one with `import_credentials` '
+				+ '(a key file), then call it again. Never returns the key.',
 			inputSchema: { type: 'object', properties: {} },
+			annotations: { readOnlyHint: true, openWorldHint: false },
 		},
 		async() => {
 			const projectDir = findProjectRoot(process.cwd())
@@ -51,7 +49,7 @@ export function resolveOwnerKeyTool(): RegisteredTool {
 					`env, no RECLAIM_PRIVATE_KEY in ${join(projectDir, ENV_FILE)}, and ` +
 					'no RECLAIM_PRIVATE_KEY_FILE. Ask the dev to generate one via ' +
 					'issue_credentials, or import one they already hold via ' +
-					'import_credentials (0x-hex or a key-file path). Then call ' +
+					'import_credentials (a key file). Then call ' +
 					'resolve_owner_key again and pass its address to run_proof as ' +
 					'ownerAddress.',
 			}

package/src/mcp/tools/mode/mode.ts

@@ -53,6 +53,7 @@ export function buildModeTools(
 					},
 					required: ['mode'],
 				},
+				annotations: { openWorldHint: false, idempotentHint: true },
 			},
 			async(parsed) => {
 				config.write({ mode: parsed.mode })
@@ -84,6 +85,7 @@ export function buildModeTools(
 					+ 'the staleness with an error naming the tool to re-run. Which '
 					+ 'login authorizes what: how_it_works({ topic: "auth" }).',
 				inputSchema: { type: 'object', properties: {} },
+				annotations: { readOnlyHint: true, openWorldHint: false },
 			},
 			async() => {
 				const persisted = config.read()?.mode

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

@@ -7,6 +7,7 @@ import assert from 'node:assert'
 import { apiUrl, orgSecret } from '../../../consts.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import { resolveDecryptionKey } from '../authenticate/decrypt-key.ts'
+import { savedOrgKey } from '../authenticate/org-key-store.ts'
 
 /** Statuses that can carry a Builder-managed terminal result. */
 const TERMINAL = new Set([
@@ -32,14 +33,13 @@ const RESULT_EVENTS = new Set([
  * `orgToken`, else `RECLAIM_ORG_SECRET`.
  */
 function resolveOrgSecret(orgToken?: string): string {
-	const secret = orgToken?.trim() || orgSecret()?.trim()
+	const secret = orgToken?.trim() || orgSecret()?.trim() || savedOrgKey()
 	assert(
 		secret,
 		new Error(
 			'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.',
+				+ 'secret (rorg_…): run issue_org_token to save a key, pass orgToken, '
+				+ 'or export RECLAIM_ORG_SECRET for the MCP server.',
 		),
 	)
 	return secret
@@ -64,7 +64,8 @@ export function verificationResultTool(): RegisteredTool {
 				+ '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 '
+				+ '`RECLAIM_ORG_SECRET`, else the key saved by `issue_org_token`. '
+				+ '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 '
@@ -84,11 +85,13 @@ export function verificationResultTool(): RegisteredTool {
 						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.',
+							+ 'Defaults to the MCP server\'s RECLAIM_ORG_SECRET, then the '
+							+ 'key saved by `issue_org_token`. Never echo it back to the '
+							+ 'user.',
 					},
 				},
 			},
+			annotations: { readOnlyHint: true, openWorldHint: true },
 		},
 		async(args) => {
 			const secret = resolveOrgSecret(args.orgToken)

package/src/tools/registry.ts

@@ -16,10 +16,23 @@ import { isProblemDetails, isProblemError } from '@reclaimprotocol/client/api'
 import type { JSONSchema } from 'zod/v4/core'
 import { toZod } from '../mcp/api/to-zod.ts'
 
+/** MCP tool hints that let a client decide when to ask for approval. */
+export interface ToolAnnotations {
+	/** The tool never changes state. */
+	readOnlyHint?: boolean
+	/** The tool can delete or overwrite state. */
+	destructiveHint?: boolean
+	/** Repeating a call with the same input has no further effect. */
+	idempotentHint?: boolean
+	/** The tool reaches systems outside this machine. */
+	openWorldHint?: boolean
+}
+
 export interface ToolDefinition {
 	name: string
 	description: string
 	inputSchema: JSONSchema.ObjectSchema
+	annotations?: ToolAnnotations
 }
 
 export interface RegisteredTool {
@@ -108,6 +121,7 @@ export function extendTool(
 			name: base.name,
 			description: extra.description ?? base.description,
 			inputSchema,
+			...(base.annotations ? { annotations: base.annotations } : {}),
 		},
 		handler: tool.handler,
 	}