@fidesbuild/mcp-server 0.9.0 → 0.10.0

package/dist/server.js

@@ -22,6 +22,7 @@ import { netObligations, settle, netRoots, PUBLISH_SELECTOR, NetError } from '@f
 import { createSubClient, SubFidesKit, SubAgent, SubFidesError, subDeployments } from '@fidesbuild/sub';
 import { quoteUniswap, checkMandate, swapActions, verifySwap, describeRoute, mandateOf, uniswap, NATIVE, SwapError } from '@fidesbuild/swap';
 import { route } from '@fidesbuild/router';
+import { LongAgent, LongFides, isLong } from '@fidesbuild/long';
 export function configFromEnv(env = process.env) {
     const home = env.FIDES_HOME ?? path.join(os.homedir(), '.fides');
     return {
@@ -142,6 +143,23 @@ export function createFidesMcpServer(cfg) {
     const subClient = subAddrs ? createSubClient({ chainId: cfg.chainId, rpc: cfg.rpc, base: cfg.addresses, addresses: subAddrs }) : null;
     const subPlans = new Map();
     const subsDir = path.join(cfg.home, 'subs');
+    // LONG FIDES: the terms (period, budget per period, calls per period) come with the FIDES from the API,
+    // and are kept here so a FIDES loaded from the file can still run.
+    const longFile = path.join(cfg.home, 'long.json');
+    const longTerms = new Map(Object.entries(fs.existsSync(longFile) ? fromJson(fs.readFileSync(longFile, 'utf8')) : {}));
+    const keepTerms = (id, terms) => { longTerms.set(id, terms); fs.mkdirSync(cfg.home, { recursive: true }); fs.writeFileSync(longFile, toJson(Object.fromEntries(longTerms), 2) + '\n'); };
+    const longPlans = new Map();
+    /** The agent for a LONG FIDES, or a message saying why it cannot run. */
+    const longAgentFor = (fides) => {
+        const terms = longTerms.get(fides.id);
+        if (!subClient)
+            return `LONG FIDES is not deployed on chain ${cfg.chainId}.`;
+        if (!terms)
+            return 'This is a LONG FIDES, but its terms (the budget per period) are not here. The app shares them when the owner signs; ask the user to open it in the FIDES app once, or sign it again.';
+        return new LongAgent({ client: subClient, fides, terms, agent, ...(cfg.api ? { api: cfg.api } : { relayer: agent }) });
+    };
+    const every = (t) => ({ 3600: 'hour', 86400: 'day', 604800: 'week', 2592000: '30 days' }[String(t.period)] ?? `${Number(t.period) / 3600} hours`);
+    const noLong = (what) => `This is a LONG FIDES. It swaps, pays paid APIs, sends and calls contracts inside its budget per period, but it does not ${what}. For that, the user signs an ordinary FIDES (fides_setup without keeps_going).`;
     const token = async (asset) => {
         const key = asset.toLowerCase();
         if (!tokens.has(key)) {
@@ -175,8 +193,11 @@ export function createFidesMcpServer(cfg) {
                 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)
+                        if (mine(x.fides) && x.status?.valid) {
                             candidates.push(x.fides);
+                            if (x.long)
+                                keepTerms(x.fides.id, x.long);
+                        }
             }
             catch { /* the API is optional: the copy kept here still works */ }
         }
@@ -203,9 +224,16 @@ export function createFidesMcpServer(cfg) {
         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';
+        const terms = isLong(fides) ? longTerms.get(fides.id) : undefined;
+        const period = terms && subClient ? await LongFides.status(subClient, fides, terms).catch(() => null) : null;
         return {
             status,
             fides: fides.id,
+            ...(isLong(fides) ? { keeps_going: !terms ? 'a LONG FIDES, but its terms are not here yet' : {
+                    budget_per_period: `${amount(terms.perPeriod[0].amount)} every ${every(terms)}`,
+                    this_period: period ? { spent: amount(period.thisPeriod[0].spent), left: amount(period.thisPeriod[0].remaining), calls: `${period.actions.used} of ${terms.maxActionsPerPeriod}`, resets_at: new Date(Number(period.resetsAt) * 1000).toISOString() } : 'unknown',
+                    note: 'The budget per period resets by itself. The total budget is the most it can ever spend.',
+                } } : {}),
             owner: fides.owner,
             agent: fides.agent,
             fides_account: fides.account,
@@ -223,12 +251,13 @@ 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.8.0' }, {
+    const server = new McpServer({ name: 'fides', version: '0.10.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". ' +
             '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. ' +
+            'For a LONG FIDES (one that keeps going, with a budget per period), plans are checked against what is left this period and in total; if this period\'s budget is used up, say when it resets. ' +
             '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', {
@@ -250,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 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.',
                 '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.',
@@ -302,8 +332,15 @@ 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'),
+            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 }) => {
+    }, async ({ services, net, delegate, swap, contracts, keeps_going }) => {
+        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 = '';
         const added = [];
         for (const c of contracts ?? []) {
@@ -335,7 +372,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')}` : ''),
+            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}` : ''),
+            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,
             steps: [
@@ -453,6 +491,25 @@ export function createFidesMcpServer(cfg) {
             if ('error' in made)
                 return fail(made.error);
             const built = made.built;
+            if (isLong(fides)) {
+                const la = longAgentFor(fides);
+                if (typeof la === 'string')
+                    return fail(la);
+                const p = await la.plan(built);
+                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 });
+                return ok({
+                    plan_id: sim.success ? id : null,
+                    ready_to_execute: sim.success,
+                    keeps_going: `period ${p.period}: checked against this period's budget and the total`,
+                    actions: p.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}), counting this period's budget` : 'duplicate, sent once' })),
+                    transactions: p.bundle ? `${p.bundle.calls.length} onchain write(s) go out as 1 transaction` : 'nothing to execute',
+                    simulation: !p.bundle ? 'nothing to execute: no action fits this period\'s budget' : sim.success ? 'simulated against the chain: it would succeed' : `would fail: ${failure(sim.reason)}`,
+                    sent: 'nothing has been sent',
+                });
+            }
             const plan = await new FidesBuilder({ client, fides, agent }).add(built).build();
             const savings = plan.estimatedSavings();
             const simulations = savings.estimatedTransactions ? await plan.simulate() : [];
@@ -490,6 +547,8 @@ export function createFidesMcpServer(cfg) {
                 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}.`);
+            if (isLong(fides))
+                return fail(noLong('settle with FIDES NET'));
             const roots = netRoots[cfg.chainId];
             if (!roots)
                 return fail(`FIDES NET is not deployed on chain ${cfg.chainId}.`);
@@ -657,20 +716,36 @@ export function createFidesMcpServer(cfg) {
             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.`);
+                if (isLong(fides)) {
+                    const la = longAgentFor(fides);
+                    if (typeof la === 'string')
+                        return fail(la);
+                    const lp = await la.plan(actions);
+                    if (lp.plan.rejected.length)
+                        return fail(`Blocked by the FIDES: ${REASONS[lp.plan.rejected[0].reason ?? ''] ?? lp.plan.rejected[0].reason}, counting this period's budget. Nothing was paid.`);
+                    const r = await la.execute(lp);
+                    if (r.status !== 'EXECUTED')
+                        return fail('Could not move the price to the agent key: ' + failure(r.error) + ' Nothing was paid.');
+                    funded = txLink(r.txHash);
+                    float = price;
+                    setFloat(fides, offer.asset, float);
+                }
+                const plan = isLong(fides) ? null : await new FidesBuilder({ client, fides, agent }).add(actions).build();
+                if (plan) {
+                    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);
                 }
