Stacks Clarity MCP Server

Instructions

Implementation Reference

• src/tools/stacks_blockchain/tokens/sip009_nft.ts:388-771 (handler)

  The execute handler function that generates a complete production-ready SIP-009 NFT Clarity contract template based on input parameters, including optional marketplace and metadata features.
  execute: async (args, context) => { try { await recordTelemetry({ action: "generate_sip009_template" }, context); const contractName = args.collectionName.toLowerCase().replace(/[^a-z0-9]/g, '-'); return `# SIP-009 NFT Collection: ${args.collectionName} ## Contract Implementation \`\`\`clarity ;; ${args.collectionName} (${args.collectionSymbol}) ;; A complete SIP-009 NFT implementation with all security features ;; Define the NFT using native Clarity primitive (REQUIRED) (define-non-fungible-token ${contractName} uint) ;; Error constants (define-constant ERR-NOT-AUTHORIZED (err u1)) (define-constant ERR-NOT-FOUND (err u2)) (define-constant ERR-ALREADY-EXISTS (err u3)) (define-constant ERR-INVALID-USER (err u4)) ${args.maxSupply ? '(define-constant ERR-MAX-SUPPLY-REACHED (err u5))' : ''} ;; Collection constants (define-constant CONTRACT-OWNER tx-sender) (define-constant COLLECTION-NAME "${args.collectionName}") (define-constant COLLECTION-SYMBOL "${args.collectionSymbol}") (define-constant BASE-URI "${args.baseUri}") ${args.maxSupply ? `(define-constant MAX-SUPPLY u${args.maxSupply})` : ''} ;; Variables (define-data-var last-token-id uint u0) (define-data-var mint-enabled bool true) ${args.includeMetadataStorage ? ` ;; On-chain metadata storage (define-map token-metadata uint { name: (string-ascii 64), description: (string-ascii 256), image: (string-ascii 256) }) ` : ''} ${args.includeMarketplace ? ` ;; Basic marketplace functionality (define-map listings uint { seller: principal, price: uint, expires-at: uint }) ` : ''} ;; Implement the SIP-009 trait (impl-trait 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait.nft-trait) ;; SIP-009 Required Functions (define-read-only (get-last-token-id) (ok (var-get last-token-id)) ) (define-read-only (get-token-uri (token-id uint)) (if (<= token-id (var-get last-token-id)) (ok (some (concat BASE-URI (uint-to-ascii token-id)))) (ok none) ) ) (define-read-only (get-owner (token-id uint)) (if (<= token-id (var-get last-token-id)) (ok (nft-get-owner? ${contractName} token-id)) (ok none) ) ) (define-public (transfer (token-id uint) (sender principal) (recipient principal)) (begin ;; Validate token exists (asserts! (<= token-id (var-get last-token-id)) ERR-NOT-FOUND) ;; Validate sender owns the token (asserts! (is-eq (some sender) (nft-get-owner? ${contractName} token-id)) ERR-NOT-AUTHORIZED) ;; Validate sender is tx-sender (asserts! (is-eq tx-sender sender) ERR-NOT-AUTHORIZED) ;; Validate recipient is different (asserts! (not (is-eq sender recipient)) ERR-INVALID-USER) ;; Perform transfer (enables post-conditions) (try! (nft-transfer? ${contractName} token-id sender recipient)) ;; Emit transfer event (print { action: "transfer", token-id: token-id, sender: sender, recipient: recipient }) (ok true) ) ) ;; Minting function (define-public (mint (recipient principal)${args.includeMetadataStorage ? ' (metadata {name: (string-ascii 64), description: (string-ascii 256), image: (string-ascii 256)})' : ''}) (let ( (next-id (+ (var-get last-token-id) u1)) ) ;; Check if minting is enabled (asserts! (var-get mint-enabled) ERR-NOT-AUTHORIZED) ;; Check authorization (asserts! (is-eq tx-sender CONTRACT-OWNER) ERR-NOT-AUTHORIZED) ${args.maxSupply ? '(asserts! (<= next-id MAX-SUPPLY) ERR-MAX-SUPPLY-REACHED)' : ''} ;; Mint the NFT (try! (nft-mint? ${contractName} next-id recipient)) ${args.includeMetadataStorage ? '(map-set token-metadata next-id metadata)' : ''} ;; Update last token ID (var-set last-token-id next-id) ;; Emit mint event (print { action: "mint", token-id: next-id, recipient: recipient${args.includeMetadataStorage ? ',\n metadata: metadata' : ''} }) (ok next-id) ) ) ;; Burn function (define-public (burn (token-id uint)) (begin ;; Validate token exists and sender owns it (asserts! (<= token-id (var-get last-token-id)) ERR-NOT-FOUND) (asserts! (is-eq (some tx-sender) (nft-get-owner? ${contractName} token-id)) ERR-NOT-AUTHORIZED) ;; Burn the NFT (try! (nft-burn? ${contractName} token-id tx-sender)) ${args.includeMetadataStorage ? '(map-delete token-metadata token-id)' : ''} ;; Emit burn event (print { action: "burn", token-id: token-id, owner: tx-sender }) (ok true) ) ) ${args.includeMetadataStorage ? ` ;; Metadata functions (define-read-only (get-token-metadata (token-id uint)) (map-get? token-metadata token-id) ) ` : ''} ;; Collection info (define-read-only (get-collection-info) (ok { name: COLLECTION-NAME, symbol: COLLECTION-SYMBOL, total-supply: (var-get last-token-id), base-uri: BASE-URI, mint-enabled: (var-get mint-enabled)${args.maxSupply ? ',\n max-supply: MAX-SUPPLY' : ''} }) ) ;; Administrative functions (define-public (toggle-mint) (begin (asserts! (is-eq tx-sender CONTRACT-OWNER) ERR-NOT-AUTHORIZED) (var-set mint-enabled (not (var-get mint-enabled))) (ok (var-get mint-enabled)) ) ) ${args.includeMarketplace ? ` ;; Basic Marketplace Functions (define-public (list-nft (token-id uint) (price uint) (expires-at uint)) (begin ;; Verify ownership (asserts! (is-eq (some tx-sender) (nft-get-owner? ${contractName} token-id)) ERR-NOT-AUTHORIZED) (asserts! (> price u0) ERR-INVALID-USER) (asserts! (> expires-at block-height) ERR-INVALID-USER) ;; Create listing (map-set listings token-id { seller: tx-sender, price: price, expires-at: expires-at }) (print { action: "list", token-id: token-id, seller: tx-sender, price: price, expires-at: expires-at }) (ok true) ) ) (define-public (unlist-nft (token-id uint)) (begin (asserts! (is-eq (some tx-sender) (nft-get-owner? ${contractName} token-id)) ERR-NOT-AUTHORIZED) (map-delete listings token-id) (print { action: "unlist", token-id: token-id, seller: tx-sender }) (ok true) ) ) (define-public (buy-nft (token-id uint)) (let ( (listing (unwrap! (map-get? listings token-id) ERR-NOT-FOUND)) (seller (get seller listing)) (price (get price listing)) ) ;; Verify listing is valid (asserts! (<= block-height (get expires-at listing)) ERR-NOT-FOUND) (asserts! (not (is-eq tx-sender seller)) ERR-INVALID-USER) ;; Transfer payment (STX) (try! (stx-transfer? price tx-sender seller)) ;; Transfer NFT (try! (nft-transfer? ${contractName} token-id seller tx-sender)) ;; Remove listing (map-delete listings token-id) (print { action: "sale", token-id: token-id, seller: seller, buyer: tx-sender, price: price }) (ok true) ) ) (define-read-only (get-listing (token-id uint)) (map-get? listings token-id) ) ` : ''} \`\`\` ## Collection Configuration - **Name**: ${args.collectionName} - **Symbol**: ${args.collectionSymbol} - **Base URI**: ${args.baseUri} ${args.maxSupply ? `- **Max Supply**: ${args.maxSupply} NFTs` : '- **Max Supply**: Unlimited'} - **On-chain Metadata**: ${args.includeMetadataStorage ? 'Enabled' : 'Disabled'} - **Marketplace Functions**: ${args.includeMarketplace ? 'Enabled' : 'Disabled'} ## Deployment Steps 1. **Save the contract** as \`${contractName}.clar\` 2. **Prepare metadata** (if using external storage): ${args.baseUri.includes('ipfs://') ? ` - Upload metadata files to IPFS - Update BASE-URI with your IPFS hash ` : ` - Set up metadata endpoint at ${args.baseUri} - Ensure HTTPS accessibility `} 3. **Test locally** with Clarinet: \`\`\`bash clarinet check clarinet test \`\`\` 4. **Deploy to testnet** first: \`\`\`bash clarinet deploy --testnet \`\`\` 5. **Deploy to mainnet** after testing: \`\`\`bash clarinet deploy --mainnet \`\`\` ## Usage Examples ### Minting NFTs \`\`\`clarity ;; Mint to specific address (contract-call? .${contractName} mint 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM${args.includeMetadataStorage ? ` { name: "NFT #1", description: "First NFT in the collection", image: "https://mynft.com/images/1.png" }` : ''}) \`\`\` ### Frontend Integration \`\`\`typescript // Transfer NFT await transferSIP009NFT( contractAddress, '${contractName}', 1, // token ID currentOwner, newOwner ); // Get NFT info const nftInfo = await getSIP009TokenInfo( contractAddress, '${contractName}', 1 ); \`\`\` ${args.includeMarketplace ? ` ### Marketplace Usage \`\`\`typescript // List NFT for sale await listNFT(tokenId, priceInSTX, expirationBlock); // Buy NFT await buyNFT(tokenId); \`\`\` ` : ''} ## Security Features ✅ - ✅ Native asset functions for post-condition support - ✅ Ownership validation for all transfers - ✅ Authorization checks using tx-sender - ✅ Token existence validation - ✅ Event emission for indexer integration ${args.maxSupply ? '- ✅ Supply limit enforcement' : ''} ${args.includeMarketplace ? '- ✅ Marketplace security (payment before transfer)' : ''} ## Metadata JSON Schema \`\`\`json { "name": "NFT Name", "description": "NFT Description", "image": "https://example.com/image.png", "external_url": "https://example.com/nft/1", "attributes": [ { "trait_type": "Rarity", "value": "Rare" } ] } \`\`\` ## Next Steps 1. Customize the contract name and save as \`.clar\` file 2. Set up metadata hosting (IPFS recommended) 3. Add to your Clarinet project 4. Write comprehensive tests 5. Deploy to testnet for testing 6. Deploy to mainnet when ready`; } catch (error) { return `❌ Failed to generate SIP-009 template: ${error}`; } },
• src/tools/stacks_blockchain/tokens/sip009_nft.ts:380-387 (schema)

  Zod schema defining the input parameters for the tool.
  parameters: z.object({ collectionName: z.string().describe("The name of the NFT collection (e.g., 'My NFT Collection')"), collectionSymbol: z.string().describe("The collection symbol (e.g., 'MNC')"), baseUri: z.string().describe("The base URI for metadata (e.g., 'https://api.mynft.com/metadata/' or 'ipfs://QmHash/')"), maxSupply: z.number().optional().describe("Optional maximum supply limit"), includeMarketplace: z.boolean().describe("Whether to include basic marketplace functionality"), includeMetadataStorage: z.boolean().describe("Whether to include on-chain metadata storage"), }),
• src/tools/index.ts:57-57 (registration)

  Registration of the tool in the FastMCP server.
  server.addTool(generateSIP009TemplateTool);
• src/tools/index.ts:15-15 (registration)

  Import of the tool from its implementation file.
  generateSIP009TemplateTool