@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.2

package/src/mcp/api/to-zod.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod'
+import type { JSONSchema } from 'zod/v4/core'
+
+/**
+ * JSON Schema → zod for the generated MCP tool inputs.
+ *
+ * The generator (`packages/app/scripts/mcp-tools-gen.ts`) inlines `$ref`s it
+ * walks through `properties`/`items`, but it does NOT recurse into `allOf` /
+ * `anyOf` / `oneOf`. So a schema composed with `allOf` (e.g.
+ * `RequestSelectionTemplate =
+ * allOf[ RequestSelection, { multiple, required } ]`,
+ * surfaced by the proof tools' `allowedJsRequests`) can carry a dangling
+ * `#/components/schemas/…` `$ref` that points outside the standalone schema
+ * object handed to `z.fromJSONSchema`. zod then throws `Reference not found`
+ * at module-load time, taking down every tool.
+ *
+ * We pre-process here (rather than hand-editing the generated file, which
+ * regen would clobber): flatten `allOf` compositions into a single object
+ * schema and neutralize any remaining unresolvable `#/components/schemas/…`
+ * `$ref` to a permissive `{}`. The schemas affected are deep proof-tool inputs
+ * the model rarely hand-builds, so loosening leaf validation there is
+ * acceptable; the common tool inputs (uuids, version patterns, contexts) keep
+ * their full constraints.
+ */
+export function toZod(schema: JSONSchema.Schema) {
+	return z.fromJSONSchema(sanitize(schema) as JSONSchema.Schema)
+}
+
+type AnySchema = Record<string, unknown>
+
+/** True for a `$ref` that can't be resolved in a standalone schema object. */
+function isDanglingComponentRef(node: AnySchema): boolean {
+	return (
+		typeof node.$ref === 'string' &&
+		(node.$ref).startsWith('#/components/')
+	)
+}
+
+/**
+ * Recursively (a) merge `allOf` members into their parent so composition
+ * resolves locally, and (b) replace any dangling `#/components/…` `$ref` with
+ * a permissive empty schema. Pure — returns a fresh tree, never mutates input.
+ */
+function sanitize(input: unknown): unknown {
+	if(Array.isArray(input)) {
+		return input.map(sanitize)
+	}
+
+	if(input === null || typeof input !== 'object') {
+		return input
+	}
+
+	const node = input as AnySchema
+
+	if(isDanglingComponentRef(node)) {
+		// Drop the ref; keep any sibling keys (rare) sanitized.
+		const { $ref: _ref, ...rest } = node
+		void _ref
+		return sanitizeEntries(rest)
+	}
+
+	// Flatten allOf into the parent object. Each member is sanitized first so
+	// its own refs/allOf collapse; object members merge their `properties`,
+	// `required`, and scalar keys upward.
+	if(Array.isArray(node.allOf)) {
+		const { allOf, ...rest } = node
+		let merged: AnySchema = sanitizeEntries(rest)
+		for(const member of allOf as unknown[]) {
+			merged = mergeObjectSchemas(merged, sanitize(member) as AnySchema)
+		}
+
+		return merged
+	}
+
+	return sanitizeEntries(node)
+}
+
+/** Sanitize every value of an object schema's keys. */
+function sanitizeEntries(node: AnySchema): AnySchema {
+	const out: AnySchema = {}
+	for(const [k, v] of Object.entries(node)) {
+		out[k] = sanitize(v)
+	}
+
+	return out
+}
+
+/**
+ * Merge two (already-sanitized) object schemas for `allOf` flattening: union
+ * `properties`, union `required`, and let later members win on scalar keys.
+ * Both sides are expected to be object-shaped; non-object members fall back to
+ * a plain key spread (the rare case).
+ */
+function mergeObjectSchemas(a: AnySchema, b: AnySchema): AnySchema {
+	const out: AnySchema = { ...a, ...b }
+
+	const aProps = a.properties as AnySchema | undefined
+	const bProps = b.properties as AnySchema | undefined
+	if(aProps || bProps) {
+		out.properties = { ...aProps, ...bProps }
+	}
+
+	const aReq = Array.isArray(a.required) ? (a.required as string[]) : []
+	const bReq = Array.isArray(b.required) ? (b.required as string[]) : []
+	if(aReq.length || bReq.length) {
+		out.required = Array.from(new Set([...aReq, ...bReq]))
+	}
+
+	// `type` should stay `object` after merging two object schemas.
+	if(a.type === 'object' || b.type === 'object' || out.properties) {
+		out.type = 'object'
+	}
+
+	return out
+}

