@fidesbuild/mcp-server 0.0.0-stage → 0.4.1

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @fidesbuild/mcp-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+FIDES for Claude, and for any other MCP app. You sign a FIDES once, with a budget, the contracts the agent may call and an expiry. Then you ask Claude in plain words, for example "pay 1 USDG to 0x…". Claude plans the actions through FIDES, shows you what is inside the FIDES and what is blocked, and executes only when you say so. Anything outside the FIDES is never sent.
+
+- Funds move from your FIDES Account, never from your wallet.
+- The agent key this server makes holds no funds. It can only sign actions inside the FIDES you signed for it.
+- Gas is paid by the hosted FIDES relayer, so the agent key needs no ETH.
+
+## Set up
+
+1. **Add FIDES to Claude.**
+
+   Claude Desktop: download [the FIDES extension](https://fidesbuilder.xyz/downloads/fides.mcpb), double-click it and click Install.
+
+   Claude Code, in a terminal, on Windows:
+
+   ```bash
+   claude mcp add fides -- cmd /c npx -y @fidesbuild/mcp-server@latest
+   ```
+
+   On macOS or Linux:
+
+   ```bash
+   claude mcp add fides -- npx -y @fidesbuild/mcp-server@latest
+   ```
+
+2. **In Claude, say "Set up FIDES".** Claude gives you a link to the FIDES app with its agent address filled in.
+
+3. **Open the link,** set the budget, the contracts and the expiry, sign, then create and fund your FIDES Account.
+
+4. **Ask Claude for what you want.** It picks up the signed FIDES by itself; there is nothing to download.
+
+Claude Code and other MCP apps need [Node](https://nodejs.org) 20.10 or later. Claude Desktop has its own.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `fides_setup` | A link to the FIDES app with this agent filled in |
+| `fides_status` | The FIDES: active or not, budget spent and remaining, FIDES Account balance, allowed contracts, expiry, agent address |
+| `fides_plan` | Builds transfers and contract calls into one plan, checks each against the FIDES, groups them, simulates. Sends nothing |
+| `fides_execute` | Executes a plan by its id. Only the actions inside the FIDES are sent |
+| `fides_pay_request` | Buys from a paid API over x402: checks the price against the service's cap in the FIDES, pays from the FIDES, returns the response |
+| `fides_receipts` | Every transaction executed under the FIDES, with explorer links |
+| `fides_help` | What you can do with FIDES, the paid APIs known to work with their prices, and what to try |
+| `fides_use_file` | Loads a `fides.json` file, for a FIDES that was not signed in the app |
+
+The FIDES used is the newest valid one signed for this agent: from the FIDES API, where the app shares a FIDES when it is signed, or from the copy kept in `~/.fides`. Each is verified onchain before it is used.
+
+## Paid APIs
+
+Claude can buy from APIs that charge per request over x402, from your FIDES. Each paid service is named in the FIDES with a cap; anything not named, or past its cap, is refused before paying. To try it, ask Claude: "Set up FIDES with the fides-demo paid service, up to 0.1 USDG", sign, then "Buy the chain stats from the FIDES demo" (0.01 USDG for Robinhood Chain's latest block, gas price and USDG supply).
+
+Paid APIs known to work, each bought through FIDES with real payments on mainnet:
+
+| Service id | URL | Price |
+| --- | --- | --- |
+| `fides-demo` | `https://api.fidesbuilder.xyz/v1/demo/chain-stats` | 0.01 USDG |
+| `spraay` | `https://gateway.spraay.app/api/v1/models` | 0.001 USDG |
+| `madeonsol` | `https://madeonsol.com/api/x402/rhc/kol/feed?limit=5` | 0.04 USDG |
+
+Any API that charges USDG on Robinhood Chain over x402 (`exact`, EIP-3009) works the same way. The service id is any name you choose when you sign. Ask Claude "What can you do with FIDES?" to get this list in the chat.
+
+## Other MCP apps
+
+Add a server with the command `npx` and the arguments `-y @fidesbuild/mcp-server@latest` (on Windows, the command `cmd` and the arguments `/c npx -y @fidesbuild/mcp-server@latest`). `npx -y @fidesbuild/mcp-server setup` makes the agent key and prints the setup link from a terminal.
+
+## Settings
+
+All optional, set in the environment of the server.
+
+| Variable | Default |
+| --- | --- |
+| `FIDES_HOME` | `~/.fides`, where `agent.json` and the FIDES in use are kept |
+| `FIDES_FILE` | `~/.fides/fides.json` |
+| `FIDES_RPC` | `https://rpc.mainnet.chain.robinhood.com` |
+| `FIDES_API` | `https://api.fidesbuilder.xyz`: the relayer that pays gas, and where signed FIDES are looked up |
+| `FIDES_APP` | `https://fidesbuilder.xyz/app`, for the setup link |
+| `FIDES_RELAY` | Set to `self` to have the agent key pay gas itself (give it a little ETH) |
+| `FIDES_LOOKUP` | Set to `off` to use only the FIDES kept in `FIDES_FILE` |
+| `FIDES_AGENT_KEY` | Use this private key instead of `~/.fides/agent.json` |
+
+The hosted relayer has a daily gas budget shared by everyone. If it runs out, `fides_execute` says so; use `FIDES_RELAY=self` or try later.
+
+Docs: [fidesbuilder.xyz/docs](https://fidesbuilder.xyz/docs#/claude)

package/dist/server.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Hex } from 'viem';
+import { type PrivateKeyAccount } from 'viem/accounts';
+import { type FidesAddresses } from '@fidesbuild/sdk';
+export type Config = {
+    /** Folder for agent.json and the default fides.json. */
+    home: string;
+    rpc: string;
+    chainId: number;
+    /** The relaying API, or null to have the agent key pay gas itself. */
+    api: string | null;
+    /** The FIDES API, asked for the FIDES signed for this agent. Null to only use fidesFile. */
+    directory: string | null;
+    /** The FIDES app, for the setup link. */
+    app: string;
+    fidesFile: string;
+    addresses?: FidesAddresses;
+    agentKey?: Hex;
+};
+export declare function configFromEnv(env?: NodeJS.ProcessEnv): Config;
+/** This computer's agent key: from FIDES_AGENT_KEY, or ~/.fides/agent.json, made on first use. */
+export declare function agentKey(cfg: Config): {
+    account: PrivateKeyAccount;
+    file: string | null;
+    created: boolean;
+};
+export declare function createFidesMcpServer(cfg: Config): McpServer & {
+    agent: `0x${string}`;
+};

package/dist/server.js

@@ -0,0 +1,591 @@
+#!/usr/bin/env node
+// fides-mcp — FIDES as tools for Claude and any other MCP client.
+//
+//   npx -y @fidesbuild/mcp-server setup     make this computer's agent key and print what to do next
+//   npx -y @fidesbuild/mcp-server           run the MCP server over stdio (what Claude starts)
+//
+// The agent key lives in ~/.fides/agent.json and holds no funds. It can only sign actions inside the
+// FIDES the owner signed for it. Bundles are relayed by the hosted FIDES API, which pays the gas,
+// unless FIDES_RELAY=self, in which case the agent key pays.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { encodeFunctionData, erc20Abi, formatUnits, parseUnits, isAddress, getAddress } from 'viem';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+import { Fides, FidesBuilder, Policy, Receipts, createFidesClient, fromJson, toJson } from '@fidesbuild/sdk';
+import { createX402, decodePaymentRequired, exactEip3009 } from '@fidesbuild/x402';
+export function configFromEnv(env = process.env) {
+    const home = env.FIDES_HOME ?? path.join(os.homedir(), '.fides');
+    return {
+        home,
+        rpc: env.FIDES_RPC ?? 'https://rpc.mainnet.chain.robinhood.com',
+        chainId: Number(env.FIDES_CHAIN_ID ?? 4663),
+        api: env.FIDES_RELAY === 'self' ? null : (env.FIDES_API ?? 'https://api.fidesbuilder.xyz').replace(/\/$/, ''),
+        directory: env.FIDES_LOOKUP === 'off' ? null : (env.FIDES_API ?? 'https://api.fidesbuilder.xyz').replace(/\/$/, ''),
+        app: (env.FIDES_APP ?? 'https://fidesbuilder.xyz/app').replace(/\/$/, ''),
+        fidesFile: env.FIDES_FILE ?? path.join(home, 'fides.json'),
+        addresses: env.FIDES_ADDRESSES ? JSON.parse(fs.readFileSync(env.FIDES_ADDRESSES, 'utf8')) : undefined,
+        agentKey: env.FIDES_AGENT_KEY,
+    };
+}
+/** This computer's agent key: from FIDES_AGENT_KEY, or ~/.fides/agent.json, made on first use. */
+export function agentKey(cfg) {
+    if (cfg.agentKey)
+        return { account: privateKeyToAccount(cfg.agentKey), file: null, created: false };
+    const file = path.join(cfg.home, 'agent.json');
+    if (fs.existsSync(file))
+        return { account: privateKeyToAccount(JSON.parse(fs.readFileSync(file, 'utf8')).privateKey), file, created: false };
+    fs.mkdirSync(cfg.home, { recursive: true, mode: 0o700 });
+    const privateKey = generatePrivateKey();
+    const account = privateKeyToAccount(privateKey);
+    fs.writeFileSync(file, JSON.stringify({ address: account.address, privateKey, note: 'FIDES agent key. It holds no funds and can only act inside the FIDES signed for it. Keep this file private.' }, null, 2) + '\n', { mode: 0o600 });
+    return { account, file, created: true };
+}
+const EXPLORER = { 4663: 'https://robinhoodchain.blockscout.com' };
+const SELECTORS = { '0xa9059cbb': 'transfer', '0x095ea7b3': 'approve', '0x23b872dd': 'transferFrom' };
+const REASONS = {
+    SPEND_LIMIT_EXCEEDED: 'over the FIDES’s budget', ASSET_NOT_ALLOWED: 'token not allowed by the FIDES', TARGET_NOT_ALLOWED: 'contract not allowed by the FIDES',
+    SELECTOR_NOT_ALLOWED: 'function not allowed by the FIDES', NATIVE_VALUE_EXCEEDED: 'sends more ETH than the FIDES allows', ACTION_LIMIT_EXCEEDED: 'over the FIDES’s action limit',
+    FIDES_EXPIRED: 'the FIDES has expired', FIDES_REVOKED: 'the FIDES has been revoked', DEPENDENCY_REJECTED: 'depends on a blocked action',
+};
+/** Simulation and relay failures, in words. */
+function failure(reason) {
+    const r = String(reason ?? '');
+    if (/InsufficientBalance|InsufficientFunds|0x356680b7|exceeds balance/i.test(r))
+        return 'The FIDES Account does not hold enough of the token. The owner needs to fund it.';
+    if (/SpendLimitExceeded|AssetOutflowExceeded/.test(r))
+        return 'This would go over the FIDES’s budget, counting what it has already spent.';
+    if (/TargetNotAllowed|SelectorNotAllowed/.test(r))
+        return 'This calls a contract or function the FIDES does not allow.';
+    if (/FidesRevoked/.test(r))
+        return 'The FIDES has been revoked.';
+    if (/FidesExpired|FidesNotYetValid/.test(r))
+        return 'The FIDES is outside its valid time window.';
+    if (/NonceAlreadyUsed/.test(r))
+        return 'This plan was already executed. Make a new plan.';
+    if (/RELAYER_BUDGET_EXHAUSTED|RELAYER_OUT_OF_GAS_MONEY|NO_RELAYER/.test(r))
+        return 'The hosted relayer cannot pay for gas right now. Try later, or set FIDES_RELAY=self and give the agent address a little ETH.';
+    return r;
+}
+// Paid APIs that have been bought through FIDES with real payments on mainnet (the docs list the same ones).
+const KNOWN_SERVICES = [
+    { id: 'fides-demo', name: 'FIDES demo', url: 'https://api.fidesbuilder.xyz/v1/demo/chain-stats', price: '0.01 USDG', returns: 'Robinhood Chain\'s latest block, gas price and USDG supply', run_by: 'FIDES' },
+    { id: 'spraay', name: 'Spraay', url: 'https://gateway.spraay.app/api/v1/models', price: '0.001 USDG', returns: 'The AI models the Spraay gateway offers, with providers and prices', run_by: 'Spraay, not FIDES' },
+    { id: 'madeonsol', name: 'MadeOnSol', url: 'https://madeonsol.com/api/x402/rhc/kol/feed?limit=5', price: '0.04 USDG', returns: 'Recent trades on Robinhood Chain by tracked wallets', run_by: 'MadeOnSol, not FIDES' },
+];
+const ok = (value) => ({ content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] });
+const fail = (message) => ({ content: [{ type: 'text', text: message }], isError: true });
+export function createFidesMcpServer(cfg) {
+    const agent = agentKey(cfg).account;
+    const client = createFidesClient({ chainId: cfg.chainId, rpc: cfg.rpc, addresses: cfg.addresses });
+    const explorer = EXPLORER[cfg.chainId];
+    const txLink = (h) => (h && explorer ? `${explorer}/tx/${h}` : h);
+    const plans = new Map();
+    const tokens = new Map();
+    const token = async (asset) => {
+        const key = asset.toLowerCase();
+        if (!tokens.has(key)) {
+            const [symbol, decimals] = await Promise.all([
+                client.public.readContract({ address: asset, abi: erc20Abi, functionName: 'symbol' }).catch(() => 'TOKEN'),
+                client.public.readContract({ address: asset, abi: erc20Abi, functionName: 'decimals' }).catch(() => 18),
+            ]);
+            tokens.set(key, { symbol: String(symbol), decimals: Number(decimals) });
+        }
+        return tokens.get(key);
+    };
+    const setupLink = `${cfg.app}/#/create?agent=${agent.address}&via=claude`;
+    const notLoaded = () => `No FIDES is signed for this agent yet. This computer's agent address is ${agent.address}.\n\n` +
+        `To set one up, the user opens this link: ${setupLink}\n` +
+        'It opens the FIDES app with this agent filled in. They set the budget, contracts and expiry, sign with their wallet, then create and fund their FIDES Account. ' +
+        'Then they come back here: the signed FIDES is picked up automatically, with nothing to download.';
+    function readFides() {
+        if (!fs.existsSync(cfg.fidesFile))
+            return null;
+        return fromJson(fs.readFileSync(cfg.fidesFile, 'utf8'));
+    }
+    const keep = (fides) => { fs.mkdirSync(path.dirname(cfg.fidesFile), { recursive: true }); fs.writeFileSync(cfg.fidesFile, toJson(fides, 2) + '\n'); };
+    // The FIDES to act under: the newest valid one signed for this agent, from the copy kept here or from
+    // the FIDES API, where the app registers a FIDES when the owner signs it. Each is verified onchain here.
+    async function currentFides() {
+        const mine = (o) => Boolean(o && String(o.agent).toLowerCase() === agent.address.toLowerCase() && Number(o.chainId) === cfg.chainId);
+        const local = readFides();
+        const candidates = mine(local) ? [local] : [];
+        if (cfg.directory) {
+            try {
+                const res = await fetch(`${cfg.directory}/v1/agents/${agent.address}/fides`);
+                if (res.ok)
+                    for (const x of fromJson(await res.text()).fidesList ?? [])
+                        if (mine(x.fides) && x.status?.valid)
+                            candidates.push(x.fides);
+            }
+            catch { /* the API is optional: the copy kept here still works */ }
+        }
+        const valid = [];
+        for (const o of candidates)
+            if ((await Fides.verify(client, o).catch(() => null))?.valid)
+                valid.push(o);
+        valid.sort((a, b) => Number(BigInt(b.validAfter) - BigInt(a.validAfter)));
+        const best = valid[0];
+        if (best && (!local || local.id !== best.id)) {
+            keep(best);
+            plans.clear();
+        }
+        return best ?? local;
+    }
+    async function summary(fides) {
+        const t = await token(fides.spendLimits[0].asset);
+        const [check, [spend], balance, code] = await Promise.all([
+            Fides.verify(client, fides),
+            Policy.remainingSpend(client, fides),
+            client.public.readContract({ address: fides.spendLimits[0].asset, abi: erc20Abi, functionName: 'balanceOf', args: [fides.account] }),
+            client.public.getCode({ address: fides.account }),
+        ]);
+        const amount = (v) => `${formatUnits(v, t.decimals)} ${t.symbol}`;
+        const outside = await stray(fides.spendLimits[0].asset);
+        const status = check.revoked ? 'revoked' : check.expired ? 'expired' : check.notYetValid ? 'not valid yet' : !check.validSignature || !check.idMatches ? 'signature does not verify' : 'active';
+        return {
+            status,
+            fides: fides.id,
+            owner: fides.owner,
+            agent: fides.agent,
+            fides_account: fides.account,
+            fides_account_created: Boolean(code),
+            fides_account_balance: amount(balance),
+            budget: amount(spend.limit),
+            spent: amount(spend.spent),
+            remaining: amount(spend.remaining),
+            budget_token: fides.spendLimits[0].asset,
+            expires: new Date(Number(fides.validUntil) * 1000).toISOString(),
+            allowed_contracts: fides.targets.map((r) => ({ contract: r.target, functions: r.selectors.map((s) => SELECTORS[s.toLowerCase()] ? `${SELECTORS[s.toLowerCase()]} (${s})` : s) })),
+            allowed_services: fides.services.map((s) => s.serviceId),
+            max_actions: fides.maxActions.toString(),
+            relay: cfg.api ? `hosted relayer at ${cfg.api} pays the gas` : `the agent key ${agent.address} pays the gas`,
+            ...(outside > 0n ? { warning: `${amount(outside)} sits on the agent key ${agent.address} outside the FIDES: it was sent to the agent address directly instead of to the FIDES Account. FIDES never spends it. To get it back, the owner can import the agent key from ${path.join(cfg.home, 'agent.json')} into a wallet on this computer, add a little ETH for gas, and send it to themselves. Funds for the agent always go to the FIDES Account address.` } : {}),
+        };
+    }
+    const server = new McpServer({ name: 'fides', version: '0.4.1' }, {
+        instructions: 'FIDES lets you act with the owner\'s funds only inside limits the owner signed (a FIDES): a budget, allowed contracts and functions, paid services, and an expiry. ' +
+            'Funds move from the owner\'s FIDES Account, never from the owner\'s wallet. If no FIDES is set up yet, call fides_setup and give the user the link. Always call fides_plan first and show the user what is inside the FIDES, what is blocked and why, ' +
+            'and ask before calling fides_execute. Actions outside the FIDES are blocked before anything is sent. Amounts are in whole token units, like "1.5". ' +
+            'When the user asks what you can do with FIDES, which paid APIs or services there are, or how to start, call fides_help and answer from it: give the paid APIs by name with their price and suggest a next step. ' +
+            'A paid service\'s id is a name the user chooses when signing, like "spraay"; nobody issues it. Any API that charges USDG on Robinhood Chain over x402 (exact, EIP-3009) works, not only the ones fides_help lists.',
+    });
+    server.registerTool('fides_help', {
+        title: 'What FIDES can do',
+        description: 'Use when the user asks what you can do with FIDES, what paid APIs or services are available, what to try, or how to get started. Returns what FIDES can do, paid APIs known to work with their URL and price, example requests, and the next step for this user.',
+        inputSchema: {},
+    }, async () => {
+        let fides = null;
+        try {
+            fides = await currentFides();
+        }
+        catch { /* answer without it */ }
+        const allowed = fides?.services.map((s) => s.serviceId) ?? [];
+        return ok({
+            can_do: [
+                'Send USDG from the FIDES Account, to one address or many, inside the budget. Several transfers go out as one transaction.',
+                'Call contracts the FIDES allows, with the functions it allows.',
+                'Buy from paid APIs that charge per request over x402, paying from the FIDES budget, each capped per service.',
+                'Show the budget spent and left, what is allowed, the expiry, and every transaction executed, with explorer links.',
+                'Everything is planned and simulated first, and shown to the user before anything is sent. Anything outside the FIDES is blocked. The hosted relayer pays the gas.',
+            ],
+            paid_apis: KNOWN_SERVICES.map((s) => ({ ...s, in_this_fides: allowed.includes(s.id) })),
+            other_paid_apis: 'Any API that charges USDG on Robinhood Chain over x402 (exact scheme, EIP-3009) works the same way. The user adds it as a service with a cap when signing (the id is any name they choose), then gives you its URL.',
+            try_saying: [
+                'Set up FIDES with these paid services: fides-demo up to 0.1 USDG, spraay up to 0.01 USDG, madeonsol up to 0.1 USDG',
+                'Pay 0.5 USDG to 0x... and 0.5 USDG to 0x...',
+                'Buy the chain stats from the FIDES demo',
+                'What\'s left in my FIDES?',
+                'Show what you\'ve executed',
+            ],
+            next_step: !fides ? 'No FIDES is set up yet. Offer to call fides_setup, with any paid services the user wants and a cap for each.'
+                : !allowed.length ? 'This FIDES has no paid services. To use a paid API, call fides_setup with the services and caps, and the user signs the new FIDES.'
+                    : `This FIDES allows these paid services: ${allowed.join(', ')}. Make sure the FIDES Account holds USDG (fides_status shows the balance).`,
+            docs: 'https://fidesbuilder.xyz/docs#/claude',
+        });
+    });
+    server.registerTool('fides_status', {
+        title: 'FIDES status',
+        description: 'The loaded FIDES: whether it is active, the budget spent and remaining, the FIDES Account balance, the allowed contracts and the expiry. Also gives this computer\'s agent address: use it when the user asks for their FIDES agent address. With no FIDES loaded, explains how to set one up.',
+        inputSchema: {},
+    }, async () => {
+        try {
+            const fides = await currentFides();
+            if (!fides)
+                return ok(notLoaded());
+            if (fides.agent.toLowerCase() !== agent.address.toLowerCase())
+                return fail(`The loaded FIDES is for agent ${fides.agent}, but this computer's agent key is ${agent.address}. Create a FIDES for ${agent.address}.`);
+            return ok(await summary(fides));
+        }
+        catch (err) {
+            return fail('Could not read the FIDES: ' + (err?.shortMessage ?? err?.message ?? err));
+        }
+    });
+    server.registerTool('fides_setup', {
+        title: 'Set up FIDES',
+        description: 'Use when the user wants to set up FIDES, connect their wallet or sign a new FIDES. Returns this computer\'s agent address and a link to the FIDES app with it filled in, where the user sets the limits and signs. The signed FIDES is then picked up automatically. To let the user buy from paid APIs (fides_pay_request), pass the services with a spending cap each. Paid APIs known to work use the ids "fides-demo", "spraay" and "madeonsol" (fides_help has their URLs and prices); for any other x402 API, the id is any name the user chooses.',
+        inputSchema: { services: z.array(z.object({ id: z.string().describe('A name for the paid service, chosen by the user, e.g. "fides-demo" or "spraay"'), max: z.string().describe('Most the agent may spend on it, in USDG, e.g. "0.1"') })).optional() },
+    }, async ({ services }) => ok({
+        agent_address: agent.address,
+        link: setupLink + (services ?? []).map((x) => `&service=${encodeURIComponent(x.id)}:${encodeURIComponent(x.max)}`).join(''),
+        services: services?.length ? services.map((x) => `${x.id}: up to ${x.max} USDG`) : undefined,
+        steps: [
+            'Open the link. It opens the FIDES app with this agent already filled in.',
+            'Connect your wallet. Set the budget, the contracts allowed and the expiry. Start small.',
+            'Sign (free), click Create FIDES Account (a little gas), and send the budget to the FIDES Account address shown.',
+            'Come back and ask me for what you want. I pick up the signed FIDES by myself.',
+        ],
+    }));
+    server.registerTool('fides_use_file', {
+        title: 'Use a FIDES file',
+        description: 'Only needed if the user has a fides.json file: loads a signed FIDES from a path on this computer, checks that it is for this computer\'s agent key, and keeps a copy. FIDES signed in the app are picked up without this.',
+        inputSchema: { path: z.string().describe('Full path to the fides.json file, e.g. C:\\Users\\me\\Downloads\\fides.json') },
+    }, async ({ path: file }) => {
+        try {
+            const full = file.replace(/^~(?=$|[\\/])/, os.homedir());
+            if (!fs.existsSync(full))
+                return fail(`No file at ${full}.`);
+            let fides;
+            try {
+                fides = fromJson(fs.readFileSync(full, 'utf8'));
+            }
+            catch {
+                return fail(`${full} is not valid JSON.`);
+            }
+            if (!fides || !fides.id || !fides.signature || !fides.agent || !Array.isArray(fides.spendLimits))
+                return fail('That file is not a signed FIDES. In the FIDES app, open the FIDES and click "Download signed FIDES".');
+            if (fides.agent.toLowerCase() !== agent.address.toLowerCase())
+                return fail(`That FIDES is for agent ${fides.agent}, but this computer's agent key is ${agent.address}. Create a new FIDES in the app with "An external agent" and paste ${agent.address}.`);
+            if (Number(fides.chainId) !== cfg.chainId)
+                return fail(`That FIDES is for chain ${fides.chainId}; this server is set up for chain ${cfg.chainId}.`);
+            keep(fides);
+            plans.clear();
+            return ok({ loaded: cfg.fidesFile, ...(await summary(fides)) });
+        }
+        catch (err) {
+            return fail('Could not load the FIDES: ' + (err?.shortMessage ?? err?.message ?? err));
+        }
+    });
+    const actionSchema = z.object({
+        kind: z.enum(['transfer', 'call']).describe('"transfer" sends a token from the FIDES Account. "call" calls an allowed contract with raw calldata.'),
+        to: z.string().optional().describe('transfer: the recipient address'),
+        amount: z.string().optional().describe('transfer: how much, in whole token units, e.g. "1.5". call: how much of the budget token the call spends, if any'),
+        token: z.string().optional().describe('transfer: the token address. Defaults to the FIDES\'s budget token'),
+        target: z.string().optional().describe('call: the contract address'),
+        data: z.string().optional().describe('call: hex calldata, starting with the 4-byte function selector'),
+        label: z.string().optional().describe('A short description shown in the plan'),
+    });
+    server.registerTool('fides_plan', {
+        title: 'Plan actions under the FIDES',
+        description: 'Builds the actions into one execution plan: checks every action against the FIDES, groups what can go out together, and simulates it against the chain. Sends nothing. Returns a plan_id for fides_execute. Show the result to the user before executing.',
+        inputSchema: { actions: z.array(actionSchema).min(1).max(50) },
+    }, async ({ actions }) => {
+        try {
+            const fides = await currentFides();
+            if (!fides)
+                return fail(notLoaded());
+            if (fides.agent.toLowerCase() !== agent.address.toLowerCase())
+                return fail(`The loaded FIDES is for agent ${fides.agent}, not this computer's agent key ${agent.address}.`);
+            const budget = fides.spendLimits[0].asset;
+            const built = [];
+            for (const [i, a] of actions.entries()) {
+                const n = i + 1;
+                if (a.kind === 'transfer') {
+                    if (!a.to || !isAddress(a.to))
+                        return fail(`Action ${n}: "to" must be an address.`);
+                    const asset = a.token ? (isAddress(a.token) ? getAddress(a.token) : null) : budget;
+                    if (!asset)
+                        return fail(`Action ${n}: "token" must be an address.`);
+                    const t = await token(asset);
+                    let amount;
+                    try {
+                        amount = parseUnits(String(a.amount ?? ''), t.decimals);
+                    }
+                    catch {
+                        return fail(`Action ${n}: "amount" must be a number of ${t.symbol}, like "1.5".`);
+                    }
+                    if (amount <= 0n)
+                        return fail(`Action ${n}: "amount" must be more than zero.`);
+                    built.push({ id: `a${n}`, type: 'TOKEN_TRANSFER', label: a.label ?? `send ${formatUnits(amount, t.decimals)} ${t.symbol} to ${getAddress(a.to)}`, target: asset, spend: { asset, amount },
+                        payload: encodeFunctionData({ abi: erc20Abi, functionName: 'transfer', args: [getAddress(a.to), amount] }) });
+                }
+                else {
+                    if (!a.target || !isAddress(a.target))
+                        return fail(`Action ${n}: "target" must be a contract address.`);
+                    if (!a.data || !/^0x([0-9a-fA-F]{2}){4,}$/.test(a.data))
+                        return fail(`Action ${n}: "data" must be hex calldata starting with the 4-byte selector.`);
+                    const t = await token(budget);
+                    let spend = 0n;
+                    if (a.amount) {
+                        try {
+                            spend = parseUnits(a.amount, t.decimals);
+                        }
+                        catch {
+                            return fail(`Action ${n}: "amount" must be a number of ${t.symbol}.`);
+                        }
+                    }
+                    built.push({ id: `a${n}`, type: 'CONTRACT_WRITE', label: a.label ?? `call ${a.data.slice(0, 10)} on ${getAddress(a.target)}`, target: getAddress(a.target), payload: a.data,
+                        ...(spend > 0n ? { spend: { asset: budget, amount: spend } } : {}) });
+                }
+            }
+            const plan = await new FidesBuilder({ client, fides, agent }).add(built).build();
+            const savings = plan.estimatedSavings();
+            const simulations = savings.estimatedTransactions ? await plan.simulate() : [];
+            const failed = simulations.filter((s) => !s.success);
+            const id = plan.planHash.slice(0, 18);
+            if (savings.estimatedTransactions && !failed.length)
+                plans.set(id, { plan, actions: built, fides });
+            return ok({
+                plan_id: savings.estimatedTransactions && !failed.length ? id : null,
+                ready_to_execute: Boolean(savings.estimatedTransactions && !failed.length),
+                actions: plan.actions().map((a) => ({ action: a.label, decision: a.decision === 'AUTHORIZED' ? 'inside the FIDES' : a.decision === 'REJECTED' ? `blocked: ${REASONS[a.reason ?? ''] ?? a.reason} (${a.reason})` : 'duplicate, sent once' })),
+                transactions: `${savings.baselineTransactions} onchain write(s) go out as ${savings.estimatedTransactions} transaction(s)`,
+                simulation: !simulations.length ? 'nothing to execute: no action is inside the FIDES' : failed.length ? `would fail: ${failure(failed[0].revertReason)}` : 'simulated against the chain: it would succeed',
+                sent: 'nothing has been sent',
+            });
+        }
+        catch (err) {
+            return fail('Could not build the plan: ' + (err?.shortMessage ?? err?.message ?? err));
+        }
+    });
+    async function post(route, body) {
+        const res = await fetch(cfg.api + route, { method: 'POST', headers: { 'content-type': 'application/json' }, body: toJson(body) });
+        const json = fromJson(await res.text());
+        if (!res.ok || json?.error)
+            throw new Error(json?.error?.code ? `${json.error.code}: ${json.error.message}` : `HTTP ${res.status}`);
+        return json;
+    }
+    /** Sends a plan's bundles: through the hosted relayer, or paid by the agent key with FIDES_RELAY=self. */
+    async function send(plan, actions, fides) {
+        if (!cfg.api)
+            return (await plan.execute()).bundles;
+        const stored = await post('/v1/plans/build', { fides, actions });
+        if (stored.planHash !== plan.planHash)
+            throw new Error('The relayer built a different plan from the same actions, so nothing was sent.');
+        return (await post(`/v1/plans/${plan.planHash}/execute`, { bundles: await plan.signedBundles() })).bundles;
+    }
+    // What each paid service has cost so far, while this server runs. The onchain limit is the budget;
+    // the per-service caps are checked here, before anything is signed.
+    const servicePaid = new Map();
+    // The float: what this tool moved to the agent key through a FIDES and has not spent yet, by FIDES and
+    // token. Kept on disk so a restart does not forget it. Only this is ever used to pay; anything else on
+    // the agent key (someone sent it there directly) did not pass through the FIDES, so it is left alone.
+    const floatFile = path.join(cfg.home, 'float.json');
+    const floats = () => { try {
+        return JSON.parse(fs.readFileSync(floatFile, 'utf8'));
+    }
+    catch {
+        return {};
+    } };
+    const floatKey = (fides, asset) => `${fides.id}:${asset.toLowerCase()}`;
+    const floatOf = (fides, asset) => BigInt(floats()[floatKey(fides, asset)] ?? '0');
+    const setFloat = (fides, asset, v) => { const m = floats(); m[floatKey(fides, asset)] = (v > 0n ? v : 0n).toString(); fs.mkdirSync(cfg.home, { recursive: true }); fs.writeFileSync(floatFile, JSON.stringify(m, null, 2)); };
+    /** What sits on the agent key that did not come through any FIDES by this tool. */
+    const stray = async (asset) => {
+        const held = await client.public.readContract({ address: asset, abi: erc20Abi, functionName: 'balanceOf', args: [agent.address] });
+        const ours = Object.entries(floats()).filter(([k]) => k.endsWith(':' + asset.toLowerCase())).reduce((n, [, v]) => n + BigInt(v), 0n);
+        return held > ours ? held - ours : 0n;
+    };
+    server.registerTool('fides_pay_request', {
+        title: 'Buy from a paid API',
+        description: `Fetches a URL from a paid API that charges per request over x402, paying from the FIDES budget. Reads the price first and refuses if it is over the service\'s cap in the FIDES or over max_price. Moves exactly the price from the FIDES Account to the agent key, pays, and returns the response. The service must be in the FIDES (its services list). Known URLs: ${KNOWN_SERVICES.map((s) => `"${s.id}" ${s.url}`).join(', ')}. Tell the user the price and get their OK before paying unless they already asked you to buy it.`,
+        inputSchema: {
+            url: z.string().describe('The paid API URL'),
+            service: z.string().optional().describe('The service id in the FIDES. Can be left out if the FIDES has exactly one service'),
+            max_price: z.string().optional().describe('Refuse if the price is above this, in USDG'),
+        },
+    }, async ({ url, service, max_price }) => {
+        try {
+            const fides = await currentFides();
+            if (!fides)
+                return fail(notLoaded());
+            if (!fides.services.length)
+                return fail(`This FIDES allows no paid services. To buy from a paid API, the user signs a new FIDES that includes one: call fides_setup with services, for example [{ id: "fides-demo", max: "0.1" }].`);
+            const id = service ?? (fides.services.length === 1 ? fides.services[0].serviceId : undefined);
+            if (!id)
+                return fail(`Say which service this is. The FIDES allows: ${fides.services.map((x) => x.serviceId).join(', ')}.`);
+            const rule = fides.services.find((x) => x.serviceId === id);
+            if (!rule)
+                return fail(`"${id}" is not a service in this FIDES. It allows: ${fides.services.map((x) => x.serviceId).join(', ')}. Anything else is blocked.`);
+            // 1. the price
+            let first;
+            try {
+                first = await fetch(url);
+            }
+            catch (err) {
+                return fail('Could not reach ' + url + ': ' + (err?.message ?? err));
+            }
+            const header = first.headers.get('PAYMENT-REQUIRED');
+            if (first.status !== 402 || !header) {
+                const text = await first.text();
+                return ok({ paid: 'nothing: this URL did not ask for payment', status: first.status, response: text.slice(0, 4000) });
+            }
+            const required = decodePaymentRequired(header);
+            const offer = required.accepts.find((r) => exactEip3009.supports(r, { fides, payer: agent }) && fides.spendLimits.some((l) => l.asset.toLowerCase() === r.asset.toLowerCase()));
+            if (!offer)
+                return fail('This service asks for a payment FIDES cannot make from this FIDES: it needs the budget token, paid with EIP-3009 on this chain. Nothing was paid.');
+            const t = await token(offer.asset);
+            const price = BigInt(offer.amount);
+            const shown = `${formatUnits(price, t.decimals)} ${t.symbol}`;
+            if (max_price) {
+                let cap;
+                try {
+                    cap = parseUnits(max_price, t.decimals);
+                }
+                catch {
+                    return fail('max_price must be a number, like "0.05".');
+                }
+                if (price > cap)
+                    return fail(`Blocked: the price is ${shown}, over your max of ${max_price}. Nothing was paid.`);
+            }
+            const paidSoFar = servicePaid.get(id) ?? 0n;
+            if (paidSoFar + price > BigInt(rule.maxSpend))
+                return fail(`Blocked: ${shown} would take "${id}" past its cap of ${formatUnits(BigInt(rule.maxSpend), t.decimals)} ${t.symbol} in this FIDES (${formatUnits(paidSoFar, t.decimals)} spent). Nothing was paid.`);
+            // 2. fund the agent key through the FIDES: reuse only float this tool moved there under this FIDES
+            const held = await client.public.readContract({ address: offer.asset, abi: erc20Abi, functionName: 'balanceOf', args: [agent.address] });
+            let float = floatOf(fides, offer.asset);
+            if (float > held)
+                float = held;
+            const x402 = createX402({ fides, payer: agent, serviceId: () => id });
+            let funded;
+            if (float < price) {
+                const actions = [x402.float(offer.asset, price - float, 'pay-float')];
+                const plan = await new FidesBuilder({ client, fides, agent }).add(actions).build();
+                if (plan.rejected().length) {
+                    const r = plan.rejected()[0];
+                    return fail(`Blocked by the FIDES: ${REASONS[r.reason ?? ''] ?? r.reason}. Nothing was paid.`);
+                }
+                const [sim] = await plan.simulate();
+                if (sim && !sim.success)
+                    return fail('Blocked: ' + failure(sim.revertReason) + ' Nothing was paid.');
+                const bundles = await send(plan, actions, fides);
+                if (!bundles.length || bundles.some((b) => b.status !== 'EXECUTED'))
+                    return fail('Could not move the price to the agent key: ' + failure(bundles.find((b) => b.error)?.error) + ' Nothing was paid.');
+                funded = txLink(bundles[0].txHash);
+                float = price;
+                setFloat(fides, offer.asset, float);
+            }
+            // 3. pay and fetch
+            const res = await x402.fetch(url);
+            const body = await res.text();
+            const p = x402.payments[0];
+            // No confirmed payment (a 402, or an error before the service settled): the price moved to the agent
+            // key is still there, recorded as float, and pays for the next request instead of moving it again.
+            if (!p)
+                return fail(`The service did not take the payment (it answered ${res.status}${body ? ': ' + body.slice(0, 200) : ''}), so nothing was paid. ${funded ? 'The price already moved to the agent key stays there and pays for the next attempt, so a retry does not move it again.' : ''}`);
+            if (p) {
+                servicePaid.set(id, paidSoFar + p.amount);
+                setFloat(fides, offer.asset, float - p.amount);
+            }
+            let response = body.slice(0, 4000);
+            try {
+                response = JSON.parse(body);
+            }
+            catch { }
+            const [spend] = await Policy.remainingSpend(client, fides);
+            return ok({
+                paid: p ? shown : 'nothing',
+                service: id,
+                settlement: txLink(p?.settlement?.transaction),
+                moved_to_agent_key: funded,
+                status: res.status,
+                response,
+                budget_remaining: `${formatUnits(spend.remaining, t.decimals)} of ${formatUnits(spend.limit, t.decimals)} ${t.symbol}`,
+            });
+        }
+        catch (err) {
+            return fail('Paid request stopped: ' + failure(err?.shortMessage ?? err?.message ?? err));
+        }
+    });
+    server.registerTool('fides_execute', {
+        title: 'Execute a plan',
+        description: 'Executes a plan made by fides_plan, by its plan_id. Only the actions inside the FIDES are sent; blocked ones never are. Moves real funds from the FIDES Account: confirm with the user first.',
+        inputSchema: { plan_id: z.string() },
+    }, async ({ plan_id }) => {
+        const entry = plans.get(plan_id);
+        if (!entry)
+            return fail('No plan with that id. Make one with fides_plan first (plans are kept until they are executed or the server restarts).');
+        plans.delete(plan_id); // a plan's bundles can be sent once
+        const { plan, actions, fides } = entry;
+        try {
+            const bundles = await send(plan, actions, fides);
+            const [spend] = await Policy.remainingSpend(client, fides);
+            const t = await token(fides.spendLimits[0].asset);
+            const executed = bundles.filter((b) => b.status === 'EXECUTED').length;
+            return ok({
+                result: executed === bundles.length ? 'executed' : executed ? 'partly executed' : 'not executed',
+                transactions: bundles.map((b) => ({ status: b.status.toLowerCase(), transaction: txLink(b.txHash), ...(b.error ? { reason: failure(b.error) } : {}) })),
+                blocked_and_not_sent: plan.rejected().map((a) => `${a.label}: ${REASONS[a.reason ?? ''] ?? a.reason}`),
+                budget_remaining: `${formatUnits(spend.remaining, t.decimals)} of ${formatUnits(spend.limit, t.decimals)} ${t.symbol}`,
+            });
+        }
+        catch (err) {
+            return fail('Execution stopped: ' + failure(err?.shortMessage ?? err?.message ?? err));
+        }
+    });
+    server.registerTool('fides_receipts', {
+        title: 'Executed transactions',
+        description: 'Every bundle executed onchain under the loaded FIDES, with transaction links, and the budget spent.',
+        inputSchema: {},
+    }, async () => {
+        try {
+            const fides = await currentFides();
+            if (!fides)
+                return fail(notLoaded());
+            const [list, [spend], t] = await Promise.all([Receipts.get(client, fides), Policy.remainingSpend(client, fides), token(fides.spendLimits[0].asset)]);
+            return ok({
+                executed: list.map((r) => ({ transaction: txLink(r.txHash), calls_succeeded: r.succeeded, calls_failed: r.failed, block: r.blockNumber.toString() })),
+                spent: `${formatUnits(spend.spent, t.decimals)} of ${formatUnits(spend.limit, t.decimals)} ${t.symbol}`,
+            });
+        }
+        catch (err) {
+            return fail('Could not read receipts: ' + (err?.shortMessage ?? err?.message ?? err));
+        }
+    });
+    return Object.assign(server, { agent: agent.address });
+}
+function setup(cfg) {
+    const { account, file, created } = agentKey(cfg);
+    const win = process.platform === 'win32';
+    const desktop = JSON.stringify({ mcpServers: { fides: win ? { command: 'cmd', args: ['/c', 'npx', '-y', '@fidesbuild/mcp-server@latest'] } : { command: 'npx', args: ['-y', '@fidesbuild/mcp-server@latest'] } } }, null, 2);
+    console.log(`FIDES for Claude
+
+Agent address: ${account.address}
+${file ? `${created ? 'New key saved' : 'Key'} in ${file}. Keep that file private. It holds no funds and can only act inside the FIDES you sign for it.` : 'Key from FIDES_AGENT_KEY.'}
+
+Next:
+1. Open this link. It opens the FIDES app with this agent filled in:
+   ${cfg.app}/#/create?agent=${account.address}&via=claude
+2. Set the budget, contracts and expiry, then sign. Create your FIDES Account and fund it.
+3. Add FIDES to Claude, if you have not yet.
+   Claude Code, in a terminal:
+     claude mcp add fides -- ${win ? 'cmd /c ' : ''}npx -y @fidesbuild/mcp-server@latest
+   Claude Desktop: Settings, Developer, Edit Config, and add:
+${desktop.split('\n').map((l) => '     ' + l).join('\n')}
+   Then restart Claude Desktop.
+4. Ask Claude for what you want. It picks up the signed FIDES by itself.
+`);
+}
+// Run directly, or through the npm bin link (which may be a symlink to this file).
+const entry = (() => { try {
+    return pathToFileURL(fs.realpathSync(process.argv[1] ?? '')).href;
+}
+catch {
+    return '';
+} })();
+if (import.meta.url === entry) {
+    const cfg = configFromEnv();
+    if (process.argv[2] === 'setup')
+        setup(cfg);
+    else if (process.argv[2] === '--help' || process.argv[2] === '-h')
+        console.log('npx -y @fidesbuild/mcp-server setup   make the agent key and print the next steps\nnpx -y @fidesbuild/mcp-server         run the MCP server over stdio\n\nEnvironment: FIDES_HOME, FIDES_FILE, FIDES_RPC, FIDES_CHAIN_ID, FIDES_API, FIDES_APP, FIDES_RELAY=self, FIDES_LOOKUP=off, FIDES_AGENT_KEY, FIDES_ADDRESSES');
+    else {
+        const server = createFidesMcpServer(cfg);
+        await server.connect(new StdioServerTransport());
+        console.error(`fides-mcp running. Agent address ${server.agent}.`);
+    }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@fidesbuild/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.1",
+  "description": "FIDES as tools for Claude and any MCP client: plan and execute actions inside a signed FIDES, gas paid by the hosted relayer.",
+  "keywords": [
+    "fides",
+    "agents",
+    "transaction-builder",
+    "mcp",
+    "claude",
+    "robinhood-chain",
+    "eip-712"
+  ],
+  "homepage": "https://fidesbuilder.xyz/docs",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "bin": {
+    "fides-mcp": "./dist/server.js"
+  },
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
+  ],
+  "engines": {
+    "node": ">=20.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@fidesbuild/sdk": "0.2.0",
+    "viem": "^2.21.0",
+    "zod": "^4.6.5",
+    "@fidesbuild/x402": "0.2.0"
+  }
 }