-                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);
@@ -882,6 +957,28 @@ export function createFidesMcpServer(cfg) {
                 const mandate = excluded.find((x) => x.why.startsWith('trading mandate'));
                 return fail(mandate ? `Blocked by the ${mandate.why} Nothing was sent.` : `Uniswap has no route for this swap: ${excluded.map((x) => `${x.route} (${x.why})`).join('; ')}. Nothing was sent.`);
             }
+            if (isLong(fides)) {
+                const la = longAgentFor(fides);
+                if (typeof la === 'string')
+                    return fail(la);
+                const [bestName, bq] = [...quotes].sort((a, b) => (b[1].quotedOut > a[1].quotedOut ? 1 : -1))[0];
+                const outInfo = bq.tokenOut === NATIVE ? { symbol: 'ETH', decimals: 18 } : await token(bq.tokenOut);
+                const fmt = (v) => `${formatUnits(v, outInfo.decimals)} ${outInfo.symbol}`;
+                const lp = await la.plan(swapActions(bq, `swap ${amount} ${tIn.symbol} to ${outInfo.symbol} on Uniswap`));
+                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 } });
+                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 }))),
+                    chosen: bestName, route: describeRoute(bq), spend: `${amount} ${tIn.symbol}`, quoted: fmt(bq.quotedOut),
+                    worst_accepted: `${fmt(bq.minOut)} (${bq.slippageBps / 100}% below the quote)`,
+                    keeps_going: `period ${lp.period}: checked against this period's budget and the total`,
+                    simulation: sim.success ? 'simulated against the chain: it would succeed' : `would fail: ${failure(sim.reason)}`,
+                    sent: 'nothing has been sent',
+                });
+            }
             const first = [...quotes.values()][0];
             const outInfo = first.tokenOut === NATIVE ? { symbol: 'ETH', decimals: 18 } : await token(first.tokenOut);
             const fmt = (v) => `${formatUnits(v, outInfo.decimals)} ${outInfo.symbol}`;
@@ -941,6 +1038,8 @@ export function createFidesMcpServer(cfg) {
                 return fail('"agent" must be an address.');
             if (child.toLowerCase() === agent.address.toLowerCase())
                 return fail('An agent cannot delegate to itself.');
+            if (isLong(parent))
+                return fail(noLong('hand out slices to other agents'));
             const v2 = await accountOf(subClient, parent.owner);
             if (v2.toLowerCase() !== parent.account.toLowerCase())
                 return fail('This FIDES cannot delegate: its FIDES Account is not one that supports SUB-FIDES. The user signs a new FIDES that allows delegation: call fides_setup with delegate: true and give them the link.');
@@ -1078,6 +1177,28 @@ export function createFidesMcpServer(cfg) {
                 return fail('Execution stopped: ' + failure(err?.shortMessage ?? err?.message ?? err));
             }
         }
+        const longEntry = longPlans.get(plan_id);
+        if (longEntry) {
+            longPlans.delete(plan_id);
+            try {
+                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);
+                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}`),
+                    ...(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}` } : {}),
+                });
+            }
+            catch (err) {
+                return fail('Execution stopped: ' + failure(err?.shortMessage ?? err?.message ?? err));
+            }
+        }
         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).');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidesbuild/mcp-server",
-  "version": "0.9.0",
+  "version": "0.10.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",
@@ -43,6 +43,7 @@
     "@fidesbuild/net": "0.2.1",
     "@fidesbuild/sub": "0.2.0",
     "@fidesbuild/swap": "0.2.1",
-    "@fidesbuild/router": "0.2.0"
+    "@fidesbuild/router": "0.2.0",
+    "@fidesbuild/long": "0.2.0"
   }
 }