@fidesbuild/mcp-server 0.10.0 → 0.11.1

package/dist/server.js

@@ -16,7 +16,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { encodeFunctionData, decodeFunctionResult, erc20Abi, formatUnits, parseUnits, isAddress, getAddress } from 'viem';
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
-import { Fides, FidesBuilder, Policy, Receipts, accountOf, createFidesClient, fromJson, toJson } from '@fidesbuild/sdk';
+import { Fides, FidesBuilder, Policy, Receipts, RelayFees, accountOf, createFidesClient, fromJson, toJson } from '@fidesbuild/sdk';
 import { createX402, decodePaymentRequired, exactEip3009 } from '@fidesbuild/x402';
 import { netObligations, settle, netRoots, PUBLISH_SELECTOR, NetError } from '@fidesbuild/net';
 import { createSubClient, SubFidesKit, SubAgent, SubFidesError, subDeployments } from '@fidesbuild/sub';
@@ -251,7 +251,7 @@ 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.10.0' }, {
+    const server = new McpServer({ name: 'fides', version: '0.11.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". ' +
@@ -279,6 +279,7 @@ export function createFidesMcpServer(cfg) {
                 'Buy from paid APIs that charge per request over x402, paying from the FIDES budget, each capped per service.',
                 'Swap on Uniswap inside a trading mandate the owner signed: tokens it may buy, worst price, most per swap; best route across Robinhood Chain including v4 hook pools, approval and swap as one transaction (fides_swap). The FIDES must allow swaps: fides_setup with swap.',
                 'Hand another agent a slice of the FIDES with its own budget and expiry (fides_delegate, SUB-FIDES); or, as the child, act inside a slice handed to you (fides_sub_plan). The FIDES must allow delegation: fides_setup with delegate: true.',
+                'Keep running when the hosted relayer\'s free daily budget is used up, by paying the relay fee in $FIDES from the FIDES Account (fides_setup with relay_fees). Fees are only paid then, and fides_execute says when one was.',
                 'Keep going for weeks on one signature (LONG FIDES): a budget per hour, day, week or month that resets by itself, a total it can never pass and an end date. fides_setup with keeps_going; then fides_plan, fides_swap and fides_pay_request work inside this period\'s budget, and fides_status shows what is left this period and when it resets.',
                 'Settle with FIDES NET: give the payments owed to and from the FIDES Account, and they are netted to final positions and settled in one transaction, with the round published onchain (fides_net). The FIDES must allow NET: fides_setup with net: true.',
                 'Show the budget spent and left, what is allowed, the expiry, and every transaction executed, with explorer links.',
@@ -332,13 +333,16 @@ export function createFidesMcpServer(cfg) {
                 max_slippage_percent: z.number().positive().max(50).optional().describe('The worst price it may accept against the quote, in percent. Default 1'),
                 max_per_swap: z.string().optional().describe('The most one swap may spend, in the budget token. Default "1"'),
             }).optional().describe('Let the agent swap on Uniswap inside a trading mandate the owner signs; fides_swap needs it'),
+            relay_fees: z.string().optional().describe('The most the agent may spend on relay fees in $FIDES, e.g. "100". Fees are only paid when the hosted relayer\'s free daily budget is used up, so the agent keeps running then. The owner funds the FIDES Account with that much $FIDES.'),
             keeps_going: z.object({
                 every: z.enum(['hour', 'day', 'week', 'month']).describe('How often the budget resets'),
                 per_period: z.string().describe('The most it may spend each period, in USDG, e.g. "5"'),
                 days: z.number().positive().max(365).optional().describe('How long it keeps going, in days. Default 30'),
             }).optional().describe('A LONG FIDES: one signature, and the agent keeps going period after period, with a budget per period that resets by itself, a total it can never pass and an end date. It cannot be combined with delegate or net.'),
         },
-    }, async ({ services, net, delegate, swap, contracts, keeps_going }) => {
+    }, async ({ services, net, delegate, swap, contracts, keeps_going, relay_fees }) => {
+        if (relay_fees !== undefined && !(Number(relay_fees) > 0))
+            return fail('relay_fees must be a number of $FIDES, like "100".');
         if (keeps_going && (delegate || net))
             return fail('A LONG FIDES cannot hand out slices or settle with NET. Leave out delegate and net, or sign an ordinary FIDES for those.');
         let targets = '';
@@ -372,7 +376,8 @@ export function createFidesMcpServer(cfg) {
         }
         return ok({
             agent_address: agent.address,
-            link: setupLink + targets + (services ?? []).map((x) => `&service=${encodeURIComponent(x.id)}:${encodeURIComponent(x.max)}`).join('') + (net && netRoots[cfg.chainId] ? `&target=${netRoots[cfg.chainId]}:${PUBLISH_SELECTOR}` : '') + (delegate ? '&delegate=1' : '') + (swap ? `&swap=${encodeURIComponent(swap.buy.map((t) => (/^weth$/i.test(t) ? uniswap[cfg.chainId]?.weth ?? t : t)).join('|'))}:${Math.round((swap.max_slippage_percent ?? 1) * 100)}:${encodeURIComponent(swap.max_per_swap ?? '1')}` : '') + (keeps_going ? `&every=${keeps_going.every}&per=${encodeURIComponent(keeps_going.per_period)}&days=${keeps_going.days ?? 30}` : ''),
+            link: setupLink + targets + (services ?? []).map((x) => `&service=${encodeURIComponent(x.id)}:${encodeURIComponent(x.max)}`).join('') + (net && netRoots[cfg.chainId] ? `&target=${netRoots[cfg.chainId]}:${PUBLISH_SELECTOR}` : '') + (delegate ? '&delegate=1' : '') + (swap ? `&swap=${encodeURIComponent(swap.buy.map((t) => (/^weth$/i.test(t) ? uniswap[cfg.chainId]?.weth ?? t : t)).join('|'))}:${Math.round((swap.max_slippage_percent ?? 1) * 100)}:${encodeURIComponent(swap.max_per_swap ?? '1')}` : '') + (keeps_going ? `&every=${keeps_going.every}&per=${encodeURIComponent(keeps_going.per_period)}&days=${keeps_going.days ?? 30}` : '') + (relay_fees ? `&fee=${encodeURIComponent(relay_fees)}` : ''),
+            relay_fees: relay_fees ? `up to ${relay_fees} $FIDES on relay fees, paid only when the hosted relayer's free daily budget is used up. Fund the FIDES Account with that much $FIDES.` : undefined,
             keeps_going: keeps_going ? `${keeps_going.per_period} USDG every ${keeps_going.every}, for ${keeps_going.days ?? 30} days. The budget resets by itself; the total is the most it can ever spend.` : undefined,
             services: services?.length ? services.map((x) => `${x.id}: up to ${x.max} USDG`) : undefined,
             contracts: added.length ? added : undefined,
@@ -499,7 +504,7 @@ export function createFidesMcpServer(cfg) {
                 const sim = p.bundle ? await la.simulate(p) : { success: false, reason: 'NOTHING_TO_SEND' };
                 const id = (p.bundleHash ?? '0x').slice(0, 18);
                 if (sim.success)
-                    longPlans.set(id, { agent: la, plan: p, fides });
+                    longPlans.set(id, { agent: la, plan: p, fides, actions: built });
                 return ok({
                     plan_id: sim.success ? id : null,
                     ready_to_execute: sim.success,
@@ -616,9 +621,32 @@ export function createFidesMcpServer(cfg) {
         return json;
     }
     /** Sends a plan's bundles: through the hosted relayer, or paid by the agent key with FIDES_RELAY=self. */
+    // The hosted relayer sends one bundle a day per FIDES Account for free. Past it, a bundle that carries the relay fee in $FIDES
+    // is still relayed, if the FIDES allows paying it. What was paid is kept for the tool's answer.
+    let lastRelayFee = null;
+    async function withRelayFee(fides, actions, bundles) {
+        if (!cfg.api)
+            return null;
+        const fees = await RelayFees.get(cfg.api, fides.account).catch(() => null);
+        if (!fees || !RelayFees.needed(fees, Math.max(1, bundles)))
+            return null;
+        if (!RelayFees.allows(fides, fees))
+            return 'This FIDES Account has used its free relayed bundle for today, and this FIDES does not allow paying the relay fee in $FIDES. Try again after 00:00 UTC, or the user signs a FIDES that allows it (fides_setup with relay_fees).';
+        const fee = RelayFees.action(fees, Math.max(1, bundles));
+        lastRelayFee = fee.label ?? null;
+        return [...actions.filter((a) => a.id !== 'relay-fee'), fee];
+    }
     async function send(plan, actions, fides) {
+        lastRelayFee = null;
         if (!cfg.api)
             return (await plan.execute()).bundles;
+        const paid = await withRelayFee(fides, actions, plan.estimatedSavings().estimatedTransactions);
+        if (typeof paid === 'string')
+            throw new Error(paid);
+        if (paid) {
+            actions = paid;
+            plan = await new FidesBuilder({ client, fides, agent }).add(actions).build();
+        }
         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.');
@@ -968,7 +996,7 @@ export function createFidesMcpServer(cfg) {
                 const sim = lp.bundle ? await la.simulate(lp) : { success: false, reason: lp.plan.rejected[0]?.reason ?? 'NOTHING_TO_SEND' };
                 const id = (lp.bundleHash ?? '0x').slice(0, 18);
                 if (sim.success)
-                    longPlans.set(id, { agent: la, plan: lp, fides, swap: { quote: bq, outDecimals: outInfo.decimals, outSymbol: outInfo.symbol } });
+                    longPlans.set(id, { agent: la, plan: lp, fides, actions: swapActions(bq, `swap ${amount} ${tIn.symbol} to ${outInfo.symbol} on Uniswap`), swap: { quote: bq, outDecimals: outInfo.decimals, outSymbol: outInfo.symbol } });
                 return ok({
                     plan_id: sim.success ? id : null, ready_to_execute: sim.success,
                     routes_compared: [...quotes].map(([name, q]) => ({ route: name, quoted: fmt(q.quotedOut), verdict: name === bestName ? 'best quote, chosen' : 'lower quote' })).concat(excluded.map((x) => ({ route: x.route, quoted: '-', verdict: 'out: ' + x.why }))),
@@ -1184,13 +1212,18 @@ export function createFidesMcpServer(cfg) {
                 const sw = longEntry.swap, f2 = longEntry.fides;
                 const outBalance = () => !sw ? Promise.resolve(0n) : sw.quote.tokenOut === NATIVE ? client.public.getBalance({ address: f2.account }) : client.public.readContract({ address: sw.quote.tokenOut, abi: erc20Abi, functionName: 'balanceOf', args: [f2.account] });
                 const before = await outBalance();
-                const r = await longEntry.agent.execute(longEntry.plan);
+                lastRelayFee = null;
+                const paid = longEntry.actions ? await withRelayFee(f2, longEntry.actions, 1) : null;
+                if (typeof paid === 'string')
+                    return fail(paid);
+                const r = await longEntry.agent.execute(paid ? await longEntry.agent.plan(paid) : longEntry.plan);
                 const st = await longEntry.agent.status().catch(() => null), t = await token(f2.spendLimits[0].asset);
                 const received = sw && r.status === 'EXECUTED' ? (await outBalance()) - before : 0n;
                 return ok({
                     result: r.status === 'EXECUTED' ? 'executed' : 'not executed',
                     transactions: r.txHash || r.error ? [{ status: r.status.toLowerCase(), transaction: txLink(r.txHash), ...(r.error ? { reason: failure(r.error) } : {}) }] : [],
                     blocked_and_not_sent: longEntry.plan.plan.rejected.map((a) => `${a.label}: ${REASONS[a.reason ?? ''] ?? a.reason}`),
+                    ...(lastRelayFee ? { relay_fee: `${lastRelayFee}, because the free relayed bundle for today is used` } : {}),
                     ...(sw && r.status === 'EXECUTED' ? { best_execution: { quoted: `${formatUnits(sw.quote.quotedOut, sw.outDecimals)} ${sw.outSymbol}`, received: `${formatUnits(received, sw.outDecimals)} ${sw.outSymbol}`, route: describeRoute(sw.quote) } } : {}),
                     ...(st ? { this_period: { spent: `${formatUnits(st.thisPeriod[0].spent, t.decimals)} ${t.symbol}`, left: `${formatUnits(st.thisPeriod[0].remaining, t.decimals)} ${t.symbol}`, resets_at: new Date(Number(st.resetsAt) * 1000).toISOString() }, total_left: `${formatUnits(st.total[0].remaining, t.decimals)} of ${formatUnits(st.total[0].limit, t.decimals)} ${t.symbol}` } : {}),
                 });
@@ -1216,6 +1249,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}`),
+                ...(lastRelayFee ? { relay_fee: `${lastRelayFee}, because the free relayed bundle for today is used` } : {}),
                 ...(swap && executed === bundles.length ? { best_execution: {
                         quoted: `${formatUnits(swap.quote.quotedOut, swap.outDecimals)} ${swap.outSymbol}`,
                         received: `${formatUnits(received, swap.outDecimals)} ${swap.outSymbol}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidesbuild/mcp-server",
-  "version": "0.10.0",
+  "version": "0.11.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",
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "@fidesbuild/sdk": "0.2.0",
+    "@fidesbuild/sdk": "0.2.7",
     "viem": "^2.21.0",
     "zod": "^4.6.5",
     "@fidesbuild/x402": "0.2.0",