🎯 Enhanced Quake Coding Arena - MCP Server

DOMINATING! EXCELLENT! GODLIKE! UNSTOPPABLE! 🎯🔥

Premium TypeScript MCP Server for gamifying your development environment with authentic Quake 3 Arena sounds and dual voice announcers

🚀 Features

🎮 25 Epic Achievements

• Streak Achievements: RAMPAGE, DOMINATING, UNSTOPPABLE, GODLIKE (both voices)

• Quality Achievements: EXCELLENT, PERFECT, IMPRESSIVE (male voice)

• Multi-Kills: WICKED SICK, HEADSHOT, MULTI KILL, ULTRA KILL, MONSTER KILL, LUDICROUS KILL, KILLING SPREE, DOUBLE KILL, TRIPLE KILL (both voices)

• Game Events: FIRST BLOOD, HUMILIATION, HOLY SHIT, BOTTOM FEEDER (both voices)

• Team Events: PREPARE TO FIGHT, PLAY (both voices)

🎤 Dual Voice System

• Male Announcer: Complete voice pack with 17 unique sounds

• Female Announcer: Complete voice pack with 16 unique sounds

• Smart fallback to male voice for unavailable female sounds

• Volume control (0-100%)

• Cross-platform audio support

🔧 MCP Integration

• 10 MCP Tools for complete control

• JSON-RPC 2.0 compliant

• Session statistics tracking

• Dual transport support: HTTP (Smithery) and stdio (local clients)

• Claude Code compatible with automatic stdio detection

• Category filtering for achievements

• Random achievement selection

• AI usage guide integration

• Voice pack testing capabilities

📦 Installation Options

Option 1: Local Development Setup

# Run local setup script
./setup-local.sh

# Or manually
npm install
npm run build
node run-server.ts

Option 2: Remote (Smithery) Deployment

⚠️ Important: Smithery packages are NOT on npm - they use HTTP endpoints!

# Run remote setup script
./setup-remote.sh

# Or use Smithery HTTP endpoint directly
# Add to your MCP configuration:
{
  "mcpServers": {
    "quake-arena": {
      "transport": "http",
      "url": "https://server.smithery.ai/@Ripnrip/quake-coding-arena-mcp/mcp"
    }
  }
}

Note: For local development/testing, use the local build method (Option 1) instead of npx.

Option 3: GitHub Pages Website

Visit the live soundboard at: https://ripnrip.github.io/Quake-Coding-Arena-MCP/

The website includes:

• ✅ Interactive soundboard with all 25 achievements

• ✅ Dual voice system (Male/Female toggle)

• ✅ Category filtering

• ✅ Volume control

• ✅ GitHub Pages ready

🎯 Available MCP Tools

Core Achievement Tools

• play_enhanced_quake_sound - Trigger specific achievements

• random_enhanced_achievement - Random by category

• list_enhanced_achievements - Browse all achievements

Control & Settings

• set_enhanced_volume - Set volume (0-100)

• set_voice_pack - Switch male/female voices

• get_voice_pack_info - Voice information

Statistics & Guides

• get_enhanced_achievement_stats - Session statistics

• get_enhanced_achievement_guide - Achievement guide

• get_ai_usage_guide - Context-specific usage tips

• test_voice_packs - Test all voice packs

🎮 Usage Examples

// Trigger a GODLIKE achievement at 80% volume
await session.call("tools/call", {
  name: "play_enhanced_quake_sound",
  arguments: {
    achievement: "GODLIKE",
    volume: 80,
    voiceGender: "female"
  }
});

// Get a random quality achievement
await session.call("tools/call", {
  name: "random_enhanced_achievement",
  arguments: {
    category: "quality",
    volume: 70
  }
});

// Switch to female voice pack
await session.call("tools/call", {
  name: "set_voice_pack",
  arguments: {
    voiceGender: "female"
  }
});

🔧 Configuration

The server automatically detects sound files and supports:

• MP3 and WAV audio formats

• Custom sound directories

• Voice pack management

• Session persistence

📁 Project Structure

quake-coding-arena-enhanced/
├── index.js              # Main MCP server
├── package.json           # NPM configuration
├── smithery.yaml         # Smithery configuration
├── sounds/               # Audio files
│   ├── male/            # Male announcer sounds
│   └── female/          # Female announcer sounds
├── README.md            # This file
└── test-mcp-server.cjs   # Test utilities

🏆 Achievement Categories

🔥 Streak Achievements (Both Voices)

• RAMPAGE (10) - Multiple quick tasks

• DOMINATING (15) - Complex problems solved

• UNSTOPPABLE (20) - Long productive sessions

• GODLIKE (25) - Legendary coding sessions

✨ Quality Achievements (Male Voice)

• EXCELLENT - Elegant solutions

• PERFECT - Flawless implementation

• IMPRESSIVE - Creative problem-solving

⚔️ Multi-Kill Achievements (Both Voices)

• HEADSHOT - Precision coding

• DOUBLE KILL - Two quick wins

• MULTI KILL - Multiple bugs squashed

• KILLING SPREE - Consistent productivity

• TRIPLE KILL - Triple efficiency

• ULTRA KILL - Exceptional performance

• MONSTER KILL - Massive code refactoring

• LUDICROUS KILL - Unbelievable solutions

• WICKED SICK - Mind-blowing solutions

🎪 Game State Announcements (Both Voices)

• FIRST BLOOD - First bug found

• HUMILIATION - Quick bug fixes

• HOLY SHIT - Unexpected breakthrough

