Pimp My Ride MCP

🚀 ピンク・マイ・ライドMCPサーバー

カーのカスタマイズとレース用のモデルコンテキストプロトコル（MCP）サーバーです。ChatGPTやClaudeを通じて自然言語で夢の車を構築し、カスタマイズできます！

⚠️ 重要提示

このプロジェクトは、Xzibitが司会を務めるMTVの番組「Pimp My Ride」へのオマージュです。MTVとは関係がなく、承認もされていません。

✨ 主な機能

• 🎨 カーカスタマイズ - 色、ホイール、ボディキット、スポイラー、排気装置、デカール、アンダーグロー
• 🏎️ ドライバープロファイル - レースペルソナ（RoadRage、SpeedDemon、CoolCalmCollectedなど）を選択
• 💾 ビルド管理 - 複数のカービルドを保存、読み込み、管理
• 📊 パフォーマンススコアリング - ビルドのパフォーマンススコアを計算
• 🔒 Pomerium認証 - PomeriumプロキシによるセキュアなID認識アクセス
• 🗄️ プラガブルストレージ - デフォルトはSQLiteで、Redis、PostgreSQL、DynamoDBに拡張可能

🔒 セキュリティ

⚠️ このMCPサーバーには、組み込みの認証や承認機能がありません。 HTTPヘッダーからIDを読み取り、暗黙的に信頼します。

本番環境でのデプロイでは、このサーバーをPomeriumの背後に配置してください。PomeriumはAIゲートウェイで、以下の機能を提供します。

• 🔐 集中認証 - アイデンティティプロバイダとのOAuth/OIDC統合
• 🛡️ 細粒度の承認 - ツールとメソッドレベルでのポリシーベースのアクセス制御
• 🔑 自動トークン管理 - OAuthトークンのリフレッシュを透過的に処理
• 📊 可観測性 - AIエージェントのやり取り、ツール呼び出し、パラメータの詳細なログ
• 🌐 セキュアゲートウェイ - 内部のMCPサーバーをAIエージェントに安全に公開

Pomeriumを使用すると、以下のようなポリシーを定義できます。

• どのユーザーがどのツールにアクセスできるか
• ユーザーまたはグループごとのレート制限
• すべてのツール呼び出しの監査ログ
• ユーザー属性に基づく動的なアクセス制御

Pomeriumを使用したアーキテクチャ

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

詳細を学ぶ: Pomerium MCP Documentation

🚀 クイックスタート

📦 インストール

npm install

設定

.envファイルを作成します（.env.exampleを参照）。

# サーバー設定
HOST=0.0.0.0
PORT=3000
NODE_ENV=development
LOG_LEVEL=info

# ストレージ設定
STORAGE_BACKEND=sqlite
SQLITE_DB_PATH=./data/pimp-my-ride.db

開発

npm run dev

本番環境

npm run build
npm start

💻 使用例

カーカスタマイズ

getCurrentBuild

現在のアクティブなカービルドを取得または作成し、すべてのカスタマイズを含めます。

updateCarConfig

カーの属性を更新します。

• color - 主な色（赤、青、緑、黄、橙、紫、ピンク、黒、白、銀、金、シアン、マゼンタ、ライム）
• secondaryColor - 二次色/アクセント色
• wheels - ホイールタイプ（ストック、スポーツ、レーシング、オフロード、クロム、ネオン、スピナー）
• bodyKit - ボディキットのスタイル（ストック、スポーツ、レーシング、ドリフト、ラグジュアリー、ラリー、マッスル）
• decal - デカール/リバリー（なし、レーシングストライプ、炎、トライバル、カモフラージュ、カーボンファイバー、チェッカー、スポンサー、カスタム）
• spoiler - スポイラータイプ（なし、ストック、スポーツ、レーシング、GTウィング、ダックテール）
• exhaust - 排気装置（ストック、スポーツ、レーシング、デュアル、クワッド、サイドエグジット）
• underglow - アンダーグロー照明（なし、赤、青、緑、紫、レインボー、白）
• performance - パフォーマンス統計（パワー、グリップ、エアロ、重量: 0 - 100）

updateDriverProfile

ドライバーのペルソナとニックネームを設定します。

• persona - ドライバーの性格: CoolCalmCollected、RoadRage、SpeedDemon、Cautious、ShowOff、Tactical、Wildcard
• nickname - ドライバーのニックネーム（1 - 50文字）

getCustomizationOptions

カーパーツとドライバーペルソナのすべての利用可能なカスタマイズオプションを取得します。

getPersonaInfo

ドライバーペルソナの詳細情報を取得します。レーシングスタイル、強み、弱点が含まれます。

ビルド管理

saveBuild

