@reclaimprotocol/agent 0.1.11 → 0.1.13

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

@@ -11,6 +11,33 @@ import { authoringTools, extendTool, } from "../../../authoring/index.js";
 import { runAttestorProof } from "../../../proof/attestor.js";
 import { replayProvider } from "../../../proof/replay.js";
 import { shapeRichProofResult } from "./proof.js";
+/**
+ * OPRF mode this LOCAL (non-TEE) attestor can actually run. Recipes carry
+ * `oprf-mpc` — the canonical/publish mode a TEE expects — but the local dev
+ * attestor can't do MPC. gnark `oprf` (Linux/Mac, needs ZK circuits) is the
+ * strongest it supports; Windows falls back to server-side `oprf-raw` (no
+ * circuits). Proving with the wrong mode fails, which is what pushed the agent
+ * to hand-craft a plaintext workaround.
+ */
+const LOCAL_OPRF_MODE = process.platform === 'win32' ? 'oprf-raw' : 'oprf';
+/**
+ * Clone `provider` with every `oprf-mpc` redaction remapped to the mode this
+ * local attestor can run, so the PROOF validates locally. The draft itself is
+ * untouched — it keeps `oprf-mpc`, so the PUBLISHED recipe is always the
+ * TEE-canonical mode regardless of where it was proved.
+ */
+function withLocalOprfMode(provider) {
+    const reds = provider.responseRedactions;
+    if (!reds?.some((r) => r.hash === 'oprf-mpc')) {
+        return provider;
+    }
+    return {
+        ...provider,
+        responseRedactions: reds.map((r) => {
+            return r.hash === 'oprf-mpc' ? { ...r, hash: LOCAL_OPRF_MODE } : r;
+        }),
+    };
+}
 /** The local backend for one capture: drive its tab over CDP, read its
  *  captured requests, prove via the in-process attestor, replay by re-fetch. */
 function localBackend(entry) {
@@ -50,7 +77,9 @@ function localBackend(entry) {
             };
         },
         prove: async (draft, opts) => {
-            const result = await runAttestorProof(draft.provider, draft.secrets, {
+            // Prove with the locally-runnable OPRF mode; the draft (→ published
+            // recipe) keeps oprf-mpc.
+            const result = await runAttestorProof(withLocalOprfMode(draft.provider), draft.secrets, {
                 ...(opts?.ownerAddress ? { ownerAddress: opts.ownerAddress } : {}),
                 ...(opts?.attestorUrl ? { attestorUrl: opts.attestorUrl } : {}),
             });

package/lib/mcp/tools/authenticate/decrypt-key.js

@@ -11,7 +11,7 @@
  * The hex is loaded via the client's `loadDecryptionKey` and passed straight
  * through as `ReclaimConfig.credential` / to `decryptCallback`.
  */
-import { loadDecryptionKey, } from '@reclaimprotocol/client';
+import { loadDecryptionKey } from '@reclaimprotocol/client';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { findProjectRoot } from "../../../paths.js";

package/lib/old/client.d.ts

@@ -71,6 +71,20 @@ export interface MyProvidersQuery {
     pageSize?: number;
     searchQuery?: string;
 }
+/** `POST /api/applications/issue-credentials` response — a brand-new,
+ *  unassociated (sandboxed) app. `appSecret` is the raw eth private key;
+ *  it's returned once and never stored server-side in recoverable form. */
+export interface IssuedAppCredentials {
+    appId: string;
+    appSecret: string;
+}
+/** `GET /api/applications/link/nonce` response — a one-time, 5-minute-TTL
+ *  challenge the caller signs with the app's private key to prove ownership
+ *  in `linkAppToAccount`. */
+export interface LinkNonce {
+    nonce: string;
+    expiresInSeconds: number;
+}
 /**
  * Minimal REST client for the OLD devtools Express backend (base `/api`).
  * Deliberately NOT a clone of `@reclaimprotocol/client`'s operationId
@@ -110,5 +124,22 @@ export declare class ReclaimOldClient {
      *  `#request`). Attaches the caller identity when one is set; queried
      *  anonymously otherwise. */
     getSessionAnalyticsLogs(sessionId: string): Promise<unknown>;
+    /** Mint a brand-new, unassociated (sandboxed) app — no auth required. Link
+     *  it to an account afterwards with `getLinkNonce` + `linkAppToAccount`, or
+     *  use it as-is within the sandbox session limit. */
+    issueCredentials(): Promise<IssuedAppCredentials>;
+    /** One-time, 5-minute challenge for `linkAppToAccount`. Requires auth —
+     *  the nonce is scoped to the authenticated user's uid. */
+    getLinkNonce(): Promise<LinkNonce>;
+    /** Link an unassociated (`issueCredentials`-minted) app to the
+     *  authenticated account. `signature` must be an EIP-191 signature, made
+     *  with the app's private key, over the exact string
+     *  `` `Link ${appId} to account ${userId} | nonce: ${nonce}` `` — see
+     *  `buildLinkMessage` in the backend's `application.controller.ts`. Fails
+     *  with `APP_ALREADY_LINKED` (400) if the app already belongs to someone. */
+    linkAppToAccount(appId: string, signature: string, nonce: string): Promise<unknown>;
+    /** Public, unauthenticated app status — `isLinked`, sandbox/quota info.
+     *  Works for any appId, owned or not. */
+    getApplicationStatus(appId: string): Promise<unknown>;
     getMyProviders(query?: MyProvidersQuery): Promise<unknown>;
 }

package/lib/old/client.js

@@ -89,6 +89,39 @@ export class ReclaimOldClient {
         }
         return json;
     }
+    /** Mint a brand-new, unassociated (sandboxed) app — no auth required. Link
+     *  it to an account afterwards with `getLinkNonce` + `linkAppToAccount`, or
+     *  use it as-is within the sandbox session limit. */
+    async issueCredentials() {
+        const res = await __classPrivateFieldGet(this, _ReclaimOldClient_instances, "m", _ReclaimOldClient_request).call(this, 'POST', '/applications/issue-credentials');
+        return res.data;
+    }
+    /** One-time, 5-minute challenge for `linkAppToAccount`. Requires auth —
+     *  the nonce is scoped to the authenticated user's uid. */
+    async getLinkNonce() {
+        const res = await __classPrivateFieldGet(this, _ReclaimOldClient_instances, "m", _ReclaimOldClient_request).call(this, 'GET', '/applications/link/nonce', {
+            auth: true,
+        });
+        return res.data;
+    }
+    /** Link an unassociated (`issueCredentials`-minted) app to the
+     *  authenticated account. `signature` must be an EIP-191 signature, made
+     *  with the app's private key, over the exact string
+     *  `` `Link ${appId} to account ${userId} | nonce: ${nonce}` `` — see
+     *  `buildLinkMessage` in the backend's `application.controller.ts`. Fails
+     *  with `APP_ALREADY_LINKED` (400) if the app already belongs to someone. */
+    linkAppToAccount(appId, signature, nonce) {
+        return __classPrivateFieldGet(this, _ReclaimOldClient_instances, "m", _ReclaimOldClient_request).call(this, 'POST', '/applications/link', {
+            body: { appId, signature, nonce },
+            auth: true,
+        });
+    }
+    /** Public, unauthenticated app status — `isLinked`, sandbox/quota info.
+     *  Works for any appId, owned or not. */
+    async getApplicationStatus(appId) {
+        const res = await __classPrivateFieldGet(this, _ReclaimOldClient_instances, "m", _ReclaimOldClient_request).call(this, 'GET', `/applications/status/${encodeURIComponent(appId)}`);
+        return res.data;
+    }
     getMyProviders(query = {}) {
         // Every one of these query params is REQUIRED by the backend
         // validator (missing/invalid → 400), so default them all here.

package/lib/old/tools/build.js

@@ -1,9 +1,15 @@
 import { authenticateTool } from "./authenticate.js";
+import { checkAppStatusTool } from "./check-app-status.js";
 import { getProviderInfoTool } from "./get-provider-info.js";
+import { issueAppCredentialsTool } from "./issue-app-credentials.js";
+import { getJsSdkIntegrationGuideTool } from "./js-sdk-integration-guide.js";
+import { linkAppTool } from "./link-app.js";
 import { getMeProvidersTool } from "./me-providers.js";
 import { createVersionFromCaptureTool } from "./publish.js";
+import { scaffoldDemoServerTool } from "./scaffold-demo-server.js";
 import { sessionAnalyticsLogsTool } from "./session-analytics-logs.js";
 import { updateProviderMetadataTool } from "./update-provider-metadata.js";
+import { verifySdkSetupTool } from "./verify-sdk-setup.js";
 /**
  * The backend-facing tools for OLD-devtools mode. Mirrors
  * `buildCredentialTools` / `buildAgentTools`: returns a flat `RegisteredTool`
@@ -22,5 +28,11 @@ export function buildOldBackendTools(client, sdkClient) {
         getProviderInfoTool(sdkClient),
         updateProviderMetadataTool(client),
         sessionAnalyticsLogsTool(client),
+        issueAppCredentialsTool(client),
+        linkAppTool(client),
+        checkAppStatusTool(client),
+        getJsSdkIntegrationGuideTool(),
+        scaffoldDemoServerTool(),
+        verifySdkSetupTool(client),
     ];
 }

package/lib/old/tools/check-app-status.d.ts

@@ -0,0 +1,8 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+import type { ReclaimOldClient } from '../client.ts';
+/**
+ * Public, unauthenticated app status lookup — works for any `appId`, owned
+ * or not, linked or sandboxed. Mirrors the backend's
+ * `GET /api/applications/status/:appId`.
+ */
+export declare function checkAppStatusTool(client: ReclaimOldClient): RegisteredTool;

package/lib/old/tools/check-app-status.js

@@ -0,0 +1,27 @@
+import { defineTool } from "../../mcp/server.js";
+/**
+ * Public, unauthenticated app status lookup — works for any `appId`, owned
+ * or not, linked or sandboxed. Mirrors the backend's
+ * `GET /api/applications/status/:appId`.
+ */
+export function checkAppStatusTool(client) {
+    return defineTool({
+        name: 'check_app_status',
+        description: 'Check a Reclaim app\'s link/sandbox status by appId — no ' +
+            'authentication required. Returns whether the app is linked to a ' +
+            'dashboard account (`isLinked`), and for linked apps, remaining ' +
+            'session quota. A 404 means the appId has never been used yet — ' +
+            'it is created lazily on the first ReclaimProofRequest.init() call ' +
+            'or via issue_app_credentials.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                appId: {
+                    type: 'string',
+                    description: 'The eth-address appId to check.',
+                },
+            },
+            required: ['appId'],
+        },
+    }, async ({ appId }) => client.getApplicationStatus(appId));
+}

