troopdegen/se2-minikit-mcp-server

SE2-Minikit MCP Server

MCP server enabling rapid Web3 development on Base with Farcaster integration

Status: ✅ Basic Scaffolding Functional Version: 0.1.0 (Alpha) Last Updated: 2025-11-07

🚀 Quick Start

Prerequisites

• Bun v1.2.16+ (for running the MCP server)
• Claude Desktop (for using the MCP server)
• Git (optional, for version control)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/se2-minikit-mcp-server.git
   cd se2-minikit-mcp-server
   

2. Install dependencies:

   bun install
   

3. Build the server:

   bun run build
   

4. Configure Claude Desktop:

   First, find your Bun path:

   which bun
   # Output example: /Users/yourusername/.bun/bin/bun
   

   Then add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

   {
     "mcpServers": {
       "scaffold-minikit": {
         "command": "/Users/yourusername/.bun/bin/bun",
         "args": ["--silent", "/absolute/path/to/se2-minikit-mcp-server/dist/index.js"],
         "env": {
           "NODE_ENV": "production",
           "LOG_LEVEL": "info"
         }
       }
     }
   }
   

   Important:

   • Use absolute paths for both command and the server path
   • --silent flag suppresses Bun's package manager output
   • NODE_ENV=production disables pretty logging (prevents stdout leaks)
   • Use the built dist/index.js file (not src/server/index.ts)
   • Claude Desktop doesn't inherit your shell's PATH

5. Restart Claude Desktop and verify the server appears in the MCP servers list.

Usage

Ask Claude to scaffold a project:

Create a Scaffold-ETH 2 project called "my-dapp" on Base Sepolia testnet

Claude will use the scaffold_project tool to generate a complete project with:

• Smart contracts (Hardhat)
• Next.js frontend
• Deployment scripts
• Testing infrastructure
• All dependencies installed

Generated Project Setup

After Claude generates your project:

cd my-dapp

# Start local blockchain
yarn chain

# Deploy contracts (in new terminal)
yarn deploy

# Start frontend (in new terminal)
cd nextjs
yarn install
yarn dev

Your dApp will be running at http://localhost:3000!

📖 Documentation

For Users

• - How to use the MCP server
• - What works now

For Developers

• - How to contribute
• - For Claude Code instances
• - System design

Project Management

• - All 44 issues
• - Dependency analysis

📚 Project Overview

An MCP server that enables developers to rapidly scaffold, configure, and deploy decentralized applications using Scaffold-ETH 2, with optional Base Minikit integration for Farcaster Mini Apps.

Key Features

• 🎯 8 MCP Tools: Scaffold, configure, deploy, validate Web3 projects
• ⚡ 6 Templates: Basic, NFT, DeFi, DAO, Gaming, Social
• 🌊 Minikit Integration: Built-in Farcaster Mini App support
• 🚀 Base Network: Optimized for Base mainnet and testnet
• 💬 Natural Language: Create dApps through conversation with Claude Code

Target Users

• Hackathon participants needing rapid dApp setup
• Web3 developers building on Base + Farcaster
• Teams prototyping blockchain applications

🏗️ Implementation Status

Progress: 35/180 story points (19.4% complete)

✅ What Works Now

Core Infrastructure (Epic 1: 62.2% complete):

• ✅ MCP server with tool/resource registries
• ✅ Template engine with variable substitution
• ✅ File manager with backup and security
• ✅ Configuration validation (Zod schemas)
• ✅ Structured logging (Pino)
• ✅ 337 tests passing

Project Scaffolding:

• ✅ scaffold_project tool - FULLY FUNCTIONAL
• ✅ Basic Scaffold-ETH 2 template
• ✅ Network support (base, baseSepolia, localhost)
• ✅ Post-generation hooks (yarn install, git init)
• ✅ Input validation and error handling

🚧 In Progress / Planned

Templates (5 remaining):

• ⏳ NFT template (ERC-721 minting)
• ⏳ DeFi template (token swaps)
• ⏳ DAO template (governance)
• ⏳ Gaming template (on-chain gaming)
• ⏳ Social template (Farcaster integration)

Epic 2: Scaffold & Configuration (35% complete):

• ✅ scaffold_project tool
• ⏳ configure_contracts tool
• ⏳ Contract validation

Epic 3: Minikit Integration (0% complete):

• Farcaster Mini Apps support
• Base Minikit components
• Frame generation

Epic 4: Deployment Pipeline (0% complete):

• Network configuration
• Contract deployment automation
• Verification and validation

See for detailed progress.

🛠️ Available Tools

scaffold_project Tool

Status: ✅ Fully functional

Parameters:

• projectName (required): kebab-case project name (e.g., "my-dapp")
• projectPath (optional): Where to create project (default: current directory)
• template (optional): "basic" | "nft" | "defi" | "dao" | "gaming" | "social" (default: "basic")
• targetNetwork (optional): "base" | "baseSepolia" | "localhost" (default: "baseSepolia")
• contractFramework (optional): "hardhat" | "foundry" (default: "hardhat")
• includesMinikit (optional): Add Minikit support (default: false)

Example Usage:

Ask Claude: "Create a Scaffold-ETH 2 project called 'my-nft-marketplace'"

Claude will invoke the tool with appropriate parameters and generate a complete project.

📦 Project Templates

Basic Template (Available Now)

The basic template includes:

