@abstract-foundation/agw-mcp 0.1.0-beta.6 → 0.1.0-beta.8

package/README.md

@@ -126,6 +126,9 @@ npx -y @abstract-foundation/agw-mcp serve --chain-id 2741
 
 # Custom RPC
 npx -y @abstract-foundation/agw-mcp serve --chain-id 2741 --rpc-url https://api.mainnet.abs.xyz
+
+# 0x API key override (for swap_tokens quote requests)
+npx -y @abstract-foundation/agw-mcp serve --chain-id 2741 --zeroex-api-key YOUR_0X_API_KEY
 ```
 
 Environment variables are also supported:
@@ -133,6 +136,7 @@ Environment variables are also supported:
 ```bash
 AGW_MCP_CHAIN_ID=2741 npx -y @abstract-foundation/agw-mcp serve
 AGW_MCP_RPC_URL=https://api.mainnet.abs.xyz npx -y @abstract-foundation/agw-mcp serve
+AGW_MCP_ZEROEX_API_KEY=YOUR_0X_API_KEY npx -y @abstract-foundation/agw-mcp serve
 AGW_MCP_APP_URL=https://mcp.abs.xyz npx -y @abstract-foundation/agw-mcp init --chain-id 2741
 ```
 

package/dist/index.mjs

@@ -8,7 +8,7 @@ import os from "node:os";
 import path from "node:path";
 import { sessionKeyValidatorAddress } from "@abstract-foundation/agw-client/constants";
 import { SessionKeyValidatorAbi, createSessionClient, getSessionHash } from "@abstract-foundation/agw-client/sessions";
-import { createPublicClient, encodeFunctionData, erc20Abi, formatUnits, http, isAddress, zeroAddress } from "viem";
+import { createPublicClient, encodeFunctionData, erc20Abi, formatUnits, getAddress, http, isAddress, parseAbiItem, zeroAddress } from "viem";
 import { abstract, abstractTestnet } from "viem/chains";
 import http$1 from "node:http";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -240,7 +240,7 @@ const SUPPORTED_CHAINS = {
 	[abstract.id]: abstract
 };
 const DEFAULT_CHAIN_ID = abstract.id;
-function normalizeOptionalString(value) {
+function normalizeOptionalString$1(value) {
 	if (typeof value !== "string") return;
 	const normalized = value.trim();
 	return normalized ? normalized : void 0;
@@ -251,9 +251,9 @@ function parseChainId(value, source) {
 	if (!Number.isInteger(chainId) || chainId <= 0) throw new Error(`Invalid chain id from ${source}. Expected a positive integer.`);
 	return chainId;
 }
-function resolveEnvValue(env, keys) {
+function resolveEnvValue$1(env, keys) {
 	for (const key of keys) {
-		const value = normalizeOptionalString(env[key]);
+		const value = normalizeOptionalString$1(env[key]);
 		if (value) return value;
 	}
 }
@@ -270,17 +270,36 @@ function getDefaultRpcUrl(chain) {
 function resolveNetworkConfig(input = {}) {
 	const env = input.env ?? process.env;
 	const chainIdFromCli = input.chainId === void 0 ? void 0 : parseChainId(input.chainId, "--chain-id");
-	const chainIdFromEnvRaw = resolveEnvValue(env, CHAIN_ID_ENV_KEYS);
+	const chainIdFromEnvRaw = resolveEnvValue$1(env, CHAIN_ID_ENV_KEYS);
 	const chainIdFromEnv = chainIdFromEnvRaw === void 0 ? void 0 : parseChainId(chainIdFromEnvRaw, "environment");
 	const chainId = chainIdFromCli ?? chainIdFromEnv ?? DEFAULT_CHAIN_ID;
 	const chain = resolveChain(chainId);
 	return {
 		chainId,
 		chain,
-		rpcUrl: normalizeOptionalString(input.rpcUrl) ?? resolveEnvValue(env, RPC_URL_ENV_KEYS) ?? getDefaultRpcUrl(chain)
+		rpcUrl: normalizeOptionalString$1(input.rpcUrl) ?? resolveEnvValue$1(env, RPC_URL_ENV_KEYS) ?? getDefaultRpcUrl(chain)
 	};
 }
 
+//#endregion
+//#region src/config/zeroex.ts
+const ZEROEX_API_KEY_ENV_KEYS = ["AGW_MCP_ZEROEX_API_KEY", "ZEROEX_API_KEY"];
+function normalizeOptionalString(value) {
+	if (typeof value !== "string") return;
+	const normalized = value.trim();
+	return normalized ? normalized : void 0;
+}
+function resolveEnvValue(env, keys) {
+	for (const key of keys) {
+		const value = normalizeOptionalString(env[key]);
+		if (value) return value;
+	}
+}
+function resolveZeroExConfig(input = {}) {
+	const env = input.env ?? process.env;
+	return { apiKey: normalizeOptionalString(input.apiKey) ?? resolveEnvValue(env, ZEROEX_API_KEY_ENV_KEYS) };
+}
+
 //#endregion
 //#region src/integrations/zeroex/quote-adapter.ts
 const DEFAULT_ZEROEX_API_BASE_URL = "https://api.0x.org";
@@ -420,11 +439,22 @@ function normalizeRouteFills(value) {
 	}
 	return fills;
 }
+function normalizeTransaction(payload) {
+	const transaction = isRecord$5(payload.transaction) ? payload.transaction : {};
+	return {
+		to: requireString(transaction.to ?? payload.to, "to"),
+		data: requireString(transaction.data ?? payload.data, "data"),
+		value: asString(transaction.value ?? payload.value) ?? "0",
+		gasLimit: asString(transaction.gas ?? payload.gas),
+		gasPrice: asString(transaction.gasPrice ?? payload.gasPrice)
+	};
+}
 function normalizeQuotePayload(payload, request) {
 	if (!isRecord$5(payload)) throw new Error("response payload must be an object");
 	const issues = isRecord$5(payload.issues) ? payload.issues : {};
 	const route = isRecord$5(payload.route) ? payload.route : {};
 	const fees = isRecord$5(payload.fees) ? payload.fees : {};
+	const transaction = normalizeTransaction(payload);
 	return {
 		quoteId: asString(payload.zid),
 		chainId: normalizePositiveInteger(payload.chainId ?? request.chainId, "chainId"),
@@ -438,14 +468,14 @@ function normalizeQuotePayload(payload, request) {
 		estimatedPriceImpact: asString(payload.estimatedPriceImpact),
 		allowanceTarget: asString(payload.allowanceTarget),
 		gas: {
-			limit: asString(payload.gas),
-			price: asString(payload.gasPrice),
+			limit: transaction.gasLimit,
+			price: transaction.gasPrice,
 			estimatedFee: asString(payload.totalNetworkFee)
 		},
 		transaction: {
-			to: requireString(payload.to, "to"),
-			data: requireString(payload.data, "data"),
-			value: asString(payload.value) ?? "0"
+			to: transaction.to,
+			data: transaction.data,
+			value: transaction.value
 		},
 		fees: {
 			integratorFee: normalizeFee(fees.integratorFee),
@@ -594,7 +624,8 @@ function createZeroExQuoteAdapter(config = {}) {
 		}
 	} };
 }
-const zeroExQuoteAdapter = createZeroExQuoteAdapter();
+const defaultZeroExConfig = resolveZeroExConfig();
+const zeroExQuoteAdapter = createZeroExQuoteAdapter({ apiKey: defaultZeroExConfig.apiKey });
 
 //#endregion
 //#region src/errors/contract.ts
@@ -2100,6 +2131,98 @@ const getSessionStatusTool = {
 
 //#endregion
 //#region src/tools/get-token-list.ts
+const ERC20_TRANSFER_EVENT = parseAbiItem("event Transfer(address indexed from, address indexed to, uint256 value)");
+const LOG_SCAN_MIN_CHUNK_SIZE = 50000n;
+const BALANCE_QUERY_CONCURRENCY = 8;
+const METADATA_QUERY_CONCURRENCY = 8;
+function getErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	try {
+		return JSON.stringify(error);
+	} catch {
+		return String(error);
+	}
+}
+function isRpcMethodUnavailableError(error) {
+	const message = getErrorMessage(error).toLowerCase();
+	return message.includes("rpc method is not whitelisted") || message.includes("method not found") || message.includes("code\":-32601") && message.includes("zks_getallaccountbalances");
+}
+function isLogRangeError(error) {
+	const message = getErrorMessage(error).toLowerCase();
+	return message.includes("too many results") || message.includes("response size exceeded") || message.includes("query timeout") || message.includes("block range") || message.includes("limit");
+}
+async function getTransferLogsWithAdaptiveChunking(publicClient, latestBlock, args) {
+	if (latestBlock < 0n) return [];
+	const logs = [];
+	let chunkSize = latestBlock + 1n;
+	let fromBlock = 0n;
+	while (fromBlock <= latestBlock) {
+		const toBlock = fromBlock + chunkSize - 1n > latestBlock ? latestBlock : fromBlock + chunkSize - 1n;
+		try {
+			const batch = await publicClient.getLogs({
+				event: ERC20_TRANSFER_EVENT,
+				args,
+				fromBlock,
+				toBlock
+			});
+			logs.push(...batch);
+			fromBlock = toBlock + 1n;
+		} catch (error) {
+			if (!isLogRangeError(error) || chunkSize <= LOG_SCAN_MIN_CHUNK_SIZE) throw error;
+			chunkSize = chunkSize / 2n;
+			if (chunkSize < LOG_SCAN_MIN_CHUNK_SIZE) chunkSize = LOG_SCAN_MIN_CHUNK_SIZE;
+		}
+	}
+	return logs;
+}
+async function mapWithConcurrency(values, concurrency, mapper) {
+	if (values.length === 0) return [];
+	const workerCount = Math.max(1, Math.min(concurrency, values.length));
+	const results = new Array(values.length);
+	let nextIndex = 0;
+	const workers = Array.from({ length: workerCount }, async () => {
+		while (nextIndex < values.length) {
+			const index = nextIndex;
+			nextIndex += 1;
+			results[index] = await mapper(values[index]);
+		}
+	});
+	await Promise.all(workers);
+	return results;
+}
+async function getTokenBalancesFromTransferLogs(publicClient, accountAddress) {
+	const normalizedAccount = getAddress(accountAddress);
+	const latestBlock = await publicClient.getBlockNumber();
+	const [incomingLogs, outgoingLogs] = await Promise.all([getTransferLogsWithAdaptiveChunking(publicClient, latestBlock, { to: normalizedAccount }), getTransferLogsWithAdaptiveChunking(publicClient, latestBlock, { from: normalizedAccount })]);
+	const tokenAddresses = /* @__PURE__ */ new Map();
+	for (const log of [...incomingLogs, ...outgoingLogs]) {
+		if (!isAddress(log.address, { strict: false })) continue;
+		tokenAddresses.set(log.address.toLowerCase(), log.address);
+	}
+	const balanceEntries = await mapWithConcurrency(Array.from(tokenAddresses.values()), BALANCE_QUERY_CONCURRENCY, async (tokenAddress) => {
+		try {
+			const rawBalance = await publicClient.readContract({
+				address: tokenAddress,
+				abi: erc20Abi,
+				functionName: "balanceOf",
+				args: [normalizedAccount]
+			});
+			if (typeof rawBalance !== "bigint" || rawBalance <= 0n) return null;
+			return {
+				tokenAddress,
+				rawBalance
+			};
+		} catch {
+			return null;
+		}
+	});
+	const balances = {};
+	for (const entry of balanceEntries) {
+		if (!entry) continue;
+		balances[entry.tokenAddress] = entry.rawBalance.toString();
+	}
+	return balances;
+}
 function normalizeTokenBalances(value) {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("token balances payload must be an object");
 	const entries = [];
@@ -2136,18 +2259,23 @@ function createDefaultTokenListReader(input) {
 	});
 	return {
 		getTokenBalances: async (accountAddress) => {
-			const request = publicClient.request;
-			const response = await request({
-				method: "zks_getAllAccountBalances",
-				params: [accountAddress]
-			});
-			if (typeof response !== "object" || response === null || Array.isArray(response)) throw new Error("zks_getAllAccountBalances returned an invalid response payload");
-			const balances = {};
-			for (const [tokenAddress, rawValue] of Object.entries(response)) {
-				if (typeof rawValue !== "string") throw new Error(`token balance for ${tokenAddress} returned a non-string value`);
-				balances[tokenAddress] = rawValue;
+			try {
+				const request = publicClient.request;
+				const response = await request({
+					method: "zks_getAllAccountBalances",
+					params: [accountAddress]
+				});
+				if (typeof response !== "object" || response === null || Array.isArray(response)) throw new Error("zks_getAllAccountBalances returned an invalid response payload");
+				const balances = {};
+				for (const [tokenAddress, rawValue] of Object.entries(response)) {
+					if (typeof rawValue !== "string") throw new Error(`token balance for ${tokenAddress} returned a non-string value`);
+					balances[tokenAddress] = rawValue;
+				}
+				return balances;
+			} catch (error) {
+				if (!isRpcMethodUnavailableError(error)) throw error;
+				return getTokenBalancesFromTransferLogs(publicClient, accountAddress);
 			}
-			return balances;
 		},
 		getTokenMetadata: async (tokenAddress) => {
 			const [symbol, decimals] = await Promise.all([publicClient.readContract({
@@ -2197,27 +2325,28 @@ function createGetTokenListTool(dependencies = { createTokenListReader: createDe
 				chainId: networkConfig.chainId,
 				rpcUrl: networkConfig.rpcUrl
 			});
-			const normalizedTokenBalances = normalizeTokenBalances(await reader.getTokenBalances(accountAddress));
-			const tokenHoldings = [];
-			for (const { tokenAddress, rawValue } of normalizedTokenBalances) try {
-				const metadata = await reader.getTokenMetadata(tokenAddress);
-				tokenHoldings.push({
-					tokenAddress,
-					symbol: metadata.symbol,
-					decimals: metadata.decimals,
-					value: {
-						raw: rawValue.toString(),
-						formatted: formatUnits(rawValue, metadata.decimals)
-					},
-					explorer: {
-						token: buildExplorerUrl(explorerBase, `/token/${tokenAddress}`),
-						holder: buildExplorerUrl(explorerBase, `/token/${tokenAddress}?a=${accountAddress}`)
-					}
-				});
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				context.logger.warn(`Skipping token ${tokenAddress}: ${message}`);
-			}
+			const tokenHoldings = (await mapWithConcurrency(normalizeTokenBalances(await reader.getTokenBalances(accountAddress)), METADATA_QUERY_CONCURRENCY, async ({ tokenAddress, rawValue }) => {
+				try {
+					const metadata = await reader.getTokenMetadata(tokenAddress);
+					return {
+						tokenAddress,
+						symbol: metadata.symbol,
+						decimals: metadata.decimals,
+						value: {
+							raw: rawValue.toString(),
+							formatted: formatUnits(rawValue, metadata.decimals)
+						},
+						explorer: {
+							token: buildExplorerUrl(explorerBase, `/token/${tokenAddress}`),
+							holder: buildExplorerUrl(explorerBase, `/token/${tokenAddress}?a=${accountAddress}`)
+						}
+					};
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					context.logger.warn(`Skipping token ${tokenAddress}: ${message}`);
+					return null;
+				}
+			})).filter((entry) => entry !== null);
 			return {
 				connected: true,
 				sessionStatus: context.sessionManager.getSessionStatus(),
@@ -2792,6 +2921,7 @@ const signTransactionTool = {
 
 //#endregion
 //#region src/tools/swap-tokens.ts
+const ZEROEX_NATIVE_ETH_SENTINEL = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
 function parseExecute$1(value) {
 	if (value === void 0) return false;
 	if (typeof value !== "boolean") throw new Error("execute must be a boolean");
@@ -2807,7 +2937,15 @@ function parseOptionalString(value, field) {
 	if (typeof value !== "string" || value.trim() === "") throw new Error(`${field} must be a non-empty string when provided`);
 	return value.trim();
 }
-function createSwapTokensTool(dependencies = { quoteAdapter: zeroExQuoteAdapter }) {
+function normalizeSwapToken(value, nativeSymbol) {
+	const normalized = value.trim();
+	if (normalized.toUpperCase() === nativeSymbol.toUpperCase()) return ZEROEX_NATIVE_ETH_SENTINEL;
+	return normalized;
+}
+function createSwapTokensTool(dependencies = {}) {
+	const createQuoteAdapter = dependencies.createQuoteAdapter ?? (() => {
+		return createZeroExQuoteAdapter({ apiKey: resolveZeroExConfig().apiKey });
+	});
 	return {
 		name: "swap_tokens",
 		description: "Fetches 0x swap quotes and executes swap transactions through AGW session keys when explicitly requested.",
@@ -2816,11 +2954,11 @@ function createSwapTokensTool(dependencies = { quoteAdapter: zeroExQuoteAdapter
 			properties: {
 				sellToken: {
 					type: "string",
-					description: "Token address/symbol to sell"
+					description: "Token address to sell, or native symbol (for example ETH)"
 				},
 				buyToken: {
 					type: "string",
-					description: "Token address/symbol to buy"
+					description: "Token address to buy, or native symbol (for example ETH)"
 				},
 				sellAmount: {
 					type: "string",
@@ -2850,11 +2988,15 @@ function createSwapTokensTool(dependencies = { quoteAdapter: zeroExQuoteAdapter
 			const session = context.sessionManager.getSession();
 			if (!session) throw new Error("session is missing");
 			const execute = parseExecute$1(params.execute);
-			const quote = await dependencies.quoteAdapter.getQuote({
+			const quoteAdapter = dependencies.quoteAdapter ?? createQuoteAdapter();
+			const networkConfig = resolveToolNetworkConfig(context, session.chainId);
+			const sellToken = normalizeSwapToken(params.sellToken, networkConfig.chain.nativeCurrency.symbol);
+			const buyToken = normalizeSwapToken(params.buyToken, networkConfig.chain.nativeCurrency.symbol);
+			const quote = await quoteAdapter.getQuote({
 				chainId: session.chainId,
 				taker: session.accountAddress,
-				sellToken: params.sellToken.trim(),
-				buyToken: params.buyToken.trim(),
+				sellToken,
+				buyToken,
 				sellAmount: parseOptionalString(params.sellAmount, "sellAmount"),
 				buyAmount: parseOptionalString(params.buyAmount, "buyAmount"),
 				slippageBps: parseOptionalInteger(params.slippageBps, "slippageBps")
@@ -2875,7 +3017,6 @@ function createSwapTokensTool(dependencies = { quoteAdapter: zeroExQuoteAdapter
 					spender: quote.issues.allowance?.spender ?? null
 				}
 			};
-			const networkConfig = resolveToolNetworkConfig(context, session.chainId);
 			await assertMainnetPolicyRegistryPreflight({
 				chainId: session.chainId,
 				to: txTarget,
@@ -3358,6 +3499,7 @@ var AgwMcpServer = class {
 //#endregion
 //#region src/index.ts
 const logger = new Logger("agw-mcp");
+const ZEROEX_API_KEY_ENV = "AGW_MCP_ZEROEX_API_KEY";
 function resolveCliVersion() {
 	try {
 		const packageJsonUrl = new URL("../package.json", import.meta.url);
@@ -3367,6 +3509,11 @@ function resolveCliVersion() {
 	} catch {}
 	return "0.1.0";
 }
+function applyZeroExApiKeyOverride(apiKeyValue) {
+	if (apiKeyValue === void 0) return;
+	if (typeof apiKeyValue !== "string" || apiKeyValue.trim() === "") throw new Error("--zeroex-api-key must be a non-empty string");
+	process.env[ZEROEX_API_KEY_ENV] = apiKeyValue.trim();
+}
 const program = new Command();
 program.name("agw-mcp").description("Local MCP server for AGW session-key workflows").version(resolveCliVersion());
 program.command("init").description("Bootstrap local AGW MCP session storage").option("--chain-id <chainId>", "EVM chain id (env: AGW_MCP_CHAIN_ID)").option("--rpc-url <rpcUrl>", "RPC URL override (env: AGW_MCP_RPC_URL)").option("--app-url <url>", "Hosted session onboarding URL (defaults to https://mcp.abs.xyz; env: AGW_MCP_APP_URL)").option("--storage-dir <dir>", "Session storage directory").action(async (options) => {
@@ -3396,7 +3543,8 @@ program.command("config").description("Print a ready-to-paste local MCP config s
 	});
 	process.stdout.write(`${JSON.stringify(snippet, null, 2)}\n`);
 });
-program.command("serve").description("Run the local stdio MCP server").option("--chain-id <chainId>", "EVM chain id (env: AGW_MCP_CHAIN_ID)").option("--rpc-url <rpcUrl>", "RPC URL override (env: AGW_MCP_RPC_URL)").option("--storage-dir <dir>", "Session storage directory").action(async (options) => {
+program.command("serve").description("Run the local stdio MCP server").option("--chain-id <chainId>", "EVM chain id (env: AGW_MCP_CHAIN_ID)").option("--rpc-url <rpcUrl>", "RPC URL override (env: AGW_MCP_RPC_URL)").option("--zeroex-api-key <apiKey>", "0x API key override (env: AGW_MCP_ZEROEX_API_KEY)").option("--storage-dir <dir>", "Session storage directory").action(async (options) => {
+	applyZeroExApiKeyOverride(options.zeroexApiKey);
 	const networkConfig = resolveNetworkConfig({
 		chainId: options.chainId,
 		rpcUrl: options.rpcUrl

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abstract-foundation/agw-mcp",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0-beta.8",
   "description": "MCP server for Abstract Global Wallet session-key workflows",
   "license": "MIT",
   "author": "Abstract Foundation",