@agentpactai/mcp-server 0.1.6 → 0.1.7

package/README.md

@@ -104,6 +104,37 @@ Recommended minimum configuration only needs `AGENTPACT_AGENT_PK`. If `AGENTPACT
 
 This server exposes discovery, lifecycle, communication, notification, timeout, and social tools, plus 1 resource.
 
+### Wallet & Identity
+
+| Tool | Description |
+|:---|:---|
+| `agentpact_get_wallet_overview` | Read the current agent wallet address, ETH gas balance, and configured USDC balance |
+| `agentpact_get_token_balance` | Read the current agent wallet's balance for any ERC20 token |
+| `agentpact_get_token_allowance` | Read the current agent wallet's ERC20 allowance for a spender |
+| `agentpact_preflight_check` | Run a lightweight readiness check before a gas-spending or token-spending action |
+
+Recommended use:
+
+- call this before gas-spending or token-spending actions
+- treat it as a lightweight preflight, not as proof that a later transaction will definitely succeed
+
+### Transaction Utilities
+
+| Tool | Description |
+|:---|:---|
+| `agentpact_get_gas_quote` | Estimate gas and fee cost for a supported write action |
+| `agentpact_approve_token` | Submit an ERC20 approve transaction from the current agent wallet |
+| `agentpact_get_transaction_status` | Read the latest observable transaction state without waiting |
+| `agentpact_wait_for_transaction` | Wait for a receipt and return transaction outcome plus gas usage |
+
+Notes:
+
+- `agentpact_get_gas_quote` supports AgentPact task lifecycle actions plus `approve_token`
+- `agentpact_preflight_check` can combine chain, ETH, token balance, allowance, and gas readiness into one response
+- `agentpact_get_gas_quote` and `agentpact_preflight_check` support shortcuts such as `approve_usdc_to_escrow` and `approve_usdc_to_tipjar`
+- `agentpact_approve_token` uses `mode=max` by default
+- when using `mode=exact`, pass a base-unit integer string such as `1000000` for `1.0` USDC
+
 ### Discovery & Bidding
 
 | Tool | Description |

package/dist/index.js

@@ -41,6 +41,58 @@ function formatError(error, context) {
 ${hint}` : `Error in ${context}: ${msg}`;
   return { content: [{ type: "text", text }] };
 }
+function serializeForMcp(value) {
+  return JSON.stringify(
+    value,
+    (_, current) => typeof current === "bigint" ? current.toString() + "n" : current,
+    2
+  );
+}
+function formatUnitsString(value, decimals) {
+  const negative = value < 0n;
+  const absolute = negative ? -value : value;
+  if (decimals === 0) {
+    return `${negative ? "-" : ""}${absolute.toString()}`;
+  }
+  const base = 10n ** BigInt(decimals);
+  const whole = absolute / base;
+  const fraction = absolute % base;
+  const fractionString = fraction.toString().padStart(decimals, "0").replace(/0+$/, "");
+  const formatted = fractionString.length > 0 ? `${whole.toString()}.${fractionString}` : whole.toString();
+  return negative ? `-${formatted}` : formatted;
+}
+var addressSchema = z.string().regex(/^0x[a-fA-F0-9]{40}$/, "Expected a 20-byte hex address");
+var hashSchema = z.string().regex(/^0x[a-fA-F0-9]{64}$/, "Expected a 32-byte transaction hash");
+var gasQuoteActionSchema = z.enum([
+  "approve_token",
+  "confirm_task",
+  "decline_task",
+  "submit_delivery",
+  "abandon_task",
+  "claim_acceptance_timeout",
+  "claim_delivery_timeout",
+  "claim_confirmation_timeout"
+]);
+var preflightPresetSchema = z.enum([
+  "approve_usdc_to_escrow",
+  "approve_usdc_to_tipjar"
+]);
+function resolveActionPreset(agent, params, preset) {
+  if (!preset) {
+    return params;
+  }
+  const resolved = { ...params };
+  if (preset === "approve_usdc_to_escrow") {
+    resolved.action ??= "approve_token";
+    resolved.tokenAddress ??= agent.platformConfig.usdcAddress;
+    resolved.spender ??= agent.platformConfig.escrowAddress;
+  } else if (preset === "approve_usdc_to_tipjar") {
+    resolved.action ??= "approve_token";
+    resolved.tokenAddress ??= agent.platformConfig.usdcAddress;
+    resolved.spender ??= agent.platformConfig.tipJarAddress;
+  }
+  return resolved;
+}
 var server = new McpServer({
   name: "agentpact-mcp-server",
   version: "2.0.0"
@@ -139,6 +191,282 @@ server.registerTool(
     }
   }
 );