package/lib/old/tools/issue-app-credentials.d.ts

@@ -0,0 +1,11 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+import type { ReclaimOldClient } from '../client.ts';
+/**
+ * Mint a brand-new eth-keypair APP (as opposed to authenticating as a
+ * dashboard user). `appId` is the eth address, `appSecret` the raw private
+ * key — this is the pair `@reclaimprotocol/js-sdk`'s `ReclaimProofRequest.init`
+ * expects. No auth required: the app starts unassociated (`creatorUid: null`)
+ * and sandboxed (`sandboxLimit: 100` sessions). Use `link_app_to_account` to
+ * attach it to your dashboard account, or `check_app_status` to inspect it.
+ */
+export declare function issueAppCredentialsTool(client: ReclaimOldClient): RegisteredTool;

package/lib/old/tools/issue-app-credentials.js

@@ -0,0 +1,35 @@
+import { defineTool } from "../../mcp/server.js";
+/**
+ * Mint a brand-new eth-keypair APP (as opposed to authenticating as a
+ * dashboard user). `appId` is the eth address, `appSecret` the raw private
+ * key — this is the pair `@reclaimprotocol/js-sdk`'s `ReclaimProofRequest.init`
+ * expects. No auth required: the app starts unassociated (`creatorUid: null`)
+ * and sandboxed (`sandboxLimit: 100` sessions). Use `link_app_to_account` to
+ * attach it to your dashboard account, or `check_app_status` to inspect it.
+ */
+export function issueAppCredentialsTool(client) {
+    return defineTool({
+        name: 'issue_app_credentials',
+        description: 'Mint a new Reclaim APP (eth keypair) on the old devtools backend — ' +
+            'no authentication required. Returns `{ appId, appSecret }`: ' +
+            '`appId` is the eth address, `appSecret` the raw private key. This ' +
+            'is the appId/appSecret pair for @reclaimprotocol/js-sdk ' +
+            '(`ReclaimProofRequest.init(appId, appSecret, providerId)`). The app ' +
+            'starts UNLINKED and sandboxed (100 sessions) — call ' +
+            'link_app_to_account to attach it to your dashboard account and ' +
+            'check_app_status to check its state. Store `appSecret` like a ' +
+            'password (e.g. in a gitignored .env as RECLAIM_APP_SECRET) — it ' +
+            'is returned once and cannot be recovered from the server.',
+        inputSchema: { type: 'object', properties: {} },
+    }, async () => {
+        const { appId, appSecret } = await client.issueCredentials();
+        return {
+            appId,
+            appSecret,
+            note: 'Unlinked, sandboxed app (100 session limit). Set RECLAIM_APP_ID ' +
+                'and RECLAIM_APP_SECRET in your .env (gitignored). Run ' +
+                'link_app_to_account to attach it to your dashboard account and ' +
+                'lift the sandbox limit.',
+        };
+    });
+}

