@agents-trust/mcp 0.1.1 → 0.1.2

package/dist/api.js

@@ -74,7 +74,7 @@ export class AgentsTrustApi {
         }
         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.');
+                throw new Error('Payments disabled. The wallet owner must configure AGENTS_TRUST_ENABLE_PAYMENTS=true for one authorization per process' + (this.settings.walletKey ? '.' : ' and supply AGENTS_TRUST_WALLET_PRIVATE_KEY.'));
             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)
@@ -105,8 +105,20 @@ export class AgentsTrustApi {
                 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.`);
+        if (!response.ok) {
+            let detail;
+            try {
+                const body = await response.json();
+                const code = typeof body?.error?.code === 'string' ? body.error.code : '';
+                const message = typeof body?.error?.message === 'string' ? body.error.message : '';
+                detail = [code, message].filter(Boolean).join(': ').replace(/\s+/g, ' ').slice(0, 200);
+            }
+            catch {
+                detail = '';
+            }
+            const retry = this.authorizationUsed && paid ? ' No automatic retry was made.' : '';
+            throw new Error(`Agents Trust returned HTTP ${response.status}${detail ? ` (${detail})` : ''}.${retry}`);
+        }
         try {
             const body = await response.json();
             return {

package/dist/server.js

@@ -1,9 +1,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { AgentsTrustApi } from './api.js';
+const RESULT = 'Returns JSON {data, payment_attempt_id, request_id}; payment_attempt_id is set only after a paid answer.';
+const PAYMENT = 'Paying needs the wallet owner to set AGENTS_TRUST_ENABLE_PAYMENTS=true and AGENTS_TRUST_WALLET_PRIVATE_KEY (Base USDC); one paid call per process, capped by AGENTS_TRUST_MAX_CALL_USDC (default 0.01). Otherwise it returns an error and sends nothing. Errors and empty results are free; paid calls are never retried.';
 export function createServer(settings = {}, request = fetch) {
     const api = new AgentsTrustApi(settings, request);
-    const server = new McpServer({ name: 'agents-trust', version: '0.1.0' });
+    const server = new McpServer({ name: 'agents-trust', version: '0.1.2' });
     const run = async (action) => {
         try {
             let text = JSON.stringify(await action());
@@ -19,19 +21,33 @@ export function createServer(settings = {}, request = fetch) {
         }
     };
     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.',
+        title: 'Recommend paid APIs for a task',
+        description: [
+            'Find which paid x402 API to call for a task described in plain words, ranked with evidence. Each pick has the endpoint URL, provider price and payment network, a ready request template, liveness, delivery evidence and risk flags.',
+            'Use it when you do not yet know which API to call; use inspect instead when you already have one exact endpoint URL, and receipt to confirm settlement after paying.',
+            'Weather, crypto prices and web search are free demo needs; other needs cost 0.01 USDC.',
+            PAYMENT, RESULT,
+            'Returns fewer picks, or none, when evidence is insufficient.',
+        ].join(' '),
         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(),
+            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.')
+                .describe('The work you need done, in plain words, e.g. "weather forecast for Berlin" or "translate text to German". 2–300 characters with at least two letters or digits.'),
+            limit: z.number().int().min(1).max(5).optional().describe('Maximum number of picks, 1–5. Default 3.'),
+            live: z.literal(1).optional().describe('Only 1 is accepted, which is also the default: prefer endpoints with recent liveness evidence.'),
+            max_price_usd: z.number().finite().min(0).optional().describe('Highest provider price per call in USD you accept. Separate from the 0.01 USDC recommendation fee; the provider\'s own quote at call time is authoritative.'),
+            chain: z.string().regex(/^[a-z0-9-]{2,16}:[A-Za-z0-9_=-]{1,64}$/).optional().describe('Only return providers that accept payment on this network, as a CAIP-2 id, e.g. eip155:8453 for Base.'),
+            view: z.enum(['legacy', 'compact', 'evidence']).optional().describe('Response detail: compact (smallest, pick essentials and request template), evidence (adds ranking, liveness, delivery and payment evidence per pick) or legacy (default, original field layout).'),
         },
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        annotations: { title: 'Recommend paid APIs for a task', 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.',
+        title: 'Inspect evidence for one endpoint',
+        description: [
+            'Read the stored evidence for one exact x402 endpoint URL: price, payment networks, liveness, delivery history and risk flags. It never calls or pays the endpoint itself.',
+            'Use it before paying an endpoint you already know, for example one returned by recommend; use recommend instead to find candidates for a task.',
+            'Demo endpoints are free; other indexed endpoints cost 1% of the endpoint\'s lowest quoted price, minimum 0.001 USDC. An unindexed URL returns ENDPOINT_NOT_INDEXED without payment.',
+            PAYMENT, RESULT,
+        ].join(' '),
         inputSchema: {
             url: z.string().min(1).max(2048).refine(value => {
                 try {
@@ -41,19 +57,33 @@ export function createServer(settings = {}, request = fetch) {
                 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(),
+            }, 'Use an absolute HTTPS endpoint URL without credentials.').describe('Exact public HTTPS endpoint URL, including any fixed query parameters, e.g. a pick\'s url from recommend. Private, malformed and credential-bearing URLs are rejected before payment.'),
+            view: z.enum(['legacy', 'compact', 'evidence', 'debug']).optional().describe('Response detail: compact (smallest), evidence (full evidence blocks), legacy (default, original field layout) or debug (adds diagnostic fields).'),
         },
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        annotations: { title: 'Inspect evidence for one endpoint', 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 },
+        title: 'Check payment settlement',
+        description: [
+            'Check whether a paid recommend or inspect answer has settled on-chain. Free, read-only, and never repeats the paid request.',
+            'Use it after a paid call, with the payment_attempt_id that call returned; answers arrive before settlement completes.',
+            'Returns data.state (pending, settled, settle_failed_after_answer or settle_unknown_after_answer) and data.transaction (transaction hash once settled, else null).',
+            'An unknown id returns a not-found error. Pending or unavailable does not prove that no money moved: check the wallet before paying again.',
+        ].join(' '),
+        inputSchema: {
+            payment_attempt_id: z.uuid({ version: 'v7' }).describe('The payment_attempt_id returned by a paid recommend or inspect call: a lowercase UUIDv7. Copy it unchanged.'),
+        },
+        annotations: { title: 'Check payment settlement', readOnlyHint: true, destructiveHint: false, idempotentHint: 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 },
+        title: 'Check service version',
+        description: [
+            'Check that the Agents Trust API is reachable and read its deployed version. Free, read-only, no parameters.',
+            'Use it to diagnose connection problems before retrying recommend or inspect; it does not measure data freshness.',
+            'Returns data.status ("ok") and data.version (deployment identifier).',
+        ].join(' '),
+        inputSchema: {},
+        annotations: { title: 'Check service version', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, () => run(() => api.health()));
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-trust/mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Find APIs, inspect endpoint evidence and look up payment receipts with Agents Trust.",
   "scripts": {
     "build": "node scripts/build.mjs",

package/server.json

@@ -3,7 +3,7 @@
   "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",
+  "version": "0.1.2",
   "websiteUrl": "https://agents-trust.com",
   "repository": {
     "url": "https://github.com/agents-trust/agents-trust-mcp",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "@agents-trust/mcp",
-      "version": "0.1.1",
+      "version": "0.1.2",
       "transport": {
         "type": "stdio"
       },