@fidesbuild/mcp-server 0.4.0 → 0.5.0

package/README.md

@@ -42,7 +42,8 @@ Claude Code and other MCP apps need [Node](https://nodejs.org) 20.10 or later. C
 | `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_use_file` | Loads an `fides.json` file, for a FIDES that was not signed in the app |
+| `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.
 
@@ -50,6 +51,16 @@ The FIDES used is the newest valid one signed for this agent: from the FIDES API
 
 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.

package/dist/server.js

@@ -18,6 +18,7 @@ import { encodeFunctionData, erc20Abi, formatUnits, parseUnits, isAddress, getAd
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
 import { Fides, FidesBuilder, Policy, Receipts, createFidesClient, fromJson, toJson } from '@fidesbuild/sdk';
 import { createX402, decodePaymentRequired, exactEip3009 } from '@fidesbuild/x402';
+import { netObligations, settle, netRoots, PUBLISH_SELECTOR, NetError } from '@fidesbuild/net';
 export function configFromEnv(env = process.env) {
     const home = env.FIDES_HOME ?? path.join(os.homedir(), '.fides');
     return {
@@ -71,6 +72,12 @@ function failure(reason) {
         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) {
@@ -161,10 +168,47 @@ export function createFidesMcpServer(cfg) {
             ...(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.0' }, {
-        instructions: 'FIDES lets you act with the owner\'s funds only inside limits the owner signed (a FIDES): a budget, allowed contracts and functions, and an expiry. ' +
+    const server = new McpServer({ name: 'fides', version: '0.5.0' }, {
+        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".',
+            '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. ' +
+            'When the user has many payments owed between their agent and services (or other parties), fides_net nets them to final positions and builds the FIDES Account\'s side of the settlement, plus the publication of the round\'s roots onchain, into one plan for fides_execute.',
+    });
+    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',
@@ -185,11 +229,14 @@ export function createFidesMcpServer(cfg) {
     });
     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; for FIDES\'s own paid demo use id "fides-demo".',
-        inputSchema: { services: z.array(z.object({ id: z.string().describe('A name for the paid service, e.g. "fides-demo"'), max: z.string().describe('Most the agent may spend on it, in USDG, e.g. "0.1"') })).optional() },
-    }, async ({ services }) => ok({
+        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(),
+            net: z.boolean().optional().describe('true to allow FIDES NET: lets the FIDES publish netting roots on FidesNetRoots, which fides_net needs'),
+        },
+    }, async ({ services, net }) => ok({
         agent_address: agent.address,
-        link: setupLink + (services ?? []).map((x) => `&service=${encodeURIComponent(x.id)}:${encodeURIComponent(x.max)}`).join(''),
+        link: setupLink + (services ?? []).map((x) => `&service=${encodeURIComponent(x.id)}:${encodeURIComponent(x.max)}`).join('') + (net && netRoots[cfg.chainId] ? `&target=${netRoots[cfg.chainId]}:${PUBLISH_SELECTOR}` : ''),
         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.',
@@ -310,6 +357,82 @@ export function createFidesMcpServer(cfg) {
             return fail('Could not build the plan: ' + (err?.shortMessage ?? err?.message ?? err));
         }
     });
+    const obligationSchema = z.object({
+        from: z.string().describe('Who owes: an address, or "me" for this FIDES Account'),
+        to: z.string().describe('Who is owed: an address, or "me" for this FIDES Account'),
+        amount: z.string().describe('How much, in whole token units, e.g. "1.5"'),
+        ref: z.string().optional().describe('What it was for, e.g. a job or invoice id. Goes into the obligations root'),
+    });
+    server.registerTool('fides_net', {
+        title: 'Net and settle what is owed (FIDES NET)',
+        description: 'Takes the payments owed between this FIDES Account ("me") and other parties, nets them to one final position per party, and builds the FIDES Account\'s side of the settlement into one plan: its net transfers plus the publication of the round\'s two roots (every obligation, every settling transfer) on FidesNetRoots, so payments and the public record go out in the same transaction. Checks every action against the FIDES and simulates. Sends nothing: returns a plan_id for fides_execute. Transfers owed by other parties are listed, not sent. Show the result to the user before executing.',
+        inputSchema: { obligations: z.array(obligationSchema).min(1).max(200), token: z.string().optional().describe('The token address. Defaults to the FIDES\'s budget token') },
+    }, async ({ obligations, token: tokenArg }) => {
+        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 roots = netRoots[cfg.chainId];
+            if (!roots)
+                return fail(`FIDES NET is not deployed on chain ${cfg.chainId}.`);
+            const allowsRoots = fides.targets.some((t) => t.target.toLowerCase() === roots.toLowerCase() && t.selectors.some((x) => x.toLowerCase() === PUBLISH_SELECTOR));
+            if (!allowsRoots)
+                return fail(`This FIDES does not allow FIDES NET to publish its roots on ${roots}. The user signs a new FIDES that does: call fides_setup with net: true (and the same services, if any) and give them the link.`);
+            const asset = tokenArg ? (isAddress(tokenArg) ? getAddress(tokenArg) : null) : fides.spendLimits[0].asset;
+            if (!asset)
+                return fail('"token" must be an address.');
+            const t = await token(asset);
+            const party = (x, n, side) => {
+                if (x.trim().toLowerCase() === 'me')
+                    return fides.account;
+                if (!isAddress(x))
+                    throw new NetError(`Obligation ${n}: "${side}" must be an address or "me".`);
+                return getAddress(x);
+            };
+            const list = obligations.map((o, i) => {
+                let amount;
+                try {
+                    amount = parseUnits(o.amount, t.decimals);
+                }
+                catch {
+                    throw new NetError(`Obligation ${i + 1}: "amount" must be a number of ${t.symbol}, like "1.5".`);
+                }
+                return { from: party(o.from, i + 1, 'from'), to: party(o.to, i + 1, 'to'), asset, amount, fidesId: fides.id, ref: o.ref ?? `${i + 1}` };
+            });
+            const s = netObligations(list);
+            const p = settle(s, { account: fides.account, chainId: cfg.chainId });
+            const plan = await new FidesBuilder({ client, fides, agent }).add(p.actions).build();
+            const savings = plan.estimatedSavings();
+            const simulations = savings.estimatedTransactions ? await plan.simulate() : [];
+            const failed = simulations.filter((x) => !x.success);
+            const ready = Boolean(savings.estimatedTransactions && !failed.length && !plan.rejected().length);
+            const id = plan.planHash.slice(0, 18);
+            if (ready)
+                plans.set(id, { plan, actions: p.actions, fides, net: { epoch: p.epoch, obligationsRoot: s.obligationsRoot, settlementRoot: s.settlementRoot } });
+            const amt = (v) => `${formatUnits(v < 0n ? -v : v, t.decimals)} ${t.symbol}`;
+            const name = (a) => (a.toLowerCase() === fides.account.toLowerCase() ? 'me' : getAddress(a));
+            const book = s.positions[asset.toLowerCase()] ?? {};
+            return ok({
+                plan_id: ready ? id : null,
+                ready_to_execute: ready,
+                gross: `${s.gross.obligations} obligations, ${amt(s.gross.volume[asset.toLowerCase()] ?? 0n)} moving`,
+                net: `${s.net.transfers} transfer(s), ${amt(s.net.volume[asset.toLowerCase()] ?? 0n)} moving`,
+                positions: Object.entries(book).map(([who, v]) => `${name(who)}: ${v < 0n ? 'pays' : 'receives'} ${amt(v)}`),
+                my_transfers: p.own.map((x) => `pay ${amt(x.amount)} to ${getAddress(x.to)}`),
+                settled_by_others: p.others.map((x) => `${name(x.from)} pays ${amt(x.amount)} to ${name(x.to)} (not sent by this FIDES)`),
+                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)`,
+                record: { contract: roots, epoch: p.epoch.toString(), obligations_root: s.obligationsRoot, settlement_root: s.settlementRoot },
+                simulation: !simulations.length ? 'nothing to execute' : failed.length ? `would fail: ${failure(failed[0].revertReason)}` : 'simulated against the chain: it would succeed',
+                sent: 'nothing has been sent',
+            });
+        }
+        catch (err) {
+            return fail(err instanceof NetError ? err.message : 'Could not net these: ' + (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());
@@ -350,7 +473,7 @@ export function createFidesMcpServer(cfg) {
     };
     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). For FIDES\'s own demo, the URL is https://api.fidesbuilder.xyz/v1/demo/chain-stats and the service is "fides-demo". Tell the user the price and get their OK before paying unless they already asked you to buy it.',
+        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'),
@@ -468,7 +591,7 @@ export function createFidesMcpServer(cfg) {
         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;
+        const { plan, actions, fides, net } = entry;
         try {
             const bundles = await send(plan, actions, fides);
             const [spend] = await Policy.remainingSpend(client, fides);
@@ -478,6 +601,7 @@ export function createFidesMcpServer(cfg) {
                 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}`),
+                ...(net && executed === bundles.length ? { netting_record: { contract: netRoots[cfg.chainId], operator: fides.account, epoch: net.epoch.toString(), obligations_root: net.obligationsRoot, settlement_root: net.settlementRoot, contract_link: explorer ? `${explorer}/address/${netRoots[cfg.chainId]}` : undefined } } : {}),
                 budget_remaining: `${formatUnits(spend.remaining, t.decimals)} of ${formatUnits(spend.limit, t.decimals)} ${t.symbol}`,
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidesbuild/mcp-server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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",
@@ -39,6 +39,7 @@
     "@fidesbuild/sdk": "0.2.0",
     "viem": "^2.21.0",
     "zod": "^4.6.5",
-    "@fidesbuild/x402": "0.2.0"
+    "@fidesbuild/x402": "0.2.0",
+    "@fidesbuild/net": "0.2.0"
   }
 }