Skip to main content
Glama

Stacks Clarity MCP Server

README.mdโ€ข13.9 kB
# Stacks Clarity MCP Server A comprehensive MCP (Model Context Protocol) server for Stacks blockchain development, providing 30+ specialized tools for Clarity smart contracts, SIP compliance, security, and performance optimization. > ๐Ÿ’ก **New to MCP?** Check out our [integration guides](integration_guides/) for step-by-step setup instructions for [Cursor](integration_guides/cursor.md), [Claude Code](integration_guides/claude_code.md), or [local development](integration_guides/development_usage.md). ## ๐Ÿš€ Overview This comprehensive MCP server provides a complete Stacks development toolkit, implementing TIER 1 and TIER 2 priorities for professional Stacks dApp development with security-first patterns and SIP compliance. ### Key Features - **๐Ÿ—๏ธ Complete SIP Standards Access** - All 30+ SIP standards with full Clarity code - **๐Ÿ” Security-First Development** - Mandatory post-conditions for all token transfers - **โšก SIP-012 Performance Optimization** - 2x database capacity and dynamic storage - **๐ŸŽจ Token Standards** - Full SIP-009 (NFT) and SIP-010 (FT) implementations - **๐Ÿงช Comprehensive Testing** - Unit, integration, and security test generation - **๐Ÿ”ง Clarinet Integration** - Complete project setup and management tools - **๐Ÿ’ฐ Account Management** - STX balances, transaction history, and validation - **๐Ÿ“š Complete Documentation** - Clarity Book, SIP standards, and integration guides ## ๐Ÿ“‹ Prerequisites - [Node.js and npm](https://nodejs.org/en) (npm โ‰ฅ 5.2.0) - [Clarinet CLI](https://github.com/hirosystems/clarinet) (for contract development) - Stacks wallet (for frontend integration) - Cursor IDE or Claude Code (for MCP integration) ## ๐Ÿ› ๏ธ Quick Setup for Cursor/Claude Code ### Option 1: Use Published Package (When Available) Once published to npm, create `.cursor/mcp.json` in your project: ```json { "mcpServers": { "stacks-clarity-mcp": { "command": "npx", "args": ["-y", "@stacks/stacks-clarity-mcp"], "env": { "HIRO_API_KEY": "", "STACKS_NETWORK": "testnet" } } } } ``` ### Option 2: Local Development Setup (Current) 1. **Clone and install**: ```bash git clone https://github.com/YOUR_USERNAME/stacks-clarity-mcp.git cd stacks-clarity-mcp npm install ``` 2. **Build the project**: ```bash npm run build ``` > **Note**: This generates the `dist/` folder with compiled JavaScript. The build is required before running the server. 3. **Configure Cursor** - Create `.cursor/mcp.json` in your project root: ```json { "mcpServers": { "stacks-clarity-mcp": { "command": "npx", "args": ["-y", "tsx", "/absolute/path/to/stacks-clarity-mcp/src/server.ts"], "env": { "HIRO_API_KEY": "", "STACKS_NETWORK": "testnet" } } } } ``` > **Important**: Replace `/absolute/path/to/stacks-clarity-mcp` with your actual path! 4. **Restart Cursor** completely (quit and reopen) 5. **Verify Setup**: - Go to `Cursor โ†’ Settings โ†’ MCP` - Look for green indicator next to `stacks-clarity-mcp` - Switch to **Agent** mode in chat - Test with: "list available stacks tools" ### Network Options - `mainnet` - Production Stacks network - `testnet` - Test network with free tokens - `devnet` - Local development with Clarinet ### Get Hiro API Key (Optional) For enhanced features and higher rate limits: 1. Visit [platform.hiro.so](https://platform.hiro.so) 2. Create an account and generate an API key 3. Add to `HIRO_API_KEY` in your config ๐Ÿ“š **Detailed guides**: See [`integration_guides/`](integration_guides/) folder for [Cursor](integration_guides/cursor.md), [Claude Code](integration_guides/claude_code.md), and [Development](integration_guides/development_usage.md) setup. ## ๐Ÿ“ฆ What's Included in the Repository **Included (pushed to GitHub):** - โœ… `src/` - TypeScript source code (452KB) - โœ… `stacks-clarity-standards/` - All 30+ SIP standards (9.2MB) - โœ… `integration_guides/` - Setup documentation - โœ… `package.json`, `tsconfig.json` - Configuration files **Excluded (not pushed):** - โŒ `node_modules/` - Dependencies (165MB) - install with `npm install` - โŒ `dist/` - Build output (448KB) - generate with `npm run build` - โŒ `.cursor/` - Local MCP config - โŒ `.env` - Environment variables > **Setup Requirement**: After cloning, you must run `npm install` and `npm run build` before using the MCP server. ## ๐Ÿ“– Available Tools (32 Total) ### ๐Ÿ” Standards & Documentation (5 tools) - `list_sips` - Discover all available SIP standards - `get_sip` - Get specific SIP content (SIP-009, SIP-010, etc.) - `get_clarity_book` - Complete Clarity language reference (34,000+ lines) - `get_token_standards` - Essential SIP-009/SIP-010 standards - `search_sips` - Search SIPs by topic ### ๐Ÿช™ Token Development (8 tools) #### SIP-010 Fungible Tokens - `get_sip010_info` - Token contract information and metadata - `get_sip010_balance` - Check FT balances for addresses - `generate_sip010_transfer` - Create transfer transactions with post-conditions - `generate_sip010_template` - Generate complete SIP-010 compliant contracts #### SIP-009 Non-Fungible Tokens - `get_sip009_token_info` - NFT information and metadata - `get_sip009_collection_info` - Collection-level information - `generate_sip009_transfer` - Create NFT transfers with post-conditions - `generate_sip009_template` - Generate complete SIP-009 compliant contracts ### ๐Ÿ” Security & Post-Conditions (5 tools) - `generate_fungible_post_condition` - Mandatory FT post-conditions - `generate_nonfungible_post_condition` - Mandatory NFT post-conditions - `generate_stx_post_condition` - STX transfer post-conditions - `analyze_transaction_post_conditions` - Validate transaction security - `generate_post_condition_template` - Security templates and patterns ### โšก Performance Optimization - SIP-012 (3 tools) - `analyze_contract_performance` - Comprehensive performance analysis - `estimate_operation_cost` - Cost estimation for Clarity operations - `generate_optimization_recommendations` - SIP-012 optimization strategies ### ๐Ÿ‘ค Account Management (4 tools) - `get_stacks_account_info` - Comprehensive account information - `check_stx_balance` - Simple STX and token balance checks - `get_transaction_history` - Account transaction history with pagination - `validate_stacks_address` - Address format and network validation ### ๐Ÿงช Development & Testing (4 tools) - `generate_clarinet_project` - Complete Clarinet project setup - `generate_clarity_contract` - SIP-compliant contract generation - `generate_contract_tests` - Unit, integration, and security tests - `configure_clarinet_project` - Network and environment configuration ### ๐ŸŽจ Frontend Development (3 tools) - `build_clarity_smart_contract` - Smart contract development guidance - `build_stacks_frontend` - Frontend integration with @stacks/connect - `build_stacks_dapp` - Complete full-stack development guide ## ๐Ÿš€ Quick Start Guide ### 1. Explore Available Standards ```typescript // Discover all SIP standards use tool: list_sips // Get specific token standards use tool: get_token_standards // Access complete Clarity reference use tool: get_clarity_book ``` ### 2. Build a SIP-010 Token ```typescript // Generate compliant token contract use tool: generate_sip010_template params: { tokenName: "MyToken", symbol: "MTK", decimals: 6, features: ["minting", "burning"] } // Create secure transfer use tool: generate_sip010_transfer params: { contractId: "ST1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R.my-token", amount: 1000000, sender: "ST1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R", recipient: "ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG", memo: "Secure transfer with post-conditions" } ``` ### 3. Set Up Development Environment ```typescript // Initialize Clarinet project use tool: generate_clarinet_project params: { projectName: "my-stacks-project", template: "fungible-token" } // Generate comprehensive tests use tool: generate_contract_tests params: { contractName: "my-token", testType: "security", scenarios: ["post-conditions", "authorization"] } ``` ## ๐Ÿ”’ Security Features ### Mandatory Post-Conditions All token transfers **MUST** include post-conditions. The MCP server enforces this: ```typescript // โœ… CORRECT: Transfer with post-conditions use tool: generate_fungible_post_condition params: { address: "ST1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R", contractId: "ST1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R.token", amount: 1000000, condition: "equal" } // Always use PostConditionMode.Deny for maximum security ``` ### SIP Compliance Enforcement - Automatic SIP-009 and SIP-010 compliance checking - Native asset function usage (ft-transfer?, nft-transfer?) - Proper error handling and authorization patterns ## โšก Performance Optimization ### SIP-012 Benefits - **2x Database Operations**: Increased read/write limits per block - **Dynamic List Storage**: Pay only for actual data size - **Optimized Cost Functions**: 100+ improved cost calculations ```typescript // Analyze contract performance use tool: analyze_contract_performance params: { contractCode: "...", // Your Clarity contract optimizationLevel: "advanced" } // Get optimization recommendations use tool: generate_optimization_recommendations params: { contractPattern: "token-contract", currentIssues: ["high gas costs", "multiple map operations"] } ``` ## ๐Ÿ“š Comprehensive Documentation Access to complete Stacks development resources: - **34,000+ lines** of Clarity Book documentation - **30+ SIP standards** with full implementations - **Security patterns** and best practices - **Performance optimization** guides - **Frontend integration** examples ## ๐Ÿ—๏ธ Integration Examples ### React Frontend with @stacks/connect ```typescript // Get complete frontend guidance use tool: build_stacks_frontend // Generate wallet connection code // Transaction signing with post-conditions // Error handling and user experience ``` ### DeFi Protocol Development ```typescript // Performance-optimized DeFi contract use tool: generate_clarity_contract params: { contractName: "amm-pool", contractType: "custom", features: ["governance", "staking"] } // Security testing use tool: generate_contract_tests params: { contractName: "amm-pool", testType: "security", scenarios: ["reentrancy", "authorization", "post-conditions"] } ``` ### NFT Marketplace ```typescript // SIP-009 compliant NFT collection use tool: generate_sip009_template params: { collectionName: "Art Collection", symbol: "ART", features: ["metadata", "royalties"] } // Marketplace contract with escrow use tool: generate_clarity_contract params: { contractName: "nft-marketplace", contractType: "custom", features: ["escrow", "royalties"] } ``` ## ๐Ÿ”ง Development Workflow 1. **Research Standards**: Use `list_sips` and `get_sip` to understand requirements 2. **Generate Contracts**: Use template tools for SIP-compliant implementations 3. **Security Testing**: Generate comprehensive security test suites 4. **Performance Optimization**: Analyze and optimize using SIP-012 tools 5. **Frontend Integration**: Build user interfaces with wallet connectivity 6. **Deployment**: Use Clarinet tools for production deployment ## ๐Ÿ“‹ Production Checklist - โœ… SIP compliance validated - โœ… Mandatory post-conditions implemented - โœ… Security tests passing - โœ… Performance optimized with SIP-012 - โœ… Frontend properly integrated - โœ… All tests (unit, integration, security) passing ## ๐Ÿ› Troubleshooting ### MCP Server Not Appearing in Cursor 1. **Check MCP Settings**: - Go to `Cursor โ†’ Settings โ†’ Cursor Settings โ†’ MCP` - Look for `stacks-clarity-mcp` entry - Check if indicator is green (connected) or red (error) - Click on the entry to see error details 2. **Verify Configuration**: - Ensure `.cursor/mcp.json` exists in project root - For local development, use **absolute path** to `server.ts` - Check that Node.js is installed: `node --version` 3. **Restart Cursor**: - Completely quit Cursor (not just close window) - Reopen Cursor - Wait 10-15 seconds for MCP to initialize 4. **Check Agent Mode**: - In Cursor chat, ensure dropdown is set to **Agent** (not normal chat) - MCP tools only work in Agent mode 5. **Test MCP Connection**: ```bash # Test the server directly npx tsx /path/to/server.ts # Or use MCP Inspector npx @modelcontextprotocol/inspector ``` ### Common Issues **"Command not found"**: Make sure you're using `npx tsx` not just `tsx` **"Module not found"**: Run `npm install` in the MCP server directory **Build errors**: For local development, use `tsx` to run from source (skips build step) **Tools not visible**: Ensure you're in **Agent mode** and the MCP shows green indicator ### Getting Help - Check [integration guides](integration_guides/) for detailed setup - Review [development_usage.md](integration_guides/development_usage.md) for local development - Use MCP Inspector to test tools: `npx @modelcontextprotocol/inspector` ## ๐Ÿค Contributing This MCP server implements the complete Stacks development stack. Contributions should maintain: - Security-first principles - SIP standard compliance - Performance optimization focus - Comprehensive documentation ## ๐Ÿ“„ License This project is licensed under the Apache-2.0 License. ## ๐Ÿ”— Resources - [Stacks Documentation](https://docs.stacks.co/) - [Clarity Language Reference](https://docs.stacks.co/clarity/) - [SIP Standards](https://github.com/stacksgov/sips) - [Clarinet CLI](https://github.com/hirosystems/clarinet) - [Stacks.js](https://github.com/hirosystems/stacks.js) --- **Built for professional Stacks development with security, performance, and compliance as top priorities.**

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/exponentlabshq/stacks-clarity-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server