現在のカービルドを特定の名前で保存します。

loadBuild

保存されたカービルドを読み込み、アクティブにします。

listBuilds

保存されたすべてのカービルドをページネーションで表示します。

deleteBuild

保存されたカービルドを削除します（アクティブなビルドは削除できません）。

getBuildDetails

ビルドの詳細情報を取得します。計算されたパフォーマンススコアが含まれます。

🔧 技術詳細

ストレージレイヤー

KVストレージ抽象化により、以下の機能が提供されます。

• 名前空間 - 論理的なデータ分離
• TTL有効期限 - 期限切れのエントリを自動的にクリーンアップ
• CASバージョニング - 同時更新のための比較と設定
• ページネーション - 大規模なデータセットのカーソルベースのページネーション

デフォルトの実装では、SQLiteをWALモードで使用して、より高い同時実行性を実現します。

認証

Pomerium認証は、HTTPヘッダーからユーザーIDを解決します。

• X-Pomerium-Claim-Sub - ユーザーID
• X-Pomerium-Claim-Email - メールアドレス
• X-Pomerium-Claim-Name - 表示名
• X-Pomerium-JWT-Assertion - JWTトークン（フォールバック）

Pomeriumを使用しない開発モードでは、サーバーは匿名のセッションベースのユーザーIDを生成します。

データモデル

ビルド構造:

{
  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エンドポイント

MCPプロトコル

• POST /mcp - MCPツール呼び出し
• GET /mcp - サーバー情報

ヘルスチェック

• GET /health - ストレージのヘルスステータス

環境変数

開発

スクリプト

npm run dev          # ウォッチモードでの開発
npm run build        # 本番環境用のビルド
npm start            # 本番環境サーバーを起動
npm run lint         # コード品質をチェック
npm run lint:fix     # リントエラーを修正
npm run format       # Prettierでコードを整形
npm test             # テストを実行

プロジェクト構造

src/
├── index.ts              # メインサーバーのエントリーポイント
├── config.ts             # 環境設定
├── logger.ts             # 構造化ロギング
├── auth/
│   └── pomerium.ts       # Pomerium認証
├── domain/
│   └── models.ts         # カーとドライバーのモデル
├── storage/
│   ├── kv.ts            # KVストレージインターフェース
│   ├── sqlite.ts        # SQLite実装
│   ├── factory.ts       # ストレージファクトリー
│   └── index.ts         # エクスポート
├── tools/
│   └── builds.ts        # ビルド管理ツール
└── lib/
    ├── utils.ts         # MCPレスポンスヘルパー
    └── errors.ts        # エラーフォーマット

デプロイ

Docker

Docker Hub: nickytonline/pimp-my-ride-mcpで利用可能です。

# Docker Hubからプル
docker pull nickytonline/pimp-my-ride-mcp

# またはローカルでビルド
docker build -t pimp-my-ride-mcp .

# 実行
docker run -p 3000:3000 -v ./data:/app/data pimp-my-ride-mcp

Pomeriumを使用したデプロイ（本番環境で推奨）

セキュアなポリシーベースのアクセス制御のために、Pomeriumの背後にデプロイします。

# pomerium-config.yaml
routes:
  - from: https://pimp-my-ride.example.com
    to: http://localhost:3000
    policy:
      - allow:
          and:
            - email:
                is: user@example.com
    # オプション: 細粒度のツールアクセス制御
    mcp_allow_tools:
      - getCurrentBuild
      - updateCarConfig
      - updateDriverProfile

詳細な設定については、Pomerium MCP docsを参照してください。

• ツールレベルの承認
• ユーザー/グループベースのアクセス制御
• レート制限
• OAuthアップストリーム統合

🗺️ ロードマップ

フェーズ2 - AI支援

• [ ] randomizeBuild - ランダムなテーマのビルドを生成
• [ ] suggestUpgrades - AIによるアップグレード推奨
• [ ] generateLivery - 配色提案

フェーズ3 - レーシング

• [ ] simulateRace - レースシミュレーション
• [ ] getLeaderboard - グローバルランキング
• [ ] レース結果の永続化

📄 ライセンス

MIT

📚 ドキュメント

• 製品要件文書 (PRD) - 詳細なアーキテクチャ、データモデル、実装フェーズ
• リポジトリガイドライン (AGENTS.md) - 開発規約、テスト、貢献ガイドライン

ポメラニアンカートについて

ポメラニアンカートは、このMCPサーバーをカーカスタマイズに使用するレースゲームです。プレイヤーは自然言語でゲームとやり取りし、レース前に夢の車を構築し、カスタマイズします。

参考資料

• Model Context Protocol
• Pomerium Documentation
• MCP Documentation