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 - 全球排名。
• [ ] 比赛结果持久化。