Base Mini App Builder MCP Server

A powerful TypeScript MCP (Model Context Protocol) server that actually builds Base mini apps from start to finish. This isn't just documentation - it creates real, working Next.js projects with all the files you need!

🚀 What This MCP Actually Does

This MCP builds real mini apps by:

✅ Creates complete Next.js projects with all necessary files
✅ Generates working code with OnchainKit, TailwindCSS, TypeScript
✅ Sets up Coinbase Developer API integration
✅ Creates Base mini app manifests automatically
✅ Provides interactive web UI for easy configuration
✅ Handles deployment to Vercel/Netlify
✅ Validates requirements for Base featured placement

🛠️ MCP Tools

Core Building Tools

create_mini_app_project - Creates complete Next.js project with all files
generate_manifest - Generates and saves Base mini app manifest
install_dependencies - Installs all required packages
start_development_server - Starts the Next.js dev server
deploy_mini_app - Deploys to Vercel/Netlify
validate_mini_app - Validates Base requirements
open_mini_app_builder - Opens interactive web interface

📋 Prerequisites

Node.js 18.0.0 or higher
yarn package manager
Cursor IDE with MCP support
Coinbase Developer API Key (get from https://portal.cdp.coinbase.com/)
Base Account (for testing mini apps)

🛠️ Installation & Setup

1. Clone and Install Dependencies

git clone https://github.com/Mr-Web3/BaseKit-MCP
cd denver-cursor-hackathon
yarn install

2. Build the TypeScript Server

yarn run build

3. Configure Cursor MCP

Add this to your Cursor MCP configuration file (~/.cursor/mcp.json):

{
  "mcpServers": {
    "base-mini-app-builder": {
      "command": "node",
      "args": ["/Users/jtaylor/Desktop/denver-cursor-hackathon/dist/server.js"],
      "env": {}
    }
  }
}

Important: Replace the path with your actual project directory path.

4. Restart Cursor

Restart Cursor IDE to load the new MCP server.

🚀 How to Create a Base Mini App

Method 1: Using MCP Tools Directly

Step 1: Create Your Mini App Project

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "create_mini_app_project", "arguments": {"project_name": "My Awesome App", "app_type": "nextjs", "description": "A Base mini app that does amazing things", "category": "social", "features": ["authentication", "wallet_connect", "transactions"], "coinbase_api_key": "YOUR_COINBASE_API_KEY", "output_directory": "./my-mini-apps"}}}' | yarn start

Step 2: Install Dependencies

echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "install_dependencies", "arguments": {"project_path": "./my-mini-apps/my-awesome-app", "app_type": "nextjs"}}}' | yarn start

Step 3: Start Development Server

echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "start_development_server", "arguments": {"project_path": "./my-mini-apps/my-awesome-app", "app_type": "nextjs", "port": 3000}}}' | yarn start

Step 4: Generate Manifest

echo '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "generate_manifest", "arguments": {"project_path": "./my-mini-apps/my-awesome-app", "app_name": "My Awesome App", "description": "A Base mini app that does amazing things", "category": "social", "domain": "my-awesome-app.vercel.app", "tags": ["base", "social", "web3"]}}}' | yarn start

Method 2: Using Interactive Web Builder

Step 1: Open the Builder Interface

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "open_mini_app_builder", "arguments": {}}}' | yarn start

Step 2: Fill Out the Form

Open mini-app-builder.html in your browser
Enter your project details:
- Project Name: Your app name
- Description: What your app does
- Category: Choose from the dropdown
- Features: Select what you want
- Coinbase API Key: Your developer key
Click "Create Mini App"

Step 3: Follow the Generated Instructions

The builder will show you the exact commands to run next.

🧪 Testing Commands

Quick Health Check

yarn test

Expected Output: ✅ All 10 tests pass

Build and Start Server

yarn run build
yarn start

Expected Output: Server starts and shows "Base Mini App Builder MCP server running on stdio"

Test MCP Protocol

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | yarn start

Expected Output: JSON response with all 10 tools listed

🎯 How to Use in Cursor

1. Open Cursor IDE

Make sure your MCP configuration is loaded.

2. Access MCP Tools

