Stacks Builder MCP Tool Benchmark

A comprehensive evaluation of Stacks Builder MCP (Model Context Protocol) tools for generating Clarity smart contracts on the Stacks blockchain.

Overview

This repository benchmarks two distinct approaches to Clarity smart contract development using the Stacks Builder MCP tools:

1. Direct Code Generation (generate_clarity_code) - AI generates complete, ready-to-deploy contracts
2. Context-Driven Development (get_clarity_context) - AI provides production examples for manual synthesis

The evaluation covers five progressively complex smart contract projects, from basic counters to DeFi staking protocols.

Results Summary

Success Rate: 5/5 projects completed successfully

Code Quality: Production-ready contracts with comprehensive error handling, security patterns, and best practices

Test Coverage: All projects include full test suites with 100% passing rates

Modifications Required: Minimal (trait imports, version compatibility adjustments only)

Projects

1. Counter

Tool: generate_clarity_code Complexity: Basic Lines of Code: 38 Functions: 4 (get-counter, increment, decrement, set-counter)

A simple counter contract demonstrating fundamental Clarity operations with read-write state management.

Key Features:

• Data variable for state storage
• Public functions for mutations
• Read-only function for queries
• Zero modifications required

2. Simple NFT Collection

Tool: generate_clarity_code Complexity: Intermediate Lines of Code: 104 Functions: 6 (4 SIP-009 standard + 2 custom) Test Coverage: 19/19 tests passing

SIP-009 compliant NFT collection with minting, transfers, and metadata management.

Key Features:

• SIP-009 Non-Fungible Token standard compliance
• Owner-only minting with collection limit (100 NFTs)
• Base URI pattern for metadata
• Comprehensive error handling (4 error codes)
• Transfer validation and ownership tracking

3. Voting Poll System

Tool: get_clarity_context Complexity: Intermediate Lines of Code: 160 Functions: 10 (3 public, 7 read-only) Context Queries: 4 queries, 15+ production examples

Time-bounded voting system with poll creation, voting, and results tracking.

Key Features:

• Create polls with up to 10 options
• Block height-based expiry
• Double-vote prevention
• Vote tracking with composite map keys
• Creator-only poll closure
• Real-time results querying

4. NFT Marketplace

Tool: get_clarity_context Complexity: Advanced Lines of Code: 179 Functions: 7 (3 public, 2 private, 2 read-only) Context Queries: 7 queries, 20+ production examples Test Coverage: 13/13 tests passing

Escrow-based NFT marketplace with STX payments and trait-based NFT compatibility.

Key Features:

• Escrow pattern for secure NFT custody during listing
• STX payment processing
• Trait-based design for any SIP-009 NFT
• Optional private listings (intended taker)
• Expiry-based validation
• Complete listing lifecycle (create, cancel, purchase)

Architecture: Based on Tiny Market patterns from Clarity Book

5. Token Staking

Tool: get_clarity_context Complexity: Advanced (DeFi) Lines of Code: 204 Functions: 8 (4 public, 4 read-only, 1 private) Context Queries: 5 queries, 15+ production examples

DeFi staking protocol with time-based rewards and STX token locking.

Key Features:

• Stake/unstake STX tokens
• 10% APY reward calculation
• Block-based interest accrual (~52,560 blocks/year)
• Separate claim rewards function
• Owner-controlled reward pool
• Minimum stake requirement (100 STX)
• Precision-safe math for reward calculations
• Automatic reward payout on unstake

Formula: (amount × rate × blocks) / (blocks_per_year × 10000)

Technology Stack

• Blockchain: Stacks (Bitcoin L2)
• Smart Contract Language: Clarity
• Development Framework: Clarinet
• Testing: Vitest with clarinet-sdk
• Environment: Node.js with TypeScript
• Standards: SIP-009 (Non-Fungible Tokens)

Prerequisites

• Clarinet - Clarity development environment
• Node.js (v18+) - For running tests
• npm or yarn - Package management

Getting Started

1. Clone the Repository

git clone <repository-url>
cd stacks-builder-benchmark

2. Choose a Project

Each project is self-contained:

cd counter              # Basic counter
cd simple-nft-collection  # NFT collection
cd voting-poll          # Voting system
cd simple-marketplace   # NFT marketplace
cd token-staking        # Staking protocol

3. Install Dependencies

npm install

4. Validate Contracts

clarinet check

5. Run Tests

# Run all tests
npm test

# Run with coverage and cost analysis
npm run test:report

# Watch mode (auto-run on file changes)
npm run test:watch

Project Structure

Each project follows the standard Clarinet structure:

project-name/
├── Clarinet.toml          # Project configuration
├── contracts/             # Clarity smart contracts (.clar)
├── tests/                 # Vitest test files (.test.ts)
├── settings/              # Network configurations (Devnet, Testnet, Mainnet)
├── package.json           # npm dependencies
├── tsconfig.json          # TypeScript configuration
├── vitest.config.ts       # Test runner configuration
└── REPORT.md              # Detailed evaluation report

Clarity Version Compatibility

Projects use different Clarity versions based on feature requirements:

• Clarity v4: counter (latest features)
• Clarity v3: simple-nft-collection, voting-poll, simple-marketplace, token-staking

Key Findings

Direct Code Generation (generate_clarity_code)

Pros:

• Production-ready code with minimal modifications
• Excellent inline documentation
• Smart architectural decisions
• Fast development (immediate output)
• Comprehensive error handling

Cons:

• No test generation
• Fixed design choices (less flexibility)
• External trait import issues for local development

Best For: Standard contracts with well-defined patterns (counters, NFTs, tokens)

Context-Driven Development (get_clarity_context)

Pros:

• Real-world production patterns
• Deep understanding through manual synthesis
• Flexible custom logic
• Learn from multiple examples
• Better for complex/novel contracts

Cons:

• Requires manual coding
• More time-intensive
• No automatic test generation
• Requires developer expertise to synthesize patterns

Best For: Complex custom logic (marketplaces, DeFi protocols, governance)

Documentation

• GENERAL_REPORT.md - Cross-project analysis and findings
• Individual REPORT.md in each project directory - Detailed evaluation per project

Resources

• Stacks Builder MCP Tool - The MCP tool evaluated in this benchmark
• Clarity Language Reference
• Clarinet Documentation
• SIP-009 Standard
• Stacks Documentation
• Clarity Book