package/lib/old/tools/js-sdk-integration-guide.d.ts

@@ -0,0 +1,2 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+export declare function getJsSdkIntegrationGuideTool(): RegisteredTool;

package/lib/old/tools/js-sdk-integration-guide.js

@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { defineTool } from "../../mcp/server.js";
+/**
+ * Verified against `@reclaimprotocol/js-sdk` v5.8.1 source
+ * (`reclaim-js-sdk/src/Reclaim.ts`) — NOT copied unchecked from the archived
+ * `reclaim-mcp-server`'s guide, which predates several of these signatures.
+ * The prose lives in `skill/js-sdk-integration.md` so it can be edited as
+ * markdown without touching code — same pattern as `provider/injection-doc.ts`.
+ * The path resolves the same from `src/old/tools` (dev) and `lib/old/tools`
+ * (published): both are three levels below the package root.
+ */
+const GUIDE = readFileSync(fileURLToPath(new URL('../../../skill/js-sdk-integration.md', import.meta.url)), 'utf8').trim();
+export function getJsSdkIntegrationGuideTool() {
+    return defineTool({
+        name: 'get_js_sdk_integration_guide',
+        description: 'Return a verified, copy-pasteable guide for integrating ' +
+            '@reclaimprotocol/js-sdk (backend proof request + callback ' +
+            'verification), checked against the current SDK source rather than ' +
+            'assumed from older docs. Covers testing locally without deploying: ' +
+            'the built-in "example" providerId for a quick smoke test, and using ' +
+            'ngrok to get a callback URL Reclaim\'s servers can actually reach. ' +
+            'Use scaffold_reclaim_demo_server to generate a runnable local demo ' +
+            'instead of copy-pasting by hand.',
+        inputSchema: { type: 'object', properties: {} },
+    }, async () => ({ guide: GUIDE }));
+}