package/src/mcp/api/tools.ts

@@ -1,7 +1,10 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type {
-	IOperationArgs, IOperationId, ReclaimClient
+	ReclaimClient
 } from '@reclaimprotocol/client'
+import type {
+	IOperationArgs, IOperationId
+} from '@reclaimprotocol/client/openapi'
 import { remapErrorAsResponse } from '../remap_errors.ts'
 import { MCP_TOOLS } from './operations.gen.ts'
 
@@ -28,9 +31,12 @@ export function registerTools(server: McpServer, client: ReclaimClient) {
 		server.registerTool(
 			toSnakeCase(opId),
 			shape,
-			async(args: IOperationArgs<IOperationId>) => {
+			async(args: unknown) => {
 				try {
-					const result = (await client.call(opId as IOperationId, args))
+					const result = await client.call(
+						opId as IOperationId,
+						args as IOperationArgs<IOperationId>,
+					)
 					return {
 						content: [{
 							type: 'text' as const, text: JSON.stringify(result.data, null, 2)

package/src/mcp/instructions.ts

@@ -0,0 +1,15 @@
+/**
+ * MCP server instructions shown to the LLM when running in BUILDER mode
+ * (`USE_OLD_DEVTOOLS=false`). The prose lives in `skill/builder-mode.md`
+ * (published via the `files` array) so it can be edited as markdown without
+ * touching code. The path resolves identically from `src/mcp` (dev) and
+ * `lib/mcp` (published) — both are two levels below the package root.
+ * Old-devtools mode has its own reduced set in `../old/instructions.ts`.
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+export const BUILDER_MODE_INSTRUCTIONS = readFileSync(
+	fileURLToPath(new URL('../../skill/builder-mode.md', import.meta.url)),
+	'utf8',
+).trim()

package/src/mcp/server.ts

@@ -1,18 +1,12 @@
-import { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import type { Tool } from '@modelcontextprotocol/sdk/types.js'
-import {
-	CallToolRequestSchema,
-	ListToolsRequestSchema,
-} from '@modelcontextprotocol/sdk/types.js'
-import { convertJsonSchemaToZod, type JSONSchema } from 'zod-from-json-schema'
+import type { JSONSchema } from 'zod/v4/core'
+import { toZod } from './api/to-zod.ts'
 import { remapErrorAsResponse } from './remap_errors.ts'
 
 export interface ToolDefinition {
 	name: string
 	description: string
-	inputSchema: JSONSchema
+	inputSchema: JSONSchema.ObjectSchema
 }
 
 export interface RegisteredTool {
@@ -38,7 +32,7 @@ export function defineTool<TArgs>(
 	definition: ToolDefinition,
 	handler: (args: TArgs) => Promise<unknown>,
 ): RegisteredTool {
-	const schema = convertJsonSchemaToZod(definition.inputSchema)
+	const schema = toZod(definition.inputSchema)
 	return {
 		definition,
 		handler: async(raw) => {
@@ -59,7 +53,7 @@ export function registerToolList(server: McpServer, tools: RegisteredTool[]) {
 			tool.definition.name,
 			{
 				description: tool.definition.description,
-				inputSchema: convertJsonSchemaToZod(tool.definition.inputSchema),
+				inputSchema: toZod(tool.definition.inputSchema),
 			},
 			async(args) => {
 				try {
@@ -78,42 +72,3 @@ export function registerToolList(server: McpServer, tools: RegisteredTool[]) {
 		)
 	}
 }
-
-export class ReclaimMcpServer {
-	#tools = new Map<string, RegisteredTool>()
-	#server: Server
-
-	constructor() {
-		this.#server = new Server(
-			{ name: 'reclaim-agent', version: '0.1.0' },
-			{ capabilities: { tools: {} } },
-		)
-
-		this.#server.setRequestHandler(ListToolsRequestSchema, async() => ({
-			// Double-cast: our `ToolDefinition` carries the same fields as the
-			// SDK's `Tool` but the SDK's type is strict-narrowed and won't
-			// accept ours without going through `unknown`.
-			tools: [...this.#tools.values()].map(
-				(t) => t.definition as unknown as Tool,
-			),
-		}))
-
-		this.#server.setRequestHandler(CallToolRequestSchema, async(req) => {
-			const tool = this.#tools.get(req.params.name)
-			if(!tool) {
-				throw new Error(`unknown tool: ${req.params.name}`)
-			}
-
-			const result = await tool.handler(req.params.arguments ?? {})
-			return { content: [{ type: 'text', text: JSON.stringify(result) }] }
-		})
-	}
-
-	register(tool: RegisteredTool) {
-		this.#tools.set(tool.definition.name, tool)
-	}
-
-	async listen(): Promise<void> {
-		await this.#server.connect(new StdioServerTransport())
-	}
-}

package/src/mcp/start.ts

@@ -1,19 +1,27 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { DEFAULT_BASE_URL, ReclaimClient } from '@reclaimprotocol/client'
-import { DEFAULT_OLD_API_URL, ReclaimOldClient } from '../old/client.ts'
-import { useOldDevtools } from '../old/flag.ts'
+import { ReclaimClient } from '@reclaimprotocol/client'
+import {
+	agentDisabled,
+	apiToken,
+	apiUrl,
+	oldApiUrl,
+	useOldDevtools,
+} from '../consts.ts'
+import { ReclaimOldClient } from '../old/client.ts'
 import { resolveInitialIdentity } from '../old/identity.ts'
 import { OLD_MODE_INSTRUCTIONS } from '../old/instructions.ts'
 import { buildOldBackendTools } from '../old/tools/build.ts'
 import { NAME, VERSION } from '../pkg.ts'
 import { registerTools } from './api/tools.ts'
-import { buildAgentTools } from './tools/agent/build.ts'
 import {
+	buildAgentTools,
 	buildCredentialTools,
 	buildLocalCredentialTools,
-} from './tools/credentials/build.ts'
-import { readSession } from './tools/credentials/session-cache.ts'
+	buildVerificationTools,
+	readSession,
+} from './tools/index.ts'
+import { BUILDER_MODE_INSTRUCTIONS } from './instructions.ts'
 import { registerToolList } from './server.ts'
 
 export async function startMcpServer() {
@@ -21,14 +29,18 @@ export async function startMcpServer() {
 
 	const server = new McpServer(
 		{ name: NAME, version: VERSION },
-		oldMode ? { instructions: OLD_MODE_INSTRUCTIONS } : undefined,
+		{
+			instructions: oldMode
+				? OLD_MODE_INSTRUCTIONS
+				: BUILDER_MODE_INSTRUCTIONS,
+		},
 	)
 
 	// Agent tools (Chrome CDP capture, provider synthesis, replay, proof) are
 	// backend-independent and registered in both modes. Skipped in hosted
 	// deployments — set RECLAIM_AGENT_DISABLED=1 to register only the API
 	// surface.
-	const agentToolsEnabled = process.env.RECLAIM_AGENT_DISABLED !== '1'
+	const agentToolsEnabled = !agentDisabled()
 
 	if(oldMode) {
 		// OLD-devtools mode (the default): the legacy backend is still in
@@ -36,7 +48,7 @@ export async function startMcpServer() {
 		// are disabled; a small ReclaimOldClient serves authenticate / publish /
 		// get_me_providers instead.
 		const oldClient = new ReclaimOldClient({
-			baseUrl: process.env.RECLAIM_OLD_API_URL || DEFAULT_OLD_API_URL,
+			baseUrl: oldApiUrl(),
 			identity: resolveInitialIdentity(),
 		})
 
@@ -49,9 +61,9 @@ export async function startMcpServer() {
 		// NOTE: registerTools() is intentionally NOT called — generated tools off.
 	} else {
 		const client = new ReclaimClient({
-			baseUrl: process.env.RECLAIM_API_URL || DEFAULT_BASE_URL,
+			baseUrl: apiUrl(),
 			// Priority: explicit env var → cached session token → unauthenticated
-			token: process.env.RECLAIM_API_TOKEN || readSession()?.token,
+			token: apiToken() || readSession()?.token,
 			headers: { 'User-Agent': `${NAME}/${VERSION}` },
 		})
 
@@ -64,6 +76,10 @@ export async function startMcpServer() {
 		// Register credential tools for ETH credential management.
 		registerToolList(server, buildCredentialTools(client))
 
+		// Higher-level verification orchestrations (e.g. fetch + decrypt result).
+		// Authenticates with RECLAIM_ORG_SECRET, not the session client.
+		registerToolList(server, buildVerificationTools())
+
 		// Add auto-generated tools with snake_case wrappers
 		// for every MCP-tagged operation.
 		registerTools(server, client)

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

@@ -1,21 +1,16 @@
 /**
  * Factory entry-point for embedding the reclaim-agent's MCP tools into
- * a host MCP server. Two consumers:
- *
- *   - The agent's own standalone `src/index.ts` (uses `ReclaimMcpServer`,
- *     the low-level wrapper around `@modelcontextprotocol/sdk`'s Server).
- *   - `@reclaimprotocol/client`'s MCP server (uses `McpServer`, the
- *     high-level SDK wrapper). Calls `registerAgentTools` to fold the
- *     agent's 16 tools alongside its auto-generated API tools.
+ * a host MCP server via `registerToolList` (server.ts) on the high-level
+ * `@modelcontextprotocol/sdk` `McpServer`. Folds the agent's tools
+ * alongside the auto-generated API tools.
  *
  * Shared state — Chrome attach state, capture store, secret store — is
  * built once per server and threaded through every tool factory.
  */
 
 import type { ReclaimClient } from '@reclaimprotocol/client'
-import { setCryptoImplementation } from '@reclaimprotocol/tls'
-import { webcryptoCrypto } from '@reclaimprotocol/tls/webcrypto'
 import { ConfigStore } from '../../../config/store.ts'
+import { ensureAttestorCrypto } from '../../../proof/proof-core.ts'
 import { type RegisteredTool } from '../../server.ts'
 import { analyzeTool } from './analyze.ts'
 import { type AttachState, attachTool } from './attach.ts'
@@ -38,21 +33,6 @@ export interface AgentState {
 	secrets: SecretStore
 }
 
-let cryptoInitialized = false
-
-/** One-time crypto backend init for @reclaimprotocol/tls. The package
- *  ships with an empty `crypto = {}` and defers backend choice to the
- *  caller; without this, the first proof call dies inside the SDK with
- *  `crypto.randomBytes is not a function`. */
-function ensureCryptoInit() {
-	if(cryptoInitialized) {
-		return
-	}
-
-	setCryptoImplementation(webcryptoCrypto)
-	cryptoInitialized = true
-}
-
 function buildAgentState(): AgentState {
 	return {
 		attach: { config: new ConfigStore() },
@@ -61,8 +41,8 @@ function buildAgentState(): AgentState {
 	}
 }
 
-/** Build the flat list of `RegisteredTool` entries. Useful when the host
- *  uses our internal `ReclaimMcpServer` interface (`.register(tool)`).
+/** Build the flat list of `RegisteredTool` entries, ready for
+ *  `registerToolList`.
  *  Pass `client` to include the builder `create_provider_version_from_capture`;
  *  omit it (e.g. OLD-devtools mode) to register only the backend-independent
  *  capture/proof tools — old mode supplies its own publish tool. */
@@ -70,7 +50,7 @@ export function buildAgentTools(
 	client?: ReclaimClient,
 ): RegisteredTool[] {
 	const state = buildAgentState()
-	ensureCryptoInit()
+	ensureAttestorCrypto()
 	const tools: RegisteredTool[] = []
 	tools.push(attachTool(state.attach))
 	for(const t of captureTools(state.attach, state.captures)) {

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

@@ -0,0 +1,4 @@
+// Barrel for the agent tool group (Chrome CDP capture, provider synthesis,
+// replay, zkTLS proof). Import from here, not the individual files.
+export { buildAgentTools } from './build.ts'
+export type { AgentState } from './build.ts'

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

@@ -1,5 +1,6 @@
 import { mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { agentTraceEnabled } from '../../../consts.ts'
 import { reclaimHomeDirPath } from '../../../paths.ts'
 import {
 	runAttestorProof,
@@ -135,11 +136,6 @@ export function proofTool(secrets: SecretStore): RegisteredTool {
 			inputSchema: {
 				type: 'object',
 				properties: {
-					// `type: 'object'` is required so MCP clients (the LLM)
-					// serialize the value as an object, not a JSON-stringified
-					// string. `properties: {}` is required so zod-from-json-schema
-					// compiles to a passthrough instead of strict-strip — leaving
-					// it off makes the server receive `{}`.
 					provider: { type: 'object', properties: {} },
 					secretParamsRef: { type: 'string' },
 					attestorUrl: { type: 'string' },
@@ -173,8 +169,7 @@ export function proofTool(secrets: SecretStore): RegisteredTool {
 			const result = await runAttestorProof(
 				provider as ReclaimProvider,
 				resolved,
-				attestorUrl,
-				ownerAddress,
+				{ attestorUrl, ownerAddress },
 			)
 
 			// Persist the full claim to disk for the dev to inspect/share.
@@ -243,7 +238,7 @@ export function proofTool(secrets: SecretStore): RegisteredTool {
 			// when investigating proof failures and the file at runLogPath
 			// will carry the input provider, sentParams, full attestor log
 			// stream, and result.
-			if(process.env['RECLAIM_AGENT_TRACE'] === '1') {
+			if(agentTraceEnabled()) {
 				const runLogPath = writeProofRunDump({
 					provider,
 					hasSecretParamsRef: secretParamsRef !== undefined,

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

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto'
 import { draftProvider } from '../../../provider/draft.ts'
 import { OPRF_MAX_BYTES } from '../../../provider/matcher.ts'
 import type { OprfMode } from '../../../provider/schema.ts'
+import { verificationWarnings } from '../../../provider/verification-checks.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import type { CaptureStore } from './capture.ts'
 
@@ -48,7 +49,11 @@ export function proposeTool(
 				'cleartext. Skill should ask the dev first. `oprf-raw` ' +
 				'is the only variant that runs ' +
 				'without external deps; `oprf` needs gnark (Linux/macOS), ' +
-				'`oprf-mpc` needs a TEE attestor.',
+				'`oprf-mpc` needs a TEE attestor. ' +
+				'The response may include `verificationWarnings` — advisory ' +
+				'author-only decisions (e.g. a user-specific URL part needing ' +
+				'the {{context.<name>}}-vs-bare call). Surface each to the ' +
+				'dev verbatim and resolve before publishing.',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -105,7 +110,13 @@ export function proposeTool(
 			}
 
 			const secretParamsRef = secrets.put(realSecrets)
-			return { provider, secretRefs, secretParamsRef }
+			const warnings = verificationWarnings(provider)
+			return {
+				provider,
+				secretRefs,
+				secretParamsRef,
+				...(warnings.length ? { verificationWarnings: warnings } : {}),
+			}
 		},
 	)
 }