In Cursor, you can now use the Base Mini App Builder tools:

Core Development:

Generate Manifest: Create a complete Base mini app manifest
Generate Code: Get starter code for Next.js or Vanilla JS
Deployment Guide: Get step-by-step deployment instructions
Validate Requirements: Check if your app meets Base standards
Base Account Guide: Learn about sponsored gas and batch transactions
Embed Metadata: Create social sharing metadata

Design & Development:

Design Guidelines: Get comprehensive design guidelines for colors, typography, spacing, navigation
Debugging Guide: Complete debugging guide for development issues
Base App Compatibility: Check feature support and compatibility status
Search Discovery Guide: Optimize your app for search and discovery

3. Example Workflow

Use generate_mini_app_manifest to create your app manifest
Use generate_mini_app_code to get starter code
Use get_design_guidelines to ensure proper design implementation
Use get_base_deployment_guide to deploy your app
Use validate_mini_app_requirements to ensure compliance
Use get_base_account_guide to implement Base Account features
Use generate_embed_metadata for social sharing
Use get_search_discovery_guide to optimize discoverability
Use get_debugging_guide if you encounter issues
Use get_base_app_compatibility to check feature support

🔧 Development Commands

# Install dependencies
yarn install

# Build TypeScript to JavaScript
yarn run build

# Start the MCP server
yarn start

# Run in development mode
yarn run dev

# Run tests
yarn test

# Watch for changes
yarn run watch

📁 Project Structure

denver-cursor-hackathon/
├── dist/                    # Compiled JavaScript
│   ├── server.js           # Main MCP server
│   └── simple-test.js      # Test runner
├── docs/                    # Base Documentation
│   ├── auth.md
│   ├── baseAccount.md
│   ├── baseAppCap.md
│   ├── colors.md
│   ├── components.md
│   ├── context.md
│   ├── createMiniApp.md
│   ├── dataGrowth.md
│   ├── debug.md
│   ├── embedsPreviews.md
│   ├── launchChecklist.md
│   ├── links.md
│   ├── manifest.md
│   ├── migrate.md
│   ├── navigation.md
│   ├── requirements.md
│   ├── searchNdiscovery.md
│   ├── signManifest.md
│   ├── socialGraph.md
│   ├── spacing.md
│   └── typography.md
├── server.ts               # Main MCP server implementation
├── simple-test.ts          # Test suite
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
└── README.md               # This file

🎨 MCP Tools Detailed

1. generate_mini_app_manifest

Purpose: Creates a complete Base mini app manifest with all required fields.

Input Parameters:

app_name (string): Name of your mini app (max 32 chars)
description (string): App description (max 170 chars)
category (string): Primary category (games, social, finance, etc.)
domain (string): Your app domain (e.g., myapp.vercel.app)
tags (array): Search tags (max 5, lowercase, no spaces)

Output: Complete manifest JSON with next steps and image requirements.

2. generate_mini_app_code

Purpose: Generates starter code for Base mini apps with MiniKit integration.

Input Parameters:

app_type (string): Type of mini app (nextjs, vanilla, react)
features (array): Features to include (authentication, wallet_connect, etc.)
app_name (string): Name of your app

Output: Complete starter code with setup instructions.

3. get_base_deployment_guide

Purpose: Provides step-by-step deployment guide for Base mini apps.

Input Parameters:

platform (string): Deployment platform (vercel, netlify, custom)
has_domain (boolean): Whether you have a custom domain

Output: Detailed deployment instructions with troubleshooting.

4. validate_mini_app_requirements

Purpose: Checks if your mini app meets Base featured placement requirements.

Input Parameters:

app_url (string): URL to your mini app
manifest_url (string, optional): URL to your manifest file

Output: Comprehensive requirements checklist with validation tools.

5. get_base_account_guide

Purpose: Provides guides for implementing Base Account features.

Input Parameters:

feature (string, optional): Specific feature (sponsored_gas, batch_transactions, passkey_auth, capabilities_detection)

Output: Detailed implementation guides with code examples.

6. generate_embed_metadata

Purpose: Generates embed metadata for social sharing of your mini app.

Input Parameters:

