Stacks Clarity MCP Server

Instructions

Implementation Reference

• src/tools/stacks_blockchain/performance/sip012_cost_analysis.ts:68-159 (handler)

  The core handler for the 'analyze_contract_performance' tool. Defines the tool object with name, description, parameters schema, and the execute function that analyzes Clarity contract code for SIP-012 performance metrics, identifies issues, and generates optimization recommendations.

  export const analyzeContractPerformanceTool: Tool<undefined, typeof ContractAnalysisScheme> = {
    name: "analyze_contract_performance",
    description: "Analyze a Clarity contract for performance bottlenecks and SIP-012 optimization opportunities. Provides detailed cost breakdown and optimization recommendations.",
    parameters: ContractAnalysisScheme,
    execute: async (args, context) => {
      try {
        await recordTelemetry({ action: "analyze_contract_performance" }, context);
        
        // Parse contract for performance analysis
        const analysis = analyzeContractCode(args.contractCode, args.functionName);
        const optimizations = generateOptimizations(analysis, args.optimizationLevel);
        
        return `# SIP-012 Performance Analysis
  
  ## Contract Overview
  - **Functions Analyzed**: ${analysis.functionCount}
  - **Map Operations**: ${analysis.mapOperations}
  - **List Operations**: ${analysis.listOperations}
  - **Contract Calls**: ${analysis.contractCalls}
  
  ## Performance Metrics
  
  ### Estimated Resource Usage
  \`\`\`
  Runtime Cost: ${analysis.estimatedCosts.runtime.toLocaleString()} units
  Read Operations: ${analysis.estimatedCosts.readCount}
  Write Operations: ${analysis.estimatedCosts.writeCount}
  Storage Read: ${analysis.estimatedCosts.readLength} bytes
  Storage Write: ${analysis.estimatedCosts.writeLength} bytes
  \`\`\`
  
  ### Block Capacity Usage
  - **Runtime**: ${((analysis.estimatedCosts.runtime / SIP012_COSTS.limits.runtime) * 100).toFixed(2)}% of block limit
  - **Read Count**: ${((analysis.estimatedCosts.readCount / SIP012_COSTS.limits.readCount) * 100).toFixed(2)}% of block limit
  - **Write Count**: ${((analysis.estimatedCosts.writeCount / SIP012_COSTS.limits.writeCount) * 100).toFixed(2)}% of block limit
  
  ## Performance Issues Detected
  
  ${analysis.issues.map(issue => `### ${issue.type}
  - **Severity**: ${issue.severity}
  - **Description**: ${issue.description}
  - **Impact**: ${issue.impact}
  - **Location**: ${issue.location || 'Multiple locations'}
  `).join('\n')}
  
  ## SIP-012 Optimization Opportunities
  
  ${optimizations.map(opt => `### ${opt.title}
  - **Type**: ${opt.type}
  - **Potential Savings**: ${opt.savings}
  - **Implementation**: ${opt.implementation}
  
  **Before:**
  \`\`\`clarity
  ${opt.before}
  \`\`\`
  
  **After:**
  \`\`\`clarity
  ${opt.after}
  \`\`\`
  `).join('\n')}
  
  ## Performance Recommendations
  
  ### Immediate Actions
  ${optimizations.filter(o => o.priority === 'high').map(o => `- ${o.title}: ${o.savings}`).join('\n')}
  
  ### Medium-term Improvements  
  ${optimizations.filter(o => o.priority === 'medium').map(o => `- ${o.title}: ${o.savings}`).join('\n')}
  
  ### Advanced Optimizations
  ${optimizations.filter(o => o.priority === 'low').map(o => `- ${o.title}: ${o.savings}`).join('\n')}
  
  ## Next Steps
  1. Implement high-priority optimizations first
  2. Profile contract with Clarinet performance tests
  3. Monitor gas usage in production
  4. Consider batch operations for high-frequency functions
  5. Leverage SIP-012 dynamic list sizing for collections
  
  ## SIP-012 Specific Benefits
  ✅ **2x Database Operations**: Take advantage of increased read/write limits
  ✅ **Dynamic List Storage**: Reduce storage costs with actual-size assessment
  ✅ **Optimized Cost Functions**: More accurate performance modeling
  ✅ **Enhanced Throughput**: Better block space utilization`;
        
      } catch (error) {
        return `❌ Failed to analyze contract performance: ${error}`;
      }
    },
  };

• src/tools/stacks_blockchain/performance/sip012_cost_analysis.ts:10-14 (schema)

  Zod schema defining the input parameters for the analyze_contract_performance tool: contract code, optional function name, and optimization level.

  const ContractAnalysisScheme = z.object({
    contractCode: z.string().describe("The Clarity contract code to analyze"),
    functionName: z.string().optional().describe("Specific function to analyze (optional)"),
    optimizationLevel: z.enum(["basic", "intermediate", "advanced"]).describe("Level of optimization analysis"),
  });

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

  Registration of the analyzeContractPerformanceTool in the FastMCP server via registerTools function.

  server.addTool(analyzeContractPerformanceTool);

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

  Import statement that brings the analyzeContractPerformanceTool into the index.ts for registration.

  import {
    analyzeContractPerformanceTool,
    estimateOperationCostTool,
    generateOptimizationRecommendationsTool
  } from "./stacks_blockchain/performance/sip012_cost_analysis.js";

• src/tools/stacks_blockchain/performance/sip012_cost_analysis.ts:324-383 (helper)

  Key helper function called by the handler to parse and analyze the contract code, count operations, estimate SIP-012 costs, and detect performance issues.

  function analyzeContractCode(code: string, targetFunction?: string) {
    // Simplified contract analysis
    const mapOperations = (code.match(/map-(get|set|delete)\?/g) || []).length;
    const listOperations = (code.match(/\b(append|filter|map|fold)\b/g) || []).length;
    const contractCalls = (code.match(/contract-call\?/g) || []).length;
    const functionCount = (code.match(/define-(public|private|read-only)/g) || []).length;
    
    // Estimate costs based on operations
    const estimatedCosts = {
      runtime: mapOperations * SIP012_COSTS.runtime.mapGet + 
              listOperations * SIP012_COSTS.runtime.listAppend + 
              contractCalls * SIP012_COSTS.runtime.contractCall,
      readCount: mapOperations + listOperations,
      writeCount: (code.match(/map-set|map-delete/g) || []).length,
      readLength: mapOperations * 40 + listOperations * 100,
      writeLength: (code.match(/map-set|map-delete/g) || []).length * 40,
    };
    
    // Identify performance issues
    const issues = [];
    
    if (mapOperations > 10) {
      issues.push({
        type: "High Database Usage",
        severity: "Medium",
        description: "Contract performs many map operations",
        impact: "May hit read/write count limits",
        location: "Multiple functions"
      });
    }
    
    if (listOperations > 5) {
      issues.push({
        type: "Inefficient List Processing",
        severity: "Medium", 
        description: "Multiple list operations detected",
        impact: "High runtime costs",
        location: "List processing functions"
      });
    }
    
    if (contractCalls > 3) {
      issues.push({
        type: "Cross-Contract Dependencies",
        severity: "Low",
        description: "Multiple external contract calls",
        impact: "Increased transaction complexity",
        location: "External interactions"
      });
    }
    
    return {
      functionCount,
      mapOperations,
      listOperations,
      contractCalls,
      estimatedCosts,
      issues
    };
  }