@fidesbuild/mcp-server 0.4.0 → 0.4.1

package/README.md

@@ -42,7 +42,8 @@ Claude Code and other MCP apps need [Node](https://nodejs.org) 20.10 or later. C
 | `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 |
-| `fides_use_file` | Loads an `fides.json` file, for a FIDES that was not signed in the app |
+| `fides_help` | What you can do with FIDES, the paid APIs known to work with their prices, and what to try |
+| `fides_use_file` | Loads a `fides.json` file, for a FIDES that was not signed in the app |
 
 The FIDES used is the newest valid one signed for this agent: from the FIDES API, where the app shares a FIDES when it is signed, or from the copy kept in `~/.fides`. Each is verified onchain before it is used.
 
@@ -50,6 +51,16 @@ The FIDES used is the newest valid one signed for this agent: from the FIDES API
 
 Claude can buy from APIs that charge per request over x402, from your FIDES. Each paid service is named in the FIDES with a cap; anything not named, or past its cap, is refused before paying. To try it, ask Claude: "Set up FIDES with the fides-demo paid service, up to 0.1 USDG", sign, then "Buy the chain stats from the FIDES demo" (0.01 USDG for Robinhood Chain's latest block, gas price and USDG supply).
 
+Paid APIs known to work, each bought through FIDES with real payments on mainnet:
+
+| Service id | URL | Price |
+| --- | --- | --- |
+| `fides-demo` | `https://api.fidesbuilder.xyz/v1/demo/chain-stats` | 0.01 USDG |
+| `spraay` | `https://gateway.spraay.app/api/v1/models` | 0.001 USDG |
+| `madeonsol` | `https://madeonsol.com/api/x402/rhc/kol/feed?limit=5` | 0.04 USDG |
+
+Any API that charges USDG on Robinhood Chain over x402 (`exact`, EIP-3009) works the same way. The service id is any name you choose when you sign. Ask Claude "What can you do with FIDES?" to get this list in the chat.
+
 ## Other MCP apps
 
 Add a server with the command `npx` and the arguments `-y @fidesbuild/mcp-server@latest` (on Windows, the command `cmd` and the arguments `/c npx -y @fidesbuild/mcp-server@latest`). `npx -y @fidesbuild/mcp-server setup` makes the agent key and prints the setup link from a terminal.

package/dist/server.js

@@ -71,6 +71,12 @@ function failure(reason) {
         return 'The hosted relayer cannot pay for gas right now. Try later, or set FIDES_RELAY=self and give the agent address a little ETH.';
     return r;
 }
+// Paid APIs that have been bought through FIDES with real payments on mainnet (the docs list the same ones).
+const KNOWN_SERVICES = [
+    { id: 'fides-demo', name: 'FIDES demo', url: 'https://api.fidesbuilder.xyz/v1/demo/chain-stats', price: '0.01 USDG', returns: 'Robinhood Chain\'s latest block, gas price and USDG supply', run_by: 'FIDES' },
+    { 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' },
+];
 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) {
@@ -161,10 +167,46 @@ 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.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, and an expiry. ' +
+    const server = new McpServer({ name: 'fides', version: '0.4.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".',
+            '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.',
+    });
+    server.registerTool('fides_help', {
+        title: 'What FIDES can do',
+        description: 'Use when the user asks what you can do with FIDES, what paid APIs or services are available, what to try, or how to get started. Returns what FIDES can do, paid APIs known to work with their URL and price, example requests, and the next step for this user.',
+        inputSchema: {},
+    }, async () => {
+        let fides = null;
+        try {
+            fides = await currentFides();
+        }
+        catch { /* answer without it */ }
+        const allowed = fides?.services.map((s) => s.serviceId) ?? [];
+        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.',
+                'Buy from paid APIs that charge per request over x402, paying from the FIDES budget, each capped per service.',
+                '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.',
+            ],
+            paid_apis: KNOWN_SERVICES.map((s) => ({ ...s, in_this_fides: allowed.includes(s.id) })),
+            other_paid_apis: 'Any API that charges USDG on Robinhood Chain over x402 (exact scheme, EIP-3009) works the same way. The user adds it as a service with a cap when signing (the id is any name they choose), then gives you its URL.',
+            try_saying: [
+                'Set up FIDES with these paid services: fides-demo up to 0.1 USDG, spraay up to 0.01 USDG, madeonsol up to 0.1 USDG',
+                'Pay 0.5 USDG to 0x... and 0.5 USDG to 0x...',
+                'Buy the chain stats from the FIDES demo',
+                'What\'s left in my FIDES?',
+                'Show what you\'ve executed',
+            ],
+            next_step: !fides ? 'No FIDES is set up yet. Offer to call fides_setup, with any paid services the user wants and a cap for each.'
+                : !allowed.length ? 'This FIDES has no paid services. To use a paid API, call fides_setup with the services and caps, and the user signs the new FIDES.'
+                    : `This FIDES allows these paid services: ${allowed.join(', ')}. Make sure the FIDES Account holds USDG (fides_status shows the balance).`,
+            docs: 'https://fidesbuilder.xyz/docs#/claude',
+        });
     });
     server.registerTool('fides_status', {
         title: 'FIDES status',
@@ -185,8 +227,8 @@ 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; for FIDES\'s own paid demo use id "fides-demo".',
-        inputSchema: { services: z.array(z.object({ id: z.string().describe('A name for the paid service, e.g. "fides-demo"'), max: z.string().describe('Most the agent may spend on it, in USDG, e.g. "0.1"') })).optional() },
+        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({
         agent_address: agent.address,
         link: setupLink + (services ?? []).map((x) => `&service=${encodeURIComponent(x.id)}:${encodeURIComponent(x.max)}`).join(''),
@@ -350,7 +392,7 @@ export function createFidesMcpServer(cfg) {
     };
     server.registerTool('fides_pay_request', {
         title: 'Buy from a paid API',
-        description: 'Fetches a URL from a paid API that charges per request over x402, paying from the FIDES budget. Reads the price first and refuses if it is over the service\'s cap in the FIDES or over max_price. Moves exactly the price from the FIDES Account to the agent key, pays, and returns the response. The service must be in the FIDES (its services list). For FIDES\'s own demo, the URL is https://api.fidesbuilder.xyz/v1/demo/chain-stats and the service is "fides-demo". Tell the user the price and get their OK before paying unless they already asked you to buy it.',
+        description: `Fetches a URL from a paid API that charges per request over x402, paying from the FIDES budget. Reads the price first and refuses if it is over the service\'s cap in the FIDES or over max_price. Moves exactly the price from the FIDES Account to the agent key, pays, and returns the response. The service must be in the FIDES (its services list). Known URLs: ${KNOWN_SERVICES.map((s) => `"${s.id}" ${s.url}`).join(', ')}. Tell the user the price and get their OK before paying unless they already asked you to buy it.`,
         inputSchema: {
             url: z.string().describe('The paid API URL'),
             service: z.string().optional().describe('The service id in the FIDES. Can be left out if the FIDES has exactly one service'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidesbuild/mcp-server",
-  "version": "0.4.0",
+  "version": "0.4.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",