Stacks MCP Server

id,language,category,name,description,code,imports_or_contract,notes 1,clarity,trait,sip009-trait,"SIP-009 NFT trait definition","(define-trait nft-trait ((get-last-token-id () (response uint uint)) (get-token-uri (uint) (response (optional (string-ascii 256)) uint)) (get-owner (uint) (response (optional principal) uint)) (transfer (uint principal principal) (response bool uint))))","SIP-009 standard","Required functions for NFT standard compliance" 2,clarity,read,get-owner,"Get NFT owner","(map-get? nft-owners { token-id: token-id })","Internal map","Returns (optional principal); none if not minted" 3,clarity,read,get-token-uri,"Get NFT metadata URI","(ok (some (concat base-uri (uint-to-ascii token-id))))","SIP-009 function","Returns IPFS or HTTP URL to metadata JSON" 4,clarity,read,get-last-token-id,"Get last minted token ID","(ok (var-get last-token-id))","SIP-009 function","Used to determine next token ID for minting" 5,clarity,mint,mint-nft,"Mint new NFT","(begin (asserts! (is-eq tx-sender contract-owner) err-not-authorized) (let ((token-id (+ (var-get last-token-id) u1))) (try! (nft-mint? nft-asset token-id recipient)) (map-set nft-owners { token-id: token-id } recipient) (var-set last-token-id token-id) (ok token-id)))","Custom function","Only owner can mint; auto-increments token ID" 6,clarity,transfer,transfer-nft,"Transfer NFT ownership","(begin (asserts! (is-eq tx-sender sender) err-not-authorized) (try! (nft-transfer? nft-asset token-id sender recipient)) (map-set nft-owners { token-id: token-id } recipient) (ok true))","SIP-009 function","Sender must be current owner; updates ownership map" 7,clarity,burn,burn-nft,"Burn (destroy) NFT","(begin (asserts! (is-eq (unwrap! (get-owner token-id) err-not-found) tx-sender) err-not-authorized) (try! (nft-burn? nft-asset token-id tx-sender)) (map-delete nft-owners { token-id: token-id }) (ok true))","Custom function","Only owner can burn; permanently removes NFT" 8,clarity,marketplace,list-nft,"List NFT for sale","(begin (asserts! (is-eq (unwrap! (get-owner token-id) err-not-found) tx-sender) err-not-authorized) (map-set listings { token-id: token-id } { seller: tx-sender price: price }) (ok true))","Marketplace function","Creates listing; NFT stays in owner wallet" 9,clarity,marketplace,buy-nft,"Buy listed NFT","(let ((listing (unwrap! (map-get? listings { token-id: token-id }) err-not-listed)) (seller (get seller listing)) (price (get price listing))) (try! (stx-transfer? price tx-sender seller)) (try! (nft-transfer? nft-asset token-id seller tx-sender)) (map-delete listings { token-id: token-id }) (ok true))","Marketplace function","Transfers STX payment and NFT ownership atomically" 10,clarity,marketplace,unlist-nft,"Remove NFT listing","(begin (asserts! (is-eq (get seller (unwrap! (map-get? listings { token-id: token-id }) err-not-listed)) tx-sender) err-not-authorized) (map-delete listings { token-id: token-id }) (ok true))","Marketplace function","Only seller can unlist; NFT ownership unchanged" 11,clarity,royalty,set-royalty,"Set NFT royalty percentage","(define-data-var royalty-percent uint u5) (define-public (set-royalty (new-royalty uint)) (begin (asserts! (is-eq tx-sender contract-owner) err-not-authorized) (asserts! (<= new-royalty u100) err-invalid-royalty) (ok (var-set royalty-percent new-royalty))))","Custom function","Typical royalty: 2.5-10%; enforced on secondary sales" 12,clarity,royalty,calculate-royalty,"Calculate royalty amount","(define-read-only (calculate-royalty (sale-price uint)) (/ (* sale-price (var-get royalty-percent)) u100))","Custom function","Returns royalty amount in microSTX" 13,clarity,collection,get-total-supply,"Get total NFTs minted","(ok (var-get last-token-id))","Common read function","Returns total number of minted tokens" 14,clarity,collection,get-collection-info,"Get collection metadata","(ok { name: collection-name symbol: collection-symbol total-supply: (var-get last-token-id) base-uri: base-uri })","Custom function","Returns collection-level metadata" 15,clarity,batch,batch-mint,"Mint multiple NFTs","(fold mint-single recipients (ok (list)))","Custom function","Gas-efficient bulk minting for drops" 16,javascript,read,get-nft-owner,"Get NFT owner via API","const response = await fetch(`https://api.hiro.so/extended/v1/tokens/nft/holdings?principal=${contractAddress}.${contractName}&token_id=${tokenId}`); const data = await response.json(); return data.results[0]?.owner","fetch or axios","Returns owner address or null if not minted" 17,javascript,read,get-nft-metadata,"Fetch NFT metadata from URI","const response = await fetch(tokenUri); const metadata = await response.json(); console.log(metadata.name metadata.image metadata.attributes)","fetch","Standard metadata: name image description attributes" 18,javascript,read,get-collection-nfts,"Get all NFTs in collection","const response = await fetch(`https://api.hiro.so/extended/v1/tokens/nft/holdings?principal=${contractAddress}.${contractName}`); const nfts = await response.json(); return nfts.results","fetch or axios","Returns array of token IDs and owners" 19,javascript,mint,mint-nft-tx,"Build mint NFT transaction","const txOptions = { contractAddress contractName functionName: 'mint' functionArgs: [principalCV(recipientAddress)] network postConditions: [Pc.principal(userAddress).willSendAsset().nft(contractAddress contractName tokenId)] }; const tx = await makeContractCall(txOptions)","import { makeContractCall principalCV Pc } from '@stacks/transactions'","Post-condition protects against unexpected transfers" 20,javascript,transfer,transfer-nft-tx,"Build transfer NFT transaction","const txOptions = { contractAddress contractName functionName: 'transfer' functionArgs: [uintCV(tokenId) principalCV(senderAddress) principalCV(recipientAddress)] network postConditions: [Pc.principal(senderAddress).willSendAsset().nft(contractAddress contractName tokenId)] }; const tx = await makeContractCall(txOptions)","import { makeContractCall uintCV principalCV Pc } from '@stacks/transactions'","Sender must own NFT; use deny mode for security" 21,javascript,marketplace,list-nft-tx,"Build list NFT transaction","const txOptions = { contractAddress: marketplaceAddress contractName: marketplaceName functionName: 'list-nft' functionArgs: [contractPrincipalCV(nftContract nftName) uintCV(tokenId) uintCV(priceInMicroStx)] network }; const tx = await makeContractCall(txOptions)","import { makeContractCall contractPrincipalCV uintCV } from '@stacks/transactions'","NFT stays in seller wallet until sold" 22,javascript,marketplace,buy-nft-tx,"Build buy NFT transaction","const txOptions = { contractAddress: marketplaceAddress contractName: marketplaceName functionName: 'buy-nft' functionArgs: [contractPrincipalCV(nftContract nftName) uintCV(tokenId)] network postConditions: [Pc.principal(buyerAddress).willSendLte(priceInMicroStx).ustx() Pc.principal(sellerAddress).willReceiveGte(priceInMicroStx * 0.95).ustx()] }; const tx = await makeContractCall(txOptions)","import { makeContractCall contractPrincipalCV uintCV Pc } from '@stacks/transactions'","Post-conditions protect buyer and seller; account for fees" 23,javascript,metadata,upload-metadata-ipfs,"Upload NFT metadata to IPFS","const metadata = { name: 'NFT Name' description: 'Description' image: 'ipfs://...' attributes: [{ trait_type: 'Background' value: 'Blue' }] }; const response = await fetch('https://api.pinata.cloud/pinning/pinJSONToIPFS' { method: 'POST' headers: { 'Content-Type': 'application/json' 'Authorization': `Bearer ${pinataJWT}` } body: JSON.stringify(metadata) }); const result = await response.json(); const tokenUri = `ipfs://${result.IpfsHash}`","fetch and Pinata API","Standard ERC-721 metadata format; store image on IPFS first" 24,javascript,batch,batch-transfer-nfts,"Batch transfer multiple NFTs","const transfers = tokenIds.map(tokenId => ({ contractAddress contractName functionName: 'transfer' functionArgs: [uintCV(tokenId) principalCV(sender) principalCV(recipient)] })); const txs = await Promise.all(transfers.map(opts => makeContractCall({ ...opts network })))","import { makeContractCall uintCV principalCV } from '@stacks/transactions'","Each transfer is separate transaction; consider gas costs" 25,api,marketplace,get-nft-listings,"Get NFT marketplace listings","const response = await fetch(`https://api.gamma.io/api/v1/collections/${contractId}/tokens`); const listings = await response.json(); const listed = listings.filter(nft => nft.listed)","fetch","Returns price seller token_id for listed NFTs" 26,api,analytics,get-nft-sales-history,"Get NFT sales history","const response = await fetch(`https://api.gamma.io/api/v1/tokens/${contractId}/${tokenId}/sales`); const sales = await response.json(); console.log(sales.map(s => ({ price: s.price_stx buyer: s.buyer seller: s.seller date: s.timestamp })))","fetch","Returns historical sales data for price discovery" 27,javascript,validation,validate-nft-ownership,"Verify user owns NFT","async function ownsNFT(userAddress contractAddress contractName tokenId) { const response = await fetch(`https://api.hiro.so/extended/v1/tokens/nft/holdings?principal=${contractAddress}.${contractName}&token_id=${tokenId}`); const data = await response.json(); return data.results[0]?.owner === userAddress }","fetch","Used for gating features or verifying ownership" 28,javascript,traits,parse-nft-attributes,"Parse and filter NFT attributes","function parseTraits(attributes) { return attributes.reduce((acc trait) => { acc[trait.trait_type] = trait.value; return acc }, {}) }; function filterByTrait(nfts traitType traitValue) { return nfts.filter(nft => nft.metadata.attributes.some(attr => attr.trait_type === traitType && attr.value === traitValue)) }","None","Useful for rarity analysis and collection filtering" 29,javascript,rarity,calculate-trait-rarity,"Calculate NFT trait rarity","function calculateRarity(collection trait) { const traitCount = collection.filter(nft => nft.attributes.some(a => a.trait_type === trait.trait_type && a.value === trait.value)).length; const rarity = (traitCount / collection.length) * 100; return { trait rarity percentage: rarity.toFixed(2) }","None","Lower percentage = rarer trait; sum trait rarities for overall rarity score" 30,api,collection,get-collection-stats,"Get collection floor price and volume","const response = await fetch(`https://api.gamma.io/api/v1/collections/${contractId}/stats`); const stats = await response.json(); console.log({ floor_price: stats.floor_price volume_24h: stats.volume_24h total_volume: stats.total_volume holders: stats.unique_holders })","fetch","Real-time collection analytics from Gamma marketplace"