Stacks Clarity MCP Server

Instructions

Implementation Reference

• src/tools/stacks_blockchain/accounts/stacks_account.ts:256-354 (handler)

  Full implementation of the validate_stacks_address tool, including the execute handler that performs address format validation, network prefix checking, and optional account info lookup.

  export const validateStacksAddressTool: Tool<undefined, typeof AddressValidationScheme> = {
    name: "validate_stacks_address",
    description: "Validate a Stacks address format and check if it's correctly formatted for the specified network.",
    parameters: AddressValidationScheme,
    execute: async (args, context) => {
      try {
        await recordTelemetry({ action: "validate_stacks_address" }, context);
        
        const address = args.address.trim();
        const network = args.network || 'mainnet';
        
        // Basic format validation
        const isValidFormat = /^S[TPMNX][A-Z0-9]{36,41}$/.test(address);
        
        if (!isValidFormat) {
          return `# Address Validation Result
  
  **Address**: ${address}
  **Valid Format**: ❌ No
  **Network**: ${network}
  
  ## Issues Detected
  - Address does not match Stacks address format
  - Expected format: S[TPMNX][A-Z0-9]{36-41}
  
  ## Valid Examples
  - **Mainnet**: SP1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R
  - **Testnet**: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
  
  ## Next Steps
  - Check address spelling and format
  - Ensure you're using the correct network prefix (SP for mainnet, ST for testnet)`;
        }
  
        // Network-specific validation
        const prefix = address.substring(0, 2);
        const expectedMainnetPrefix = 'SP';
        const expectedTestnetPrefix = 'ST';
        
        let networkMatch = true;
        let actualNetwork = 'unknown';
        
        if (prefix === expectedMainnetPrefix) {
          actualNetwork = 'mainnet';
          networkMatch = (network === 'mainnet');
        } else if (prefix === expectedTestnetPrefix) {
          actualNetwork = 'testnet';
          networkMatch = (network === 'testnet');
        } else {
          networkMatch = false;
        }
  
        // Try to get additional info if address is valid
        let additionalInfo = '';
        if (isValidFormat && networkMatch) {
          try {
            const apiService = new StacksApiService();
            const validNetwork = network as "mainnet" | "testnet" | "devnet";
            const accountInfo = await apiService.getAccountInfo(address, validNetwork);
            const balance = (parseInt(accountInfo.balance) / 1000000).toLocaleString();
            
            additionalInfo = `\n## Account Status
  - **STX Balance**: ${balance} STX
  - **Account Nonce**: ${accountInfo.nonce}
  - **Status**: Account exists and is active`;
            
          } catch (error) {
            additionalInfo = `\n## Account Status
  - **Status**: Valid format but account may not exist or be inactive
  - **Note**: ${error}`;
          }
        }
  
        return `# Address Validation Result
  
  **Address**: ${address}
  **Valid Format**: ${isValidFormat ? '✅ Yes' : '❌ No'}
  **Expected Network**: ${network}
  **Actual Network**: ${actualNetwork}
  **Network Match**: ${networkMatch ? '✅ Yes' : '❌ No'}
  
  ## Address Details
  - **Prefix**: ${prefix}
  - **Length**: ${address.length} characters
  - **Format**: ${isValidFormat ? 'Correct Stacks address format' : 'Invalid format'}
  
  ${!networkMatch && isValidFormat ? `\n⚠️ **Network Mismatch**: Address is for ${actualNetwork} but you specified ${network}` : ''}
  
  ${additionalInfo}
  
  ## Supported Networks
  - **Mainnet**: Addresses start with 'SP'
  - **Testnet**: Addresses start with 'ST'`;
        
      } catch (error) {
        return `❌ Failed to validate address: ${error}`;
      }
    },
  };

• src/tools/stacks_blockchain/accounts/stacks_account.ts:28-31 (schema)

  Zod schema defining the input parameters for the validate_stacks_address tool.

  const AddressValidationScheme = z.object({
    address: z.string().describe("Address to validate"),
    network: z.enum(["mainnet", "testnet"]).optional().describe("Network to validate against"),
  });

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

  Registration of the validateStacksAddressTool in the FastMCP server.

  server.addTool(validateStacksAddressTool);

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

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

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