package/lib/old/tools/link-app.d.ts

@@ -0,0 +1,10 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+import type { ReclaimOldClient } from '../client.ts';
+/**
+ * Link an unassociated app (minted via `issue_app_credentials`, or any
+ * eth-keypair app you already hold the private key for) to the currently
+ * authenticated dashboard account. Proves ownership by signing a one-time
+ * challenge with the app's private key — the private key itself is only
+ * ever used locally to sign, never sent to the server.
+ */
+export declare function linkAppTool(client: ReclaimOldClient): RegisteredTool;

package/lib/old/tools/link-app.js

@@ -0,0 +1,73 @@
+import { signEip191 } from '@reclaimprotocol/client';
+import { defineTool } from "../../mcp/server.js";
+/** Byte-for-byte the same format as the backend's `buildLinkMessage` in
+ *  `application.controller.ts` — MUST stay in lockstep with it. */
+function buildLinkMessage(appId, userId, nonce) {
+    return `Link ${appId} to account ${userId} | nonce: ${nonce}`;
+}
+/** The uid the backend binds into the signed message — `req.user.uid` there.
+ *  For a bearer identity this comes back from `POST /users/login`; for an eth
+ *  identity, `OldIdentity.uid` (already `eth:<address>`) IS that uid. */
+async function resolveUserId(client) {
+    const identity = client.getIdentity();
+    if (!identity) {
+        throw new Error('Not authenticated against old devtools. Call reclaim_authenticate ' +
+            'first.');
+    }
+    if (identity.kind === 'eth') {
+        return identity.uid;
+    }
+    const res = await client.loginWithToken();
+    const uid = res?.user?.uid;
+    if (!uid) {
+        throw new Error('Could not resolve your account uid from POST /users/login — ' +
+            'unexpected response shape.');
+    }
+    return uid;
+}
+/**
+ * Link an unassociated app (minted via `issue_app_credentials`, or any
+ * eth-keypair app you already hold the private key for) to the currently
+ * authenticated dashboard account. Proves ownership by signing a one-time
+ * challenge with the app's private key — the private key itself is only
+ * ever used locally to sign, never sent to the server.
+ */
+export function linkAppTool(client) {
+    return defineTool({
+        name: 'link_app_to_account',
+        description: 'Link an eth-keypair app to your authenticated dashboard account — ' +
+            'use this to keep using an appId/appSecret you already have ' +
+            '(instead of minting a fresh one via issue_app_credentials). ' +
+            'Requires reclaim_authenticate first. Fetches a one-time nonce, ' +
+            'signs `Link <appId> to account <userId> | nonce: <nonce>` locally ' +
+            'with `appSecret` (EIP-191, never transmitted), and submits the ' +
+            'signature. Fails with APP_ALREADY_LINKED if the app is already ' +
+            'linked to a (possibly different) account.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                appId: {
+                    type: 'string',
+                    description: 'The eth-address appId to link.',
+                },
+                appSecret: {
+                    type: 'string',
+                    description: 'The app\'s raw eth private key — used only locally to sign ' +
+                        'the link challenge, never sent to the server.',
+                },
+            },
+            required: ['appId', 'appSecret'],
+        },
+    }, async ({ appId, appSecret }) => {
+        const userId = await resolveUserId(client);
+        const { nonce } = await client.getLinkNonce();
+        const message = buildLinkMessage(appId, userId, nonce);
+        const signature = signEip191(message, appSecret);
+        await client.linkAppToAccount(appId, signature, nonce);
+        return {
+            linked: true,
+            appId,
+            note: 'App linked to your account. Run check_app_status to confirm.',
+        };
+    });
+}

