Stacks Clarity MCP Server

Instructions

Implementation Reference

• src/tools/stacks_blockchain/tokens/sip010_ft.ts:102-150 (handler)

  The execute handler for the 'get_sip010_info' tool. Fetches SIP-010 token metadata (name, symbol, decimals, supply, URI) by calling multiple read-only contract functions via Hiro API and formats the response.

  export const getSIP010InfoTool: Tool<undefined, typeof SIP010TokenInfoScheme> = {
    name: "get_sip010_info",
    description: "Get complete information about a SIP-010 fungible token including name, symbol, decimals, total supply, and metadata URI.",
    parameters: SIP010TokenInfoScheme,
    execute: async (args, context) => {
      try {
        await recordTelemetry({ action: "get_sip010_info" }, context);
        
        // Get all token information in parallel
        const [nameResult, symbolResult, decimalsResult, supplyResult, uriResult] = await Promise.all([
          callReadOnlyFunction(args.contractAddress, args.contractName, "get-name", [], args.network),
          callReadOnlyFunction(args.contractAddress, args.contractName, "get-symbol", [], args.network),
          callReadOnlyFunction(args.contractAddress, args.contractName, "get-decimals", [], args.network),
          callReadOnlyFunction(args.contractAddress, args.contractName, "get-total-supply", [], args.network),
          callReadOnlyFunction(args.contractAddress, args.contractName, "get-token-uri", [], args.network),
        ]);
        
        // Parse results
        const name = nameResult.okay ? nameResult.result.replace(/"/g, '') : 'Unknown';
        const symbol = symbolResult.okay ? symbolResult.result.replace(/"/g, '') : 'Unknown';
        const decimals = decimalsResult.okay ? parseInt(decimalsResult.result.replace('u', '')) : 0;
        const totalSupply = supplyResult.okay ? parseInt(supplyResult.result.replace('u', '')) : 0;
        const uri = uriResult.okay && uriResult.result !== 'none' ? uriResult.result : 'No URI';
        
        return `# SIP-010 Token Information
  
  **Contract**: ${args.contractAddress}.${args.contractName}
  **Network**: ${args.network}
  
  ## Token Details
  - **Name**: ${name}
  - **Symbol**: ${symbol}
  - **Decimals**: ${decimals}
  - **Total Supply**: ${totalSupply} base units (${totalSupply / Math.pow(10, decimals)} ${symbol})
  - **Metadata URI**: ${uri}
  
  ## Contract Verification
  ✅ This contract implements the SIP-010 standard trait.
  
  ## Usage Notes
  - All amounts are in base units (multiply by 10^${decimals} for human amounts)
  - Post-conditions are REQUIRED for all transfers
  - Use native Stacks post-conditions for security`;
        
      } catch (error) {
        return `❌ Failed to get SIP-010 token info: ${error}`;
      }
    },
  };

• src/tools/stacks_blockchain/tokens/sip010_ft.ts:30-34 (schema)

  Zod input schema for the get_sip010_info tool, defining required parameters: contractAddress, contractName, and network.

  const SIP010TokenInfoScheme = z.object({
    contractAddress: z.string().describe("The contract address"),
    contractName: z.string().describe("The contract name of the SIP-010 token"),
    network: NetworkScheme.describe("The Stacks network"),
  });

• src/tools/index.ts:49-49 (registration)

  Registration of the getSIP010InfoTool (get_sip010_info) with the FastMCP server.

  server.addTool(getSIP010InfoTool);

• src/tools/stacks_blockchain/tokens/sip010_ft.ts:37-70 (helper)

  Helper function used by get_sip010_info to call read-only Clarity functions on Stacks contracts using the Hiro API.

  async function callReadOnlyFunction(
    contractAddress: string,
    contractName: string,
    functionName: string,
    functionArgs: any[],
    network: string
  ): Promise<any> {
    const apiUrl = network === "mainnet" 
      ? "https://api.hiro.so" 
      : "https://api.testnet.hiro.so";
    
    try {
      const response = await fetch(
        `${apiUrl}/v2/contracts/call-read/${contractAddress}/${contractName}/${functionName}`,
        {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            sender: contractAddress,
            arguments: functionArgs,
          }),
        }
      );
      
      if (!response.ok) {
        const data: any = await response.json();
        throw new Error(data.error || `HTTP ${response.status}`);
      }
      
      return await response.json();
    } catch (error) {
      throw new Error(`Failed to call ${functionName}: ${error}`);
    }
  }