Stacks Clarity MCP Server

Instructions

Implementation Reference

• src/tools/stacks_blockchain/accounts/stacks_account.ts:34-114 (handler)

  Full implementation of the get_stacks_account_info tool handler, including execute function that fetches and formats Stacks account information.

  export const getStacksAccountInfoTool: Tool<undefined, typeof AccountInfoScheme> = {
    name: "get_stacks_account_info",
    description: "Get comprehensive information about a Stacks account including STX balance, nonce, tokens, and recent activity.",
    parameters: AccountInfoScheme,
    execute: async (args, context) => {
      try {
        await recordTelemetry({ action: "get_stacks_account_info" }, context);
        
        const apiService = new StacksApiService();
        const network = (process.env.STACKS_NETWORK as "mainnet" | "testnet" | "devnet") || "mainnet";
        const accountInfo = await apiService.getAccountInfo(args.address, network);
        
        let response = `# Stacks Account Information
  
  ## Address: ${args.address}
  
  ### STX Balance
  - **Total STX**: ${(parseInt(accountInfo.balance) / 1000000).toLocaleString()} STX
  - **Available STX**: ${(parseInt(accountInfo.balance) / 1000000).toLocaleString()} STX
  - **Locked STX**: ${(parseInt(accountInfo.locked) / 1000000).toLocaleString()} STX
  
  ### Account Details
  - **Account Nonce**: ${accountInfo.nonce}
  - **Account Status**: Active
  
  ### Network Information
  - **Network**: ${process.env.STACKS_NETWORK || 'mainnet'}
  - **API Endpoint**: ${process.env.STACKS_API_URL || 'https://api.stacks.co'}`;
  
        // Add token information if requested
        if (args.includeTokens) {
          try {
            const balanceData = await apiService.getAccountBalance(args.address, network);
            
            if (balanceData && balanceData.fungible_tokens) {
              response += `\n\n### Token Balances\n`;
              Object.entries(balanceData.fungible_tokens).forEach(([tokenId, tokenData]: [string, any]) => {
                response += `- **${tokenId}**: ${tokenData.balance}\n`;
              });
            } else {
              response += `\n\n### Token Balances\nNo token balances found.`;
            }
          } catch (error) {
            response += `\n\n### Token Balances\n⚠️ Could not retrieve token balances: ${error}`;
          }
        }
  
        // Add transaction history if requested
        if (args.includeTransactions) {
          try {
            const txData = await apiService.getAccountTransactions(args.address, network, 10);
            const transactions = txData.results || [];
            
            if (transactions && transactions.length > 0) {
              response += `\n\n### Recent Transactions (Last 10)\n`;
              transactions.forEach((tx: any, index: number) => {
                response += `${index + 1}. **${tx.tx_type}** - ${tx.tx_status} (Block: ${tx.block_height || 'Pending'})\n`;
                response += `   - TX ID: ${tx.tx_id}\n`;
                response += `   - Fee: ${(parseInt(tx.fee_rate || '0') / 1000000).toFixed(6)} STX\n\n`;
              });
            } else {
              response += `\n\n### Recent Transactions\nNo recent transactions found.`;
            }
          } catch (error) {
            response += `\n\n### Recent Transactions\n⚠️ Could not retrieve transactions: ${error}`;
          }
        }
  
        response += `\n\n## Useful Tools
  - Use \`check_stx_balance\` for simple STX balance checks
  - Use \`get_transaction_history\` for detailed transaction analysis
  - Use \`validate_stacks_address\` to verify address format
  - Use \`get_sip010_balance\` for specific token balance checks`;
  
        return response;
        
      } catch (error) {
        return `❌ Failed to get account information: ${error}`;
      }
    },
  };

• src/tools/stacks_blockchain/accounts/stacks_account.ts:11-15 (schema)

  Zod input schema for the tool defining address and optional flags for tokens and transactions.

  const AccountInfoScheme = z.object({
    address: z.string().describe("Stacks address (e.g., SP1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R)"),
    includeTokens: z.boolean().optional().describe("Include token balances in response"),
    includeTransactions: z.boolean().optional().describe("Include recent transactions in response"),
  });

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

  Registration of the getStacksAccountInfoTool with the FastMCP server.

  server.addTool(getStacksAccountInfoTool);

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

  Import statement that brings the getStacksAccountInfoTool into the index for registration.

  import {
    getStacksAccountInfoTool,
    checkSTXBalanceTool,
    getTransactionHistoryTool,
    validateStacksAddressTool
  } from "./stacks_blockchain/accounts/stacks_account.js";