• Smart Contract: Simple YourContract.sol with Hardhat
• Frontend: Next.js app with wallet connection (RainbowKit)
• Deployment: Ready-to-deploy scripts
• Testing: Hardhat test infrastructure
• Configuration: Environment setup and network configs

🚀 Tech Stack

MCP Server:

• Bun v1.2.16+ (runtime)
• TypeScript 5.9.3 (strict mode)
• MCP SDK v1.21.0
• Pino (structured logging)
• Zod (schema validation)

Generated Projects:

• Scaffold-ETH 2 (base framework)
• Yarn (package manager, official SE2 standard)
• Hardhat (smart contracts)
• Next.js 14+ (frontend)
• RainbowKit (wallet connection)
• Wagmi (Web3 hooks)
• Base Network (mainnet + Sepolia)

Testing:

• Bun Test (unit/integration, 337 tests)
• Playwright (E2E, planned)

🤝 Contributing

We welcome contributions! See for detailed guidelines.

Development Setup

# Clone and setup
git clone https://github.com/yourusername/se2-minikit-mcp-server.git
cd se2-minikit-mcp-server
bun install

# Run tests
bun test

# Run tests in watch mode
bun test --watch

# Type check
bun run typecheck

# Lint
bun run lint

# Build
bun run build

Good First Issues

Looking to contribute? Check out:

• Issue #6: NFT Template (5 points) - Create ERC-721 template
• Issue #7: DeFi Template (5 points) - Create token swap template
• Issue #8: Advanced Templates (5 points) - DAO/Gaming/Social templates

Each template follows the same structure as the basic template, making them great for new contributors!

Project Structure

se2-minikit-mcp-server/
├── src/
│   ├── server/           # MCP server implementation
│   ├── tools/            # MCP tool handlers
│   ├── resources/        # Resource handlers
│   ├── engines/          # Template/deployment engines
│   ├── config/           # Configuration system
│   ├── types/            # TypeScript types
│   └── utils/            # Utilities
├── templates/            # Project templates
│   └── basic/           # Basic SE2 template
├── tests/
│   ├── unit/            # Unit tests
│   └── integration/     # Integration tests
├── docs/                # Documentation
└── claudedocs/          # Claude-specific docs

📈 Development Progress

Completed (35/180 points)

✅ Issues #1-5, #9-11: Core infrastructure and basic scaffolding

• MCP server skeleton with registries
• Template engine with variable substitution
• File manager with security
• Configuration validation
• Logging infrastructure
• Basic Scaffold-ETH 2 template
• scaffold_project tool (fully functional)

Next Steps

Short-term (2-3 weeks):

• Issue #6-8: Additional templates (NFT, DeFi, DAO, Gaming, Social)
• Issue #12: configure_contracts tool
• Issue #13: Contract validation

Medium-term (4-8 weeks):

• Epic 3: Minikit integration
• Epic 4: Deployment pipeline

See for complete roadmap.

📊 Success Metrics

Current Performance

• ✅ Project scaffold: < 10 seconds
• ✅ Test coverage: 100% (337/337 tests passing)
• ✅ Build time: < 1 second
• ✅ TypeScript: Strict mode, zero errors

Goals

• 1000+ projects created (3 months post-launch)
• 80% task success rate
• Average rating > 4.5/5

🔗 Resources

• Scaffold-ETH 2: https://docs.scaffoldeth.io/llms-full.txt
• Base Minikit: https://docs.base.org/mini-apps/llms-full.txt
• Farcaster Mini Apps: https://miniapps.farcaster.xyz/llms-full.txt
• OnchainKit: https://onchainkit.xyz/
• MCP Protocol: https://modelcontextprotocol.io/

🗺️ Roadmap

v0.1.0 - Alpha (Current)

• ✅ Core MCP server infrastructure
• ✅ Template engine with variable substitution
• ✅ Basic Scaffold-ETH 2 template
• ✅ scaffold_project tool (fully functional)
• ✅ 337 tests passing
• ✅ TypeScript strict mode

v0.2.0 - Beta (2-3 weeks)

• NFT template (ERC-721 minting)
• DeFi template (token swaps)
• DAO/Gaming/Social templates
• configure_contracts tool
• Contract validation

v1.0.0 - Initial Release (8-12 weeks)

• All 8 MCP tools implemented
• 6 project templates complete
• Minikit integration (Farcaster Mini Apps)
• Deployment pipeline
• Security audit

v1.1.0+ - Future

• Multi-chain support (Optimism, Arbitrum)
• Advanced contract templates
• Gas optimization tools
• Visual project builder

📄 License

[To be determined]

🙏 Acknowledgments

Built with:

• Scaffold-ETH 2
• Base Minikit
• OnchainKit
• Farcaster
• Model Context Protocol

📞 Support & Community

• Issues: GitHub Issues
• Troubleshooting:
• Documentation:
• Status:
• Contributing:

⚠️ Important Notes

Package Manager Separation

MCP Server uses Bun for development (faster, native TypeScript)

Generated Projects use Yarn (official Scaffold-ETH 2 standard)

This separation ensures:

• ✅ Fast MCP server development
• ✅ Generated projects follow official SE2 conventions
• ✅ Users can reference SE2 docs without confusion

Current Limitations

• Only "basic" template available (5 more templates planned)
• Only Hardhat support (Foundry planned)
• No Minikit integration yet (planned for v0.2.0)
• No automated deployment yet (planned for v1.0.0)

Ready to build?

1. Follow Quick Start to install the MCP server
2. Ask Claude to scaffold a project
3. Start building your dApp on Base!

For development, see 🚀