@fidesbuild/mcp-server 0.8.0 → 0.8.1

package/README.md

@@ -38,7 +38,11 @@ Claude Code and other MCP apps need [Node](https://nodejs.org) 20.10 or later. C
 | --- | --- |
 | `fides_setup` | A link to the FIDES app with this agent filled in |
 | `fides_status` | The FIDES: active or not, budget spent and remaining, FIDES Account balance, allowed contracts, expiry, agent address |
-| `fides_plan` | Builds transfers and contract calls into one plan, checks each against the FIDES, groups them, simulates. Sends nothing |
+| `fides_plan` | Builds transfers and contract calls into one plan, checks each against the FIDES, groups them, simulates. Sends nothing. Calls any verified contract by function name and plain values, encoded from its verified source |
+| `fides_inspect_contract` | Reads any contract on the chain and lists what an agent could call, with risky functions flagged |
+| `fides_read_contract` | Reads a value from any verified contract by function name, such as a market or a balance. Free |
+| `fides_check_api` | Reads a paid API's price without paying, and says whether a FIDES can pay it |
+| `fides_swap` | Swaps on Uniswap inside the trading mandate the owner signed |
 | `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 |

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type Hex } from 'viem';
+import { type Address, type Hex, type AbiFunction, type AbiParameter } from 'viem';
 import { type PrivateKeyAccount } from 'viem/accounts';
 import { type FidesAddresses } from '@fidesbuild/sdk';
 import { type SubAddresses } from '@fidesbuild/sub';
@@ -28,6 +28,10 @@ export declare function agentKey(cfg: Config): {
     file: string | null;
     created: boolean;
 };
+/** Turns plain JSON values into what viem encodes for each ABI type. "me" is the FIDES Account. */
+export declare function coerce(p: AbiParameter, v: unknown, me: Address | null, at: string): unknown;
+/** Encodes a call from one ABI function and plain JSON args. */
+export declare function encodeCall(abi: AbiFunction, args: unknown[], me: Address | null): Hex;
 export declare function createFidesMcpServer(cfg: Config): McpServer & {
     agent: `0x${string}`;
 };

package/dist/server.js

@@ -14,7 +14,7 @@ import { pathToFileURL } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { encodeFunctionData, erc20Abi, formatUnits, parseUnits, isAddress, getAddress } from 'viem';
+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 { createX402, decodePaymentRequired, exactEip3009 } from '@fidesbuild/x402';
@@ -81,6 +81,52 @@ const KNOWN_SERVICES = [
     { 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' },
 ];
+/** Turns plain JSON values into what viem encodes for each ABI type. "me" is the FIDES Account. */
+export function coerce(p, v, me, at) {
+    const arr = p.type.match(/^(.*)\[(\d*)\]$/);
+    if (arr) {
+        if (!Array.isArray(v))
+            throw new Error(`${at} must be a list`);
+        return v.map((x, i) => coerce({ ...p, type: arr[1] }, x, me, `${at}[${i}]`));
+    }
+    if (p.type === 'tuple') {
+        const parts = p.components;
+        const get = (c, i) => (Array.isArray(v) ? v[i] : v?.[c.name ?? '']);
+        if (v === null || typeof v !== 'object')
+            throw new Error(`${at} must be an object with ${parts.map((c) => c.name).join(', ')}`);
+        const out = parts.map((c, i) => coerce(c, get(c, i), me, `${at}.${c.name ?? i}`));
+        return Array.isArray(v) || parts.some((c) => !c.name) ? out : Object.fromEntries(parts.map((c, i) => [c.name, out[i]]));
+    }
+    if (/^u?int\d*$/.test(p.type)) {
+        if (!/^-?\d+$/.test(String(v ?? '').trim()))
+            throw new Error(`${at} must be a whole number in the token's smallest unit, as a string (got ${JSON.stringify(v)})`);
+        return BigInt(String(v).trim());
+    }
+    if (p.type === 'address') {
+        if (typeof v === 'string' && /^me$/i.test(v)) {
+            if (!me)
+                throw new Error(`${at}: "me" needs a signed FIDES`);
+            return me;
+        }
+        if (typeof v !== 'string' || !isAddress(v))
+            throw new Error(`${at} must be an address`);
+        return getAddress(v);
+    }
+    if (p.type === 'bool')
+        return v === true || v === 'true';
+    if (/^bytes\d*$/.test(p.type)) {
+        const h = v === '' || v == null ? '0x' : String(v);
+        if (!/^0x([0-9a-fA-F]{2})*$/.test(h))
+            throw new Error(`${at} must be hex bytes, like "0x"`);
+        return h;
+    }
+    return v;
+}
+/** Encodes a call from one ABI function and plain JSON args. */
+export function encodeCall(abi, args, me) {
+    const values = abi.inputs.map((p, i) => coerce(p, args[i], me, p.name || `arg ${i + 1}`));
+    return encodeFunctionData({ abi: [abi], functionName: abi.name, args: values });
+}
 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) {
@@ -198,7 +244,8 @@ export function createFidesMcpServer(cfg) {
         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.',
+                'Use any verified contract on Robinhood Chain: read what it lets an agent do, risky functions flagged (fides_inspect_contract), allow the functions you choose (fides_setup with contracts), read values from it for free (fides_read_contract), and call it by function name and plain values (fides_plan with function and args). Example: supply USDG to a Morpho market and withdraw it, never borrow.',
+                'Use any paid API that charges on Robinhood Chain: read its price without paying (fides_check_api), allow it with a cap (fides_setup with services), then pay per request (fides_pay_request).',
                 '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.',
@@ -240,7 +287,7 @@ 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 paid API, call fides_check_api with its URL and use the service_id it returns. To let the agent call any contract on the chain, pass contracts with the functions it may call by name (fides_inspect_contract lists them and flags the risky ones).',
+        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 paid API, call fides_check_api with its URL and use the service_id it returns. To let the agent call any contract on the chain, pass contracts with the functions it may call by name (fides_inspect_contract lists them and flags the risky ones). When a function pulls tokens from the account (such as Morpho supply, or a vault deposit), also allow approve on that token, so the agent can approve exactly the amount in the same transaction.',
         inputSchema: {
             services: z.array(z.object({ id: z.string().describe('The service id: "fides-demo", "spraay", "madeonsol", or for any other paid API the service_id fides_check_api returns (its host)'), max: z.string().describe('Most the agent may spend on it, in USDG, e.g. "0.1"') })).optional(),
             contracts: z.array(z.object({
@@ -329,18 +376,20 @@ export function createFidesMcpServer(cfg) {
         }
     });
     const actionSchema = z.object({
-        kind: z.enum(['transfer', 'call']).describe('"transfer" sends a token from the FIDES Account. "call" calls an allowed contract with raw calldata.'),
+        kind: z.enum(['transfer', 'call']).describe('"transfer" sends a token from the FIDES Account. "call" calls an allowed contract, by function name and args (encoded from its verified source), or with raw calldata.'),
         to: z.string().optional().describe('transfer: the recipient address'),
-        amount: z.string().optional().describe('transfer: how much, in whole token units, e.g. "1.5". call: how much of the budget token the call spends, if any'),
+        amount: z.string().optional().describe('transfer: how much, in whole token units, e.g. "1.5". call: how much of the budget token the call spends, if any, in whole units'),
         token: z.string().optional().describe('transfer: the token address. Defaults to the FIDES\'s budget token'),
         target: z.string().optional().describe('call: the contract address'),
-        data: z.string().optional().describe('call: hex calldata, starting with the 4-byte function selector'),
+        function: z.string().optional().describe('call: the function name, e.g. "supply", or its signature when the name is overloaded. FIDES encodes the call from the contract\'s verified source'),
+        args: z.array(z.any()).optional().describe('call with function: the arguments in order. Integers as strings in the token\'s smallest unit (USDG has 6 decimals: 0.05 USDG is "50000"). Structs as objects keyed by field name. "me" for an address means this FIDES Account. Empty bytes as "0x"'),
+        data: z.string().optional().describe('call: hex calldata, starting with the 4-byte function selector. Use function and args instead when you can'),
         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()) {
+        for (let [i, a] of actions.entries()) {
             const n = i + 1;
             if (a.kind === 'transfer') {
                 if (!a.to || !isAddress(a.to))
@@ -364,8 +413,14 @@ export function createFidesMcpServer(cfg) {
             else {
                 if (!a.target || !isAddress(a.target))
                     return { error: `Action ${n}: "target" must be a contract address.` };
+                if (a.function && !a.data) {
+                    const enc = await encodeByName(getAddress(a.target), a.function, a.args ?? [], 'write');
+                    if ('error' in enc)
+                        return { error: `Action ${n}: ${enc.error}` };
+                    a = { ...a, data: enc.data, label: a.label ?? enc.label };
+                }
                 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.` };
+                    return { error: `Action ${n}: give "function" and "args", or "data" as hex calldata starting with the 4-byte selector.` };
                 const t = await token(budget);
                 let spend = 0n;
                 if (a.amount) {
@@ -384,7 +439,7 @@ export function createFidesMcpServer(cfg) {
     }
     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.',
+        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. Call contracts by function name and args; FIDES encodes them from the verified source. When a contract pulls tokens (e.g. Morpho supply), put an approve of exactly that amount first in the same plan, so nothing stays approved, and set amount on the call so it counts against the budget. Use "me" for addresses that should be the FIDES Account.',
         inputSchema: { actions: z.array(actionSchema).min(1).max(50) },
     }, async ({ actions }) => {
         try {
@@ -658,6 +713,42 @@ export function createFidesMcpServer(cfg) {
             throw new Error(json?.error?.message ?? `HTTP ${res.status}`);
         return json;
     }
+    /** Encodes a call to `fn` on `target` from the contract's verified ABI (standard ERC-20 functions work without one). */
+    async function encodeByName(target, fn, args, kind) {
+        let info = null;
+        try {
+            info = await inspect(target);
+        }
+        catch { /* fall back to ERC-20 below */ }
+        const list = (kind === 'write' ? info?.functions : info?.reads) ?? [];
+        const byName = (x) => x.abi.name === fn || `${x.abi.name}(${x.abi.inputs.map((i) => i.type).join(',')})` === fn.replace(/\s/g, '') || x.signature === fn;
+        let matches = list.filter((x) => x.abi && byName(x));
+        if (!matches.length) {
+            const std = erc20Abi.filter((x) => x.type === 'function' && x.name === fn && (kind === 'read') === (x.stateMutability === 'view'));
+            matches = std.map((abi) => ({ abi }));
+        }
+        if (matches.length > 1)
+            matches = matches.filter((x) => x.abi.inputs.length === args.length);
+        if (!matches.length) {
+            if (info && !info.verified)
+                return { error: `${target} is not verified on Sourcify, so "${fn}" cannot be encoded by name. Pass "data" as hex calldata instead.` };
+            const names = list.map((x) => x.name).filter(Boolean);
+            return { error: `${info?.name ?? target} has no ${kind === 'write' ? 'write' : 'read'} function "${fn}"${names.length ? `. It has: ${[...new Set(names)].join(', ')}` : ''}.` };
+        }
+        if (matches.length > 1)
+            return { error: `"${fn}" is overloaded; give its signature, one of: ${matches.map((x) => `${x.abi.name}(${x.abi.inputs.map((i) => i.type).join(',')})`).join(', ')}.` };
+        const abi = matches[0].abi;
+        if (args.length !== abi.inputs.length)
+            return { error: `${abi.name} takes ${abi.inputs.length} argument(s): ${abi.inputs.map((i) => `${i.type} ${i.name ?? ''}`.trim()).join(', ')}. Got ${args.length}.` };
+        const me = (await currentFides().catch(() => null))?.account ?? null;
+        try {
+            const data = encodeCall(abi, args, me);
+            return { data, label: `${info?.name ?? 'contract'}.${abi.name} on ${target}`, abi, name: info?.name ?? null };
+        }
+        catch (err) {
+            return { error: err?.shortMessage ?? err?.message ?? String(err) };
+        }
+    }
     server.registerTool('fides_inspect_contract', {
         title: 'What a contract lets an agent do',
         description: 'Reads any contract on the chain from its verified source (proxies followed) and lists the functions that change something, in plain words, with risks flagged: "danger" (lasting approvals, handing control to another address, upgrades, debt), "warn" (the agent picks where funds go, or it sends ETH) and "admin" (operator-only; will fail for an agent). Use it before fides_setup with contracts, and recommend only the functions the user needs. Sends nothing.',
@@ -672,13 +763,38 @@ export function createFidesMcpServer(cfg) {
             return ok({
                 name: info.name, address: info.address, verified: true, proxy: info.proxy ?? undefined,
                 functions: info.functions.map((fn) => ({ name: fn.name, does: fn.about || undefined, signature: fn.signature, selector: fn.selector, risks: fn.risks.length ? fn.risks.map((r) => `${r.level}: ${r.why}`) : undefined })),
-                next: 'To allow some of these, call fides_setup with contracts: [{ address, functions: [names] }] and give the user the link.',
+                reads: info.reads?.length ? info.reads.map((fn) => fn.signature) : undefined,
+                next: 'To allow some of these, call fides_setup with contracts: [{ address, functions: [names] }] and give the user the link. Once signed, call them with fides_plan: { kind: "call", target, function, args }. Read functions are free: fides_read_contract.',
             });
         }
         catch (err) {
             return fail('Could not read the contract: ' + (err?.message ?? err));
         }
     });
+    server.registerTool('fides_read_contract', {
+        title: 'Read from a contract',
+        description: 'Calls a read-only (view) function on any verified contract on the chain, by name, and returns the result. Free: nothing is signed or sent, and it needs no permission in the FIDES. Use it to look up what a write needs, such as a market\'s parameters or a balance. Integers come back as strings in the smallest unit.',
+        inputSchema: {
+            address: z.string().describe('The contract address'),
+            function: z.string().describe('The view function name, or its signature when overloaded'),
+            args: z.array(z.any()).optional().describe('The arguments in order. Integers as strings. "me" for an address means this FIDES Account'),
+        },
+    }, async ({ address, function: fn, args }) => {
+        try {
+            if (!isAddress(address))
+                return fail('That is not a contract address.');
+            const enc = await encodeByName(getAddress(address), fn, args ?? [], 'read');
+            if ('error' in enc)
+                return fail(enc.error);
+            const { data } = await client.public.call({ to: getAddress(address), data: enc.data });
+            const result = decodeFunctionResult({ abi: [enc.abi], functionName: enc.abi.name, data: data ?? '0x' });
+            const named = enc.abi.outputs.length > 1 && enc.abi.outputs.every((o) => o.name) && Array.isArray(result) ? Object.fromEntries(enc.abi.outputs.map((o, i) => [o.name, result[i]])) : result;
+            return ok({ contract: enc.name ?? address, function: enc.abi.name, result: JSON.parse(JSON.stringify(named, (_k, x) => (typeof x === 'bigint' ? x.toString() : x))) });
+        }
+        catch (err) {
+            return fail('Could not read: ' + failure(err?.shortMessage ?? err?.message ?? err));
+        }
+    });
     server.registerTool('fides_check_api', {
         title: 'Can FIDES pay this API?',
         description: 'Calls a paid API\'s URL once, without paying, and reads its x402 price: whether a FIDES on Robinhood Chain can pay it, the price, who is paid, and the service id and a suggested cap to use with fides_setup. Use it when the user wants the agent to use a paid API that is not one of the known ones. Pays nothing.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidesbuild/mcp-server",
-  "version": "0.8.0",
+  "version": "0.8.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",
@@ -14,14 +14,9 @@
   "homepage": "https://fidesbuilder.xyz/docs",
   "license": "MIT",
   "type": "module",
-  "exports": {
-    ".": {
-      "types": "./dist/server.d.ts",
-      "default": "./dist/server.js"
-    }
-  },
+  "exports": "./src/server.ts",
   "bin": {
-    "fides-mcp": "./dist/server.js"
+    "fides-mcp": "./src/server.ts"
   },
   "files": [
     "dist",
@@ -32,7 +27,16 @@
     "node": ">=20.10"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      }
+    },
+    "bin": {
+      "fides-mcp": "./dist/server.js"
+    }
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
@@ -44,4 +48,4 @@
     "@fidesbuild/sub": "0.2.0",
     "@fidesbuild/swap": "0.2.0"
   }
-}
+}