Pimp My Ride MCP Server

# 🏎️ Pimp My Ride MCP Server A Model Context Protocol (MCP) server for car customization and racing. Build and customize your dream ride with natural language through ChatGPT or Claude! <div align="center"> <img src="https://commons.wikimedia.org/wiki/Special:FilePath/Gumball_3000_-_2007_(483318373).jpg" alt="Xzibit at Gumball 3000 - 2007" width="400"> <p><em>Photo: <a href="https://creativecommons.org/licenses/by-sa/2.0/">CC BY-SA 2.0</a>, via Wikimedia Commons</em></p> </div> > **Note:** This project is an homage to the MTV show _Pimp My Ride_ hosted by Xzibit. Not affiliated with or endorsed by MTV. ## Features - 🎨 **Car Customization** - Colors, wheels, body kits, spoilers, exhausts, decals, and underglow - 🏎️ **Driver Profiles** - Choose your racing persona (RoadRage, SpeedDemon, CoolCalmCollected, etc.) - 💾 **Build Management** - Save, load, and manage multiple car builds - 📊 **Performance Scoring** - Get calculated performance scores for your builds - 🔒 **Pomerium Authentication** - Secure identity-aware access with Pomerium proxy - 🗄️ **Pluggable Storage** - SQLite by default, extensible to Redis, PostgreSQL, DynamoDB ## Security ⚠️ **This MCP server has no built-in authentication or authorization.** It reads identity from HTTP headers and trusts them implicitly. For production deployments, **secure this server behind [Pomerium](https://www.pomerium.com/)**, an AI gateway that provides: - 🔐 **Centralized Authentication** - OAuth/OIDC integration with your identity provider - 🛡️ **Fine-grained Authorization** - Policy-based access control at the tool and method level - 🔑 **Automatic Token Management** - Handles OAuth token refresh transparently - 📊 **Observability** - Detailed logs of AI agent interactions, tool calls, and parameters - 🌐 **Secure Gateway** - Expose internal MCP servers safely to AI agents Pomerium enables you to define policies like: - Which users can access which tools - Rate limiting per user or group - Audit logging of all tool calls - Dynamic access control based on user attributes ### Architecture with Pomerium ```mermaid sequenceDiagram participant User as AI Agent/User participant Pomerium as Pomerium Gateway participant MCP as Pimp My Ride MCP Server participant Storage as SQLite Storage User->>Pomerium: MCP Request Pomerium->>Pomerium: Authenticate User (OAuth/OIDC) Pomerium->>Pomerium: Authorize Tool Access (Policy Check) Pomerium->>MCP: Forward Request + Identity Headers Note over Pomerium,MCP: X-Pomerium-Claim-Sub<br/>X-Pomerium-Claim-Email<br/>X-Pomerium-Claim-Name MCP->>MCP: Extract User Identity MCP->>Storage: Read/Write Build Data Storage-->>MCP: Data Response MCP-->>Pomerium: MCP Response Pomerium-->>User: MCP Response ``` **Learn more:** [Pomerium MCP Documentation](https://www.pomerium.com/docs/capabilities/mcp) ## Quick Start ### Installation ```bash npm install ``` ### Configuration Create a `.env` file (see `.env.example`): ```bash # Server Configuration HOST=0.0.0.0 PORT=3000 NODE_ENV=development LOG_LEVEL=info # Storage Configuration STORAGE_BACKEND=sqlite SQLITE_DB_PATH=./data/pimp-my-ride.db ``` ### Development ```bash npm run dev ``` ### Production ```bash npm run build npm start ``` ## Available Tools ### Car Customization #### `getCurrentBuild` Retrieve or create your active car build with all customizations. #### `updateCarConfig` Update car attributes: - **color** - Primary color (red, blue, green, yellow, orange, purple, pink, black, white, silver, gold, cyan, magenta, lime) - **secondaryColor** - Secondary/accent color - **wheels** - Wheel type (stock, sport, racing, offroad, chrome, neon, spinner) - **bodyKit** - Body kit style (stock, sport, racing, drift, luxury, rally, muscle) - **decal** - Decal/livery (none, racing_stripes, flames, tribal, camo, carbon_fiber, checkered, sponsor, custom) - **spoiler** - Spoiler type (none, stock, sport, racing, gt_wing, ducktail) - **exhaust** - Exhaust system (stock, sport, racing, dual, quad, side_exit) - **underglow** - Underglow lighting (none, red, blue, green, purple, rainbow, white) - **performance** - Performance stats (power, grip, aero, weight: 0-100) #### `updateDriverProfile` Set driver persona and nickname: - **persona** - Driver personality: CoolCalmCollected, RoadRage, SpeedDemon, Cautious, ShowOff, Tactical, Wildcard - **nickname** - Driver nickname (1-50 characters) #### `getCustomizationOptions` Get all available customization options for car parts and driver personas. #### `getPersonaInfo` Get detailed information about driver personas including racing style, strengths, and weaknesses. ### Build Management #### `saveBuild` Save the current car build under a specific name. #### `loadBuild` Load a saved car build and make it active. #### `listBuilds` List all saved car builds with pagination support. #### `deleteBuild` Delete a saved car build (cannot delete active build). #### `getBuildDetails` Get detailed information about a build including calculated performance score. ## Architecture ### Storage Layer The KV storage abstraction provides: - **Namespaces** - Logical data isolation - **TTL Expiration** - Automatic cleanup of expired entries - **CAS Versioning** - Compare-and-Set for concurrent updates - **Pagination** - Cursor-based pagination for large datasets Default implementation uses SQLite with WAL mode for better concurrency. ### Authentication Pomerium authentication resolves user identity from HTTP headers: - `X-Pomerium-Claim-Sub` - User ID - `X-Pomerium-Claim-Email` - Email address - `X-Pomerium-Claim-Name` - Display name - `X-Pomerium-JWT-Assertion` - JWT token (fallback) In development mode without Pomerium, the server generates anonymous session-based user IDs. ### Data Model **Build Structure:** ```typescript { id: string, name?: string, car: { color, secondaryColor, wheels, bodyKit, decal, spoiler, exhaust, underglow, performance: { power, grip, aero, weight } }, driver: { persona, nickname? }, createdAt: number, updatedAt: number } ``` ## API Endpoints ### MCP Protocol - `POST /mcp` - MCP tool calls - `GET /mcp` - Server info ### Health Check - `GET /health` - Storage health status ## Environment Variables | Variable | Description | Default | | ----------------- | --------------------------------------------- | ------------------------ | | `HOST` | Server host/interface to bind | `0.0.0.0` | | `PORT` | Server port | `3000` | | `NODE_ENV` | Environment (development/production/test) | `development` | | `LOG_LEVEL` | Logging level (error/warn/info/debug) | `info` | | `STORAGE_BACKEND` | Storage type (sqlite/redis/postgres/dynamodb) | `sqlite` | | `SQLITE_DB_PATH` | SQLite database file path | `./data/pimp-my-ride.db` | | `SQLITE_VERBOSE` | Enable SQL query logging | `false` | ## Development ### Scripts ```bash npm run dev # Development with watch mode npm run build # Build for production npm start # Start production server npm run lint # Check code quality npm run lint:fix # Fix linting issues npm run format # Format code with Prettier npm test # Run tests ``` ### Project Structure ``` src/ ├── index.ts # Main server entry point ├── config.ts # Environment configuration ├── logger.ts # Structured logging ├── auth/ │ └── pomerium.ts # Pomerium authentication ├── domain/ │ └── models.ts # Car and driver models ├── storage/ │ ├── kv.ts # KV storage interface │ ├── sqlite.ts # SQLite implementation │ ├── factory.ts # Storage factory │ └── index.ts # Exports ├── tools/ │ └── builds.ts # Build management tools └── lib/ ├── utils.ts # MCP response helpers └── errors.ts # Error formatting ``` ## Deployment ### Docker Available on [Docker Hub: nickytonline/pimp-my-ride-mcp](https://hub.docker.com/r/nickytonline/pimp-my-ride-mcp) ```bash # Pull from Docker Hub docker pull nickytonline/pimp-my-ride-mcp # Or build locally docker build -t pimp-my-ride-mcp . # Run docker run -p 3000:3000 -v ./data:/app/data pimp-my-ride-mcp ``` ### With Pomerium (Recommended for Production) Deploy behind Pomerium for secure, policy-based access control: ```yaml # pomerium-config.yaml routes: - from: https://pimp-my-ride.example.com to: http://localhost:3000 policy: - allow: and: - email: is: user@example.com # Optional: Fine-grained tool access control mcp_allow_tools: - getCurrentBuild - updateCarConfig - updateDriverProfile ``` See [Pomerium MCP docs](https://www.pomerium.com/docs/capabilities/mcp) for advanced configuration including: - Tool-level authorization - User/group-based access control - Rate limiting - OAuth upstream integration ## Roadmap ### Phase 2 - AI Assistance - [ ] `randomizeBuild` - Generate random themed builds - [ ] `suggestUpgrades` - AI-powered upgrade recommendations - [ ] `generateLivery` - Color scheme suggestions ### Phase 3 - Racing - [ ] `simulateRace` - Race simulation - [ ] `getLeaderboard` - Global rankings - [ ] Race results persistence ## License MIT ## Documentation - **[Product Requirements Document (PRD)](docs/PRD.md)** - Detailed architecture, data models, and implementation phases - **[Repository Guidelines (AGENTS.md)](AGENTS.md)** - Development conventions, testing, and contribution guidelines ## About Pomeranian Kart Pomeranian Kart is a racing game that uses this MCP server for car customization. Players interact with the game through natural language, building and customizing their dream cars before racing. ## References - [Model Context Protocol](https://modelcontextprotocol.io/) - [Pomerium Documentation](https://www.pomerium.com/docs/) - [MCP Documentation](https://modelcontextprotocol.io/docs)