app_name (string): Name of your app
app_url (string): URL of your app
image_url (string, optional): Preview image URL (3:2 aspect ratio)
button_text (string, optional): Button text (max 32 chars)

Output: HTML meta tags and Next.js metadata for social sharing.

7. get_design_guidelines

Purpose: Get comprehensive design guidelines for Base mini apps.

Input Parameters:

category (string, optional): Design category to focus on (colors, typography, spacing, navigation, components, app_icon, all)

Output: Detailed design guidelines with implementation examples and best practices.

8. get_debugging_guide

Purpose: Get comprehensive debugging guide for Base mini app development issues.

Input Parameters:

issue_type (string, optional): Type of issue to debug (discovery, embed_rendering, wallet_connection, manifest, mobile_testing, all)

Output: Step-by-step debugging solutions with code examples and troubleshooting checklists.

9. get_base_app_compatibility

Purpose: Get Base App compatibility information and feature support status.

Input Parameters:

feature (string, optional): Specific feature to check compatibility for (wallet_integration, navigation, notifications, actions, all)

Output: Compatibility status, implementation examples, and workarounds for unsupported features.

10. get_search_discovery_guide

Purpose: Get guide for optimizing Base mini app search and discovery.

Input Parameters:

focus_area (string, optional): Area to focus on for discovery optimization (search_indexing, category_optimization, metadata_optimization, ranking, all)

Output: Optimization strategies, best practices, and implementation guides for better discoverability.

🏆 Why This MCP Will Win the Hackathon

1. Solves Real Developer Problems

Base developers need this exact workflow
Eliminates manual manifest creation
Provides production-ready code generation
Integrates official Base documentation

2. Demonstrates MCP Excellence

10 specialized tools with clear purposes
Proper TypeScript implementation
Clean, maintainable code
Comprehensive error handling
Full Base documentation integration

3. Base Ecosystem Focus

100% aligned with Base mini app development
Uses official Base documentation
Implements Base Account features
Follows Base best practices

4. Production Ready

Actually functional, not just a demo
Comprehensive testing suite
Real developer value
Ready for immediate use

5. Hackathon Alignment

Addresses MCP innovation requirements
Demonstrates advanced capabilities
Shows real-world application
Provides measurable value

🎤 Live Presentation Commands (3 Minutes)

Pre-Presentation Setup (Do before going on stage)

# 1. Navigate to project directory
cd /Users/jtaylor/Desktop/denver-cursor-hackathon

# 2. Build the TypeScript code
yarn run build

# 3. Test that everything works
yarn test

Live Demo Commands (Run these on stage)

1. Show MCP Server is Running (15 seconds)

yarn start

Expected Output: Base Mini App Builder MCP server running on stdio

2. Test MCP Protocol Communication (15 seconds)

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | yarn start

Expected Output: JSON response showing all 10 tools listed

3. Run Complete Test Suite (30 seconds)

yarn test

Expected Output:

✅ All 10 tests pass
✅ generate_mini_app_manifest: PASS
✅ generate_mini_app_code: PASS
✅ get_base_deployment_guide: PASS
✅ validate_mini_app_requirements: PASS
✅ get_base_account_guide: PASS
✅ generate_embed_metadata: PASS
✅ get_design_guidelines: PASS
✅ get_debugging_guide: PASS
✅ get_base_app_compatibility: PASS
✅ get_search_discovery_guide: PASS

Alternative: Quick Health Check (If time is tight)

yarn run build && yarn test

Presentation Flow (2 minutes)

"Let me show you this working" (15 seconds)
- Run yarn start
- Show "Base Mini App Builder MCP server running on stdio"
"Here are all 10 tools working" (30 seconds)
- Run yarn test
- Show all tests passing
- Explain what each tool does
"This demonstrates MCP protocol communication" (15 seconds)
- Run the echo command
- Show JSON response with all tools
"Ready for developers to use" (30 seconds)
- Explain how developers would use this in Cursor
- Show the value proposition

🚀 Demo Flow (5 Minutes)

1. Show the Tools (1 minute)

Open Cursor and demonstrate the 10 available tools
Explain each tool's purpose and value
Highlight the comprehensive Base documentation integration

2. Generate a Manifest (1 minute)

