Pimp My Ride MCP

🚀 🏎️ 我的座駕改裝MCP服務器

這是一個用於汽車定製和賽車的模型上下文協議（MCP）服務器。你可以通過ChatGPT或Claude，使用自然語言來打造和定製你的夢想座駕！

⚠️ 重要提示

本項目是對MTV節目《我的座駕改裝秀》（由Xzibit主持）的致敬之作，與MTV沒有關聯，也未得到其認可。

✨ 主要特性

• 🎨 汽車定製 - 可定製顏色、車輪、車身套件、擾流板、排氣系統、貼紙和底盤燈。
• 🏎️ 車手檔案 - 選擇你的賽車風格（如“路怒族”“速度狂人”“冷靜沉穩型”等）。
• 💾 改裝管理 - 保存、加載和管理多個汽車改裝方案。
• 📊 性能評分 - 獲取改裝方案的計算性能得分。
• 🔒 Pomerium認證 - 使用Pomerium代理實現安全的身份感知訪問。
• 🗄️ 可插拔存儲 - 默認使用SQLite，可擴展至Redis、PostgreSQL、DynamoDB。

🔒 安全性

⚠️ 重要提示

此MCP服務器沒有內置的身份驗證或授權機制。它從HTTP頭中讀取身份信息並隱式信任這些信息。

對於生產環境部署，請將此服務器置於 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文檔

🚀 快速開始

📦 安裝指南

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 工具
# 可更新汽車的各種屬性，如顏色、車輪、車身套件等
# 示例代碼可根據實際調用方式補充

高級用法

保存和加載改裝方案

# 保存當前汽車改裝方案
# 調用 saveBuild 工具並指定保存名稱
# 示例代碼可根據實際調用方式補充

# 加載已保存的汽車改裝方案
# 調用 loadBuild 工具並指定要加載的方案名稱
# 示例代碼可根據實際調用方式補充

📚 詳細文檔

可用工具

汽車定製

• getCurrentBuild：檢索或創建包含所有定製信息的活躍汽車改裝方案。
• updateCarConfig：更新汽車屬性，包括：
  • color - 主顏色（紅、藍、綠、黃、橙、紫、粉、黑、白、銀、金、青、品紅、綠）
  • secondaryColor - 次要/強調色
  • wheels - 車輪類型（原廠、運動、賽車、越野、鍍鉻、霓虹、旋轉）
  • bodyKit - 車身套件風格（原廠、運動、賽車、漂移、豪華、拉力、肌肉）
  • decal - 貼紙/塗裝（無、賽車條紋、火焰、部落、迷彩、碳纖維、方格、贊助商、自定義）
  • spoiler - 擾流板類型（無、原廠、運動、賽車、GT尾翼、鴨尾）
  • exhaust - 排氣系統（原廠、運動、賽車、雙出、四出、側出）
  • underglow - 底盤燈（無、紅、藍、綠、紫、彩虹、白）
  • performance - 性能統計（動力、抓地力、空氣動力學、重量：0 - 100）
• updateDriverProfile：設置車手風格和暱稱：
  • persona - 車手個性：冷靜沉穩型、路怒族、速度狂人、謹慎型、愛炫耀型、戰術型、 wildcard
  • nickname - 車手暱稱（1 - 50 個字符）
• getCustomizationOptions：獲取汽車部件和車手風格的所有可用定製選項。
• getPersonaInfo：獲取車手風格的詳細信息，包括賽車風格、優勢和劣勢。

改裝管理

• saveBuild：將當前汽車改裝方案以特定名稱保存。
• loadBuild：加載已保存的汽車改裝方案並使其成為活躍方案。
• listBuilds：列出所有已保存的汽車改裝方案，支持分頁。
• deleteBuild：刪除已保存的汽車改裝方案（不能刪除活躍方案）。
• getBuildDetails：獲取改裝方案的詳細信息，包括計算的性能得分。

API端點

MCP協議

• POST /mcp - MCP工具調用
• GET /mcp - 服務器信息

健康檢查

• GET /health - 存儲健康狀態

環境變量

🔧 技術細節

存儲層

KV存儲抽象提供以下功能：

• 命名空間 - 邏輯數據隔離。
• TTL過期 - 自動清理過期條目。
• CAS版本控制 - 用於併發更新的比較和設置。
• 分頁 - 基於遊標對大型數據集進行分頁。

默認實現使用SQLite的WAL模式以提高併發性能。

認證

Pomerium認證從HTTP頭中解析用戶身份：

• 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
}

🚀 開發相關

腳本

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文檔 以獲取高級配置，包括：

• 工具級別的授權。
• 基於用戶/組的訪問控制。
• 速率限制。
• OAuth上游集成。

📄 許可證

本項目採用MIT許可證。

📚 文檔

• 產品需求文檔 (PRD) - 詳細的架構、數據模型和實現階段。
• 倉庫指南 (AGENTS.md) - 開發規範、測試和貢獻指南。

關於博美卡丁車

博美卡丁車是一款賽車遊戲，它使用此MCP服務器進行汽車定製。玩家通過自然語言與遊戲交互，在比賽前打造和定製他們的夢想之車。

參考資料

• 模型上下文協議
• Pomerium文檔
• MCP文檔

🚧 路線圖

第二階段 - AI輔助

• [ ] randomizeBuild - 生成隨機主題的改裝方案。
• [ ] suggestUpgrades - 基於AI的升級建議。
• [ ] generateLivery - 配色方案建議。

第三階段 - 賽車

• [ ] simulateRace - 賽車模擬。
• [ ] getLeaderboard - 全球排名。
• [ ] 比賽結果持久化。