@phantom/mcp-server 0.1.0 → 0.1.1

package/README.md

@@ -13,9 +13,11 @@ An MCP (Model Context Protocol) server that provides LLMs like Claude with direc
 - **SSO Authentication**: Seamless integration with Phantom's embedded wallet SSO flow (Google/Apple login)
 - **Session Persistence**: Automatic session management with stamper keys stored in `~/.phantom-mcp/session.json`
 - **Multi-Chain Support**: Works with Solana, Ethereum, Bitcoin, and Sui networks
-- **Three MCP Tools**:
+- **Five MCP Tools**:
   - `get_wallet_addresses` - Get blockchain addresses for the authenticated embedded wallet
   - `sign_transaction` - Sign transactions across supported chains
+  - `transfer_tokens` - Transfer SOL or SPL tokens on Solana (executes immediately)
+  - `buy_token` - Fetch a Solana swap quote from the Phantom quotes API (can execute immediately)
   - `sign_message` - Sign UTF-8 messages with automatic chain-specific routing
 
 ## Installation
@@ -179,6 +181,10 @@ This opens an interactive web UI where you can test tool calls without Claude De
 
 ## Available Tools
 
+> **Execution Warning**
+> `transfer_tokens` always submits a transaction immediately, and `buy_token` can submit immediately when `execute: true`.
+> If you need finer control (simulation, review, multi-sig, or custom signing), build your own transaction and use `sign_transaction` instead.
+
 ### 1. get_wallet_addresses
 
 Gets all blockchain addresses for the authenticated embedded wallet (Solana, Ethereum, Bitcoin, Sui).
