GitHub Stats

    Stars

    0

    Forks

    5

    Release Date

    4/8/2025

    about 2 months ago

    Detailed Description

    MCP Server for Agent8

    A server implementing the Model Context Protocol (MCP) to support Agent8 SDK development. Developed with TypeScript and pnpm, supporting stdio, SSE, and streamable-http transports.

    Features

    This Agent8 MCP Server implements the following MCP specification capabilities:

    Prompts

    • System Prompt for Agent8 SDK: Provides optimized guidelines for Agent8 SDK development through the system-prompt-for-agent8-sdk prompt template.

    Tools

    • Code Examples Search: Retrieves relevant Agent8 game development code examples from a vector database using the search_code_examples tool.
    • Game Resource Search: Searches for game development assets (sprites, animations, sounds, etc.) using semantic similarity matching via the search_game_resources tool.
    • Asset Generation: Comprehensive toolset for game asset creation:
      • Images: Generate 2D game assets using the image_asset_generate tool
      • Cinematics: Create cinematic sequences with cinematic_asset_generate tool
      • Audio: Generate music tracks and sound effects with music_generate and sfx_generate tools
      • Skyboxes: Create 360° environmental backgrounds with skybox_generate tool
      • Support Tools: Status checking, result retrieval, and wait utilities for asynchronous generation

    Installation

    # Install dependencies
    pnpm install
    
    # Build
    pnpm build
    

    Using Docker

    You can run this application using Docker in several ways:

    Option 1: Pull from GitHub Container Registry (Recommended)

    # Pull the latest image
    docker pull ghcr.io/planetarium/mcp-agent8:latest
    
    # Run the container
    docker run -p 3333:3333 --env-file .env ghcr.io/planetarium/mcp-agent8:latest
    

    Option 2: Build Locally

    # Build the Docker image
    docker build -t agent8-mcp-server .
    
    # Run the container with environment variables
    docker run -p 3333:3333 --env-file .env agent8-mcp-server
    

    Docker Environment Configuration

    There are three ways to configure environment variables when running with Docker:

    1. Using --env-file (Recommended):

      # Create and configure your .env file first
      cp .env.example .env
      nano .env
      
      # Run with .env file
      docker run -p 3000:3000 --env-file .env agent8-mcp-server
      
    2. Using individual -e flags:

      docker run -p 3000:3000 \
        -e SUPABASE_URL=your_supabase_url \
        -e SUPABASE_SERVICE_ROLE_KEY=your_service_role_key \
        -e OPENAI_API_KEY=your_openai_api_key \
        -e MCP_TRANSPORTS=sse,streamable-http \
        -e PORT=3000 \
        -e LOG_LEVEL=info \
        agent8-mcp-server
      
    3. Using Docker Compose (for development/production setup):

      The project includes a pre-configured docker-compose.yml file with:

      • Automatic port mapping from .env configuration
      • Environment variables loading
      • Volume mounting for data persistence
      • Container auto-restart policy
      • Health check configuration

      To run the server:

      docker compose up
      

      To run in detached mode:

      docker compose up -d
      

    Required Environment Variables:

    • SUPABASE_URL: Supabase URL for database connection
    • SUPABASE_SERVICE_ROLE_KEY: Supabase service role key for authentication
    • OPENAI_API_KEY: OpenAI API key for AI functionality

    The Dockerfile uses a multi-stage build process to create a minimal production image:

    • Uses Node.js 20 Alpine as the base image for smaller size
    • Separates build and runtime dependencies
    • Only includes necessary files in the final image
    • Exposes port 3000 by default

    Usage

    Command Line Options

    # View help
    pnpm start --help
    
    # View version information
    pnpm start --version
    

    Supported options:

    • --debug: Enable debug mode
    • --transports <types>: Transport methods (comma-separated: stdio,sse,streamable-http), default: stdio
    • --port <number>: Port to use for HTTP-based transports (sse, streamable-http), default: 3000
    • --log-destination <dest>: Log destination (stdout, stderr, file, none)
    • --log-file <path>: Path to log file (when log-destination is file)
    • --log-level <level>: Log level (debug, info, warn, error), default: info
    • --env-file <path>: Path to .env file

    Using Environment Variables

    The server supports configuration via environment variables, which can be set directly or via a .env file.

    1. Create a .env file in the project root (see .env.example for reference):
    # Copy the example file
    cp .env.example .env
    
    # Edit the .env file with your settings
    nano .env
    
    1. Run the server (it will automatically load the .env file):
    pnpm start
    
    1. Or specify a custom path to the .env file:
    pnpm start --env-file=/path/to/custom/.env
    

    Configuration Priority

    The server uses the following priority order when determining configuration values:

    1. Command line arguments (highest priority)
    2. Environment variables (from .env file or system environment)
    3. Default values (lowest priority)

    This allows you to set baseline configuration in your .env file while overriding specific settings via command line arguments when needed.

    Supported Environment Variables

    | Variable | Description | Default | | --------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------- | | MCP_TRANSPORTS | Transport methods (comma-separated: stdio,sse,streamable-http) | stdio | | PORT | Port to use for HTTP-based transports (sse, streamable-http) | 3000 | | LOG_LEVEL | Log level (debug, info, warn, error) | info | | LOG_DESTINATION | Log destination (stdout, stderr, file, none) | stderr (for stdio transport), stdout (for http transports) | | LOG_FILE | Path to log file (when LOG_DESTINATION is file) | (none) | | DEBUG | Enable debug mode (true/false) | false | | V8_AUTH_API_ENDPOINT | Authentication API endpoint URL | (none) | | V8_AUTH_REQUIRE | Require authentication for API endpoints | false | | SUPABASE_URL | Supabase URL for database connection | (required) | | SUPABASE_SERVICE_ROLE_KEY | Supabase service role key for authentication | (required) | | OPENAI_API_KEY | OpenAI API key for AI functionality | (required) | | FAL_KEY | fal.ai API key for asset generation | (required) | | BLOCKADE_LABS_API_KEY | Blockade Labs API key for skybox generation | (required for skybox generation) | | V8_CREDIT_CLIENT_ID | Client ID for credit consumption API | (none, optional for asset generation) | | V8_CREDIT_CLIENT_SECRET | Client secret for credit consumption API | (none, optional for asset generation) | | V8_CREDIT_API_ENDPOINT | API endpoint for credit consumption | (required for asset generation) | | ENABLE_ALL_TOOLS | Enable or disable all tools globally | true | | ENABLE_VECTOR_SEARCH_TOOLS | Enable or disable all vector search tools | true | | ENABLE_ASSET_GENERATE_TOOLS | Enable or disable all asset generation tools (images, cinematics, audio, skyboxes) | true | | ENABLE_IMAGE_GENERATION_TOOLS | Enable or disable image generation tools | true | | ENABLE_CINEMATIC_GENERATION_TOOLS | Enable or disable cinematic generation tools | true | | ENABLE_AUDIO_GENERATION_TOOLS | Enable or disable audio generation tools | true | | ENABLE_SKYBOX_GENERATION_TOOLS | Enable or disable skybox generation tools | true | | ENABLE_CODE_EXAMPLE_SEARCH_TOOL | Enable or disable code example search tool | true | | ENABLE_GAME_RESOURCE_SEARCH_TOOL | Enable or disable game resource search tool | true | | ENABLE_UI_THEME_TOOLS | Enable or disable UI theme tool | true |

    Tool Activation Priority: The tool activation settings follow this priority order:

    1. Individual tool settings (e.g., ENABLE_CODE_EXAMPLE_SEARCH_TOOL)
    2. Asset type settings (e.g., ENABLE_IMAGE_GENERATION_TOOLS, ENABLE_CINEMATIC_GENERATION_TOOLS)
    3. Tool group settings (e.g., ENABLE_VECTOR_SEARCH_TOOLS, ENABLE_ASSET_GENERATE_TOOLS)
    4. Global tool setting (ENABLE_ALL_TOOLS)

    Individual settings always override group settings, and group settings override the global setting. When individual settings are explicitly set, they take precedence over their parent settings.

    Important: To enable only specific tools, you should set all higher-level settings to false and only enable the specific tools you need. This approach provides a more consistent and predictable configuration.

    Examples:

    # Enable only vector search tools
    ENABLE_ALL_TOOLS=false
    ENABLE_VECTOR_SEARCH_TOOLS=true
    
    # Enable only image generation tool, disable all others
    ENABLE_ALL_TOOLS=false
    ENABLE_ASSET_GENERATE_TOOLS=false
    ENABLE_IMAGE_GENERATION_TOOLS=true
    
    # Enable only code example search tool, disable all others
    ENABLE_ALL_TOOLS=false
    ENABLE_VECTOR_SEARCH_TOOLS=false
    ENABLE_CODE_EXAMPLE_SEARCH_TOOL=true
    
    # Enable only cinematic and audio generation tools
    ENABLE_ALL_TOOLS=false
    ENABLE_ASSET_GENERATE_TOOLS=false
    ENABLE_CINEMATIC_GENERATION_TOOLS=true
    ENABLE_AUDIO_GENERATION_TOOLS=true
    

    Using Single Transport

    # Build and run with stdio transport
    pnpm build
    pnpm start --transports=stdio
    
    # Build and run with SSE transport (default port: 3000)
    pnpm build
    pnpm start --transports=sse --port=3000
    
    # Build and run with streamable-http transport (default port: 3000)
    pnpm build
    pnpm start --transports=streamable-http --port=3000
    

    Using Multiple Transports

    # Build and run with both SSE and streamable-http transports on the same port
    pnpm build
    pnpm start --transports=sse,streamable-http --port=3000
    
    # Build and run with all transports (stdio + http-based transports)
    pnpm build
    pnpm start --transports=stdio,sse,streamable-http --port=3000
    

    Using Environment Variables for Multiple Transports

    # Set environment variables
    export MCP_TRANSPORTS=sse,streamable-http
    export PORT=3000
    
    # Run the server
    pnpm start
    

    Debug Mode

    # Run in debug mode
    pnpm start --debug
    

    Available Prompts

    • systemprompt-agent8-sdk

    Client Integration

    Using with Claude Desktop

    1. Add the following to Claude Desktop configuration file (claude_desktop_config.json):
    {
      "mcpServers": {
        "Agent8": {
          "command": "npx",
          "args": ["--yes", "agent8-mcp-server"]
        }
      }
    }
    
    1. Restart Claude Desktop

    Adding New Prompts

    Add new prompts to the registerSamplePrompts method in the src/prompts/provider.ts file.

    License

    MIT

    About the Project

    This app has not been claimed by its owner yet.

    Claim Ownership

    Receive Updates

    Security Updates

    Get notified about trust rating changes

    to receive email notifications.