Frog Build MCP

MCP (Model Context Protocol) server for building FrogJS games with Claude Desktop.

Version: 1.1.0
References: [email protected]

Features

• 🎯 Complete FrogJS guidelines with embedded TypeScript definitions
• 🔄 Auto-syncs TypeScript defs from frogjs library on build
• 🛡️ Input validation for all tools
• 📦 No external fetching required - all docs embedded
• 🌐 Connects to frog-build-web API
• 🎨 Game portals with 10x10 banners
• 📱 Mobile-first HTML templates
• 🎮 9 comprehensive tools

Quick Start (One Command!)

npx frog-build-mcp --config-claude

This will:

1. Install frog-build-mcp (if not already installed)
2. Automatically configure Claude Desktop
3. Set up connection to production API

Then restart Claude Desktop and start building games!

Installation

For Claude Desktop users:

# Auto-configure (recommended)
npx frog-build-mcp --config-claude

For developers:

git clone <repository>
cd frog-build-mcp
npm install
npm run build

Build Process

The build automatically:

1. Syncs TypeScript definitions from ../frogjs/dist/frog.d.ts
2. Embeds them in src/guidelines.ts
3. Compiles TypeScript to dist/

npm run build
# → Syncs from frogjs
# → Compiles to dist/

Claude Desktop Configuration

Automatic (Recommended)

npx frog-build-mcp --config-claude

This automatically:

• Finds your Claude Desktop config file
• Adds frog-build-mcp configuration
• Uses production API (https://frogbuild.matandile.games/api)
• No manual setup needed!

Manual (Alternative)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "frog-build": {
      "command": "npx",
      "args": ["-y", "frog-build-mcp"]
    }
  }
}

Note:

• Uses npx for automatic installation
• Connects to production API by default
• For local API: Set FROG_BUILD_API_URL environment variable

Available Tools (9 Total)

Guidelines

1. get_frogjs_guidelines - Complete guidelines with embedded TypeScript API

Portals

2. create_portal - Create game collection page with title and game list
3. update_portal - Update portal title, description, or game list
4. list_portals - List all game portals

Games

5. create_game - Create game with required 10x10 banner
6. update_game - Update game name, description, banner, or HTML
7. get_game_info - Get game metadata without HTML content
8. get_game_full - Get complete game data including HTML
9. list_games - List all games with banners (shows visually to user)

Usage

Prerequisites

Option A: Use Production API (Recommended)

1. Run npx frog-build-mcp --config-claude
2. Restart Claude Desktop
3. Start building games!

No local server needed - uses hosted API at https://frogbuild.matandile.games

Option B: Local Development

1. Start the web server:

   cd ../frog-build-web
   npm start

2. Configure with local API URL
3. Restart Claude Desktop

Creating Games

You: Create a snake game

Claude: [Reads embedded guidelines with TypeScript API]
        [Generates mobile-first HTML with meta tags]
        [Creates 10x10 emoji banner]
        [Calls create_game]
        
        Game ID: snake-game-cosmic-42
        Banner: [10x10 emoji grid displayed]
        URL: http://localhost:3000/game/snake-game-cosmic-42

Creating Portals

You: Create a portal called "Retro Arcade"

Claude: [Creates portal]
        Portal ID: retro-arcade-portal-42
        URL: http://localhost:3000/portal/retro-arcade-portal-42

You: Add these games to the portal: [list of game IDs]

Claude: [Updates portal with game list]
        Portal now has 5 games

Critical Rules Enforced

The MCP server ensures Claude follows these rules:

1. INTEGER coordinates only - No fractional positions
2. Single character sprites - One emoji/char per sprite
3. Check grid boundaries - Validate positions
4. Control movement speed - Use timers, not every frame
5. Use default theme - Unless user requests specific
6. Only supported input - Arrow keys + Space only
7. FrogJS methods only - No canvas bypass
8. Emojis/characters only - No images
9. Grid thinking - Cells not pixels
10. Simple and fun - Embrace constraints
11. Mobile-first HTML - Required meta tags and CSS

Game Requirements

Every game must include:

• ✅ Required 10x10 character banner
• ✅ Mobile-first HTML with iOS meta tags
• ✅ Viewport meta tag
• ✅ Mobile CSS reset
• ✅ Theme selection (or default)
• ✅ usedControls specification

Project Structure

src/
├── index.ts         # Entry point (63 lines)
├── config.ts        # Configuration (7 lines)
├── api-client.ts    # HTTP client (40 lines)
├── guidelines.ts    # Auto-generated with TypeScript defs
├── tools.ts         # Tool definitions (186 lines)
└── handlers.ts      # Tool handlers with validation (277 lines)

scripts/
└── sync-from-frogjs.js  # Auto-syncs TypeScript defs

Keeping in Sync

Manual Sync

# 1. Build frogjs
cd ../frogjs
npm run build

# 2. Build MCP (auto-syncs)
cd ../frog-build-mcp
npm run build

# 3. Restart Claude Desktop

Automated Sync

Use the root-level version update script:

# From root directory
node update-frogjs-version.js 1.0.0-alpha.13
# → Updates frogjs version
# → Builds frogjs
# → Syncs and builds MCP
# → Syncs and builds web server

Environment Variables

• FROG_BUILD_API_URL - API endpoint (optional)
  • Default: https://frogbuild.matandile.games/api (production)
  • Local dev: http://localhost:3000/api

Example for local development:

{
  "mcpServers": {
    "frog-build": {
      "command": "npx",
      "args": ["-y", "frog-build-mcp"],
      "env": {
        "FROG_BUILD_API_URL": "http://localhost:3000/api"
      }
    }
  }
}

FrogJS Features Referenced

Current version (alpha.12) includes:

• Theme system (10 curated themes)
• Mobile controls (responsive, iOS-safe)
• Auto fullscreen on mobile
• Single character validation
• Integer coordinate enforcement

Development

# Build
npm run build

# The build will:
# - Sync TypeScript defs from frogjs
# - Update guidelines with current API
# - Compile to dist/

Troubleshooting

Tools not showing in Claude:

• Verify absolute path in config
• Check dist/index.js exists
• Restart Claude Desktop completely

Connection errors:

• Ensure web server is running
• Check FROG_BUILD_API_URL is correct
• Test: curl http://localhost:3000/health

Outdated API:

• Run npm run build to sync from frogjs
• Restart Claude Desktop

Related Projects

• frogjs - Game framework library
• frog-build-web - Web server and game hosting
• update-frogjs-version.js - Root-level version sync script

License

MIT

Ready to build awesome FrogJS games! 🐸🎮