v0.2.6: sync from monorepo 2026-03-07

Author: azeth-sync[bot]

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azeth/mcp-server",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "mcpName": "io.github.azeth-protocol/mcp-server",
   "type": "module",
   "description": "MCP server for the Azeth trust infrastructure — smart accounts, payments, reputation, and discovery tools for AI agents",
@@ -41,8 +41,8 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@azeth/common": "^0.2.5",
-    "@azeth/sdk": "^0.2.5",
+    "@azeth/common": "^0.2.6",
+    "@azeth/sdk": "^0.2.6",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "dotenv": "^16.4.0",
     "viem": "^2.21.0",

src/tools/payments.ts

@@ -3,7 +3,9 @@ import { URL } from 'node:url';
 import dns from 'node:dns/promises';
 import { isAddress, parseUnits } from 'viem';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { AzethError, AZETH_CONTRACTS, TOKENS, formatTokenAmount } from '@azeth/common';
+import type { AzethKit } from '@azeth/sdk';
 import { createClient, resolveChain, validateAddress } from '../utils/client.js';
 import { resolveAddress } from '../utils/resolve.js';
 import { success, error, handleError, guardianRequiredError } from '../utils/response.js';
@@ -175,6 +177,45 @@ async function validateExternalUrl(urlStr: string): Promise<ValidatedUrl> {
   return { url: urlStr, pinnedIPv4 };
 }
 