@@ -252,7 +258,134 @@ Signs a transaction using the authenticated embedded wallet. Supports Solana, Et
 }
 ```
 
-### 3. sign_message
+### 3. transfer_tokens
+
+Transfers SOL or SPL tokens on Solana by building, signing, and sending the transaction.
+
+**Parameters:**
+
+- `walletId` (optional, string): The wallet ID to use for transfer (defaults to authenticated wallet)
+- `networkId` (required, string): Solana network identifier (e.g., "solana:mainnet", "solana:devnet")
+- `to` (required, string): Recipient Solana address
+- `amount` (required, string): Transfer amount as a string (e.g., "0.5" or "1000000")
+- `amountUnit` (optional, string): Amount unit (`ui` for SOL/token units, `base` for lamports/base units; default: `ui`)
+- `tokenMint` (optional, string): SPL token mint address (omit for SOL)
+- `decimals` (optional, number): Token decimals (optional for SPL tokens; fetched from chain if omitted)
+- `derivationIndex` (optional, number): Derivation index for the account (default: 0)
+- `rpcUrl` (optional, string): Solana RPC URL (defaults based on networkId)
+- `createAssociatedTokenAccount` (optional, boolean): Create destination ATA if missing (default: true)
+
+**Example (SOL):**
+
+```json
+{
+  "networkId": "solana:mainnet",
+  "to": "H8FpYTgx4Uy9aF9Nk9fCTqKKFLYQ9KfC6UJhMkMDzCBh",
+  "amount": "0.1",
+  "amountUnit": "ui"
+}
+```
+
+**Example (SPL Token):**
+
+```json
+{
+  "networkId": "solana:devnet",
+  "to": "H8FpYTgx4Uy9aF9Nk9fCTqKKFLYQ9KfC6UJhMkMDzCBh",
+  "tokenMint": "So11111111111111111111111111111111111111112",
+  "amount": "1.5",
+  "amountUnit": "ui"
+}
+```
+
+**Response:**
+
+```json
+{
+  "walletId": "05307b6d-2d5a-43d6-8d11-08db650a169b",
+  "networkId": "solana:mainnet",
+  "from": "H8FpYTgx4Uy9aF9Nk9fCTqKKFLYQ9KfC6UJhMkMDzCBh",
+  "to": "H8FpYTgx4Uy9aF9Nk9fCTqKKFLYQ9KfC6UJhMkMDzCBh",
+  "tokenMint": null,
+  "signature": "5oVZJ8b7k2rGm3rP3Gm5J3tFjR6eUpCkG6TGNKxgqQ7s...",
+  "rawTransaction": "base64url-encoded-signed-transaction"
+}
+```
+
+### 4. buy_token
+
+Fetches a Solana swap quote from the Phantom quotes API. Optionally signs and sends the first quote transaction.
+
+**Parameters:**
+
+- `walletId` (optional, string): The wallet ID to use for the taker address (defaults to authenticated wallet)
+- `networkId` (optional, string): Solana network identifier (default: `solana:mainnet`)
+- `buyTokenMint` (optional, string): Mint address of the token to buy (omit if buying native SOL)
+- `buyTokenIsNative` (optional, boolean): Set true to buy native SOL (default: false)
+- `sellTokenMint` (optional, string): Mint address of the token to sell (omit if selling native SOL)
+- `sellTokenIsNative` (optional, boolean): Set true to sell native SOL (default: true if `sellTokenMint` not provided)
+- `amount` (required, string): Sell amount (e.g., "0.5" or "1000000")
+- `amountUnit` (optional, string): Amount unit (`ui` for token units, `base` for atomic units; default: `base`)
+- `buyTokenDecimals` (optional, number): Buy token decimals (used when `amountUnit` is `ui` and `exactOut` is true)
+- `sellTokenDecimals` (optional, number): Sell token decimals (used when `amountUnit` is `ui`)
+- `slippageTolerance` (optional, number): Slippage tolerance in percent (0-100)
+- `exactOut` (optional, boolean): Treat amount as buy amount instead of sell amount
+- `autoSlippage` (optional, boolean): Enable auto slippage calculation
+- `base64EncodedTx` (optional, boolean): Request base64-encoded transaction data in the quote response
+- `execute` (optional, boolean): If true, sign and send the first quote transaction after fetching
+- `taker` (optional, string): Taker address (defaults to wallet's Solana address)
+- `rpcUrl` (optional, string): Solana RPC URL (for mint decimals lookup when `amountUnit` is `ui`)
+- `quoteApiUrl` (optional, string): Quotes API URL override
+- `derivationIndex` (optional, number): Derivation index for the taker address (default: 0)
+
+**Example:**
+
+```json
+{
+  "networkId": "solana:mainnet",
+  "sellTokenIsNative": true,
+  "buyTokenMint": "So11111111111111111111111111111111111111112",
+  "amount": "0.5",
+  "amountUnit": "ui",
+  "slippageTolerance": 1,
+  "execute": true
+}
+```
+
+**Response:**
+
+```json
+{
+  "quoteRequest": {
+    "taker": {
+      "chainId": "solana:101",
+      "resourceType": "address",
+      "address": "H8FpYTgx4Uy9aF9Nk9fCTqKKFLYQ9KfC6UJhMkMDzCBh"
+    },
+    "buyToken": {
+      "chainId": "solana:101",
+      "resourceType": "address",
+      "address": "So11111111111111111111111111111111111111112"
+    },
+    "sellToken": {
+      "chainId": "solana:101",
+      "resourceType": "nativeToken",
+      "slip44": "501"
+    },
+    "sellAmount": "500000000"
+  },
+  "quoteResponse": {
+    "type": "quotes",
+    "quotes": []
+  },
+  "execution": {
+    "signature": "5oVZJ8b7k2rGm3rP3Gm5J3tFjR6eUpCkG6TGNKxgqQ7s...",
+    "rawTransaction": "base64url-encoded-signed-transaction"
+  }
+}
+```
+
+### 5. sign_message
 
 Signs a UTF-8 message using the authenticated embedded wallet. Automatically routes to the correct signing method based on the network (Ethereum vs other chains).
 

package/dist/index.js

@@ -1132,6 +1132,57 @@ var getWalletAddressesTool = {
   }
 };
 
+// src/tools/sign-transaction.ts
+var import_utils = require("@phantom/utils");
+
+// src/utils/network.ts
+var import_constants = require("@phantom/constants");
+function normalizeNetworkId(networkId) {
+  const normalized = networkId.toLowerCase();
+  switch (normalized) {
+    case "solana:mainnet":
+    case "solana:mainnet-beta":
+      return import_constants.NetworkId.SOLANA_MAINNET;
+    case "solana:devnet":
+      return import_constants.NetworkId.SOLANA_DEVNET;
+    case "solana:testnet":
+      return import_constants.NetworkId.SOLANA_TESTNET;
+    default:
+      return networkId;
+  }
+}
+function normalizeSwapperChainId(networkId) {
+  const normalized = networkId.toLowerCase();
+  switch (normalized) {
+    case "solana:mainnet":
+    case "solana:mainnet-beta":
+    case import_constants.NetworkId.SOLANA_MAINNET.toLowerCase():
+    case "solana:101":
+      return "solana:101";
+    case "solana:devnet":
+    case import_constants.NetworkId.SOLANA_DEVNET.toLowerCase():
+    case "solana:103":
+      return "solana:103";
+    case "solana:testnet":
+    case import_constants.NetworkId.SOLANA_TESTNET.toLowerCase():
+    case "solana:102":
+      return "solana:102";
+    default:
+      return networkId;
+  }
+}
+
+// src/utils/solana.ts
+var import_client2 = require("@phantom/client");
+async function getSolanaAddress(context, walletId, derivationIndex) {
+  const addresses = await context.client.getWalletAddresses(walletId, void 0, derivationIndex);
+  const solanaAddress = addresses.find((addr) => addr.addressType === import_client2.AddressType.solana) || addresses.find((addr) => addr.addressType.toLowerCase() === "solana");
+  if (!solanaAddress) {
+    throw new Error("No Solana address found for this wallet");
+  }
+  return solanaAddress.address;
+}
+
 // src/tools/sign-transaction.ts
 var signTransactionTool = {
   name: "sign_transaction",
@@ -1185,9 +1236,12 @@ var signTransactionTool = {
       throw new Error("account must be a string");
     }
     const transaction = params.transaction;
-    const networkId = params.networkId;
+    const networkId = normalizeNetworkId(params.networkId);
     const derivationIndex = typeof params.derivationIndex === "number" ? params.derivationIndex : void 0;
-    const account = typeof params.account === "string" ? params.account : void 0;
+    let account = typeof params.account === "string" ? params.account : void 0;
+    if (!account && (0, import_utils.isSolanaChain)(networkId)) {
+      account = await getSolanaAddress(context, walletId, derivationIndex);
+    }
     logger2.info(`Signing transaction for wallet ${walletId} on network ${networkId}`);
     try {
       const result = await client.signTransaction({
@@ -1210,7 +1264,7 @@ var signTransactionTool = {
 };
 
 // src/tools/sign-message.ts
-var import_utils = require("@phantom/utils");
+var import_utils2 = require("@phantom/utils");
 var import_base64url = require("@phantom/base64url");
 var signMessageTool = {
   name: "sign_message",
@@ -1257,12 +1311,12 @@ var signMessageTool = {
       }
     }
     const message = params.message;
-    const networkId = params.networkId;
+    const networkId = normalizeNetworkId(params.networkId);
     const derivationIndex = typeof params.derivationIndex === "number" ? params.derivationIndex : void 0;
     logger2.info(`Signing message for wallet ${walletId} on network ${networkId}`);
     try {
       let signature;
-      if ((0, import_utils.isEthereumChain)(networkId)) {
+      if ((0, import_utils2.isEthereumChain)(networkId)) {
         const base64Message = (0, import_base64url.stringToBase64url)(message);
         logger2.debug("Using Ethereum message signing");
         signature = await client.ethereumSignMessage({
@@ -1292,8 +1346,619 @@ var signMessageTool = {
   }
 };
 
+// src/tools/transfer-tokens.ts
+var import_base64url2 = require("@phantom/base64url");
+var import_client3 = require("@phantom/client");
+var import_utils3 = require("@phantom/utils");
+var import_web3 = require("@solana/web3.js");
+var import_spl_token = require("@solana/spl-token");
+
+// src/utils/amount.ts
+function parseBaseUnitAmount(amount) {
+  if (!/^\d+$/.test(amount)) {
+    throw new Error("amount must be a non-negative integer string when amountUnit is 'base'");
+  }
+  return BigInt(amount);
+}
+function parseUiAmount(amount, decimals) {
+  if (!/^\d+(\.\d+)?$/.test(amount)) {
+    throw new Error("amount must be a non-negative decimal string");
+  }
+  if (!Number.isInteger(decimals) || decimals < 0) {
+    throw new Error("decimals must be a non-negative integer");
+  }
+  const [whole, fraction = ""] = amount.split(".");
+  if (fraction.length > decimals) {
+    throw new Error(`amount has too many decimal places for token decimals (${decimals})`);
+  }
+  const paddedFraction = fraction.padEnd(decimals, "0");
+  const combined = `${whole}${paddedFraction}`.replace(/^0+/, "") || "0";
+  return BigInt(combined);
+}
+function requirePositiveAmount(amount) {
+  if (amount <= 0n) {
+    throw new Error("amount must be greater than 0");
+  }
+}
+
+// src/tools/transfer-tokens.ts
+var DEFAULT_SOLANA_RPC_URLS = {
+  [import_client3.NetworkId.SOLANA_MAINNET]: "https://api.mainnet-beta.solana.com",
+  [import_client3.NetworkId.SOLANA_DEVNET]: "https://api.devnet.solana.com",
+  [import_client3.NetworkId.SOLANA_TESTNET]: "https://api.testnet.solana.com"
+};
+var DEFAULT_COMMITMENT = "confirmed";
+function resolveSolanaRpcUrl(networkId, rpcUrl) {
+  if (rpcUrl && typeof rpcUrl === "string") {
+    return rpcUrl;
+  }
+  const resolved = DEFAULT_SOLANA_RPC_URLS[networkId];
+  if (!resolved) {
+    throw new Error(
+      `rpcUrl is required for networkId "${networkId}". Supported defaults: ${Object.keys(DEFAULT_SOLANA_RPC_URLS).join(
+        ", "
+      )}`
+    );
+  }
+  return resolved;
+}
+var transferTokensTool = {
+  name: "transfer_tokens",
+  description: "Transfers SOL or SPL tokens on Solana using the authenticated embedded wallet. Builds, signs, and sends the transaction.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      walletId: {
+        type: "string",
+        description: "Optional wallet ID to use for transfer (defaults to authenticated wallet)"
+      },
+      networkId: {
+        type: "string",
+        description: 'Solana network identifier (e.g., "solana:mainnet", "solana:devnet")'
+      },
+      to: {
+        type: "string",
+        description: "Recipient Solana address"
+      },
+      amount: {
+        type: "string",
+        description: 'Transfer amount as a string (e.g., "0.5" or "1000000")'
+      },
+      amountUnit: {
+        type: "string",
+        description: "Amount unit: 'ui' for SOL/token units, 'base' for lamports/base units",
+        enum: ["ui", "base"]
+      },
+      tokenMint: {
+        type: "string",
+        description: "Optional SPL token mint address. If omitted, transfers SOL."
+      },
+      decimals: {
+        type: "number",
+        description: "Token decimals (optional for SPL tokens; fetched from chain if omitted)",
+        minimum: 0
+      },
+      derivationIndex: {
+        type: "number",
+        description: "Optional derivation index for the account (default: 0)",
+        minimum: 0
+      },
+      rpcUrl: {
+        type: "string",
+        description: "Optional Solana RPC URL (defaults based on networkId)"
+      },
+      createAssociatedTokenAccount: {
+        type: "boolean",
+        description: "Create destination associated token account if missing (default: true)"
+      }
+    },
+    required: ["networkId", "to", "amount"]
+  },
+  handler: async (params, context) => {
+    const { client, session, logger: logger2 } = context;
+    if (typeof params.networkId !== "string") {
+      throw new Error("networkId must be a string");
+    }
+    const normalizedNetworkId = normalizeNetworkId(params.networkId);
+    if (!(0, import_utils3.isSolanaChain)(normalizedNetworkId)) {
+      throw new Error("transfer_tokens currently supports Solana networks only");
+    }
+    if (typeof params.to !== "string") {
+      throw new Error("to must be a string");
+    }
+    if (typeof params.amount !== "string") {
+      throw new Error("amount must be a string");
+    }
+    const walletId = typeof params.walletId === "string" ? params.walletId : session.walletId;
+    if (!walletId) {
+      throw new Error("walletId is required (missing from session and not provided)");
+    }
+    const derivationIndex = typeof params.derivationIndex === "number" ? params.derivationIndex : void 0;
+    if (derivationIndex !== void 0 && (!Number.isInteger(derivationIndex) || derivationIndex < 0)) {
+      throw new Error("derivationIndex must be a non-negative integer");
+    }
+    const amountUnit = typeof params.amountUnit === "string" ? params.amountUnit : "ui";
+    if (amountUnit !== "ui" && amountUnit !== "base") {
+      throw new Error("amountUnit must be 'ui' or 'base'");
+    }
+    const tokenMint = typeof params.tokenMint === "string" ? params.tokenMint : void 0;
+    const createAta = typeof params.createAssociatedTokenAccount === "boolean" ? params.createAssociatedTokenAccount : true;
+    const rpcUrl = resolveSolanaRpcUrl(
+      normalizedNetworkId,
+      typeof params.rpcUrl === "string" ? params.rpcUrl : void 0
+    );
+    const connection = new import_web3.Connection(rpcUrl, DEFAULT_COMMITMENT);
+    const fromAddress = await getSolanaAddress(context, walletId, derivationIndex);
+    const fromPubkey = new import_web3.PublicKey(fromAddress);
+    const toPubkey = new import_web3.PublicKey(params.to);
+    logger2.info(`Preparing transfer from ${fromAddress} to ${params.to} on ${normalizedNetworkId}`);
+    try {
+      const tx = new import_web3.Transaction();
+      if (!tokenMint) {
+        const lamports = amountUnit === "base" ? parseBaseUnitAmount(params.amount) : parseUiAmount(
+          params.amount,
+          9
+          /* SOL decimals */
+        );
+        requirePositiveAmount(lamports);
+        tx.add(
+          import_web3.SystemProgram.transfer({
+            fromPubkey,
+            toPubkey,
+            lamports
+          })
+        );
+      } else {
+        const mintPubkey = new import_web3.PublicKey(tokenMint);
+        const sourceAta = await (0, import_spl_token.getAssociatedTokenAddress)(mintPubkey, fromPubkey, false);
+        const destinationAta = await (0, import_spl_token.getAssociatedTokenAddress)(mintPubkey, toPubkey, false);
+        const sourceInfo = await connection.getAccountInfo(sourceAta, DEFAULT_COMMITMENT);
+        if (!sourceInfo) {
+          throw new Error("Source associated token account not found for this wallet");
+        }
+        const destinationInfo = await connection.getAccountInfo(destinationAta, DEFAULT_COMMITMENT);
+        if (!destinationInfo) {
+          if (createAta) {
+            tx.add((0, import_spl_token.createAssociatedTokenAccountInstruction)(fromPubkey, destinationAta, toPubkey, mintPubkey));
+          } else {
+            throw new Error("Destination associated token account does not exist");
+          }
+        }
+        let decimals;
+        if (typeof params.decimals === "number") {
+          if (!Number.isInteger(params.decimals) || params.decimals < 0) {
+            throw new Error("decimals must be a non-negative integer");
+          }
+          decimals = params.decimals;
+        }
+        if (amountUnit === "ui" && decimals === void 0) {
+          const mintInfo = await (0, import_spl_token.getMint)(connection, mintPubkey, DEFAULT_COMMITMENT);
+          decimals = mintInfo.decimals;
+        }
+        if (amountUnit === "ui" && decimals === void 0) {
+          throw new Error("Unable to determine token decimals");
+        }
+        const amountBaseUnits = amountUnit === "base" ? parseBaseUnitAmount(params.amount) : parseUiAmount(params.amount, decimals);
+        requirePositiveAmount(amountBaseUnits);
+        if (amountUnit === "base" || decimals === void 0) {
+          tx.add((0, import_spl_token.createTransferInstruction)(sourceAta, destinationAta, fromPubkey, amountBaseUnits));
+        } else {
+          tx.add(
+            (0, import_spl_token.createTransferCheckedInstruction)(
+              sourceAta,
+              mintPubkey,
+              destinationAta,
+              fromPubkey,
+              amountBaseUnits,
+              decimals
+            )
+          );
+        }
+      }
+      const { blockhash } = await connection.getLatestBlockhash(DEFAULT_COMMITMENT);
+      tx.feePayer = fromPubkey;
+      tx.recentBlockhash = blockhash;
+      const serialized = tx.serialize({ requireAllSignatures: false, verifySignatures: false });
+      const encoded = (0, import_base64url2.base64urlEncode)(serialized);
+      const result = await client.signAndSendTransaction({
+        walletId,
+        transaction: encoded,
+        networkId: normalizedNetworkId,
+        derivationIndex,
+        account: fromAddress
+      });
+      logger2.info(`Transfer submitted for wallet ${walletId}`);
+      return {
+        walletId,
+        networkId: normalizedNetworkId,
+        from: fromAddress,
+        to: params.to,
+        tokenMint: tokenMint ?? null,
+        signature: result.hash ?? null,
+        rawTransaction: result.rawTransaction
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logger2.error(`Failed to transfer tokens: ${errorMessage}`);
+      throw new Error(`Failed to transfer tokens: ${errorMessage}`);
+    }
+  }
+};
+
+// src/tools/buy-token.ts
+var import_utils4 = require("@phantom/utils");
+var import_web32 = require("@solana/web3.js");
+var import_spl_token2 = require("@solana/spl-token");
+var import_bs58 = __toESM(require("bs58"));
+var import_base64url3 = require("@phantom/base64url");
+var DEFAULT_QUOTES_API_URL = "https://api.phantom.app/swap/v2/quotes";
+var DEFAULT_SOLANA_RPC_URLS2 = {
+  "solana:101": "https://api.mainnet-beta.solana.com",
+  "solana:103": "https://api.devnet.solana.com",
+  "solana:102": "https://api.testnet.solana.com"
+};
+function validateHttpsUrl(url, context) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`${context} URL is not valid: ${url}`);
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error(`${context} URL must use HTTPS protocol, got: ${parsed.protocol}`);
+  }
+  if (!parsed.hostname) {
+    throw new Error(`${context} URL missing hostname: ${url}`);
+  }
+}
+function resolveQuotesApiUrl(override) {
+  let url;
+  if (override && typeof override === "string") {
+    url = override;
+  } else if (process.env.PHANTOM_QUOTES_API_URL) {
+    url = process.env.PHANTOM_QUOTES_API_URL;
+  } else {
+    url = DEFAULT_QUOTES_API_URL;
+  }
+  validateHttpsUrl(url, "Quotes API");
+  return url;
+}
+function resolveSolanaRpcUrl2(chainId, override) {
+  let url;
+  if (override && typeof override === "string") {
+    url = override;
+  } else {
+    const defaultUrl = DEFAULT_SOLANA_RPC_URLS2[chainId];
+    if (!defaultUrl) {
+      throw new Error(
+        `rpcUrl is required for chainId "${chainId}". Supported defaults: ${Object.keys(DEFAULT_SOLANA_RPC_URLS2).join(
+          ", "
+        )}`
+      );
+    }
+    url = defaultUrl;
+  }
+  validateHttpsUrl(url, "Solana RPC");
+  return url;
+}
+function decodeTransactionData(transactionData, base64Encoded) {
+  if (base64Encoded) {
+    const bytes = Buffer.from(transactionData, "base64");
+    if (!bytes.length) {
+      throw new Error("Failed to decode base64 transaction data");
+    }
+    return bytes;
+  }
+  try {
+    return import_bs58.default.decode(transactionData);
+  } catch (error) {
+    const bytes = Buffer.from(transactionData, "base64");
+    if (!bytes.length) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to decode transaction data: ${errorMessage}`);
+    }
+    return bytes;
+  }
+}
+var buyTokenTool = {
+  name: "buy_token",
+  description: "Fetches a swap quote from Phantom's quotes API for buying a token (Solana only). By default, this tool only fetches a quote and does not submit a transaction. Pass execute: true to sign and send the transaction.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      walletId: {
+        type: "string",
+        description: "Optional wallet ID to use for the taker address (defaults to authenticated wallet)"
+      },
+      networkId: {
+        type: "string",
+        description: 'Solana network identifier (e.g., "solana:mainnet", "solana:devnet")'
+      },
+      buyTokenMint: {
+        type: "string",
+        description: "Mint address of the token to buy (omit if buying native SOL)"
+      },
+      buyTokenIsNative: {
+        type: "boolean",
+        description: "Set true to buy native SOL (default: false)"
+      },
+      sellTokenMint: {
+        type: "string",
+        description: "Mint address of the token to sell (omit if selling native SOL)"
+      },
+      sellTokenIsNative: {
+        type: "boolean",
+        description: "Set true to sell native SOL (default: true if sellTokenMint not provided)"
+      },
+      amount: {
+        type: "string",
+        description: `The amount to swap as a string (e.g., "0.5" or "1000000"). When exactOut is false (default), this is the sell amount. When exactOut is true, this is the buy amount. Interpretation depends on amountUnit: 'ui' interprets as token units (e.g., 0.5 SOL), 'base' interprets as atomic units (e.g., 500000000 lamports).`
+      },
+      amountUnit: {
+        type: "string",
+        description: "Amount unit: 'ui' for token units, 'base' for atomic units (default: 'base')",
+        enum: ["ui", "base"]
+      },
+      buyTokenDecimals: {
+        type: "number",
+        description: "Decimals for the buy token (used when amountUnit is 'ui' and exactOut is true)",
+        minimum: 0
+      },
+      sellTokenDecimals: {
+        type: "number",
+        description: "Decimals for the sell token (optional if amountUnit is 'ui')",
+        minimum: 0
+      },
+      slippageTolerance: {
+        type: "number",
+        description: "Slippage tolerance in percent (0-100)",
+        minimum: 0,
+        maximum: 100
+      },
+      exactOut: {
+        type: "boolean",
+        description: "If true, amount is treated as buy amount instead of sell amount"
+      },
+      autoSlippage: {
+        type: "boolean",
+        description: "Enable auto slippage calculation"
+      },
+      base64EncodedTx: {
+        type: "boolean",
+        description: "Request base64-encoded transaction data in the quote response"
+      },
+      execute: {
+        type: "boolean",
+        description: "If true, sign and send the first quote transaction after fetching"
+      },
+      taker: {
+        type: "string",
+        description: "Taker address (defaults to wallet's Solana address)"
+      },
+      rpcUrl: {
+        type: "string",
+        description: "Optional Solana RPC URL (for mint decimals lookup when amountUnit is 'ui')"
+      },
+      quoteApiUrl: {
+        type: "string",
+        description: "Optional quotes API URL override"
+      },
+      derivationIndex: {
+        type: "number",
+        description: "Optional derivation index for the taker address (default: 0)",
+        minimum: 0
+      }
+    },
+    required: ["amount"]
+  },
+  handler: async (params, context) => {
+    const { session, logger: logger2 } = context;
+    const networkId = typeof params.networkId === "string" ? params.networkId : "solana:mainnet";
+    const normalizedNetworkId = normalizeNetworkId(networkId);
+    const swapperChainId = normalizeSwapperChainId(networkId);
+    if (!(0, import_utils4.isSolanaChain)(networkId) && !(0, import_utils4.isSolanaChain)(swapperChainId)) {
+      throw new Error("buy_token currently supports Solana networks only");
+    }
+    if (typeof params.amount !== "string") {
+      throw new Error("amount must be a string");
+    }
+    const walletId = typeof params.walletId === "string" ? params.walletId : session.walletId;
+    if (!walletId) {
+      throw new Error("walletId is required (missing from session and not provided)");
+    }
+    const derivationIndex = typeof params.derivationIndex === "number" ? params.derivationIndex : void 0;
+    if (derivationIndex !== void 0 && (!Number.isInteger(derivationIndex) || derivationIndex < 0)) {
+      throw new Error("derivationIndex must be a non-negative integer");
+    }
+    const amountUnit = typeof params.amountUnit === "string" ? params.amountUnit : "base";
+    if (amountUnit !== "ui" && amountUnit !== "base") {
+      throw new Error("amountUnit must be 'ui' or 'base'");
+    }
+    const buyTokenIsNative = typeof params.buyTokenIsNative === "boolean" ? params.buyTokenIsNative : false;
+    const sellTokenIsNative = typeof params.sellTokenIsNative === "boolean" ? params.sellTokenIsNative : params.sellTokenMint ? false : true;
+    const buyTokenMint = typeof params.buyTokenMint === "string" ? params.buyTokenMint : void 0;
+    const sellTokenMint = typeof params.sellTokenMint === "string" ? params.sellTokenMint : void 0;
+    if (!buyTokenIsNative && !buyTokenMint) {
+      throw new Error("buyTokenMint is required unless buyTokenIsNative is true");
+    }
+    if (!sellTokenIsNative && !sellTokenMint) {
+      throw new Error("sellTokenMint is required unless sellTokenIsNative is true");
+    }
+    if (sellTokenIsNative && sellTokenMint) {
+      throw new Error("sellTokenMint must be omitted when sellTokenIsNative is true");
+    }
+    if (buyTokenMint) {
+      try {
+        new import_web32.PublicKey(buyTokenMint);
+      } catch {
+        throw new Error("buyTokenMint must be a valid Solana address");
+      }
+    }
+    if (sellTokenMint) {
+      try {
+        new import_web32.PublicKey(sellTokenMint);
+      } catch {
+        throw new Error("sellTokenMint must be a valid Solana address");
+      }
+    }
+    const taker = typeof params.taker === "string" ? params.taker : await getSolanaAddress(context, walletId, derivationIndex);
+    try {
+      new import_web32.PublicKey(taker);
+    } catch {
+      throw new Error("taker must be a valid Solana address");
+    }
+    const exactOut = typeof params.exactOut === "boolean" ? params.exactOut : false;
+    let amountBaseUnits;
+    if (amountUnit === "base") {
+      amountBaseUnits = parseBaseUnitAmount(params.amount);
+    } else {
+      let decimals;
+      if (exactOut) {
+        if (buyTokenIsNative) {
+          decimals = 9;
+        } else if (typeof params.buyTokenDecimals === "number") {
+          if (!Number.isInteger(params.buyTokenDecimals) || params.buyTokenDecimals < 0) {
+            throw new Error("buyTokenDecimals must be a non-negative integer");
+          }
+          decimals = params.buyTokenDecimals;
+        } else if (buyTokenMint) {
+          const rpcUrl = resolveSolanaRpcUrl2(
+            swapperChainId,
+            typeof params.rpcUrl === "string" ? params.rpcUrl : void 0
+          );
+          const connection = new import_web32.Connection(rpcUrl, "confirmed");
+          const mintInfo = await (0, import_spl_token2.getMint)(connection, new import_web32.PublicKey(buyTokenMint), "confirmed");
+          decimals = mintInfo.decimals;
+        } else {
+          throw new Error("buyTokenMint is required to lookup decimals");
+        }
+      } else if (sellTokenIsNative) {
+        decimals = 9;
+      } else if (typeof params.sellTokenDecimals === "number") {
+        if (!Number.isInteger(params.sellTokenDecimals) || params.sellTokenDecimals < 0) {
+          throw new Error("sellTokenDecimals must be a non-negative integer");
+        }
+        decimals = params.sellTokenDecimals;
+      } else if (sellTokenMint) {
+        const rpcUrl = resolveSolanaRpcUrl2(
+          swapperChainId,
+          typeof params.rpcUrl === "string" ? params.rpcUrl : void 0
+        );
+        const connection = new import_web32.Connection(rpcUrl, "confirmed");
+        const mintInfo = await (0, import_spl_token2.getMint)(connection, new import_web32.PublicKey(sellTokenMint), "confirmed");
+        decimals = mintInfo.decimals;
+      } else {
+        throw new Error("sellTokenMint is required to lookup decimals");
+      }
+      amountBaseUnits = parseUiAmount(params.amount, decimals);
+    }
+    requirePositiveAmount(amountBaseUnits);
+    const quoteApiUrl = resolveQuotesApiUrl(typeof params.quoteApiUrl === "string" ? params.quoteApiUrl : void 0);
+    const buyToken = buyTokenIsNative ? { chainId: swapperChainId, resourceType: "nativeToken", slip44: "501" } : { chainId: swapperChainId, resourceType: "address", address: buyTokenMint };
+    const sellToken = sellTokenIsNative ? { chainId: swapperChainId, resourceType: "nativeToken", slip44: "501" } : { chainId: swapperChainId, resourceType: "address", address: sellTokenMint };
+    const body = {
+      taker: { chainId: swapperChainId, resourceType: "address", address: taker },
+      buyToken,
+      sellToken
+    };
+    if (exactOut) {
+      body.buyAmount = amountBaseUnits.toString();
+    } else {
+      body.sellAmount = amountBaseUnits.toString();
+    }
+    if (typeof params.slippageTolerance === "number") {
+      if (!Number.isFinite(params.slippageTolerance) || params.slippageTolerance < 0 || params.slippageTolerance > 100) {
+        throw new Error("slippageTolerance must be a number between 0 and 100");
+      }
+      body.slippageTolerance = params.slippageTolerance;
+    }
+    if (typeof params.exactOut === "boolean") {
+      body.exactOut = exactOut;
+    }
+    if (typeof params.autoSlippage === "boolean") {
+      body.autoSlippage = params.autoSlippage;
+    }
+    if (typeof params.base64EncodedTx === "boolean") {
+      body.base64EncodedTx = params.base64EncodedTx;
+    }
+    const quoteApiOrigin = new URL(quoteApiUrl).origin;
+    logger2.info(`Requesting quote from ${quoteApiOrigin}`);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 1e4);
+    let response;
+    try {
+      response = await fetch(quoteApiUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new Error("Quote API request timed out after 10 seconds");
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    const responseText = await response.text();
+    let responseJson;
+    try {
+      responseJson = responseText ? JSON.parse(responseText) : null;
+    } catch (parseError) {
+      logger2.debug(`Failed to parse response as JSON: ${parseError}`);
+      responseJson = responseText;
+    }
+    if (!response.ok) {
+      const message = typeof responseJson === "string" ? responseJson : JSON.stringify(responseJson);
+      throw new Error(`Quote API error (${response.status}): ${message}`);
+    }
+    const execute = typeof params.execute === "boolean" ? params.execute : false;
+    if (!execute) {
+      return {
+        quoteRequest: body,
+        quoteResponse: responseJson
+      };
+    }
+    if (typeof responseJson !== "object" || responseJson === null || !Array.isArray(responseJson.quotes)) {
+      throw new Error("Quote response has unexpected format: missing quotes array");
+    }
+    const quotes = responseJson.quotes;
+    const quote = quotes[0];
+    const transactionData = quote?.transactionData?.[0];
+    if (!transactionData) {
+      throw new Error("Quote response missing transaction data in first quote");
+    }
+    const decoded = decodeTransactionData(transactionData, params.base64EncodedTx);
+    const encoded = (0, import_base64url3.base64urlEncode)(decoded);
+    const result = await context.client.signAndSendTransaction({
+      walletId,
+      transaction: encoded,
+      networkId: normalizedNetworkId,
+      derivationIndex,
+      account: taker
+    });
+    return {
+      quoteRequest: body,
+      quoteResponse: responseJson,
+      execution: {
+        signature: result.hash ?? null,
+        rawTransaction: result.rawTransaction
+      }
+    };
+  }
+};
+
 // src/tools/index.ts
