@agents-trust/mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agents Trust
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# Agents Trust MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Find APIs for your task from Claude Desktop, Cursor or Claude Code. Recommendations include URLs, prices and call details. Inspect returns the stored evidence for one exact endpoint URL. This stdio server runs on your computer. Paid calls use your own wallet; Agents Trust holds no wallet keys.
+
+Runtime requires Node.js 20 or later. Install from npm; your MCP host starts it over standard input/output:
+
+```sh
+npx -y @agents-trust/mcp
+```
+
+Supply a wallet only to the runtime launcher (see Configuration). To build from source instead, see Development.
+
+## Tools and cost
+
+| Tool | Input | Result | Fee |
+| --- | --- | --- | --- |
+| `recommend` | `need`; optional `limit`, `live`, `max_price_usd`, `chain`, `view` | APIs for your task and call details | 0.01 USDC outside the free demos |
+| `inspect` | `url`; optional `view` | Stored endpoint evidence without calling the provider | 1% of the endpoint's lowest quoted price, minimum 0.001 USDC |
+| `receipt` | `payment_attempt_id` | Eventual settlement result | Free |
+| `health` | none | Service version | Free |
+
+Ask your host to call `inspect` with an exact endpoint URL from a recommendation. Preserve its fixed query parameters. For `inspect`, `view` accepts `legacy`, `compact`, `evidence` or `debug`; for `recommend` it accepts `legacy`, `compact` or `evidence`. Omitting it uses the API's legacy response. An unknown URL returns an unpaid 404. The API rejects malformed, credential-bearing and private URLs before payment. Inspect never calls or purchases the provider's service.
+
+`recommend` inputs: `need` is 2–300 characters with at least two letters or digits; `limit` is 1–5; `live` may be `1` to prefer recently verified endpoints; `chain` is a CAIP-2 network such as `eip155:8453`; `max_price_usd` is a non-negative number. `receipt` takes the `payment_attempt_id` returned with a paid answer (a UUID version 7).
+
+Example: ask your host to call `recommend` with `{"need":"weather","view":"compact"}`. Free demos may change. `max_price_usd` limits a recommended provider's price; it does not limit the recommendation fee. Calling a recommended API is a separate purchase.
+
+A paid answer includes `payment_attempt_id` when available. Use `receipt` to check settlement; receiving an answer does not confirm settlement. A pending receipt can be looked up again for free.
+
+## Configuration
+
+| Environment variable | Default | Purpose |
+| --- | --- | --- |
+| `AGENTS_TRUST_ENABLE_PAYMENTS` | unset / disabled | Owner opt-in: exact `true` grants at most one payment authorization per server process |
+| `AGENTS_TRUST_WALLET_PRIVATE_KEY` | unset | Your EVM private key, with `0x` prefix; needed for paid calls |
+| `AGENTS_TRUST_MAX_CALL_USDC` | `0.01` | Maximum fee for one Recommend or Inspect call in USDC |
+| `AGENTS_TRUST_SESSION_CAP_USDC` | `0.01` | Maximum reserved spend for one server process |
+
+Payments stay disabled even when a wallet key is present. The wallet owner can explicitly supply `AGENTS_TRUST_ENABLE_PAYMENTS=true` in the local launcher or select the bundle’s payment opt-in. This grants the process one authorization within the monetary caps; there is no per-call human confirmation. An agent tool argument, service response or provider instruction cannot grant payment authority. Use a dedicated low-balance wallet with USDC on **Base mainnet**. The server signs x402 authorizations locally and sends them only to `https://api.agents-trust.com`. It accepts the published Base USDC asset and Agents Trust payment address. A changed address requires a server update. Other payment networks are unsupported.
+
+Limits accept non-negative decimal strings with up to six decimal places. Zero disables paid calls. Reservations count signing attempts, including failed or uncertain requests, and remain reserved until the process exits. The process consumes its single authorization before signing, even if signing or the request fails. Raising a monetary cap does not allow a second authorization. Free calls and receipts remain available. Restarting the server resets both the session cap and the authorization grant. Stop the host from automatically restarting with payment opt-in until the wallet owner has reconciled prior attempts. Recommend and Inspect share the same grant, reservation cap and serialized payment queue, including concurrent calls. Paid submissions are never automatically repeated. On an uncertain result, check your wallet and any receipt before making another paid call.
+
+Without a key, free tools and free demo recommendations work. A paid Recommend or Inspect request returns a message explaining which variable to configure. Keep keys out of chat, version control and shell history. Have your local secret manager or host supply the wallet variable to the child process.
+
+### Claude Desktop
+
+Merge this into `claude_desktop_config.json`. The free configuration requires no key:
+
+```json
+{
+  "mcpServers": {
+    "agents-trust": {
+      "command": "npx",
+      "args": ["-y", "@agents-trust/mcp"],
+      "env": {
+        "AGENTS_TRUST_MAX_CALL_USDC": "0.01",
+        "AGENTS_TRUST_SESSION_CAP_USDC": "0.01"
+      }
+    }
+  }
+}
+```
+
+For paid calls, explicitly grant `AGENTS_TRUST_ENABLE_PAYMENTS=true` and supply `AGENTS_TRUST_WALLET_PRIVATE_KEY` to this process through your secure local launcher. GUI applications need the full path to your Node executable and do not always inherit your terminal environment.
+
+### Cursor
+
+Use the same `mcpServers` block in `~/.cursor/mcp.json` or `.cursor/mcp.json`, adding `"type": "stdio"` to the server entry ([Cursor configuration](https://cursor.com/docs/mcp)). To read a key already injected into Cursor's environment, add this entry to the server's `env` object:
+
+```json
+"AGENTS_TRUST_WALLET_PRIVATE_KEY": "${env:AGENTS_TRUST_WALLET_PRIVATE_KEY}"
+```
+
+Keep wallet configuration local; do not commit it.
+
+### Claude Code
+
+```sh
+claude mcp add --transport stdio agents-trust -- npx -y @agents-trust/mcp
+```
+
+See [Claude Code MCP configuration](https://code.claude.com/docs/en/mcp). Launch Claude Code with payment opt-in chosen by the wallet owner and the wallet variable supplied by your secret manager. The server inherits it from the host.
+
+## Development
+
+Build from source in a shell without `AGENTS_TRUST_WALLET_PRIVATE_KEY`; the build and bundle commands refuse that variable even when it is empty.
+
+```sh
+git clone https://github.com/agents-trust/agents-trust-mcp.git
+cd agents-trust-mcp
+npm ci
+npm run typecheck
+npm run lint
+npm test
+npm run build
+```
+
+Run the local server with `node dist/index.js`. Standard output carries MCP messages only. Tests generate throwaway keys in memory and make no payments. Development tests require Node.js 22.13+ or 24; CI also checks the built stdio server on Node.js 20.
+
+`npm run test:paid` is an offline cryptographic authorization test using a generated throwaway key and mocked HTTP. No test reads a funded wallet or submits a real payment. Dependency installation scripts are disabled by `.npmrc`; use `npm ci` to preserve the reviewed lockfile. The bundle packer is also locked locally.
+
+MIT licensed. See [LICENSE](LICENSE).

package/dist/api.js

@@ -0,0 +1,122 @@
+import { x402Client, x402HTTPClient } from '@x402/fetch';
+import { ExactEvmScheme } from '@x402/evm/exact/client';
+import { privateKeyToAccount } from 'viem/accounts';
+const ORIGIN = 'https://api.agents-trust.com';
+const USDC = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913';
+const PAYEE = '0x96368628b679a459fe69815bacca5cb0232ac397';
+export function units(value) {
+    if (!/^(0|[1-9]\d*)(\.\d{1,6})?$/.test(value))
+        throw new Error('Invalid USDC limit; use up to six decimal places.');
+    const [whole, fraction = ''] = value.split('.');
+    return BigInt(whole) * 1000000n + BigInt(fraction.padEnd(6, '0'));
+}
+export class AgentsTrustApi {
+    settings;
+    request;
+    spent = 0n;
+    authorizationUsed = false;
+    tail = Promise.resolve();
+    maxCall;
+    sessionCap;
+    constructor(settings = {}, request = fetch) {
+        this.settings = settings;
+        this.request = request;
+        this.maxCall = units(settings.maxCallUsdc ?? '0.01');
+        this.sessionCap = units(settings.sessionCapUsdc ?? '0.01');
+    }
+    // Count every signing attempt conservatively, including failures and uncertain responses.
+    recommend(params) {
+        return this.paidCall('/recommend', params);
+    }
+    inspect(params) {
+        return this.paidCall('/inspect', params);
+    }
+    paidCall(path, params) {
+        const task = this.tail.then(() => this.call(path, params, true));
+        this.tail = task.catch(() => undefined);
+        return task;
+    }
+    health() { return this.call('/health', {}); }
+    receipt(paymentAttemptId) { return this.call('/receipt', { payment_attempt_id: paymentAttemptId }); }
+    select(required, url) {
+        if (required.x402Version !== 2 || required.resource?.url !== url || !Array.isArray(required.accepts)) {
+            throw new Error('Unsupported payment challenge. No payment sent.');
+        }
+        const offer = required.accepts.find(o => o.scheme === 'exact' && o.network === 'eip155:8453'
+            && o.asset.toLowerCase() === USDC && o.payTo.toLowerCase() === PAYEE
+            && typeof o.amount === 'string' && /^[1-9]\d*$/.test(o.amount)
+            && Number.isInteger(o.maxTimeoutSeconds) && o.maxTimeoutSeconds > 0 && o.maxTimeoutSeconds <= 300
+            && o.extra?.name === 'USD Coin' && o.extra?.version === '2'
+            && (o.extra?.assetTransferMethod === undefined || o.extra.assetTransferMethod === 'eip3009'));
+        if (!offer)
+            throw new Error('No supported Base USDC payment offer. No payment sent.');
+        const amount = BigInt(offer.amount);
+        if (amount > this.maxCall)
+            throw new Error('Price exceeds AGENTS_TRUST_MAX_CALL_USDC. No payment sent.');
+        if (this.spent + amount > this.sessionCap)
+            throw new Error('Session spend cap reached. No payment sent.');
+        return offer;
+    }
+    async send(url, headers) {
+        return this.request(url, { headers, redirect: 'error', signal: AbortSignal.timeout(30_000) });
+    }
+    async call(path, params, paid = false) {
+        const url = new URL(path, ORIGIN);
+        for (const [name, value] of Object.entries(params))
+            if (value !== undefined)
+                url.searchParams.set(name, String(value));
+        let response;
+        try {
+            response = await this.send(url.href);
+        }
+        catch {
+            throw new Error('Agents Trust request failed.');
+        }
+        if (response.status === 402 && paid) {
+            if (this.settings.enablePayments !== true)
+                throw new Error('Payments disabled. The wallet owner must configure AGENTS_TRUST_ENABLE_PAYMENTS=true for one authorization per process.');
+            if (this.authorizationUsed)
+                throw new Error('Payment authorization already used in this process. Check your wallet and receipt before granting another process permission.');
+            if (!this.settings.walletKey)
+                throw new Error('Set AGENTS_TRUST_WALLET_PRIVATE_KEY to pay with Base USDC.');
+            try {
+                const account = privateKeyToAccount(this.settings.walletKey);
+                const client = new x402Client().register('eip155:8453', new ExactEvmScheme(account));
+                const http = new x402HTTPClient(client);
+                const required = http.getPaymentRequiredResponse(name => response.headers.get(name));
+                // Inspect quotes bind the canonical endpoint, without the response view.
+                // Keep the original request URL for both HTTP requests.
+                const endpoint = path === '/inspect' ? new URL(String(params.url)) : null;
+                const resource = endpoint
+                    ? `${ORIGIN}/inspect?url=${encodeURIComponent(`${endpoint.protocol}//${endpoint.host}${endpoint.pathname}${endpoint.search}`)}`
+                    : url.href;
+                const offer = this.select(required, resource);
+                this.spent += BigInt(offer.amount);
+                this.authorizationUsed = true;
+                const payload = await http.createPaymentPayload({ ...required, accepts: [offer] });
+                // Preserve the challenge extensions; never automatically retry an authorization.
+                response = await this.send(url.href, http.encodePaymentSignatureHeader(payload));
+            }
+            catch (error) {
+                if (error instanceof Error && /^(Price exceeds|Session spend cap|No supported Base|Unsupported payment)/.test(error.message))
+                    throw error;
+                // Discard upstream error details: they can contain signing inputs.
+                // eslint-disable-next-line preserve-caught-error
+                throw new Error('Payment could not complete. Budget remains reserved; check your wallet and receipt before another call.');
+            }
+        }
+        if (!response.ok)
+            throw new Error(`Agents Trust returned HTTP ${response.status}. No automatic retry was made.`);
+        try {
+            const body = await response.json();
+            return {
+                data: body,
+                payment_attempt_id: response.headers.get('x-at-payment-attempt-id'),
+                request_id: response.headers.get('x-at-request-id'),
+            };
+        }
+        catch {
+            throw new Error('Agents Trust returned an unreadable response. Check any payment receipt before another call.');
+        }
+    }
+}

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+try {
+    const server = createServer({
+        enablePayments: process.env.AGENTS_TRUST_ENABLE_PAYMENTS === 'true',
+        walletKey: process.env.AGENTS_TRUST_WALLET_PRIVATE_KEY,
+        maxCallUsdc: process.env.AGENTS_TRUST_MAX_CALL_USDC,
+        sessionCapUsdc: process.env.AGENTS_TRUST_SESSION_CAP_USDC,
+    });
+    await server.connect(new StdioServerTransport());
+}
+catch {
+    process.stderr.write('Agents Trust could not start. Check wallet and USDC limit configuration.\n');
+    process.exitCode = 1;
+}

package/dist/server.js

@@ -0,0 +1,59 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { AgentsTrustApi } from './api.js';
+export function createServer(settings = {}, request = fetch) {
+    const api = new AgentsTrustApi(settings, request);
+    const server = new McpServer({ name: 'agents-trust', version: '0.1.0' });
+    const run = async (action) => {
+        try {
+            let text = JSON.stringify(await action());
+            if (settings.walletKey)
+                text = text.split(settings.walletKey).join('[redacted]');
+            return { content: [{ type: 'text', text }] };
+        }
+        catch (error) {
+            let text = error instanceof Error ? error.message : 'Agents Trust request failed.';
+            if (settings.walletKey)
+                text = text.split(settings.walletKey).join('[redacted]');
+            return { isError: true, content: [{ type: 'text', text }] };
+        }
+    };
+    server.registerTool('recommend', {
+        description: 'Find APIs for your task, with URLs, prices and call details. Payment requires owner opt-in and consumes the process’s single authorization, up to the configured USDC limit.',
+        inputSchema: {
+            need: z.string().refine(s => Array.from(s).length >= 2 && Array.from(s).length <= 300 && /[\p{L}\p{N}].*[\p{L}\p{N}]/u.test(s), 'Use 2–300 characters with at least two letters or digits.'),
+            limit: z.number().int().min(1).max(5).optional(),
+            live: z.literal(1).optional(),
+            max_price_usd: z.number().finite().min(0).optional().describe('Maximum provider price; separate from the recommendation fee.'),
+            chain: z.string().regex(/^[a-z0-9-]{2,16}:[A-Za-z0-9_=-]{1,64}$/).optional(),
+            view: z.enum(['legacy', 'compact', 'evidence']).optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, args => run(() => api.recommend(args)));
+    server.registerTool('inspect', {
+        description: 'Read stored evidence for one exact API endpoint URL, without calling or paying that provider. The Inspect fee is 1% of the endpoint\'s lowest quoted price, with a 0.001 USDC floor. Read the actual quote. Payment requires owner opt-in and shares the process\'s single authorization and USDC limits with Recommend.',
+        inputSchema: {
+            url: z.string().min(1).max(2048).refine(value => {
+                try {
+                    const url = new URL(value);
+                    return url.protocol === 'https:' && !url.username && !url.password;
+                }
+                catch {
+                    return false;
+                }
+            }, 'Use an absolute HTTPS endpoint URL without credentials.').describe('Exact endpoint URL, including its fixed query parameters. The API rejects private URLs before payment.'),
+            view: z.enum(['legacy', 'compact', 'evidence', 'debug']).optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, args => run(() => api.inspect(args)));
+    server.registerTool('receipt', {
+        description: 'Look up payment settlement by payment attempt ID. Free.',
+        inputSchema: { payment_attempt_id: z.uuid() },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, args => run(() => api.receipt(args.payment_attempt_id)));
+    server.registerTool('health', {
+        description: 'Read the Agents Trust service version. Free.', inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, () => run(() => api.health()));
+    return server;
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@agents-trust/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Find APIs, inspect endpoint evidence and look up payment receipts with Agents Trust.",
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "prepack": "npm run build",
+    "test:paid": "vitest run test/paid.test.ts",
+    "smoke": "node scripts/smoke.mjs",
+    "bundle": "npm run build && node scripts/bundle.mjs",
+    "check:artifacts": "node scripts/check-artifacts.mjs"
+  },
+  "keywords": [],
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@x402/core": "2.28.0",
+    "@x402/evm": "2.28.0",
+    "@x402/fetch": "2.28.0",
+    "viem": "2.57.7",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "22.20.5",
+    "eslint": "10.12.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.71.2",
+    "vitest": "5.0.5",
+    "fflate": "0.8.3"
+  },
+  "bin": {
+    "agents-trust-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "server.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agents-trust/agents-trust-mcp.git"
+  },
+  "homepage": "https://agents-trust.com",
+  "mcpName": "com.agents-trust/recommend",
+  "publishConfig": {
+    "access": "public"
+  },
+  "overrides": {
+    "zod": "4.6.7",
+    "body-parser": "2.4.0",
+    "fast-uri": "3.1.9"
+  }
+}

package/server.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "com.agents-trust/recommend",
+  "title": "Agents Trust",
+  "description": "Find APIs and inspect endpoint evidence. Pay with your own Base USDC wallet.",
+  "version": "0.1.1",
+  "websiteUrl": "https://agents-trust.com",
+  "repository": {
+    "url": "https://github.com/agents-trust/agents-trust-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@agents-trust/mcp",
+      "version": "0.1.1",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "AGENTS_TRUST_ENABLE_PAYMENTS",
+          "description": "Owner opt-in: exactly true allows one payment authorization per server process",
+          "isRequired": false,
+          "default": "false",
+          "format": "string"
+        },
+        {
+          "name": "AGENTS_TRUST_WALLET_PRIVATE_KEY",
+          "description": "Your wallet private key for Base USDC payments",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        },
+        {
+          "name": "AGENTS_TRUST_MAX_CALL_USDC",
+          "description": "Maximum Recommend or Inspect fee in USDC",
+          "default": "0.01",
+          "format": "string"
+        },
+        {
+          "name": "AGENTS_TRUST_SESSION_CAP_USDC",
+          "description": "Per-process USDC reservation cap",
+          "default": "0.01",
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}