+/**
+ * Apply smart account selection from the `smartAccount` tool parameter.
+ * Accepts "#N" (1-based index from azeth_accounts) or a full address.
+ * Returns a CallToolResult error if resolution fails, or null on success.
+ */
+function applySmartAccountSelection(client: AzethKit, smartAccount: string): CallToolResult | null {
+  const accounts = client.smartAccounts;
+  if (!accounts || accounts.length === 0) {
+    return error('ACCOUNT_NOT_FOUND', 'No smart accounts found.', 'Use azeth_create_account to create one.');
+  }
+
+  const indexMatch = smartAccount.match(/^#(\d+)$/);
+  if (indexMatch) {
+    const idx = parseInt(indexMatch[1]!) - 1;
+    if (idx < 0 || idx >= accounts.length) {
+      return error('INVALID_INPUT',
+        `Account #${indexMatch[1]} not found. You have ${accounts.length} account(s).`,
+        'Use azeth_accounts to list your accounts.');
+    }
+    client.setActiveAccount(accounts[idx]!);
+    return null;
+  }
+
+  if (/^0x[0-9a-fA-F]{40}$/i.test(smartAccount)) {
+    try {
+      client.setActiveAccount(smartAccount as `0x${string}`);
+    } catch {
+      return error('INVALID_INPUT',
+        `Address ${smartAccount} is not one of your smart accounts.`,
+        'Use azeth_accounts to list your accounts.');
+    }
+    return null;
+  }
+
+  return error('INVALID_INPUT',
+    'Invalid smartAccount format.',
+    'Use "#N" (e.g., "#2") for account index, or a full Ethereum address. Run azeth_accounts to see your accounts.');
+}
+
 /** Register payment-related MCP tools: azeth_pay, azeth_smart_pay, azeth_create_payment_agreement */
 export function registerPaymentTools(server: McpServer): void {
   // ──────────────────────────────────────────────
@@ -203,6 +244,7 @@ export function registerPaymentTools(server: McpServer): void {
         method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).optional().describe('HTTP method. Defaults to "GET".'),
         body: z.string().max(100_000).optional().describe('Request body for POST/PUT/PATCH requests (JSON string, max 100KB).'),
         maxAmount: z.string().max(32).optional().describe('Maximum USDC amount willing to pay (e.g., "5.00"). Rejects if service costs more.'),
+        smartAccount: z.string().optional().describe('Smart account to pay from. Use "#1", "#2", etc. (index from azeth_accounts) or a full address. Defaults to your first smart account.'),
       }),
     },
     async (args) => {
@@ -216,6 +258,12 @@ export function registerPaymentTools(server: McpServer): void {
       let client;
       try {
         client = await createClient(args.chain);
+
+        // Apply smart account selection if specified
+        if (args.smartAccount) {
+          const selectionErr = applySmartAccountSelection(client, args.smartAccount);
+          if (selectionErr) return selectionErr;
+        }
         let maxAmount: bigint | undefined;
         if (args.maxAmount) {
           try {
@@ -353,12 +401,20 @@ export function registerPaymentTools(server: McpServer): void {
         maxAmount: z.string().max(32).optional().describe('Maximum USDC amount willing to pay per service (e.g., "1.00"). Rejects if service costs more.'),
         minReputation: z.coerce.number().min(0).max(100).optional().describe('Minimum reputation score (0-100) to consider. Services below this are excluded.'),
         autoFeedback: z.boolean().optional().describe('Automatically submit a reputation opinion after payment based on service quality. Defaults to false.'),
+        smartAccount: z.string().optional().describe('Smart account to pay from. Use "#1", "#2", etc. (index from azeth_accounts) or a full address. Defaults to your first smart account.'),
       }),
     },
     async (args) => {
       let client;
       try {
         client = await createClient(args.chain);
+
+        // Apply smart account selection if specified
+        if (args.smartAccount) {
+          const selectionErr = applySmartAccountSelection(client, args.smartAccount);
+          if (selectionErr) return selectionErr;
+        }
+
         let maxAmount: bigint | undefined;
         if (args.maxAmount) {
           try {

src/utils/error-selectors.ts

@@ -12,6 +12,13 @@
 interface ErrorInfo {
   name: string;
   description: string;
+  suggestion?: string;
+}
+
+/** Decoded error with human-readable message and optional remediation suggestion */
+export interface DecodedError {
+  message: string;
+  suggestion?: string;
 }
 
 /** Pre-computed selector → error info */
@@ -38,18 +45,18 @@ const SELECTOR_MAP: Record<string, ErrorInfo | undefined> = {
   '0x0bbfcdcc': { name: 'NotTightening', description: 'Only tightening (reducing limits) can bypass the timelock.' },
   '0x6320ab2b': { name: 'NoPendingEmergency', description: 'No emergency withdrawal is pending.' },
   '0x4806710a': { name: 'ChangeAlreadyPending', description: 'A guardrail change is already pending.' },
-  '0x24831e77': { name: 'ExecutorSpendExceedsLimit', description: 'Payment amount exceeds the guardian daily spend limit.' },
+  '0x24831e77': { name: 'ExecutorSpendExceedsLimit', description: 'Payment amount exceeds the guardian daily spend limit.', suggestion: 'Check your limits with azeth_get_guardrails. Wait until tomorrow or increase the daily limit via the guardian.' },
 
   // PaymentAgreementModule
   '0x95a68634': { name: 'SelfAgreement', description: 'Cannot create a payment agreement with yourself.' },
-  '0xf84835a0': { name: 'TokenNotWhitelisted', description: 'The token is not in the guardian whitelist. Add it via setTokenWhitelist.' },
+  '0xf84835a0': { name: 'TokenNotWhitelisted', description: 'The token is not in the guardian whitelist.', suggestion: 'Use azeth_whitelist_token to add the token to your guardian whitelist before retrying.' },
   '0xb5c6c3ab': { name: 'AgreementNotExists', description: 'The specified agreement does not exist.' },
   '0xfe1da89a': { name: 'InvalidAgreement', description: 'The agreement is invalid (already cancelled or completed).' },
-  '0x9563bcf0': { name: 'GuardianLimitExceeded', description: 'The payment exceeds guardian spending limits.' },
+  '0x9563bcf0': { name: 'GuardianLimitExceeded', description: 'The payment exceeds guardian spending limits.', suggestion: 'Check your limits with azeth_get_guardrails. Split into smaller amounts or increase limits via the guardian.' },
   '0x90b8ec18': { name: 'TransferFailed', description: 'The token transfer failed.' },
 
   // ReputationModule
-  '0xae525b83': { name: 'InsufficientPaymentUSD', description: 'You must pay at least $1 USD to the target before rating. Use azeth_get_net_paid to check your payment history.' },
+  '0xae525b83': { name: 'InsufficientPaymentUSD', description: 'You must pay at least $1 USD to the target before rating.', suggestion: 'Payments via azeth_pay, azeth_smart_pay, azeth_transfer, and payment agreements all count toward the $1 minimum. Use azeth_get_net_paid to check your payment history.' },
   '0xcb02f599': { name: 'SelfRatingNotAllowed', description: 'You cannot rate yourself.' },
   '0x645c0b06': { name: 'SiblingRatingNotAllowed', description: 'You cannot rate accounts owned by the same EOA.' },
   '0x565c8a5a': { name: 'InvalidValueDecimals', description: 'Value decimals must be between 0 and 18.' },
@@ -69,7 +76,7 @@ const SELECTOR_MAP: Record<string, ErrorInfo | undefined> = {
   // Oracle
   '0x1f8f95a0': { name: 'InvalidOraclePrice', description: 'The oracle returned an invalid price.' },
   '0xbf16aab6': { name: 'UnsupportedToken', description: 'The oracle does not support this token.' },
-  '0xcf479181': { name: 'InsufficientBalance', description: 'The smart account has insufficient token balance for this operation.' },
+  '0xf4d678b8': { name: 'InsufficientBalance', description: 'The smart account has insufficient token balance for this operation.', suggestion: 'Use azeth_deposit to fund your smart account, or use the smartAccount parameter to select a different account. Run azeth_accounts to see all your accounts and their balances.' },
 
   // Common (shared across multiple contracts)
   '0x0dc149f0': { name: 'AlreadyInitialized', description: 'This module is already initialized for the account.' },
@@ -93,31 +100,31 @@ const PANIC_SELECTOR = '4e487b71';         // Panic(uint256)
  *     selector is buried inside the hex at a 32-byte ABI boundary.
  *  4. Error(string) decoding: extracts the revert string from standard Solidity reverts
  */
-export function decodeErrorSelector(message: string): string | undefined {
+export function decodeErrorSelector(message: string): DecodedError | undefined {
   const hexMatches = message.matchAll(/0x([0-9a-fA-F]{8,})/g);
   for (const match of hexMatches) {
     const hexData = match[1]!.toLowerCase();
 
     // Pass 1: Check the outer selector (first 8 chars)
     const outerSelector = `0x${hexData.slice(0, 8)}`;
     const outerKnown = SELECTOR_MAP[outerSelector];
-    if (outerKnown) return `${outerKnown.name}: ${outerKnown.description}`;
+    if (outerKnown) return { message: `${outerKnown.name}: ${outerKnown.description}`, suggestion: outerKnown.suggestion };
 
     // Pass 1b: Try to decode Error(string) at the outer level
     const outerString = tryDecodeErrorString(hexData);
-    if (outerString) return outerString;
+    if (outerString) return { message: outerString };
 
     // Pass 2: Scan interior at 64-char (32-byte) ABI word boundaries for known
     // selectors. ERC-4337 EntryPoint wraps inner reverts in FailedOpWithRevert
     // where the actual error selector is ABI-encoded at a word boundary.
     for (let i = 64; i + 8 <= hexData.length; i += 64) {
       const innerSelector = `0x${hexData.slice(i, i + 8)}`;
       const innerKnown = SELECTOR_MAP[innerSelector];
-      if (innerKnown) return `${innerKnown.name}: ${innerKnown.description}`;
+      if (innerKnown) return { message: `${innerKnown.name}: ${innerKnown.description}`, suggestion: innerKnown.suggestion };
 
       // Try to decode inner Error(string) — common in EntryPoint FailedOpWithRevert
       const innerString = tryDecodeErrorString(hexData.slice(i));
-      if (innerString) return innerString;
+      if (innerString) return { message: innerString };
     }
   }
   return undefined;

src/utils/response.ts

@@ -77,8 +77,8 @@ export function handleError(err: unknown): CallToolResult {
     if (decoded) {
       return error(
         err.code,
-        decoded,
-        getSuggestion(err.code, err.details),
+        decoded.message,
+        decoded.suggestion ?? getSuggestion(err.code, err.details),
       );
     }
     return error(
@@ -92,7 +92,7 @@ export function handleError(err: unknown): CallToolResult {
     // Attempt to decode contract revert selectors from the error message
     const decoded = decodeErrorSelector(err.message);
     if (decoded) {
-      return error('CONTRACT_ERROR', decoded, getSuggestion('CONTRACT_ERROR'));
+      return error('CONTRACT_ERROR', decoded.message, decoded.suggestion ?? getSuggestion('CONTRACT_ERROR'));
     }
     return error('UNKNOWN_ERROR', sanitizeErrorMessage(err.message));
   }
@@ -101,7 +101,7 @@ export function handleError(err: unknown): CallToolResult {
   const stringified = String(err);
   const decoded = decodeErrorSelector(stringified);
   if (decoded) {
-    return error('CONTRACT_ERROR', decoded, getSuggestion('CONTRACT_ERROR'));
+    return error('CONTRACT_ERROR', decoded.message, decoded.suggestion ?? getSuggestion('CONTRACT_ERROR'));
   }
   return error('UNKNOWN_ERROR', sanitizeErrorMessage(stringified));
 }
@@ -196,7 +196,7 @@ function getSuggestion(code: string, details?: Record<string, unknown>): string
     case 'ACCOUNT_EXISTS':
       return 'An account already exists. Use azeth_accounts to list existing accounts.';
     case 'INSUFFICIENT_PAYMENT':
-      return 'You must pay the target agent at least $1 USD (via azeth_transfer) before rating them. Use azeth_get_net_paid to check your payment history.';
+      return 'You must pay the target at least $1 USD before rating. Payments via azeth_pay, azeth_smart_pay, azeth_transfer, and payment agreements all count. Use azeth_get_net_paid to check your payment history.';
     case 'RECIPIENT_UNREACHABLE':
       return 'The recipient is not reachable on the XMTP network. Use azeth_check_reachability to verify before sending.';
     case 'SERVER_UNAVAILABLE':