-var tools = [getWalletAddressesTool, signTransactionTool, signMessageTool];
+var tools = [
+  getWalletAddressesTool,
+  signTransactionTool,
+  signMessageTool,
+  transferTokensTool,
+  buyTokenTool
+];
 function getTool(name) {
   return tools.find((tool) => tool.name === name);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phantom/mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP Server for Phantom Wallet",
   "repository": {
     "type": "git",
@@ -37,14 +37,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@phantom/api-key-stamper": "workspace:^",
-    "@phantom/base64url": "workspace:^",
-    "@phantom/client": "workspace:^",
-    "@phantom/constants": "workspace:^",
-    "@phantom/crypto": "workspace:^",
-    "@phantom/server-sdk": "workspace:^",
-    "@phantom/utils": "workspace:^",
+    "@phantom/api-key-stamper": "^1.0.2",
+    "@phantom/base64url": "^1.0.2",
+    "@phantom/client": "^1.0.2",
+    "@phantom/constants": "^1.0.2",
+    "@phantom/crypto": "^1.0.2",
+    "@phantom/server-sdk": "^1.0.2",
+    "@phantom/utils": "^1.0.2",
+    "@solana/spl-token": "^0.4.14",
+    "@solana/web3.js": "^1.95.5",
     "axios": "^1.6.7",
+    "bs58": "^6.0.0",
     "open": "^10.0.3",
     "openid-client": "^5.6.5"
   },
@@ -55,4 +58,4 @@
   "publishConfig": {
     "directory": "_release/package"
   }
-}
+}