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!") ) \`\`\``; } }