package/lib/old/tools/publish.js

@@ -104,9 +104,16 @@ export function createVersionFromCaptureTool(client) {
                     type: 'array',
                     description: 'Multiple proven drafts → one multi-request version (each ' +
                         'becomes a parallel `requestData` entry, all verified ' +
-                        'together). Each item has the same shape as `provider`. Pass ' +
-                        'this OR `provider`, not both.',
-                    minItems: 1,
+                        'together). Each item has the same shape as `provider` (if ' +
+                        'both are passed, they are combined). May be omitted (or ' +
+                        'empty) together with `provider` ONLY when adding a version ' +
+                        'to an EXISTING provider (`providerId` set) — publishes with ' +
+                        'zero `requestData` entries, for a pure customInjection/' +
+                        'HAWKEYE provider that relies entirely on ' +
+                        '`allowedInjectedRequestData` for validation instead of a ' +
+                        'static requestData stub. Registering a brand-new provider ' +
+                        'always needs at least one draft (its name comes from the ' +
+                        'first one).',
                     items: {
                         type: 'object',
                         properties: {
@@ -241,15 +248,23 @@ export function createVersionFromCaptureTool(client) {
             required: ['initialUrl'],
         },
     }, async (args) => {
-        // Exactly one of `provider` / `providers` — normalize to an array so a
-        // multi-request capture publishes every request, not just the first.
-        const hasMany = Array.isArray(args.providers) && args.providers.length > 0;
-        const hasOne = !!args.provider;
-        if (hasMany === hasOne) {
-            throw new Boom('Pass exactly one of `provider` (a single draft) or `providers` ' +
-                '(an array of 1+ drafts).', { statusCode: 400 });
+        // `provider` / `providers` are just two spellings of the same input —
+        // fold them into one array. Zero drafts is allowed ONLY when adding a
+        // version to an EXISTING provider (`providerId` set): that publishes
+        // with zero `requestData` entries, for a pure customInjection/HAWKEYE
+        // provider whose claims are validated entirely via
+        // `allowedInjectedRequestData`. Registering a brand-new provider still
+        // needs at least one draft — its name comes from the first one.
+        const providers = [
+            ...(args.provider ? [args.provider] : []),
+            ...(args.providers ?? []),
+        ];
+        if (!providers.length && !args.providerId) {
+            throw new Boom('Pass at least one of `provider`/`providers` when registering a ' +
+                'new provider (its name comes from the first draft). Omitting ' +
+                'both is only allowed when adding a version to an EXISTING ' +
+                'provider via `providerId`.', { statusCode: 400 });
         }
-        const providers = hasMany ? args.providers : [args.provider];
         const opts = {
             initialUrl: args.initialUrl,
             description: args.description,

package/lib/old/tools/scaffold-demo-server.d.ts

@@ -0,0 +1,2 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+export declare function scaffoldDemoServerTool(): RegisteredTool;

package/lib/old/tools/scaffold-demo-server.js

@@ -0,0 +1,94 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineTool } from "../../mcp/server.js";
+import { findProjectRoot } from "../../paths.js";
+/** The demo's source files live in `samples/demo-server/` so they can be
+ *  edited (and even run) as plain files without touching code — same pattern
+ *  as `skill/*.md`. The path resolves the same from `src/old/tools` (dev) and
+ *  `lib/old/tools` (published): both are three levels below the package root.
+ *
+ *  `server.js` there is corrected against `@reclaimprotocol/js-sdk` v5.8.1
+ *  (`Reclaim.ts`): awaits `getRequestUrl()`, uses `setContext` (not deprecated
+ *  `addContext`), JSON-parses the raw webhook body before `verifyProof`,
+ *  passes the required `{ providerId, providerVersion }` config, and reads
+ *  `result.isVerified` (not `is_verified`). `providerVersion` is left unpinned
+ *  by default — the built-in "example" providerId isn't versioned, so pinning
+ *  one is only meaningful once you swap in your own provider. */
+const SAMPLE_DIR = fileURLToPath(new URL('../../../samples/demo-server', import.meta.url));
+function readSample(name) {
+    return readFileSync(join(SAMPLE_DIR, name), 'utf8');
+}
+/** `server.js` with its `__PROVIDER_ID__` / `__PROVIDER_VERSION__` tokens
+ *  substituted with JS literals. */
+function serverJs(providerId, providerVersion) {
+    return readSample('server.js')
+        .replace('__PROVIDER_ID__', JSON.stringify(providerId))
+        .replace('__PROVIDER_VERSION__', providerVersion ? JSON.stringify(providerVersion) : 'undefined');
+}
+/**
+ * Scaffold a small, runnable Express demo that exercises the full
+ * @reclaimprotocol/js-sdk flow end-to-end: request a proof (backend), open it
+ * (frontend), and verify the async webhook callback (backend). Corrected
+ * against the CURRENT SDK API (see js-sdk-integration-guide) rather than
+ * older examples that predate several signature changes.
+ */
+const DEFAULT_PROVIDER_ID = 'example';
+export function scaffoldDemoServerTool() {
+    return defineTool({
+        name: 'scaffold_reclaim_demo_server',
+        description: 'Write a small runnable Express demo (server.js, package.json, ' +
+            '.env.example, README.md) that requests a Reclaim proof and ' +
+            'verifies the async webhook callback, using the CURRENT ' +
+            '@reclaimprotocol/js-sdk API. Defaults `providerId` to the built-in ' +
+            '"example" smoke-test provider so you can confirm the whole loop ' +
+            'without authoring one first. The webhook callback needs a URL ' +
+            'Reclaim\'s servers can reach — localhost never works — via EITHER ' +
+            'a tunnel (ngrok or similar) OR quickly deploying this demo to a ' +
+            'dev/staging server the user already has; ASK THE USER which they\'d ' +
+            'rather use before assuming ngrok, since either sets `PUBLIC_URL` in ' +
+            '.env (the generated README covers both). Use ' +
+            'get_js_sdk_integration_guide for the annotated write-up of the ' +
+            'same flow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                targetDir: {
+                    type: 'string',
+                    description: 'Directory to write the demo into (created if missing). ' +
+                        'Relative paths resolve against the project root.',
+                },
+                providerId: {
+                    type: 'string',
+                    description: 'Provider id the demo requests a proof for (default ' +
+                        '"example", a built-in smoke-test provider — good for ' +
+                        'confirming the flow works before wiring in a real one).',
+                },
+                providerVersion: {
+                    type: 'string',
+                    description: 'Provider version to pin (default: unpinned — "example" ' +
+                        'isn\'t versioned, so only set this once you swap in your ' +
+                        'own provider).',
+                },
+            },
+            required: ['targetDir'],
+        },
+    }, async ({ targetDir, providerId, providerVersion }) => {
+        const dir = isAbsolute(targetDir)
+            ? targetDir
+            : join(findProjectRoot(process.cwd()), targetDir);
+        mkdirSync(dir, { recursive: true });
+        const id = providerId ?? DEFAULT_PROVIDER_ID;
+        writeFileSync(join(dir, 'server.js'), serverJs(id, providerVersion));
+        writeFileSync(join(dir, 'package.json'), readSample('package.json'));
+        writeFileSync(join(dir, '.env.example'), readSample('.env.example'));
+        writeFileSync(join(dir, 'README.md'), readSample('README.md'));
+        return {
+            dir,
+            providerId: id,
+            files: ['server.js', 'package.json', '.env.example', 'README.md'],
+            next: 'cd into the directory, npm install, copy .env.example to .env ' +
+                'and fill it in (including PUBLIC_URL from ngrok), then npm start.',
+        };
+    });
+}

package/lib/old/tools/verify-sdk-setup.d.ts

@@ -0,0 +1,9 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+import type { ReclaimOldClient } from '../client.ts';
+/**
+ * Health-check a project's @reclaimprotocol/js-sdk setup: SDK installed,
+ * RECLAIM_APP_ID/RECLAIM_APP_SECRET present (env or .env), and (if an appId
+ * is found) whether that app is actually linked/has quota, via the real
+ * check_app_status endpoint — not just static file checks.
+ */
+export declare function verifySdkSetupTool(client: ReclaimOldClient): RegisteredTool;