Stacks Clarity MCP Server

Instructions

Implementation Reference

• src/tools/stacks_blockchain/accounts/stacks_account.ts:171-253 (handler)

  Full implementation of the get_transaction_history tool handler, including description, parameters schema reference, and the execute function that fetches and formats transaction history using StacksApiService.

  export const getTransactionHistoryTool: Tool<undefined, typeof TransactionHistoryScheme> = {
    name: "get_transaction_history",
    description: "Get detailed transaction history for a Stacks address with pagination support.",
    parameters: TransactionHistoryScheme,
    execute: async (args, context) => {
      try {
        await recordTelemetry({ action: "get_transaction_history" }, context);
        
        const apiService = new StacksApiService();
        const network = (process.env.STACKS_NETWORK as "mainnet" | "testnet" | "devnet") || "mainnet";
        const limit = Math.min(args.limit || 20, 50); // Cap at 50
        const offset = args.offset || 0;
        
        const txData = await apiService.getAccountTransactions(args.address, network, limit, offset);
        const transactions = txData.results || [];
        
        if (!transactions || transactions.length === 0) {
          return `# Transaction History
  
  **Address**: ${args.address}
  **Result**: No transactions found.
  
  The address may be new or have no transaction activity yet.`;
        }
  
        let response = `# Transaction History
  
  **Address**: ${args.address}
  **Showing**: ${transactions.length} transactions (offset: ${offset})
  
  `;
  
        transactions.forEach((tx: any, index: number) => {
          const txNumber = offset + index + 1;
          const fee = (parseInt(tx.fee_rate || '0') / 1000000).toFixed(6);
          
          response += `## ${txNumber}. ${tx.tx_type.toUpperCase()} Transaction
  
  **Status**: ${tx.tx_status}
  **TX ID**: \`${tx.tx_id}\`
  **Block Height**: ${tx.block_height || 'Pending'}
  **Fee**: ${fee} STX
  **Nonce**: ${tx.nonce}
  
  `;
  
          // Add type-specific details
          if (tx.tx_type === 'token_transfer') {
            const amount = (parseInt(tx.token_transfer?.amount || '0') / 1000000).toFixed(6);
            response += `**Amount**: ${amount} STX
  **From**: ${tx.sender_address}
  **To**: ${tx.token_transfer?.recipient_address}
  **Memo**: ${tx.token_transfer?.memo || 'None'}
  
  `;
          } else if (tx.tx_type === 'contract_call') {
            response += `**Contract**: ${tx.contract_call?.contract_id}
  **Function**: ${tx.contract_call?.function_name}
  **Sender**: ${tx.sender_address}
  
  `;
          } else if (tx.tx_type === 'smart_contract') {
            response += `**Contract**: ${tx.smart_contract?.contract_id}
  **Source Code**: ${tx.smart_contract?.source_code ? 'Available' : 'Not available'}
  
  `;
          }
        });
  
        response += `\n## Pagination
  - **Current Offset**: ${offset}
  - **Results Per Page**: ${limit}
  - **Next Page**: Use offset ${offset + limit} to get more transactions
  
  Use \`get_stacks_account_info\` for account overview or specific transaction tools for detailed analysis.`;
  
        return response;
        
      } catch (error) {
        return `❌ Failed to get transaction history: ${error}`;
      }
    },
  };

• src/tools/stacks_blockchain/accounts/stacks_account.ts:22-26 (schema)

  Zod schema defining the input parameters for the get_transaction_history tool: address (required), limit and offset (optional).

  const TransactionHistoryScheme = z.object({
    address: z.string().describe("Stacks address to get transaction history for"),
    limit: z.number().optional().describe("Number of transactions to retrieve (default: 20, max: 50)"),
    offset: z.number().optional().describe("Number of transactions to skip for pagination"),
  });

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

  Registration of the getTransactionHistoryTool with the FastMCP server in the central tools index.

  server.addTool(getTransactionHistoryTool);