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

Author: azeth-sync[bot]

README.md

@@ -9,7 +9,9 @@
 
 MCP (Model Context Protocol) server for Azeth -- the trust, discovery, and payment layer for the machine economy. Provides 32 tools for AI agents to create accounts, make payments, discover services, manage reputation, and communicate via XMTP.
 
-## Setup
+## Zero-Config Setup
+
+No API keys required. A private key is auto-generated and persisted at `~/.azeth/key`. Gas is sponsored automatically.
 
 ### Claude Desktop
 
@@ -20,11 +22,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
   "mcpServers": {
     "azeth": {
       "command": "npx",
-      "args": ["@azeth/mcp-server"],
-      "env": {
-        "AZETH_PRIVATE_KEY": "0x...",
-        "PIMLICO_API_KEY": "your-pimlico-api-key"
-      }
+      "args": ["@azeth/mcp-server"]
     }
   }
 }
@@ -39,27 +37,26 @@ Add to `.claude/settings.json` in your project:
   "mcpServers": {
     "azeth": {
       "command": "npx",
-      "args": ["@azeth/mcp-server"],
-      "env": {
-        "AZETH_PRIVATE_KEY": "0x...",
-        "PIMLICO_API_KEY": "your-pimlico-api-key"
-      }
+      "args": ["@azeth/mcp-server"]
     }
   }
 }
 ```
 
-### Local Development
+Then ask Claude: *"Create me a smart account called PriceFeedBot"* -- that's it.
+
+### With Your Own Key
+
+For production or to use an existing key, add environment variables:
 
 ```json
 {
   "mcpServers": {
     "azeth": {
-      "command": "node",
-      "args": ["path/to/Azeth/packages/mcp-server/dist/index.js"],
+      "command": "npx",
+      "args": ["@azeth/mcp-server"],
       "env": {
-        "AZETH_PRIVATE_KEY": "0x...",
-        "PIMLICO_API_KEY": "your-pimlico-api-key"
+        "AZETH_PRIVATE_KEY": "0x..."
       }
     }
   }
@@ -68,14 +65,17 @@ Add to `.claude/settings.json` in your project:
 
 ## Environment Variables
 
+All optional. The server works with zero configuration on testnet.
+
 | Variable | Required | Description |
 |---|---|---|
-| `AZETH_PRIVATE_KEY` | Yes | Account owner's private key (0x-prefixed hex) |
-| `PIMLICO_API_KEY` | Yes* | Pimlico bundler/paymaster API key (*required for state-changing operations) |
-| `AZETH_CHAIN` | No | `"baseSepolia"` or `"base"` (default: `baseSepolia`) |
-| `AZETH_RPC_URL` | No | Custom RPC endpoint |
+| `AZETH_PRIVATE_KEY` | No | Account owner's private key. Auto-generated and saved to `~/.azeth/key` if not set. |
+| `PIMLICO_API_KEY` | No | Pimlico bundler API key. Falls back to Azeth server bundler proxy if not set. |
+| `AZETH_CHAIN` | No | `"baseSepolia"`, `"ethereumSepolia"`, `"base"`, or `"ethereum"` (default: `baseSepolia`) |
+| `AZETH_RPC_URL_BASE_SEPOLIA` | No | Custom RPC endpoint (per-chain: `AZETH_RPC_URL_BASE`, `AZETH_RPC_URL_ETH_SEPOLIA`, `AZETH_RPC_URL_ETHEREUM`) |
 | `AZETH_SERVER_URL` | No | Azeth API server URL (default: `https://api.azeth.ai`) |
-| `XMTP_ENCRYPTION_KEY` | No | For XMTP messaging tools |
+| `AZETH_GUARDIAN_KEY` | No | Separate guardian key for co-signing high-value operations |
+| `XMTP_ENCRYPTION_KEY` | No | For persistent XMTP messaging across restarts |
 
 ## Tools (32)
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azeth/mcp-server",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "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.4",
-    "@azeth/sdk": "^0.2.4",
+    "@azeth/common": "^0.2.5",
+    "@azeth/sdk": "^0.2.5",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "dotenv": "^16.4.0",
     "viem": "^2.21.0",

src/tools/account.ts

@@ -55,12 +55,12 @@ export function registerAccountTools(server: McpServer): void {
         '',
         'Returns: The deployed smart account address, trust registry token ID, and transaction hash.',
         '',
+        'Gas is automatically sponsored — no ETH required. The SDK uses a gasless relay (EIP-712 signature)',
+        'so the account can be created without any pre-funding. On testnet, USDC is also auto-funded.',
+        '',
         'Guardian: By default, the guardian is derived from AZETH_GUARDIAN_KEY env var. If not set, falls back to self-guardian (owner address).',
         'For production, always use a separate guardian key. Set AZETH_GUARDIAN_KEY in your .env file.',
         '',
-        'Note: This is a state-changing operation that deploys contracts on-chain. It requires ETH for gas.',
-        'The owner private key is read from the AZETH_PRIVATE_KEY environment variable.',
-        '',
         'Example: { "name": "PriceFeedBot", "entityType": "service", "description": "Real-time crypto price data", "capabilities": ["price-feed", "market-data"] }',
       ].join('\n'),
       inputSchema: z.object({
@@ -151,6 +151,8 @@ export function registerAccountTools(server: McpServer): void {
           TOKENS[chain].WETH,
         ];
 
+        const serverUrl = process.env['AZETH_SERVER_URL'] ?? 'https://api.azeth.ai';
+
         const result = await client.createAccount({
           owner: client.address,
           guardrails: {
@@ -171,7 +173,6 @@ export function registerAccountTools(server: McpServer): void {
           },
         });
 
-        const serverUrl = process.env['AZETH_SERVER_URL'] ?? 'https://api.azeth.ai';
         const tokenIdStr = result.tokenId.toString();
         const badgeUrl = `${serverUrl}/badge/${tokenIdStr}`;
         const profileUrl = `https://azeth.ai/agent/${result.account}`;
@@ -199,6 +200,13 @@ export function registerAccountTools(server: McpServer): void {
           { txHash: result.txHash },
         );
       } catch (err) {
+        if (err instanceof Error && err.message.includes('insufficient funds')) {
+          return error(
+            'INSUFFICIENT_BALANCE',
+            'Account deployment failed: gasless relay unavailable and your EOA has no ETH for direct deployment.',
+            'The relay at api.azeth.ai may be down or rate-limited. Try again later, or send a small amount of ETH to your EOA address for direct deployment.',
+          );
+        }
         return handleError(err);
       } finally {
         try { await client?.destroy(); } catch (e) { process.stderr.write(`[azeth-mcp] destroy error: ${e instanceof Error ? e.message : String(e)}\n`); }

src/tools/registry.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { hexToString } from 'viem';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { discoverServicesWithFallback, getRegistryEntry } from '@azeth/sdk';
-import { AZETH_CONTRACTS, ERC8004_REGISTRY, formatTokenAmount, CATALOG_MAX_ENTRIES, CATALOG_MAX_PATH_LENGTH } from '@azeth/common';
+import { AZETH_CONTRACTS, ERC8004_REGISTRY, RPC_ENV_KEYS, SUPPORTED_CHAINS, formatTokenAmount, CATALOG_MAX_ENTRIES, CATALOG_MAX_PATH_LENGTH } from '@azeth/common';
 import type { CatalogEntry, CatalogMethod } from '@azeth/common';
 import { TrustRegistryModuleAbi, ReputationModuleAbi } from '@azeth/common/abis';
 import { createClient, resolveChain, resolveViemChain, validateAddress } from '../utils/client.js';
@@ -287,7 +287,7 @@ export function registerRegistryTools(server: McpServer): void {
         // Create a public client for the on-chain fallback
         const { createPublicClient, http } = await import('viem');
         const chain = resolveViemChain(chainName);
-        const rpcUrl = process.env['AZETH_RPC_URL'];
+        const rpcUrl = process.env[RPC_ENV_KEYS[chainName]] ?? SUPPORTED_CHAINS[chainName].rpcDefault;
         const publicClient = createPublicClient({ chain, transport: http(rpcUrl) });
 
         const result = await discoverServicesWithFallback(
@@ -444,7 +444,7 @@ export function registerRegistryTools(server: McpServer): void {
         // Create a public client for on-chain reads
         const { createPublicClient, http } = await import('viem');
         const viemChain = resolveViemChain(chainName);
-        const rpcUrl = process.env['AZETH_RPC_URL'];
+        const rpcUrl = process.env[RPC_ENV_KEYS[chainName]] ?? SUPPORTED_CHAINS[chainName].rpcDefault;
         const publicClient = createPublicClient({ chain: viemChain, transport: http(rpcUrl) });
 
         // Resolve tokenId from address if needed

src/tools/reputation.ts

@@ -3,7 +3,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { createClient, resolveChain, resolveViemChain, validateAddress } from '../utils/client.js';
 import { success, error, handleError, formatUSD } from '../utils/response.js';
 import { ReputationModuleAbi, TrustRegistryModuleAbi } from '@azeth/common/abis';
-import { AzethError, AZETH_CONTRACTS, formatTokenAmount } from '@azeth/common';
+import { AzethError, AZETH_CONTRACTS, RPC_ENV_KEYS, SUPPORTED_CHAINS, formatTokenAmount } from '@azeth/common';
 
 /** Maximum uint256 value for on-chain IDs */
 const MAX_UINT256 = (1n << 256n) - 1n;
@@ -151,7 +151,7 @@ export function registerReputationTools(server: McpServer): void {
 
         const resolved = resolveChain(args.chain);
         const chain = resolveViemChain(resolved);
-        const rpcUrl = process.env['AZETH_RPC_URL'];
+        const rpcUrl = process.env[RPC_ENV_KEYS[resolved]] ?? SUPPORTED_CHAINS[resolved].rpcDefault;
 
         const publicClient = createPublicClient({
           chain,
@@ -278,7 +278,7 @@ export function registerReputationTools(server: McpServer): void {
 
         const resolved = resolveChain(args.chain);
         const chain = resolveViemChain(resolved);
-        const rpcUrl = process.env['AZETH_RPC_URL'];
+        const rpcUrl = process.env[RPC_ENV_KEYS[resolved]] ?? SUPPORTED_CHAINS[resolved].rpcDefault;
 
         const publicClient = createPublicClient({
           chain,

src/utils/client.ts

@@ -1,5 +1,5 @@
 import { AzethKit, type AzethKitConfig } from '@azeth/sdk';
-import { AzethError, resolveChainAlias, resolveViemChain, type XMTPConfig, type SupportedChainName } from '@azeth/common';
+import { AzethError, resolveChainAlias, resolveViemChain, RPC_ENV_KEYS, type XMTPConfig, type SupportedChainName } from '@azeth/common';
 
 /** Resolve a chain argument to a canonical SupportedChainName.
  *  Resolution order: explicit arg > AZETH_CHAIN env > 'baseSepolia' default.
@@ -73,7 +73,9 @@ export async function createClient(
     guardianAutoSign,
   };
 
-  const rpcUrl = process.env['AZETH_RPC_URL'];
+  // SDK resolves RPC from SUPPORTED_CHAINS[chain].rpcDefault when config.rpcUrl is not set.
+  // Per-chain env vars (AZETH_RPC_URL_BASE_SEPOLIA, etc.) override the default.
+  const rpcUrl = process.env[RPC_ENV_KEYS[resolvedChain]];
   if (rpcUrl) {
     config.rpcUrl = rpcUrl;
   }

src/utils/resolve.ts

@@ -1,5 +1,5 @@
 import type { AzethKit } from '@azeth/sdk';
-import { AzethError, AZETH_CONTRACTS, ERC8004_REGISTRY } from '@azeth/common';
+import { AzethError, AZETH_CONTRACTS, ERC8004_REGISTRY, RPC_ENV_KEYS, SUPPORTED_CHAINS } from '@azeth/common';
 import { TrustRegistryModuleAbi, AzethOracleAbi } from '@azeth/common/abis';
 import { validateAddress, resolveChain, resolveViemChain } from './client.js';
 
@@ -128,7 +128,7 @@ export async function resolveAddress(
     try {
       const { createPublicClient, http } = await import('viem');
       const viemChain = resolveViemChain(chain);
-      const rpcUrl = process.env['AZETH_RPC_URL'];
+      const rpcUrl = process.env[RPC_ENV_KEYS[chain]] ?? SUPPORTED_CHAINS[chain].rpcDefault;
       const pubClient = createPublicClient({ chain: viemChain, transport: http(rpcUrl) });
 
       const tokenId = BigInt(tokenMatch[1]!);
@@ -275,7 +275,7 @@ async function resolveNameOnChain(
   const { createPublicClient, http } = await import('viem');
   const chain = resolveChain(process.env['AZETH_CHAIN']);
   const viemChain = resolveViemChain(chain);
-  const rpcUrl = process.env['AZETH_RPC_URL'];
+  const rpcUrl = process.env[RPC_ENV_KEYS[chain]] ?? SUPPORTED_CHAINS[chain].rpcDefault;
 
   const registryAddress = ERC8004_REGISTRY[chain];
   const oracleAddress = AZETH_CONTRACTS[chain]?.priceOracle;