@quackai/q402-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of tracking or otherwise improving the Work,
+      but excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Quack AI Labs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -0,0 +1,124 @@
+# @quackai/q402-mcp
+
+> MCP server for Q402 — gasless USDC and USDT payments across 7 EVM chains, callable directly from Claude Desktop and any other Model Context Protocol client.
+
+[![npm](https://img.shields.io/npm/v/@quackai/q402-mcp.svg)](https://www.npmjs.com/package/@quackai/q402-mcp)
+[![license](https://img.shields.io/npm/l/@quackai/q402-mcp.svg)](./LICENSE)
+
+Claude can now reason about stablecoin payments end to end — quote a transfer across 7 chains, pick the cheapest route, and (optionally) settle the transaction over [Q402](https://q402.quackai.ai)'s EIP-7702 relayer infrastructure. The recipient receives the full amount; the sender pays $0 in gas.
+
+---
+
+## Quick start (Claude Desktop)
+
+```bash
+claude mcp add q402 -- npx @quackai/q402-mcp
+```
+
+Or, if you prefer editing the config file directly, add this entry to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "q402": {
+      "command": "npx",
+      "args": ["-y", "@quackai/q402-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop and ask:
+
+> *"Compare gas costs to send 50 USDC to vitalik.eth across all 7 Q402 chains."*
+
+You'll get a ranked breakdown immediately — no API key, no signup, no funds at risk.
+
+---
+
+## Tools exposed
+
+| Tool | Auth | Purpose |
+|---|---|---|
+| `q402_quote` | none | Compare gas cost and supported tokens across chains. Read-only. |
+| `q402_balance` | API key | Verify the API key, show tier (live vs sandbox), and remaining quota. |
+| `q402_pay` | API key + private key + flag | Send a gasless payment. **Sandbox by default** — see [Sandbox vs live mode](#sandbox-vs-live-mode). |
+
+`q402_pay` follows a "confirm in chat first" contract: the tool description instructs the model to never call it without explicit user approval of the recipient address, amount, chain, and token.
+
+> Per-chain gas tank balances and full transaction history live in the [dashboard](https://q402.quackai.ai/dashboard) — those endpoints require a wallet signature, not a bare API key, so the MCP server points the agent there instead of exposing them.
+
+---
+
+## Sandbox vs live mode
+
+By default the MCP server operates in **sandbox mode**: `q402_pay` returns a deterministic-looking fake transaction hash, no funds move, no gas-tank credit is consumed. That makes it safe to plug into any Claude Desktop install without worrying about an LLM hallucinating a payment.
+
+To enable real on-chain transactions, **all three** environment variables must be set:
+
+```bash
+Q402_API_KEY=q402_live_...           # live-tier key from /dashboard
+Q402_PRIVATE_KEY=0xabc...            # signer for the payer EOA
+Q402_ENABLE_REAL_PAYMENTS=1          # explicit opt-in
+```
+
+Anything missing → automatic sandbox fallback with a hint pointing at what to set.
+
+### Hard caps
+
+Two additional guards run before every payment regardless of mode:
+
+| Env var | Default | Effect |
+|---|---|---|
+| `Q402_MAX_AMOUNT_PER_CALL` | `5` | Reject any single call where `amount > N` USD-equivalent. |
+| `Q402_ALLOWED_RECIPIENTS` | (empty = off) | Comma-separated address allowlist. When set, all other recipients are rejected. |
+
+Combined with the `confirm: true` argument the tool requires, this means the model needs (a) explicit user OK in chat, (b) amount ≤ cap, (c) recipient on allowlist if one exists, (d) all three live-mode env vars set, before a single wei moves.
+
+---
+
+## Configuration reference
+
+| Env var | Required for | Notes |
+|---|---|---|
+| `Q402_API_KEY` | balance/history/live-pay | Issue at https://q402.quackai.ai/dashboard. `q402_test_*` keys keep sandbox on. |
+| `Q402_PRIVATE_KEY` | live-pay | Signer for the payer EOA. **Never share. Never paste in chat.** |
+| `Q402_ENABLE_REAL_PAYMENTS` | live-pay | Set to `1` to opt in. Any other value (or unset) → sandbox. |
+| `Q402_MAX_AMOUNT_PER_CALL` | optional | USD-equivalent cap. Defaults to `5`. |
+| `Q402_ALLOWED_RECIPIENTS` | optional | Comma-separated lowercase addresses. Defaults to no allowlist. |
+| `Q402_RELAY_BASE_URL` | optional | Defaults to `https://q402.quackai.ai/api`. Override for self-hosted Q402. |
+
+---
+
+## Supported chains
+
+| Chain | Chain ID | Token(s) | Notes |
+|---|---|---|---|
+| BNB Chain | 56 | USDC, USDT | |
+| Ethereum | 1 | USDC, USDT | L1 — gas is volatile, quote is a snapshot. |
+| Avalanche C-Chain | 43114 | USDC, USDT | |
+| X Layer | 196 | USDC, USDT | |
+| Stable | 988 | USDT0 (USDC and USDT both alias) | Gas paid in USDT0. |
+| Mantle | 5000 | USDC, USDT0 | LayerZero OFT USDT0 since 2025-11-27. |
+| Injective EVM | 1776 | USDT only | Native USDC via Circle CCTP announced for Q2 2026. |
+
+---
+
+## Why this exists
+
+x402 standardised "402 Payment Required" semantics for AI agents but the official Coinbase facilitator only covers a few chains and assumes ERC-3009 token support — which excludes BNB USDT, Mantle USDT0, Injective USDT, and the chains where most stablecoin volume actually lives.
+
+Q402 implements the same payer experience (single signature, $0 gas, instant settlement) on all 7 of those chains using EIP-7702 delegated execution, which works with any ERC-20. This MCP server makes that infrastructure addressable from Claude itself.
+
+If you want to dig into how the wire protocol differs from x402, see [Q402 docs](https://q402.quackai.ai/docs).
+
+---
+
+## Repository
+
+Source code: https://github.com/bitgett/q402-mcp
+Issues / requests: https://github.com/bitgett/q402-mcp/issues
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

package/dist/index.js

@@ -0,0 +1,627 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/config.ts
+import { isAddress } from "ethers";
+var DEFAULT_RELAY_BASE = "https://q402.quackai.ai/api";
+var DEFAULT_MAX_AMOUNT = 5;
+function classifyApiKey(k) {
+  if (!k) return "missing";
+  if (k.startsWith("q402_live_")) return "live";
+  if (k.startsWith("q402_test_")) return "test";
+  return "missing";
+}
+function parseAllowedRecipients(raw) {
+  if (!raw) return [];
+  return raw.split(",").map((s) => s.trim().toLowerCase()).filter((s) => s.length > 0 && isAddress(s));
+}
+function parseMaxAmount(raw) {
+  if (!raw) return DEFAULT_MAX_AMOUNT;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_MAX_AMOUNT;
+  return n;
+}
+function loadConfig() {
+  const apiKey = process.env.Q402_API_KEY ?? null;
+  const apiKeyKind = classifyApiKey(apiKey);
+  const privateKey = process.env.Q402_PRIVATE_KEY ?? null;
+  const realPaymentsRequested = process.env.Q402_ENABLE_REAL_PAYMENTS === "1";
+  const live = realPaymentsRequested && apiKeyKind === "live" && typeof privateKey === "string" && privateKey.length > 0;
+  return {
+    apiKey,
+    apiKeyKind,
+    privateKey,
+    realPaymentsRequested,
+    mode: live ? "live" : "sandbox",
+    relayBaseUrl: (process.env.Q402_RELAY_BASE_URL ?? DEFAULT_RELAY_BASE).replace(/\/$/, ""),
+    maxAmountPerCallUsd: parseMaxAmount(process.env.Q402_MAX_AMOUNT_PER_CALL),
+    allowedRecipients: parseAllowedRecipients(process.env.Q402_ALLOWED_RECIPIENTS)
+  };
+}
+var CONFIG = loadConfig();
+
+// src/tools/quote.ts
+import { z } from "zod";
+
+// src/chains.ts
+var CHAIN_KEYS = [
+  "avax",
+  "bnb",
+  "eth",
+  "xlayer",
+  "stable",
+  "mantle",
+  "injective"
+];
+var CHAIN_CONFIG = {
+  avax: {
+    key: "avax",
+    name: "Avalanche C-Chain",
+    chainId: 43114,
+    domainName: "Q402 Avalanche",
+    implContract: "0x96a8C74d95A35D0c14Ec60364c78ba6De99E9A4c",
+    gasToken: "AVAX",
+    explorer: "https://snowtrace.io",
+    usdc: { address: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", decimals: 6 },
+    usdt: { address: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7", decimals: 6 },
+    approxGasCostUsd: 3e-3
+  },
+  bnb: {
+    key: "bnb",
+    name: "BNB Chain",
+    chainId: 56,
+    domainName: "Q402 BNB Chain",
+    implContract: "0x6cF4aD62C208b6494a55a1494D497713ba013dFa",
+    gasToken: "BNB",
+    explorer: "https://bscscan.com",
+    usdc: { address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", decimals: 18 },
+    usdt: { address: "0x55d398326f99059fF775485246999027B3197955", decimals: 18 },
+    approxGasCostUsd: 1e-3
+  },
+  eth: {
+    key: "eth",
+    name: "Ethereum Mainnet",
+    chainId: 1,
+    domainName: "Q402 Ethereum",
+    implContract: "0x8E67a64989CFcb0C40556b13ea302709CCFD6AaD",
+    gasToken: "ETH",
+    explorer: "https://etherscan.io",
+    usdc: { address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", decimals: 6 },
+    usdt: { address: "0xdAC17F958D2ee523a2206206994597C13D831ec7", decimals: 6 },
+    approxGasCostUsd: 1.2,
+    note: "L1 \u2014 gas is volatile; quote is a snapshot, expect 5\u201310x swings during congestion."
+  },
+  xlayer: {
+    key: "xlayer",
+    name: "X Layer",
+    chainId: 196,
+    domainName: "Q402 X Layer",
+    implContract: "0x8D854436ab0426F5BC6Cc70865C90576AD523E73",
+    gasToken: "OKB",
+    explorer: "https://www.oklink.com/xlayer",
+    usdc: { address: "0x74b7F16337b8972027F6196A17a631aC6dE26d22", decimals: 6 },
+    usdt: { address: "0x1E4a5963aBFD975d8c9021ce480b42188849D41D", decimals: 6 },
+    approxGasCostUsd: 2e-3
+  },
+  stable: {
+    key: "stable",
+    name: "Stable Chain",
+    chainId: 988,
+    domainName: "Q402 Stable",
+    implContract: "0x2fb2B2D110b6c5664e701666B3741240242bf350",
+    gasToken: "USDT0",
+    explorer: "https://stable-explorer.io",
+    // USDT0 (the only token on Stable) — both USDC and USDT API tokens resolve here.
+    usdc: { address: "0x779ded0c9e1022225f8e0630b35a9b54be713736", decimals: 18 },
+    usdt: { address: "0x779ded0c9e1022225f8e0630b35a9b54be713736", decimals: 18 },
+    approxGasCostUsd: 5e-4,
+    note: "Gas is paid in USDT0; both USDC and USDT API inputs alias to USDT0."
+  },
+  mantle: {
+    key: "mantle",
+    name: "Mantle",
+    chainId: 5e3,
+    domainName: "Q402 Mantle",
+    implContract: "0x2fb2B2D110b6c5664e701666B3741240242bf350",
+    gasToken: "MNT",
+    explorer: "https://mantlescan.xyz",
+    usdc: { address: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9", decimals: 6 },
+    // USDT0 (LayerZero OFT) — Mantle ecosystem default since the 2025-11-27 migration.
+    usdt: { address: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736", decimals: 6 },
+    approxGasCostUsd: 2e-3
+  },
+  injective: {
+    key: "injective",
+    name: "Injective EVM",
+    chainId: 1776,
+    domainName: "Q402 Injective",
+    implContract: "0x2fb2B2D110b6c5664e701666B3741240242bf350",
+    gasToken: "INJ",
+    explorer: "https://blockscout.injective.network",
+    // Mirror entry for the registry shape — both API tokens point at the same USDT.
+    // q402_pay rejects token: "USDC" with chain: "injective" upfront via supportedTokens.
+    usdc: { address: "0x88f7F2b685F9692caf8c478f5BADF09eE9B1Cc13", decimals: 6 },
+    usdt: { address: "0x88f7F2b685F9692caf8c478f5BADF09eE9B1Cc13", decimals: 6 },
+    supportedTokens: ["USDT"],
+    approxGasCostUsd: 4e-3,
+    note: "USDT only until Circle CCTP native USDC ships (announced for Q2 2026)."
+  }
+};
+function getChain(key) {
+  const cfg = CHAIN_CONFIG[key];
+  if (!cfg) throw new Error(`Unsupported chain: ${key}. Supported: ${CHAIN_KEYS.join(", ")}`);
+  return cfg;
+}
+function tokenFor(cfg, token) {
+  return token === "USDC" ? cfg.usdc : cfg.usdt;
+}
+
+// src/tools/quote.ts
+var QuoteInputSchema = z.object({
+  amount: z.string().regex(/^\d+(\.\d+)?$/, 'amount must be a positive decimal string like "5.00"').describe('Human-readable decimal amount the user intends to send (e.g. "5", "50.00").'),
+  token: z.enum(["USDC", "USDT"]).optional().describe("Optional token filter. When omitted, both stablecoin options are reported."),
+  chain: z.enum(["avax", "bnb", "eth", "xlayer", "stable", "mantle", "injective"]).optional().describe(
+    "Optional chain filter. When omitted, all 7 chains are compared and ranked by gas cost."
+  )
+});
+function quoteForChain(cfg) {
+  const supported = cfg.supportedTokens ?? ["USDC", "USDT"];
+  return {
+    chain: cfg.key,
+    name: cfg.name,
+    chainId: cfg.chainId,
+    gasToken: cfg.gasToken,
+    approxGasCostUsd: cfg.approxGasCostUsd,
+    supportedTokens: supported,
+    gasTokenForReceiver: "0 (gasless)",
+    ...cfg.note ? { note: cfg.note } : {}
+  };
+}
+function runQuote(input) {
+  const filterChain = input.chain;
+  const filterToken = input.token;
+  const candidates = (filterChain ? [filterChain] : CHAIN_KEYS).map((k) => CHAIN_CONFIG[k]).filter((cfg) => {
+    if (!filterToken) return true;
+    if (cfg.supportedTokens && !cfg.supportedTokens.includes(filterToken)) return false;
+    return true;
+  });
+  if (candidates.length === 0) {
+    throw new Error(
+      `No chain in the registry supports token ${filterToken}. Try omitting the token filter to see all options.`
+    );
+  }
+  const quotes = candidates.map(quoteForChain).sort((a, b) => a.approxGasCostUsd - b.approxGasCostUsd);
+  const cheapest = quotes[0];
+  return {
+    amount: input.amount,
+    recommendedChain: cheapest.chain,
+    quotes,
+    disclaimer: "Gas cost is order-of-magnitude only. Real cost depends on network congestion at relay time. Q402 always charges $0 to the payer's wallet \u2014 gas is paid from the developer's pre-funded gas tank."
+  };
+}
+var QUOTE_TOOL = {
+  name: "q402_quote",
+  description: "Compare gas costs and supported tokens across the 7 chains Q402 relays for. Read-only \u2014 no API key needed, no funds move. Use this before q402_pay so the user can pick the cheapest chain.",
+  // Plain JSON schema mirroring the Zod schema above; MCP servers receive parameters as JSON.
+  inputSchema: {
+    type: "object",
+    properties: {
+      amount: {
+        type: "string",
+        description: 'Human-readable decimal amount, e.g. "5" or "50.00".'
+      },
+      token: {
+        type: "string",
+        enum: ["USDC", "USDT"],
+        description: "Optional token filter."
+      },
+      chain: {
+        type: "string",
+        enum: CHAIN_KEYS,
+        description: "Optional chain filter; omit to compare all 7."
+      }
+    },
+    required: ["amount"],
+    additionalProperties: false
+  }
+};
+
+// src/tools/pay.ts
+import { isAddress as isAddress2 } from "ethers";
+import { z as z2 } from "zod";
+
+// src/client.ts
+import {
+  JsonRpcProvider,
+  Wallet,
+  hexlify,
+  parseUnits,
+  randomBytes,
+  toBigInt
+} from "ethers";
+var DEFAULT_RPC = {
+  1: "https://ethereum.publicnode.com",
+  56: "https://bsc-dataseed1.binance.org/",
+  43114: "https://api.avax.network/ext/bc/C/rpc",
+  196: "https://rpc.xlayer.tech",
+  988: "https://rpc.stable.xyz",
+  5e3: "https://rpc.mantle.xyz",
+  1776: "https://sentry.evm-rpc.injective.network/"
+};
+var TRANSFER_AUTH_TYPES = {
+  TransferAuthorization: [
+    { name: "owner", type: "address" },
+    { name: "facilitator", type: "address" },
+    { name: "token", type: "address" },
+    { name: "recipient", type: "address" },
+    { name: "amount", type: "uint256" },
+    { name: "nonce", type: "uint256" },
+    { name: "deadline", type: "uint256" }
+  ]
+};
+var AUTHORIZATION_TYPES = {
+  Authorization: [
+    { name: "address", type: "address" },
+    { name: "nonce", type: "uint256" }
+  ]
+};
+function toRawAmount(amount, decimals) {
+  if (typeof amount !== "string" || amount.trim() === "") {
+    throw new Error('amount must be a non-empty decimal string (e.g. "5.00")');
+  }
+  if (!/^\d+(\.\d+)?$/.test(amount)) {
+    throw new Error(
+      `invalid amount "${amount}" \u2014 use a positive decimal string (no sign, no scientific notation, no whitespace)`
+    );
+  }
+  let raw;
+  try {
+    raw = parseUnits(amount, decimals);
+  } catch {
+    throw new Error(`amount "${amount}" exceeds ${decimals} decimal places`);
+  }
+  if (raw <= 0n) {
+    throw new Error(`amount must be greater than zero (got "${amount}")`);
+  }
+  return raw.toString();
+}
+async function signAuthorization(wallet, args) {
+  const domain = { name: "EIP7702Authorization", version: "1", chainId: args.chainId };
+  const sig = await wallet.signTypedData(domain, AUTHORIZATION_TYPES, {
+    address: args.address,
+    nonce: args.nonce
+  });
+  const r = sig.slice(0, 66);
+  const s = "0x" + sig.slice(66, 130);
+  const v = parseInt(sig.slice(130, 132), 16);
+  const yParity = v === 27 ? 0 : 1;
+  return { chainId: args.chainId, address: args.address, nonce: args.nonce, yParity, r, s };
+}
+var Q402NodeClient = class _Q402NodeClient {
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  /**
+   * Build a TX-shaped explorer URL from the chain's explorer base.
+   */
+  static explorerUrl(chain, txHash) {
+    if (!txHash) return null;
+    return `${chain.explorer.replace(/\/$/, "")}/tx/${txHash}`;
+  }
+  async fetchFacilitator() {
+    const url = `${this.opts.relayBaseUrl.replace(/\/$/, "")}/relay/info`;
+    const resp = await fetch(url);
+    if (!resp.ok) {
+      throw new Error(
+        `failed to fetch relay facilitator info from ${url} (${resp.status})`
+      );
+    }
+    const data = await resp.json();
+    if (!data.facilitator || typeof data.facilitator !== "string") {
+      throw new Error("relay/info did not return a facilitator address");
+    }
+    return data.facilitator;
+  }
+  async pay(input) {
+    const { chain, relayBaseUrl, apiKey, privateKey } = this.opts;
+    const tokenCfg = tokenFor(chain, input.token);
+    if (chain.supportedTokens && !chain.supportedTokens.includes(input.token)) {
+      throw new Error(
+        `token ${input.token} is not supported on chain ${chain.key}. Supported: ${chain.supportedTokens.join(", ")}.`
+      );
+    }
+    const amountRaw = toRawAmount(input.amount, tokenCfg.decimals);
+    const deadline = Math.floor(Date.now() / 1e3) + 600;
+    const rpcUrl = this.opts.rpcUrl ?? DEFAULT_RPC[chain.chainId];
+    if (!rpcUrl) {
+      throw new Error(
+        `no RPC URL configured for chain ${chain.key} (chainId ${chain.chainId})`
+      );
+    }
+    const provider = new JsonRpcProvider(rpcUrl);
+    const wallet = new Wallet(privateKey, provider);
+    const owner = await wallet.getAddress();
+    const facilitator = await this.fetchFacilitator();
+    const paymentNonce = toBigInt(randomBytes(32));
+    const witnessSig = await wallet.signTypedData(
+      {
+        name: chain.domainName,
+        version: "1",
+        chainId: chain.chainId,
+        verifyingContract: owner
+        // EIP-7702: address(this) resolves to the EOA
+      },
+      TRANSFER_AUTH_TYPES,
+      {
+        owner,
+        facilitator,
+        token: tokenCfg.address,
+        recipient: input.to,
+        amount: BigInt(amountRaw),
+        nonce: paymentNonce,
+        deadline: BigInt(deadline)
+      }
+    );
+    const authNonce = await provider.getTransactionCount(owner);
+    const authorization = await signAuthorization(wallet, {
+      chainId: chain.chainId,
+      address: chain.implContract,
+      nonce: authNonce
+    });
+    const baseBody = {
+      apiKey,
+      chain: chain.key,
+      token: input.token,
+      from: owner,
+      to: input.to,
+      amount: amountRaw,
+      deadline,
+      witnessSig,
+      authorization,
+      facilitator
+    };
+    const body = chain.key === "xlayer" ? { ...baseBody, xlayerNonce: paymentNonce.toString() } : chain.key === "stable" ? { ...baseBody, stableNonce: paymentNonce.toString() } : { ...baseBody, nonce: paymentNonce.toString() };
+    const resp = await fetch(`${relayBaseUrl.replace(/\/$/, "")}/relay`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    const data = await resp.json();
+    if (!resp.ok) {
+      throw new Error(data.error ?? `relay failed (HTTP ${resp.status})`);
+    }
+    data.mode = "live";
+    data.explorerUrl = _Q402NodeClient.explorerUrl(chain, data.txHash);
+    return data;
+  }
+};
+function sandboxPay(chain, input) {
+  const tokenCfg = tokenFor(chain, input.token);
+  const tokenAmount = toRawAmount(input.amount, tokenCfg.decimals);
+  const fakeHash = "0x" + hexlify(randomBytes(32)).slice(2);
+  return {
+    success: true,
+    txHash: fakeHash,
+    tokenAmount,
+    token: input.token,
+    chain: chain.key,
+    method: "sandbox",
+    mode: "sandbox",
+    explorerUrl: null
+  };
+}
+
+// src/tools/pay.ts
+var PayInputSchema = z2.object({
+  chain: z2.enum(["avax", "bnb", "eth", "xlayer", "stable", "mantle", "injective"]),
+  to: z2.string().refine(isAddress2, "to must be a valid 0x-prefixed EVM address").describe("Recipient EVM address (0x + 40 hex)."),
+  amount: z2.string().regex(/^\d+(\.\d+)?$/, "amount must be a positive decimal string").describe('Human-readable decimal amount, e.g. "5.00".'),
+  token: z2.enum(["USDC", "USDT"]),
+  confirm: z2.literal(true).describe(
+    "MUST be true. Prove the user explicitly approved this exact recipient and amount in the conversation right before this tool was called. Setting this to true on behalf of the user without confirmation is a violation of the tool contract."
+  )
+});
+function maxAmountGuard(amount, cap) {
+  const numeric = Number(amount);
+  if (!Number.isFinite(numeric)) {
+    throw new Error(`unparseable amount "${amount}"`);
+  }
+  if (numeric > cap) {
+    throw new Error(
+      `amount $${amount} exceeds the per-call cap of $${cap}. Set Q402_MAX_AMOUNT_PER_CALL to a higher value if intentional.`
+    );
+  }
+}
+function recipientGuard(to, allow) {
+  if (allow.length === 0) return;
+  if (!allow.includes(to.toLowerCase())) {
+    throw new Error(
+      `recipient ${to} is not in Q402_ALLOWED_RECIPIENTS. Either add this address to the allowlist or unset the env var to disable the guard.`
+    );
+  }
+}
+async function runPay(input) {
+  const chain = getChain(input.chain);
+  tokenFor(chain, input.token);
+  if (chain.supportedTokens && !chain.supportedTokens.includes(input.token)) {
+    throw new Error(
+      `token ${input.token} is not supported on chain ${chain.key}. Supported on this chain: ${chain.supportedTokens.join(", ")}.`
+    );
+  }
+  const guardsApplied = [];
+  maxAmountGuard(input.amount, CONFIG.maxAmountPerCallUsd);
+  guardsApplied.push(`max_amount<=${CONFIG.maxAmountPerCallUsd}`);
+  recipientGuard(input.to, CONFIG.allowedRecipients);
+  if (CONFIG.allowedRecipients.length > 0) {
+    guardsApplied.push(`recipient_allowlist[${CONFIG.allowedRecipients.length}]`);
+  }
+  if (CONFIG.mode === "sandbox") {
+    const result2 = sandboxPay(chain, {
+      to: input.to,
+      amount: input.amount,
+      token: input.token
+    });
+    guardsApplied.push("mode=sandbox");
+    const setupHint = describeSandboxReason();
+    return { result: result2, guardsApplied, setupHint };
+  }
+  const client = new Q402NodeClient({
+    apiKey: CONFIG.apiKey,
+    privateKey: CONFIG.privateKey,
+    chain,
+    relayBaseUrl: CONFIG.relayBaseUrl
+  });
+  const result = await client.pay({
+    to: input.to,
+    amount: input.amount,
+    token: input.token
+  });
+  guardsApplied.push("mode=live");
+  return { result, guardsApplied };
+}
+function describeSandboxReason() {
+  const missing = [];
+  if (CONFIG.apiKeyKind !== "live") missing.push("Q402_API_KEY (must start with q402_live_)");
+  if (!CONFIG.privateKey) missing.push("Q402_PRIVATE_KEY");
+  if (!CONFIG.realPaymentsRequested) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
+  if (missing.length === 0) return "Sandbox mode active (no env state change needed).";
+  return "Sandbox mode is active because the following env vars are missing or not yet set: " + missing.join(", ") + ". Get a live API key at https://q402.quackai.ai/dashboard.";
+}
+var PAY_TOOL = {
+  name: "q402_pay",
+  description: "Send a gasless USDC or USDT payment via Q402. SANDBOX BY DEFAULT \u2014 no funds move unless Q402_API_KEY (live tier), Q402_PRIVATE_KEY, and Q402_ENABLE_REAL_PAYMENTS=1 are all set. The recipient receives the full amount; the sender pays $0 in gas. ALWAYS get explicit user confirmation of the exact recipient address, amount, chain, and token in conversation immediately before calling this tool.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      chain: {
+        type: "string",
+        enum: CHAIN_KEYS,
+        description: "Target chain."
+      },
+      to: {
+        type: "string",
+        description: "Recipient EVM address (0x + 40 hex)."
+      },
+      amount: {
+        type: "string",
+        description: 'Human-readable decimal amount, e.g. "5.00".'
+      },
+      token: {
+        type: "string",
+        enum: ["USDC", "USDT"],
+        description: "Stablecoin to send. On Injective only USDT is currently supported."
+      },
+      confirm: {
+        type: "boolean",
+        const: true,
+        description: "MUST be true and only set after the user has confirmed recipient + amount in chat."
+      }
+    },
+    required: ["chain", "to", "amount", "token", "confirm"],
+    additionalProperties: false
+  }
+};
+
+// src/tools/balance.ts
+import { z as z3 } from "zod";
+var BalanceInputSchema = z3.object({});
+function mask(key) {
+  if (!key || key.length < 12) return null;
+  return `${key.slice(0, 12)}\u2026${key.slice(-4)}`;
+}
+async function runBalance() {
+  if (CONFIG.apiKeyKind === "missing") {
+    return {
+      apiKeyKind: "missing",
+      apiKeyMasked: null,
+      dashboardUrl: "https://q402.quackai.ai/dashboard",
+      setupHint: "Set Q402_API_KEY to a key issued at https://q402.quackai.ai/dashboard. Test-tier keys (q402_test_*) work too \u2014 they show sandbox quota."
+    };
+  }
+  const resp = await fetch(`${CONFIG.relayBaseUrl}/keys/verify`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ apiKey: CONFIG.apiKey })
+  });
+  const verifyJson = resp.ok ? await resp.json() : { error: `HTTP ${resp.status}` };
+  return {
+    apiKeyKind: CONFIG.apiKeyKind,
+    apiKeyMasked: mask(CONFIG.apiKey),
+    verify: verifyJson,
+    dashboardUrl: "https://q402.quackai.ai/dashboard"
+  };
+}
+var BALANCE_TOOL = {
+  name: "q402_balance",
+  description: "Verify the configured API key and show its tier (live vs sandbox) and remaining subscription quota. Read-only. For per-chain gas tank balances, point the user at https://q402.quackai.ai/dashboard \u2014 that data needs a wallet signature, not a bare key.",
+  inputSchema: {
+    type: "object",
+    properties: {},
+    additionalProperties: false
+  }
+};
+
+// src/index.ts
+var PACKAGE_NAME = "@quackai/q402-mcp";
+var PACKAGE_VERSION = "0.1.0";
+function jsonText(value) {
+  return { type: "text", text: JSON.stringify(value, null, 2) };
+}
+async function main() {
+  const server = new Server(
+    { name: PACKAGE_NAME, version: PACKAGE_VERSION },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [QUOTE_TOOL, BALANCE_TOOL, PAY_TOOL]
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    try {
+      switch (name) {
+        case "q402_quote": {
+          const parsed = QuoteInputSchema.parse(args ?? {});
+          return { content: [jsonText(runQuote(parsed))] };
+        }
+        case "q402_balance": {
+          BalanceInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runBalance())] };
+        }
+        case "q402_pay": {
+          const parsed = PayInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runPay(parsed))] };
+        }
+        default:
+          return {
+            isError: true,
+            content: [jsonText({ error: `unknown tool: ${name}` })]
+          };
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        isError: true,
+        content: [jsonText({ error: message, tool: name })]
+      };
+    }
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write(
+    `${PACKAGE_NAME} v${PACKAGE_VERSION} ready (mode=${CONFIG.mode}, cap=$${CONFIG.maxAmountPerCallUsd}, allowlist=${CONFIG.allowedRecipients.length})
+`
+  );
+}
+main().catch((err) => {
+  process.stderr.write(`fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@quackai/q402-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Q402 — gasless stablecoin payments across 7 EVM chains, callable directly from Claude Desktop and any MCP-compatible AI agent.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "q402",
+    "x402",
+    "stablecoin",
+    "usdc",
+    "usdt",
+    "gasless",
+    "eip-7702",
+    "payments",
+    "ai-agents"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "q402-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "ethers": "^6.16.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bitgett/q402-mcp.git"
+  },
+  "homepage": "https://q402.quackai.ai/claude",
+  "bugs": {
+    "url": "https://github.com/bitgett/q402-mcp/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Quack AI Labs <hello@quackai.ai>",
+  "publishConfig": {
+    "access": "public"
+  }
+}