@fidesbuild/mcp-server 0.5.1 → 0.6.0

package/dist/server.d.ts

@@ -3,6 +3,7 @@ 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';
+import { type SubAddresses } from '@fidesbuild/sub';
 export type Config = {
     /** Folder for agent.json and the default fides.json. */
     home: string;
@@ -16,6 +17,8 @@ export type Config = {
     app: string;
     fidesFile: string;
     addresses?: FidesAddresses;
+    /** SUB-FIDES contracts, when not the published ones for the chain. */
+    sub?: SubAddresses;
     agentKey?: Hex;
 };
 export declare function configFromEnv(env?: NodeJS.ProcessEnv): Config;

package/dist/server.js

@@ -16,9 +16,10 @@ 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 { Fides, FidesBuilder, Policy, Receipts, 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';
 export function configFromEnv(env = process.env) {
     const home = env.FIDES_HOME ?? path.join(os.homedir(), '.fides');
     return {
@@ -30,6 +31,7 @@ export function configFromEnv(env = process.env) {
         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,
+        sub: env.FIDES_SUB_ADDRESSES ? JSON.parse(fs.readFileSync(env.FIDES_SUB_ADDRESSES, 'utf8')) : undefined,
         agentKey: env.FIDES_AGENT_KEY,
     };
 }
@@ -87,6 +89,11 @@ export function createFidesMcpServer(cfg) {
     const txLink = (h) => (h && explorer ? `${explorer}/tx/${h}` : h);
     const plans = new Map();
     const tokens = new Map();
+    // SUB-FIDES: a FIDES on a V2 account can hand slices of itself to other agents.
+    const subAddrs = cfg.sub ?? subDeployments[cfg.chainId];
+    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');
     const token = async (asset) => {
         const key = asset.toLowerCase();
         if (!tokens.has(key)) {
@@ -168,7 +175,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.5.1' }, {
+    const server = new McpServer({ name: 'fides', version: '0.6.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". ' +
@@ -192,6 +199,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.',
+                '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.',
                 '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.',
@@ -234,10 +242,11 @@ export function createFidesMcpServer(cfg) {
         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'),
+            delegate: z.boolean().optional().describe('true to let this agent hand slices of the FIDES to other agents (SUB-FIDES), which fides_delegate needs'),
         },
-    }, async ({ services, net }) => ok({
+    }, async ({ services, net, delegate }) => ok({
         agent_address: agent.address,
-        link: setupLink + (services ?? []).map((x) => `&service=${encodeURIComponent(x.id)}:${encodeURIComponent(x.max)}`).join('') + (net && netRoots[cfg.chainId] ? `&target=${netRoots[cfg.chainId]}:${PUBLISH_SELECTOR}` : ''),
+        link: setupLink + (services ?? []).map((x) => `&service=${encodeURIComponent(x.id)}:${encodeURIComponent(x.max)}`).join('') + (net && netRoots[cfg.chainId] ? `&target=${netRoots[cfg.chainId]}:${PUBLISH_SELECTOR}` : '') + (delegate ? '&delegate=1' : ''),
         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.',
@@ -285,6 +294,51 @@ export function createFidesMcpServer(cfg) {
         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'),
     });
+    /** The tool's actions as Builder actions, in the budget token unless a transfer names another. */
+    async function buildActions(actions, budget) {
+        const built = [];
+        for (const [i, a] of actions.entries()) {
+            const n = i + 1;
+            if (a.kind === 'transfer') {
+                if (!a.to || !isAddress(a.to))
+                    return { error: `Action ${n}: "to" must be an address.` };
+                const asset = a.token ? (isAddress(a.token) ? getAddress(a.token) : null) : budget;
+                if (!asset)
+                    return { error: `Action ${n}: "token" must be an address.` };
+                const t = await token(asset);
+                let amount;
+                try {
+                    amount = parseUnits(String(a.amount ?? ''), t.decimals);
+                }
+                catch {
+                    return { error: `Action ${n}: "amount" must be a number of ${t.symbol}, like "1.5".` };
+                }
+                if (amount <= 0n)
+                    return { error: `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 { error: `Action ${n}: "target" must be a contract address.` };
+                if (!a.data || !/^0x([0-9a-fA-F]{2}){4,}$/.test(a.data))
+                    return { error: `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 { error: `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 } } : {}) });
+            }
+        }
+        return { built };
+    }
     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.',
@@ -296,48 +350,10 @@ 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}.`);
-            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 made = await buildActions(actions, fides.spendLimits[0].asset);
+            if ('error' in made)
+                return fail(made.error);
+            const built = made.built;
             const plan = await new FidesBuilder({ client, fides, agent }).add(built).build();
             const savings = plan.estimatedSavings();
             const simulations = savings.estimatedTransactions ? await plan.simulate() : [];
@@ -583,11 +599,165 @@ export function createFidesMcpServer(cfg) {
             return fail('Paid request stopped: ' + failure(err?.shortMessage ?? err?.message ?? err));
         }
     });
+    // ---- SUB-FIDES ----
+    server.registerTool('fides_delegate', {
+        title: 'Hand another agent a slice of the FIDES (SUB-FIDES)',
+        description: 'This agent hands another agent a SUB-FIDES: its own budget, contracts and expiry, inside this FIDES. The child can never exceed it, and everything it spends also counts against this FIDES. This agent signs it; nothing is sent onchain and it costs nothing. The child agent (Claude or an SDK agent running FIDES) finds it by itself, or the user can hand it the file. Needs a FIDES that allows delegation: fides_setup with delegate: true. Confirm the amount and the agent with the user first.',
+        inputSchema: {
+            agent: z.string().describe('The child agent\'s address'),
+            amount: z.string().describe('The most the child may spend, in the budget token, e.g. "0.1"'),
+            minutes: z.number().int().positive().optional().describe('How long the slice lasts. Defaults to as long as this FIDES; never longer'),
+        },
+    }, async ({ agent: child, amount, minutes }) => {
+        try {
+            if (!subClient || !subAddrs)
+                return fail(`SUB-FIDES is not deployed on chain ${cfg.chainId}.`);
+            const parent = await currentFides();
+            if (!parent)
+                return fail(notLoaded());
+            if (parent.agent.toLowerCase() !== agent.address.toLowerCase())
+                return fail(`The loaded FIDES is for agent ${parent.agent}, not this computer's agent key ${agent.address}.`);
+            if (!isAddress(child))
+                return fail('"agent" must be an address.');
+            if (child.toLowerCase() === agent.address.toLowerCase())
+                return fail('An agent cannot delegate to itself.');
+            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.');
+            const asset = parent.spendLimits[0].asset, t = await token(asset);
+            let value;
+            try {
+                value = parseUnits(amount, t.decimals);
+            }
+            catch {
+                return fail(`"amount" must be a number of ${t.symbol}, like "0.1".`);
+            }
+            const expiry = minutes ? BigInt(Math.min(Number(parent.validUntil), Math.floor(Date.now() / 1000) + minutes * 60)) : parent.validUntil;
+            const unsigned = SubFidesKit.create(parent, { agent: getAddress(child), spend: [{ asset, amount: value }], expiry });
+            const sub = await SubFidesKit.sign(unsigned, agent, subClient, parent);
+            if (cfg.api)
+                await SubFidesKit.register(cfg.api, parent, sub);
+            fs.mkdirSync(subsDir, { recursive: true });
+            const file = path.join(subsDir, `${sub.id.slice(0, 18)}.json`);
+            fs.writeFileSync(file, toJson({ parent, sub }, 2) + '\n');
+            return ok({
+                sub_fides: sub.id,
+                child_agent: sub.agent,
+                budget: `${formatUnits(value, t.decimals)} ${t.symbol}`,
+                expires: new Date(Number(sub.validUntil) * 1000).toISOString(),
+                contracts: sub.targets.map((r) => r.target),
+                file,
+                how_the_child_gets_it: cfg.api ? 'Shared with the FIDES API: a child running FIDES (Claude or the SDK) finds it by its agent address. The file is a copy to hand over directly.' : 'Hand the child the file.',
+                revoke: 'The owner can revoke it any time in the FIDES app, on this FIDES\'s page.',
+            });
+        }
+        catch (err) {
+            return fail(err instanceof SubFidesError ? err.message : 'Could not delegate: ' + (err?.shortMessage ?? err?.message ?? err));
+        }
+    });
+    /** The SUB-FIDES handed to this agent that can still act: from a file, or found through the FIDES API. */
+    async function receivedSubs(file) {
+        const found = [];
+        if (file) {
+            const full = file.replace(/^~(?=$|[\\/])/, os.homedir());
+            found.push(fromJson(fs.readFileSync(full, 'utf8')));
+        }
+        if (cfg.directory) {
+            try {
+                const res = await fetch(`${cfg.directory}/v1/agents/${agent.address}/subs`);
+                if (res.ok)
+                    for (const x of fromJson(await res.text()).subs ?? [])
+                        if (x.parentStatus?.valid)
+                            found.push({ parent: x.parent, sub: x.sub });
+            }
+            catch { /* the API is optional when a file is given */ }
+        }
+        const now = BigInt(Math.floor(Date.now() / 1000));
+        const live = [];
+        for (const x of found) {
+            if (x.sub.agent.toLowerCase() !== agent.address.toLowerCase() || now >= x.sub.validUntil)
+                continue;
+            if (subClient && await SubFidesKit.isRevoked(subClient, x.parent, x.sub).catch(() => true))
+                continue;
+            live.push(x);
+        }
+        return live.sort((a, b) => Number(b.sub.validAfter - a.sub.validAfter));
+    }
+    server.registerTool('fides_sub_plan', {
+        title: 'Plan actions under a SUB-FIDES handed to this agent',
+        description: 'For when another agent handed this agent a SUB-FIDES (a slice of its FIDES). Builds the actions into one plan, checks every action against the slice, and simulates it. Sends nothing. Returns a plan_id for fides_execute, which sends it through the relayer (no gas needed). Show the result to the user before executing.',
+        inputSchema: { actions: z.array(actionSchema).min(1).max(50), file: z.string().optional().describe('Path to a SUB-FIDES file, if the user has one. Otherwise it is found by this agent\'s address') },
+    }, async ({ actions, file }) => {
+        try {
+            if (!subClient)
+                return fail(`SUB-FIDES is not deployed on chain ${cfg.chainId}.`);
+            const [x] = await receivedSubs(file);
+            if (!x)
+                return fail(`No active SUB-FIDES has been handed to this agent (${agent.address}). The delegating agent creates one with this address, or the user gives you its file.`);
+            const made = await buildActions(actions, x.sub.spendLimits[0]?.asset ?? x.parent.spendLimits[0].asset);
+            if ('error' in made)
+                return fail(made.error);
+            const child = new SubAgent({ client: subClient, parent: x.parent, sub: x.sub, agent, ...(cfg.api ? { api: cfg.api } : { relayer: agent }) });
+            const p = await child.plan(made.built);
+            const sim = p.bundle ? await child.simulate(p) : { success: false, reason: 'NOTHING_TO_SEND' };
+            const id = (p.bundleHash ?? '0x').slice(0, 18);
+            if (sim.success)
+                subPlans.set(id, { agent: child, plan: p, parent: x.parent, sub: x.sub });
+            const t = await token(x.sub.spendLimits[0]?.asset ?? x.parent.spendLimits[0].asset);
+            return ok({
+                plan_id: sim.success ? id : null,
+                ready_to_execute: sim.success,
+                sub_fides: x.sub.id,
+                slice: `${x.sub.spendLimits.map((l) => formatUnits(l.amount, t.decimals) + ' ' + t.symbol).join(', ')} until ${new Date(Number(x.sub.validUntil) * 1000).toISOString()}`,
+                delegated_by: x.parent.agent,
+                actions: p.plan.actions.map((a) => ({ action: a.label, decision: a.decision === 'AUTHORIZED' ? 'inside the SUB-FIDES' : a.decision === 'REJECTED' ? `blocked: ${REASONS[a.reason ?? ''] ?? a.reason} (${a.reason})` : '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 is inside the SUB-FIDES' : sim.success ? 'simulated against the chain: it would succeed' : `would fail: ${failure(sim.reason)}`,
+                sent: 'nothing has been sent',
+            });
+        }
+        catch (err) {
+            return fail('Could not build the plan: ' + (err?.shortMessage ?? err?.message ?? err));
+        }
+    });
+    server.registerTool('fides_subs', {
+        title: 'SUB-FIDES handed out and received',
+        description: 'The SUB-FIDES this agent has handed to other agents, and the ones handed to it that can still act.',
+        inputSchema: {},
+    }, async () => {
+        try {
+            const given = fs.existsSync(subsDir) ? fs.readdirSync(subsDir).filter((n) => n.endsWith('.json')).map((n) => fromJson(fs.readFileSync(path.join(subsDir, n), 'utf8')).sub) : [];
+            const now = BigInt(Math.floor(Date.now() / 1000));
+            return ok({
+                handed_out: given.map((s) => ({ sub_fides: s.id, child_agent: s.agent, budget: s.spendLimits.map((l) => l.amount.toString()), expires: new Date(Number(s.validUntil) * 1000).toISOString(), expired: now >= s.validUntil })),
+                received: (await receivedSubs()).map((x) => ({ sub_fides: x.sub.id, delegated_by: x.parent.agent, expires: new Date(Number(x.sub.validUntil) * 1000).toISOString() })),
+            });
+        }
+        catch (err) {
+            return fail('Could not list SUB-FIDES: ' + (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 subEntry = subPlans.get(plan_id);
+        if (subEntry) {
+            subPlans.delete(plan_id);
+            try {
+                const r = await subEntry.agent.execute(subEntry.plan);
+                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) } : {}) }] : [],
+                    under: `SUB-FIDES ${subEntry.sub.id} from ${subEntry.parent.agent}`,
+                    blocked_and_not_sent: subEntry.plan.plan.rejected.map((a) => `${a.label}: ${REASONS[a.reason ?? ''] ?? a.reason}`),
+                });
+            }
+            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.5.1",
+  "version": "0.6.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",
@@ -40,6 +40,7 @@
     "viem": "^2.21.0",
     "zod": "^4.6.5",
     "@fidesbuild/x402": "0.2.0",
-    "@fidesbuild/net": "0.2.1"
+    "@fidesbuild/net": "0.2.1",
+    "@fidesbuild/sub": "0.2.0"
   }
 }