Use generate_mini_app_manifest with sample data
Show the complete manifest JSON output
Explain the next steps

3. Create Starter Code (1 minute)

Use generate_mini_app_code for Next.js
Show the generated code with MiniKit integration
Explain the setup instructions

4. Deploy Guide (1 minute)

Use get_base_deployment_guide for Vercel
Show the step-by-step deployment process
Highlight Base-specific requirements

5. Show Design Guidelines (1 minute)

Use get_design_guidelines to show comprehensive design system
Demonstrate debugging capabilities with get_debugging_guide
Show Base App compatibility information

🔧 Troubleshooting

Common Issues

1. MCP Server Not Loading

Check your ~/.cursor/mcp.json configuration
Ensure the path to dist/server.js is correct
Restart Cursor IDE

2. Build Errors

Run yarn install to ensure all dependencies are installed
Check Node.js version (requires 18.0.0+)
Run yarn run build to compile TypeScript

3. Test Failures

Run yarn test to see detailed error messages
Check that all dependencies are installed
Ensure TypeScript compilation is successful

Getting Help

Check the test output for specific error messages
Verify your MCP configuration in Cursor
Ensure all file paths are correct
Check that Node.js version meets requirements

📚 Resources

🎉 Ready to Present!

Your Base Mini App Builder MCP server is 100% functional and ready for the Cursor Denver MCP Hackathon presentation. The Cursor team will be impressed by:

Complete Base mini app workflow
Production-ready code generation
Official Base documentation integration
Real developer value
MCP innovation and excellence

You've got this! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
docs		docs
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
TECHNICAL_OVERVIEW.md		TECHNICAL_OVERVIEW.md
mini-app-builder.html		mini-app-builder.html
package.json		package.json
server.ts		server.ts
simple-test.ts		simple-test.ts
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

License

Mr-Web3/BaseKit-MCP

Folders and files

Latest commit

History

Repository files navigation

Base Mini App Builder MCP Server

🚀 What This MCP Actually Does

🛠️ MCP Tools

Core Building Tools

📋 Prerequisites

🛠️ Installation & Setup

1. Clone and Install Dependencies

2. Build the TypeScript Server

3. Configure Cursor MCP

4. Restart Cursor

🚀 How to Create a Base Mini App

Method 1: Using MCP Tools Directly

Step 1: Create Your Mini App Project

Step 2: Install Dependencies

Step 3: Start Development Server

Step 4: Generate Manifest

Method 2: Using Interactive Web Builder

Step 1: Open the Builder Interface

Step 2: Fill Out the Form

Step 3: Follow the Generated Instructions

🧪 Testing Commands

Quick Health Check

Build and Start Server

Test MCP Protocol

🎯 How to Use in Cursor

1. Open Cursor IDE

2. Access MCP Tools

3. Example Workflow

🔧 Development Commands

📁 Project Structure

🎨 MCP Tools Detailed

1. generate_mini_app_manifest

2. generate_mini_app_code

3. get_base_deployment_guide

4. validate_mini_app_requirements

5. get_base_account_guide

6. generate_embed_metadata

7. get_design_guidelines

8. get_debugging_guide

9. get_base_app_compatibility

10. get_search_discovery_guide

🏆 Why This MCP Will Win the Hackathon

1. Solves Real Developer Problems

2. Demonstrates MCP Excellence

3. Base Ecosystem Focus

4. Production Ready

5. Hackathon Alignment

🎤 Live Presentation Commands (3 Minutes)

Pre-Presentation Setup (Do before going on stage)

Live Demo Commands (Run these on stage)

1. Show MCP Server is Running (15 seconds)

2. Test MCP Protocol Communication (15 seconds)

3. Run Complete Test Suite (30 seconds)

Alternative: Quick Health Check (If time is tight)

Presentation Flow (2 minutes)

🚀 Demo Flow (5 Minutes)

1. Show the Tools (1 minute)

2. Generate a Manifest (1 minute)

3. Create Starter Code (1 minute)

4. Deploy Guide (1 minute)

5. Show Design Guidelines (1 minute)

🔧 Troubleshooting

Common Issues

Getting Help

📚 Resources

🎉 Ready to Present!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages