@fidesbuild/mcp-server 0.4.1 → 0.5.1

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 {
@@ -167,12 +168,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.4.1' }, {
+    const server = new McpServer({ name: 'fides', version: '0.5.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.',
+            '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',
@@ -190,6 +192,7 @@ export function createFidesMcpServer(cfg) {
                 '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.',
+                '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.',
             ],
@@ -228,10 +231,13 @@ 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. 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({
+        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.',
@@ -352,6 +358,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, decimals: t.decimals, symbol: t.symbol });
+            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());
@@ -510,7 +592,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);
@@ -520,6 +602,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.1",
+  "version": "0.5.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",
@@ -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.1"
   }
 }