• BOTTOM FEEDER - Learning from mistakes

👥 Team Events (Both Voices)

• PREPARE TO FIGHT - Team motivation

• PLAY - Game on, let's code!

🎯 Perfect For

• Developers wanting gamified coding environments

• Teams needing motivational feedback

• Streamers wanting engaging content

• Educators teaching coding concepts

• Anyone loving Quake 3 Arena nostalgia!

📊 Requirements

• Node.js 18+ for MCP server

• MCP-compatible IDE (Cursor, Claude Desktop, etc.)

• Audio system for sound playback

🔗 Integration Examples

Claude Desktop

{
  "mcpServers": {
    "quake-arena": {
      "command": "npx",
      "args": ["@Ripnrip/quake-coding-arena-mcp"]
    }
  }
}

Cursor / Claude Code

• Local Build Method (Recommended):

  {
    "mcpServers": {
      "quake-coding-arena": {
        "command": "node",
        "args": ["/path/to/.smithery/index.cjs"]
      }
    }
  }

• HTTP Endpoint Method (When server is running):

  {
    "mcpServers": {
      "quake-coding-arena": {
        "transport": "http",
        "url": "http://localhost:6487/mcp"
      }
    }
  }

• See CLAUDE-CODE-SETUP.md and CURSOR-HTTP-SETUP.md for detailed instructions

Chat Widget + Sound Bridge

Clone-ready example that proxies ChatGPT responses and calls this MCP server to play Quake achievements. See examples/chat-widget for setup instructions (OpenAI key + MCP URL required).

📜 License

MIT License - Feel free to use and modify!

🎯 Get Started

1. Install: smithery install quake-coding-arena-enhanced

2. Configure: Add to your MCP client

3. Achieve: Start triggering those epic sounds!

🏆 READY TO DOMINATE THE CODING ARENA! 🎯🔥

Built with ❤️ and Quake 3 Arena nostalgia Published via Smithery - The MCP Server Registry

📝 Recent Updates

December 10, 2025 - JSON Parsing Fix & Transport Support

• 🔧 Fixed JSON parsing errors when using with Claude Code and other stdio-based MCP clients

• 📡 Added stdio transport support with automatic detection for local MCP clients

• 🚫 Fixed console.log interference by redirecting all logs to stderr (prevents JSON-RPC protocol issues)

• ✅ Tested and verified sound playback functionality with both HTTP and stdio transports

• 📚 Created comprehensive setup guides:

  • CLAUDE-CODE-SETUP.md - Complete Claude Code integration guide

  • CURSOR-HTTP-SETUP.md - Cursor IDE HTTP endpoint setup

  • CURSOR-SETUP-COMPLETE.md - Cursor MCP configuration guide

• 🔌 Dual transport support: Server now works with both HTTP (Smithery) and stdio (local clients)

• 🎯 Port conflict handling with automatic port selection and interactive prompts

December 10, 2025 - Female Audio Expansion Update

• 🎤 Added 16 female voice audio files to the sounds/female/ directory

• 🏆 Expanded to 25 total achievements with comprehensive multi-kill support

• 🔄 Updated voice pack configuration to properly point to female audio directory

• 📚 Enhanced documentation to reflect new female audio capabilities

• 🔧 Fixed TypeScript build issues and improved import resolution

• ✅ Full compatibility maintained with existing male voice functionality

New Female Audio Includes:

• Classic streak announcements (RAMPAGE, DOMINATING, UNSTOPPABLE, GODLIKE)

• Multi-kill sequences (HEADSHOT, MULTI KILL, KILLING SPREE, ULTRA KILL, MONSTER KILL, LUDICROUS KILL)

• Game state announcements (FIRST BLOOD, HUMILIATION, HOLY SHIT, BOTTOM FEEDER)

• Team motivation sounds (PLAY)

Technical Improvements:

• Smart fallback system to male voice for missing female audio

• Enhanced achievement categorization with 25 total achievements

• Updated MCP tool descriptions and documentation

• Verified cross-platform audio compatibility

Built with ❤️ and Quake 3 Arena nostalgia Published via Smithery - The MCP Server Registry

🌐 Smithery Cloud Deployment

When deployed via Smithery, the MCP server runs as a cloud service with HTTP endpoints. All audio files (including the 16 female voice files) are automatically included via the package.json "files" array.

📖 Detailed Guide: See SMITHERY-DEPLOYMENT.md for complete deployment documentation.

How Audio Works in Cloud Mode:

• ✅ All 25 achievements available with both male/female voices

• ✅ 16 female + 17 male audio files automatically bundled by Smithery

• ✅ Voice pack switching via set_voice_pack tool

• ✅ Volume control via set_enhanced_volume tool

• ✅ Complete sound library included in deployment (via package.json "files" array)

• ⚠️ Requires explicit tool invocation - Audio plays when MCP tools are called

• 🎯 Audio plays locally - Smithery triggers playback on user's machine via system commands

Cloud vs Local Differences:

• Local: Can trigger sounds automatically via file system events

• Cloud: Sounds only play when MCP tools are explicitly invoked by user/AI

• Both: Same achievement system, voice packs, and audio quality

• Both: All 16 female audio files available

Using Female Voice via Smithery:

// Switch to female voice pack
await session.call("tools/call", {
  name: "set_voice_pack",
  arguments: { voiceGender: "female" }
});

// Play female achievement
await session.call("tools/call", {
  name: "play_enhanced_quake_sound", 
  arguments: {
    achievement: "HEADSHOT",
    volume: 85
  }
});