Stacks Clarity MCP Server

Instructions

Implementation Reference

• src/tools/stacks_blockchain/development/clarinet_project.ts:34-266 (handler)

  The main handler implementation defining the 'generate_clarinet_project' tool. The execute function generates a comprehensive Markdown guide for setting up a new Clarinet project including structure, configurations, templates, and commands.

  export const generateClarinetsProjectTool: Tool<undefined, typeof ClarinetsInitScheme> = {
    name: "generate_clarinet_project",
    description: "Generate a complete Clarinet project setup with proper structure, configuration, and starter contracts.",
    parameters: ClarinetsInitScheme,
    execute: async (args, context) => {
      try {
        await recordTelemetry({ action: "generate_clarinet_project" }, context);
        
        const projectName = args.projectName;
        const projectPath = args.projectPath || './';
        const template = args.template || 'empty';
        
        return `# Clarinet Project Setup Guide
  
  ## Project: ${projectName}
  
  ### 1. Initialize Clarinet Project
  
  \`\`\`bash
  # Create new Clarinet project
  clarinet new ${projectName}
  cd ${projectName}
  
  # Verify Clarinet installation
  clarinet --version
  \`\`\`
  
  ### 2. Project Structure
  
  After initialization, your project will have this structure:
  
  \`\`\`
  ${projectName}/
  ├── Clarinet.toml           # Main project configuration
  ├── settings/               # Network-specific settings
  │   ├── Devnet.toml
  │   ├── Testnet.toml
  │   └── Mainnet.toml
  ├── contracts/              # Clarity contracts
  ├── tests/                  # TypeScript/JavaScript tests
  ├── deployments/            # Deployment plans
  └── .gitignore
  \`\`\`
  
  ### 3. Clarinet.toml Configuration
  
  \`\`\`toml
  [project]
  name = "${projectName}"
  authors = []
  description = ""
  telemetry = true
  cache_dir = "./.clarinet/cache"
  requirements = []
  
  [contracts.${projectName}]
  path = "contracts/${projectName}.clar"
  clarity_version = 2
  epoch = "2.4"
  
  [repl]
  costs_version = 2
  parser_version = 2
  
  [repl.analysis]
  passes = ["check_checker"]
  
  [repl.analysis.check_checker]
  strict = false
  trusted_sender = false
  trusted_caller = false
  callee_filter = false
  \`\`\`
  
  ### 4. Network Configurations
  
  #### Devnet Settings (\`settings/Devnet.toml\`)
  \`\`\`toml
  [network]
  name = "devnet"
  deployment_fee_rate = 10
  
  [accounts.deployer]
  mnemonic = "twice kind fence tip hidden tilt action fragile skin nothing glory cousin green tomorrow spring wrist shed math olympic multiply hip blue scout claw"
  balance = 100000000000000
  
  [accounts.wallet_1] 
  mnemonic = "sell invite acquire kitten bamboo drastic jelly vivid peace spawn twice guilt pave pen trash pretty park cube fragile unaware remain midnight betray rebuild"
  balance = 100000000000000
  
  [accounts.wallet_2]
  mnemonic = "hold excess usual excess ring elephant install account glad dry fragile donkey gaze humble truck breeze nation gasp vacuum limb head keep delay hospital"
  balance = 100000000000000
  \`\`\`
  
  ### 5. ${template.charAt(0).toUpperCase() + template.slice(1)} Template Implementation
  
  ${getTemplateImplementation(template, projectName)}
  
  ### 6. Essential Development Commands
  
  \`\`\`bash
  # Start Clarinet console for interactive development
  clarinet console
  
  # Run tests
  clarinet test
  
  # Check contract syntax
  clarinet check
  
  # Generate deployment plan
  clarinet deployments generate --devnet
  
  # Deploy to devnet
  clarinet deployments apply --devnet
  
  # Start local devnet (if needed)
  clarinet integrate
  
  # Format contract code
  clarinet fmt
  \`\`\`
  
  ### 7. Test Setup
  
  Create a basic test file: \`tests/${projectName}_test.ts\`
  
  \`\`\`typescript
  import { Clarinet, Tx, Chain, Account, types } from 'https://deno.land/x/clarinet@v1.0.0/index.ts';
  import { assertEquals } from 'https://deno.land/std@0.90.0/testing/asserts.ts';
  
  Clarinet.test({
      name: "Ensure that basic functionality works",
      async fn(chain: Chain, accounts: Map<string, Account>) {
          const deployer = accounts.get("deployer")!;
          const wallet1 = accounts.get("wallet_1")!;
          
          let block = chain.mineBlock([
              // Add your test transactions here
          ]);
          
          assertEquals(block.receipts.length, 0);
          assertEquals(block.height, 2);
      },
  });
  \`\`\`
  
  ### 8. VS Code Integration
  
  Create \`.vscode/settings.json\` for better development experience:
  
  \`\`\`json
  {
      "clarinet.enable": true,
      "editor.formatOnSave": true,
      "[clarity]": {
          "editor.tabSize": 2,
          "editor.insertSpaces": true
      },
      "files.associations": {
          "*.clar": "clarity"
      }
  }
  \`\`\`
  
  ### 9. Git Setup
  
  Add to \`.gitignore\`:
  
  \`\`\`
  # Clarinet
  .clarinet/
  costs-reports.json
  
  # Logs
  *.log
  npm-debug.log*
  
  # Dependencies
  node_modules/
  
  # IDE
  .vscode/
  .idea/
  \`\`\`
  
  ### 10. Next Steps
  
  1. **Add Contracts**: Place your Clarity contracts in \`contracts/\`
  2. **Write Tests**: Create comprehensive tests in \`tests/\`
  3. **Configure Networks**: Update settings for testnet/mainnet
  4. **Add Dependencies**: Use \`requirements\` in Clarinet.toml for contract dependencies
  5. **CI/CD**: Set up GitHub Actions for automated testing
  
  ### 11. Useful Development Tools
  
  \`\`\`bash
  # Generate contract scaffold
  clarinet contract new my-contract
  
  # Add existing contract
  clarinet contract add my-contract contracts/my-contract.clar
  
  # Interactive Clarinet console commands
  clarinet console
  > (contract-call? .${projectName} some-function)
  > ::get_costs
  > ::get_contracts_by_trait
  \`\`\`
  
  ### 12. Performance Optimization
  
  Use these Clarinet commands for performance analysis:
  
  \`\`\`bash
  # Generate cost analysis
  clarinet test --costs
  
  # Check contract coverage
  clarinet test --coverage
  
  # Analyze contract size
  clarinet check --decode
  \`\`\`
  
  Your Clarinet project is now ready for development! Use the MCP tools like \`generate_clarity_contract\` and \`generate_contract_tests\` to add functionality to your project.`;
        
      } catch (error) {
        return `❌ Failed to generate Clarinet project: ${error}`;
      }
    },
  };

