feat: add NFT functionality

README.md

@@ -19,6 +19,7 @@ This MCP server extends any MCP client's capabilities by providing tools to do a
 - Call contract functions
 - Onramp funds via [Coinbase](https://www.coinbase.com/developer-platform/products/onramp)
 - Manage ERC20 tokens
+- List and transfer NFTs (ERC721 and ERC1155)
 - Buy [OpenRouter](http://openrouter.ai/) credits with USDC
 
 The server interacts with Base, powered by Base Developer Tools and [AgentKit](https://github.com/coinbase/agentkit).
@@ -77,6 +78,7 @@ For more detailed information on contributing to Base MCP, including adding new
 - Coinbase API credentials (API Key Name and Private Key)
 - A wallet seed phrase
 - Coinbase Project ID (for onramp functionality)
+- Alchemy API Key (required for NFT functionality)
 - Optional: OpenRouter API Key (for buying OpenRouter credits)
 
 ## Installation
@@ -135,6 +137,10 @@ SEED_PHRASE=your seed phrase here
 # You can obtain this from the Coinbase Developer Portal
 COINBASE_PROJECT_ID=your_project_id
 
+# Alchemy API Key (required for NFT functionality)
+# You can obtain this from https://alchemy.com
+ALCHEMY_API_KEY=your_alchemy_api_key
+
 # OpenRouter API Key (optional for buying OpenRouter credits)
 # You can obtain this from https://openrouter.ai/keys
 OPENROUTER_API_KEY=your_openrouter_api_key
@@ -179,6 +185,7 @@ You can easily access this file via the Claude Desktop app by navigating to Clau
            "COINBASE_API_PRIVATE_KEY": "your_private_key",
            "SEED_PHRASE": "your seed phrase here",
            "COINBASE_PROJECT_ID": "your_project_id",
+           "ALCHEMY_API_KEY": "your_alchemy_api_key",
            "OPENROUTER_API_KEY": "your_openrouter_api_key"
          },
          "disabled": false,
@@ -317,6 +324,34 @@ Example query to Claude:
 
 > "Transfer 10 USDC to 0x1234567890abcdef1234567890abcdef12345678."
 
+### list_nfts
+
+Lists NFTs owned by a specific address.
+
+Parameters:
+
+- `ownerAddress`: The address of the owner whose NFTs to list
+- `limit`: Maximum number of NFTs to return (default: 50)
+
+Example query to Claude:
+
+> "Show me the NFTs owned by 0x89A93a48C6Ef8085B9d07e46AaA96DFDeC717040."
+
+### transfer_nft
+
+Transfers an NFT to another address. Supports both ERC721 and ERC1155 standards.
+
+Parameters:
+
+- `contractAddress`: The address of the NFT contract
+- `tokenId`: The token ID of the NFT to transfer
+- `toAddress`: The address of the recipient
+- `amount`: The amount to transfer (only used for ERC1155, default: 1)
+
+Example query to Claude:
+
+> "Transfer my NFT with contract 0x3F06FcF75f45F1bb61D56D68fA7b3F32763AA15c and token ID 56090175025510453004781233574040052668718235229192064098345825090519343038548 to 0x1234567890abcdef1234567890abcdef12345678."
+
 ### buy_openrouter_credits
 
 Buys OpenRouter credits with USDC.

examples.md

@@ -138,6 +138,39 @@ _Claude uses the `erc20_transfer` tool with the following parameters:_
 
 **Claude:** I've initiated the transfer of 10 USDC to 0x9876543210abcdef9876543210abcdef98765432. The transaction hash is: 0xfedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210
 
+## NFT Operations
+
+### Listing NFTs
+
+**You:** Show me the NFTs owned by 0x89A93a48C6Ef8085B9d07e46AaA96DFDeC717040.
+
+**Claude:** I'll check what NFTs are owned by that address.
+
+_Claude uses the `list_nfts` tool with the following parameters:_
+
+- ownerAddress: 0x89A93a48C6Ef8085B9d07e46AaA96DFDeC717040
+
+**Claude:** I found 1 NFT owned by 0x89A93a48C6Ef8085B9d07e46AaA96DFDeC717040:
+
+1. Owl (ERC1155)
+   Contract: 0x3F06FcF75f45F1bb61D56D68fA7b3F32763AA15c
+   Token ID: 56090175025510453004781233574040052668718235229192064098345825090519343038548
+
+### Transferring an NFT
+
+**You:** Transfer my NFT with contract 0x3F06FcF75f45F1bb61D56D68fA7b3F32763AA15c and token ID 56090175025510453004781233574040052668718235229192064098345825090519343038548 to 0x1234567890abcdef1234567890abcdef12345678.
+
+**Claude:** I'll set up that NFT transfer for you.
+
+_Claude uses the `transfer_nft` tool with the following parameters:_
+
+- contractAddress: 0x3F06FcF75f45F1bb61D56D68fA7b3F32763AA15c
+- tokenId: 56090175025510453004781233574040052668718235229192064098345825090519343038548
+- toAddress: 0x1234567890abcdef1234567890abcdef12345678
+- amount: 1
+
+**Claude:** I've initiated the transfer of your Owl NFT to 0x1234567890abcdef1234567890abcdef12345678. The transaction hash is: 0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
+
 ## Onramp and Payments
 
 ### Checking Available Onramp Assets

src/lib/contracts/erc1155.ts

@@ -0,0 +1,56 @@
+// ERC1155 token standard ABI
+export const erc1155Abi = [
+  {
+    inputs: [
+      { internalType: 'address', name: 'account', type: 'address' },
+      { internalType: 'uint256', name: 'id', type: 'uint256' },
+    ],
+    name: 'balanceOf',
+    outputs: [{ internalType: 'uint256', name: '', type: 'uint256' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [
+      { internalType: 'address[]', name: 'accounts', type: 'address[]' },
+      { internalType: 'uint256[]', name: 'ids', type: 'uint256[]' },
+    ],
+    name: 'balanceOfBatch',
+    outputs: [{ internalType: 'uint256[]', name: '', type: 'uint256[]' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+  {
+    inputs: [
+      { internalType: 'address', name: 'from', type: 'address' },
+      { internalType: 'address', name: 'to', type: 'address' },
+      { internalType: 'uint256', name: 'id', type: 'uint256' },
+      { internalType: 'uint256', name: 'amount', type: 'uint256' },
+      { internalType: 'bytes', name: 'data', type: 'bytes' },
+    ],
+    name: 'safeTransferFrom',
+    outputs: [],
+    stateMutability: 'nonpayable',
+    type: 'function',
+  },
+  {
+    inputs: [
+      { internalType: 'address', name: 'from', type: 'address' },
+      { internalType: 'address', name: 'to', type: 'address' },
+      { internalType: 'uint256[]', name: 'ids', type: 'uint256[]' },
+      { internalType: 'uint256[]', name: 'amounts', type: 'uint256[]' },
+      { internalType: 'bytes', name: 'data', type: 'bytes' },
+    ],
+    name: 'safeBatchTransferFrom',
+    outputs: [],
+    stateMutability: 'nonpayable',
+    type: 'function',
+  },
+  {
+    inputs: [{ internalType: 'bytes4', name: 'interfaceId', type: 'bytes4' }],
+    name: 'supportsInterface',
+    outputs: [{ internalType: 'bool', name: '', type: 'bool' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+] as const;

src/tools/index.ts

@@ -1,6 +1,7 @@
 import { callContractTool } from './contracts/index.js';
 import { erc20BalanceTool, erc20TransferTool } from './erc20/index.js';
 import { getMorphoVaultsTool } from './morpho/index.js';
+import { listNftsTool, transferNftTool } from './nft/index.js';
 import { getOnrampAssetsTool, onrampTool } from './onramp/index.js';
 import { buyOpenRouterCreditsTool } from './open-router/index.js';
 import type { ToolHandler, ToolWithHandler } from './types.js';
@@ -12,6 +13,8 @@ export const baseMcpTools: ToolWithHandler[] = [
   onrampTool,
   erc20BalanceTool,
   erc20TransferTool,
+  listNftsTool,
+  transferNftTool,
   buyOpenRouterCreditsTool,
 ];
 

src/tools/nft/handlers.ts

@@ -0,0 +1,82 @@
+import { isAddress } from 'viem';
+import type { PublicActions, WalletClient } from 'viem';
+import { base } from 'viem/chains';
+import type { z } from 'zod';
+import { constructBaseScanUrl } from '../utils/index.js';
+import { ListNftsSchema, TransferNftSchema } from './schemas.js';
+import { fetchNftsFromAlchemy, formatNftData, transferNft } from './utils.js';
+
+export async function listNftsHandler(
+  wallet: WalletClient & PublicActions,
+  args: z.infer<typeof ListNftsSchema>,
+): Promise<string> {
+  try {
+    // Validate owner address
+    if (!isAddress(args.ownerAddress)) {
+      throw new Error(`Invalid owner address: ${args.ownerAddress}`);
+    }
+
+    // Fetch NFTs from Alchemy API
+    const nftData = await fetchNftsFromAlchemy({
+      ownerAddress: args.ownerAddress,
+      limit: args.limit,
+    });
+
+    // Format the NFT data
+    const nfts = formatNftData({
+      nftData,
+    });
+
+    // Format the result
+    if (nfts.length === 0) {
+      return 'No NFTs found for this address.';
+    }
+
+    const formattedNfts = nfts
+      .map((nft, index) => {
+        return `${index + 1}. ${nft.title} (${nft.tokenType})
+  Contract: ${nft.contractAddress}
+  Token ID: ${nft.tokenId}
+  ${nft.imageUrl ? `Image: ${nft.imageUrl}` : ''}`;
+      })
+      .join('\n\n');
+
+    return `Found ${nfts.length} NFTs:\n\n${formattedNfts}`;
+  } catch (error) {
+    console.error('Error listing NFTs:', error);
+    return `Error listing NFTs: ${error instanceof Error ? error.message : String(error)}`;
+  }
+}
+
+export async function transferNftHandler(
+  wallet: WalletClient & PublicActions,
+  args: z.infer<typeof TransferNftSchema>,
+): Promise<string> {
+  try {
+    // Validate addresses
+    if (!isAddress(args.contractAddress)) {
+      throw new Error(`Invalid contract address: ${args.contractAddress}`);
+    }
+
+    if (!isAddress(args.toAddress)) {
+      throw new Error(`Invalid recipient address: ${args.toAddress}`);
+    }
+
+    // Execute the transfer
+    const txHash = await transferNft({
+      wallet,
+      contractAddress: args.contractAddress,
+      tokenId: args.tokenId,
+      toAddress: args.toAddress,
+      amount: args.amount,
+    });
+
+    // Construct transaction URL
+    const txUrl = constructBaseScanUrl(wallet.chain ?? base, txHash);
+
+    return `NFT transfer initiated!\n\nTransaction: ${txUrl}\n\nPlease wait for the transaction to be confirmed.`;
+  } catch (error) {
+    console.error('Error transferring NFT:', error);
+    return `Error transferring NFT: ${error instanceof Error ? error.message : String(error)}`;
+  }
+}

src/tools/nft/index.ts

@@ -0,0 +1,25 @@
+import { generateTool } from '../../utils.js';
+import { listNftsHandler, transferNftHandler } from './handlers.js';
+import { ListNftsSchema, TransferNftSchema } from './schemas.js';
+
+// Re-export utility functions for use elsewhere in the codebase
+export {
+  fetchNftsFromAlchemy,
+  formatNftData,
+  detectNftStandard,
+  transferNft,
+} from './utils.js';
+
+export const listNftsTool = generateTool({
+  name: 'list_nfts',
+  description: 'List NFTs owned by a specific address',
+  inputSchema: ListNftsSchema,
+  toolHandler: listNftsHandler,
+});
+
+export const transferNftTool = generateTool({
+  name: 'transfer_nft',
+  description: 'Transfer an NFT to another address',
+  inputSchema: TransferNftSchema,
+  toolHandler: transferNftHandler,
+});

src/tools/nft/schemas.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+export const ListNftsSchema = z.object({
+  ownerAddress: z
+    .string()
+    .describe('The address of the owner whose NFTs to list'),
+  limit: z
+    .number()
+    .optional()
+    .describe('Maximum number of NFTs to return (default: 50)'),
+});
+
+export const TransferNftSchema = z.object({
+  contractAddress: z.string().describe('The address of the NFT contract'),
+  tokenId: z.string().describe('The token ID of the NFT to transfer'),
+  toAddress: z.string().describe('The address of the recipient'),
+  amount: z
+    .string()
+    .optional()
+    .describe('The amount to transfer (only used for ERC1155, default: 1)'),
+});

src/tools/nft/types.ts

@@ -0,0 +1,49 @@
+import type { PublicActions, WalletClient } from 'viem';
+
+/**
+ * Define a more specific type for NFT data
+ */
+export type NftData = {
+  contract?: { address?: string };
+  tokenId?: string;
+  id?: { tokenId?: string };
+  title?: string;
+  name?: string;
+  description?: string;
+  tokenType?: string;
+  media?: Array<{ gateway?: string; raw?: string }>;
+  image?: string;
+  metadata?: Record<string, unknown>;
+};
+
+/**
+ * Formatted NFT data structure
+ */
+export type FormattedNft = {
+  contractAddress: string;
+  tokenId: string;
+  title: string;
+  description: string;
+  tokenType: string;
+  imageUrl: string;
+  metadata: Record<string, unknown>;
+};
+
+/**
+ * Parameters for fetching NFTs
+ */
+export type FetchNftsParams = {
+  ownerAddress: string;
+  limit?: number;
+};
+
+/**
+ * Parameters for transferring NFTs
+ */
+export type TransferNftParams = {
+  wallet: WalletClient & PublicActions;
+  contractAddress: `0x${string}`;
+  tokenId: string;
+  toAddress: `0x${string}`;
+  amount?: string;
+};