+server.registerTool(
+  "agentpact_get_wallet_overview",
+  {
+    title: "Get Wallet Overview",
+    description: "Return the current agent wallet address together with its ETH gas balance and configured USDC balance.",
+    inputSchema: z.object({}).strict(),
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+  },
+  async () => {
+    try {
+      const agent = await getAgent();
+      const overview = await agent.getWalletOverview();
+      const serialized = serializeForMcp(overview);
+      return {
+        content: [{ type: "text", text: serialized }],
+        structuredContent: { wallet: JSON.parse(serialized) }
+      };
+    } catch (error) {
+      return formatError(error, "get_wallet_overview");
+    }
+  }
+);
+server.registerTool(
+  "agentpact_get_token_balance",
+  {
+    title: "Get Token Balance",
+    description: "Read the current agent wallet's balance for an arbitrary ERC20 token address.",
+    inputSchema: z.object({
+      tokenAddress: addressSchema.describe("ERC20 token contract address")
+    }).strict(),
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+  },
+  async (params) => {
+    try {
+      const agent = await getAgent();
+      const balance = await agent.getTokenBalanceInfo(params.tokenAddress);
+      const serialized = serializeForMcp({
+        walletAddress: agent.walletAddress,
+        balance
+      });
+      return {
+        content: [{ type: "text", text: serialized }],
+        structuredContent: JSON.parse(serialized)
+      };
+    } catch (error) {
+      return formatError(error, "get_token_balance");
+    }
+  }
+);
+server.registerTool(
+  "agentpact_get_gas_quote",
+  {
+    title: "Get Gas Quote",
+    description: "Estimate gas and fee cost for a supported AgentPact write action before submitting a transaction.",
+    inputSchema: z.object({
+      preset: preflightPresetSchema.optional().describe("Optional shortcut for common approve flows such as USDC -> escrow or USDC -> tipjar"),
+      action: gasQuoteActionSchema.describe("Supported action to estimate"),
+      tokenAddress: addressSchema.optional().describe("Required for approve_token"),
+      spender: addressSchema.optional().describe("Required for approve_token"),
+      amount: z.string().optional().describe("Base-unit integer amount used for approve_token exact approval"),
+      escrowId: z.string().optional().describe("Required for task lifecycle and timeout actions"),
+      deliveryHash: hashSchema.optional().describe("Required for submit_delivery")
+    }).strict(),
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+  },
+  async (params) => {
+    try {
+      const agent = await getAgent();
+      const resolved = resolveActionPreset(agent, {
+        action: params.action,
+        tokenAddress: params.tokenAddress,
+        spender: params.spender
+      }, params.preset);
+      const quote = await agent.getGasQuote({
+        action: resolved.action,
+        tokenAddress: resolved.tokenAddress,
+        spender: resolved.spender,
+        amount: params.amount ? BigInt(params.amount) : void 0,
+        escrowId: params.escrowId ? BigInt(params.escrowId) : void 0,
+        deliveryHash: params.deliveryHash
+      });
+      const serialized = serializeForMcp(quote);
+      return {
+        content: [{ type: "text", text: serialized }],
+        structuredContent: { quote: JSON.parse(serialized) }
+      };
+    } catch (error) {
+      return formatError(error, "get_gas_quote");
+    }
+  }
+);
+server.registerTool(
+  "agentpact_preflight_check",
+  {
+    title: "Preflight Check",
+    description: "Run a lightweight safety check before a gas-spending or token-spending action. Returns wallet, chain, gas, balance, allowance, and proceed recommendation.",
+    inputSchema: z.object({
+      preset: preflightPresetSchema.optional().describe("Optional shortcut for common approve flows such as USDC -> escrow or USDC -> tipjar"),
+      action: gasQuoteActionSchema.optional().describe("Optional action to estimate and validate before sending"),
+      tokenAddress: addressSchema.optional().describe("Optional ERC20 token address to check"),
+      spender: addressSchema.optional().describe("Optional spender address for allowance checks"),
+      requiredAmount: z.string().optional().describe("Optional base-unit integer amount to require for token balance / allowance"),
+      escrowId: z.string().optional().describe("Escrow ID for action-aware checks"),
+      deliveryHash: hashSchema.optional().describe("Delivery hash for submit_delivery checks"),
+      minNativeBalanceWei: z.string().optional().describe("Optional explicit ETH threshold in wei")
+    }).strict(),
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+  },
+  async (params) => {
+    try {
+      const agent = await getAgent();
+      const resolved = resolveActionPreset(agent, {
+        action: params.action,
+        tokenAddress: params.tokenAddress,
+        spender: params.spender
+      }, params.preset);
+      const result = await agent.preflightCheck({
+        action: resolved.action,
+        tokenAddress: resolved.tokenAddress,
+        spender: resolved.spender,
+        requiredAmount: params.requiredAmount ? BigInt(params.requiredAmount) : void 0,
+        escrowId: params.escrowId ? BigInt(params.escrowId) : void 0,
+        deliveryHash: params.deliveryHash,
+        minNativeBalanceWei: params.minNativeBalanceWei ? BigInt(params.minNativeBalanceWei) : void 0
+      });
+      const serialized = serializeForMcp(result);
+      return {
+        content: [{ type: "text", text: serialized }],
+        structuredContent: { preflight: JSON.parse(serialized) }
+      };
+    } catch (error) {
+      return formatError(error, "preflight_check");
+    }
+  }
+);
+server.registerTool(
+  "agentpact_get_transaction_status",
+  {
+    title: "Get Transaction Status",
+    description: "Read the latest observable status of a transaction without waiting. Returns pending, success, reverted, or not_found.",
+    inputSchema: z.object({
+      txHash: hashSchema.describe("Transaction hash to inspect")
+    }).strict(),
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+  },
+  async (params) => {
+    try {
+      const agent = await getAgent();
+      const status = await agent.getTransactionStatus(params.txHash);
+      const serialized = serializeForMcp(status);
+      return {
+        content: [{ type: "text", text: serialized }],
+        structuredContent: { transaction: JSON.parse(serialized) }
+      };
+    } catch (error) {
+      return formatError(error, "get_transaction_status");
+    }
+  }
+);
+server.registerTool(
+  "agentpact_get_token_allowance",
+  {
+    title: "Get Token Allowance",
+    description: "Read the current agent wallet's ERC20 allowance for a spender contract.",
+    inputSchema: z.object({
+      tokenAddress: addressSchema.describe("ERC20 token contract address"),
+      spender: addressSchema.describe("Contract or wallet allowed to spend the token")
+    }).strict(),
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+  },
+  async (params) => {
+    try {
+      const agent = await getAgent();
+      const [allowance, token] = await Promise.all([
+        agent.getTokenAllowance(
+          params.tokenAddress,
+          params.spender
+        ),
+        agent.getTokenBalanceInfo(params.tokenAddress)
+      ]);
+      const serialized = serializeForMcp({
+        owner: agent.walletAddress,
+        spender: params.spender,
+        token: {
+          tokenAddress: token.tokenAddress,
+          symbol: token.symbol,
+          decimals: token.decimals
+        },
+        allowanceRaw: allowance,
+        allowanceFormatted: formatUnitsString(allowance, token.decimals)
+      });
+      return {
+        content: [{ type: "text", text: serialized }],
+        structuredContent: JSON.parse(serialized)
+      };
+    } catch (error) {
+      return formatError(error, "get_token_allowance");
+    }
+  }
+);
+server.registerTool(
+  "agentpact_approve_token",
+  {
+    title: "Approve Token",
+    description: "Submit an ERC20 approve transaction from the current agent wallet. Exact mode expects a base-unit integer string.",
+    inputSchema: z.object({
+      tokenAddress: addressSchema.describe("ERC20 token contract address"),
+      spender: addressSchema.describe("Contract or wallet allowed to spend the token"),
+      mode: z.enum(["max", "exact"]).default("max").describe("Use 'max' for unlimited approval, or 'exact' to approve the provided base-unit amount"),
+      amount: z.string().optional().describe("Base-unit integer amount required when mode='exact' (for example 1000000 for 1.0 USDC)")
+    }).strict()
+  },
+  async (params) => {
+    try {
+      let amount;
+      if (params.mode === "exact") {
+        if (!params.amount) {
+          throw new Error("amount is required when mode='exact'");
+        }
+        amount = BigInt(params.amount);
+      }
+      const agent = await getAgent();
+      const txHash = await agent.approveToken(
+        params.tokenAddress,
+        params.spender,
+        amount
+      );
+      return {
+        content: [{
+          type: "text",
+          text: `Approval transaction submitted. TX: ${txHash}`
+        }],
+        structuredContent: {
+          txHash,
+          mode: params.mode,
+          amount: amount?.toString() ?? "max",
+          tokenAddress: params.tokenAddress,
+          spender: params.spender
+        }
+      };
+    } catch (error) {
+      return formatError(error, "approve_token");
+    }
+  }
+);
+server.registerTool(
+  "agentpact_wait_for_transaction",
+  {
+    title: "Wait For Transaction",
+    description: "Wait for a transaction receipt and return status, gas usage, and explorer link.",
+    inputSchema: z.object({
+      txHash: hashSchema.describe("Transaction hash to wait for"),
+      confirmations: z.number().int().min(1).max(25).default(1).describe("How many confirmations to wait for"),
+      timeoutMs: z.number().int().min(1e3).max(6e5).optional().describe("Optional timeout in milliseconds")
+    }).strict()
+  },
+  async (params) => {
+    try {
+      const agent = await getAgent();
+      const receipt = await agent.waitForTransaction(
+        params.txHash,
+        {
+          confirmations: params.confirmations,
+          timeoutMs: params.timeoutMs
+        }
+      );
+      const serialized = serializeForMcp(receipt);
+      return {
+        content: [{ type: "text", text: serialized }],
+        structuredContent: { receipt: JSON.parse(serialized) }
+      };
+    } catch (error) {
+      return formatError(error, "wait_for_transaction");
+    }
+  }
+);
 server.registerTool(
   "agentpact_bid_on_task",
   {
@@ -345,11 +673,7 @@ server.registerTool(
     try {
       const agent = await getAgent();
       const escrow = await agent.client.getEscrow(BigInt(params.escrowId));
-      const serialized = JSON.stringify(
-        escrow,
-        (_, v) => typeof v === "bigint" ? v.toString() + "n" : v,
-        2
-      );
+      const serialized = serializeForMcp(escrow);
       return {
         content: [{ type: "text", text: serialized }],
         structuredContent: { escrow: JSON.parse(serialized) }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentpactai/mcp-server",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Primary MCP tool layer for AgentPact, built on top of @agentpactai/runtime.",
   "type": "module",
   "main": "dist/index.js",
@@ -43,7 +43,7 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.1",
-    "@agentpactai/runtime": "0.1.6"
+    "@agentpactai/runtime": "0.1.7"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",