• src/tools/stacks_blockchain/development/clarinet_project.ts:10-14 (schema)

  Zod schema defining the input parameters for the generate_clarinet_project tool: projectName (required), projectPath (optional), template (optional enum).

  const ClarinetsInitScheme = z.object({
    projectName: z.string().describe("Name of the Clarinet project to create"),
    projectPath: z.string().optional().describe("Path where to create the project (default: current directory)"),
    template: z.enum(["counter", "nft", "fungible-token", "empty"]).optional().describe("Project template to use"),
  });

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

  Registration of the generate_clarinet_project tool in the central tools index by adding it to the FastMCP server.

  server.addTool(generateClarinetsProjectTool);

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

  Import of the generateClarinetsProjectTool from its implementation file, enabling registration.

  import {
    generateClarinetsProjectTool,
    generateClarityContractTool,
    generateContractTestsTool,
    configureClarinetsProjectTool
  } from "./stacks_blockchain/development/clarinet_project.js";

• src/tools/stacks_blockchain/development/clarinet_project.ts:734-806 (helper)

  Helper function that generates template-specific Clarity contract code based on the chosen project template (counter, nft, etc.). Used within the handler.

  function getTemplateImplementation(template: string, projectName: string): string {
    switch (template) {
      case 'counter':
        return `\`\`\`clarity
  ;; Counter Template Implementation
  (define-data-var counter uint u0)
  
  (define-read-only (get-counter)
    (var-get counter)
  )
  
  (define-public (increment)
    (ok (var-set counter (+ (var-get counter) u1)))
  )
  
  (define-public (decrement)
    (ok (var-set counter (- (var-get counter) u1)))
  )
  \`\`\``;
  
      case 'nft':
        return `\`\`\`clarity
  ;; SIP-009 NFT Template Implementation
  (use-trait sip009-trait 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait.nft-trait)
  
  (define-non-fungible-token ${projectName} uint)
  (define-data-var last-token-id uint u0)
  
  (define-public (mint (recipient principal))
    (let ((token-id (+ (var-get last-token-id) u1)))
      (var-set last-token-id token-id)
      (nft-mint? ${projectName} token-id recipient)
    )
  )
  
  (define-public (transfer (token-id uint) (sender principal) (recipient principal))
    (begin
      (asserts! (is-eq tx-sender sender) (err u403))
      (nft-transfer? ${projectName} token-id sender recipient)
    )
  )
  \`\`\``;
  
      case 'fungible-token':
        return `\`\`\`clarity
  ;; SIP-010 Fungible Token Template Implementation
  (use-trait sip010-trait 'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-010-trait-ft-standard.sip-010-trait)
  
  (define-fungible-token ${projectName})
  
  (define-public (transfer (amount uint) (sender principal) (recipient principal) (memo (optional (buff 34))))
    (begin
      (asserts! (is-eq tx-sender sender) (err u403))
      (ft-transfer? ${projectName} amount sender recipient)
    )
  )
  
  (define-public (mint (amount uint) (recipient principal))
    (ft-mint? ${projectName} amount recipient)
  )
  \`\`\``;
  
      default:
        return `\`\`\`clarity
  ;; Empty Template - Add your contract logic here
  (define-constant contract-owner tx-sender)
  
  (define-public (hello-world)
    (ok "Hello, Stacks!")
  )
  \`\`\``;
    }
  }