Race MCP

🚀 赛车MCP服务器

这是一个全面的MCP（模型上下文协议）服务器，用于处理iRacing的遥测数据。它能提供实时赛车建议、车辆监测、遥测数据分析，以及关于赛车数据的对话交互功能。

🚀 快速开始

本MCP服务器通过以下方式将iRacing的遥测数据转化为可付诸行动的赛车洞察：

• 借助高级分析实现实时遥测数据流式传输
• 基于驾驶模式提供人工智能赛车教练指导
• 具备智能车辆监测和交通感知能力
• 进行详细圈速分析并给出改进建议
• 对赛事进行会话监测并分析性能趋势
• 拥有对话界面，可进行自然的赛车讨论

✨ 主要特性

核心功能

• 实时遥测数据处理：通过pyirsdk从iRacing获取实时数据
• 高级分析：进行G力计算、赛车线分析和档位优化
• 赛车人工智能教练：根据驾驶风格和具体情况提供个性化建议
• 车辆监测系统：具备交通感知和定位智能
• 性能分析：逐圈详细分析并给出改进建议
• 赛事跟踪：长期性能趋势和统计数据

MCP集成

• 5种交互工具：可直接访问和分析遥测数据
• 3种实时资源：提供流式数据以进行持续监测
• 3种人工智能提示：具备专业的教练角色（教练、监测员、调校分析师）
• JSON - RPC 2.0：符合标准MCP协议
• STDIO传输：可与MCP客户端集成

📦 安装指南

前提条件

• Python 3.8及以上版本
• iRacing模拟器（用于实时遥测数据）
• 建议使用虚拟环境

快速设置

# 克隆仓库
git clone <your-repo-url>
cd race-mcp

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在Windows上使用：.venv\Scripts\activate

# 安装带有依赖项的包
pip install -e .

手动安装依赖项

如果您更喜欢手动安装：

pip install mcp pyirsdk pydantic aiofiles

💻 使用示例

运行服务器

# 激活虚拟环境
source .venv/bin/activate

# 直接运行MCP服务器
python -m race_mcp_server

# 或者使用便捷的启动脚本
./start_server.sh

# 以调试日志模式运行
./start_server.sh --debug

# 在模拟模式下运行（无需iRacing）
./start_server.sh --simulation

模拟iRacing数据生成器

在开发过程中，如果没有模拟器，可以使用独立进程通过TCP发送逼真的iRacing风格遥测数据。

# 在端口9000上启动模拟遥测数据流
python -m race_mcp_server.mock_iracing_stream --port 9000

客户端可以连接到指定的主机和端口，接收以换行符分隔的JSON遥测数据帧，这些数据帧模拟了真实iRacing数据流的结构。

使用图形界面启动

安装完成后，您可以使用一个小型图形界面启动服务器：

race-mcp-gui

该图形界面提供启动/停止控制，并显示服务器日志，方便快速准备赛车赛事。

测试服务器

# 运行全面测试
python test_client.py

# 或者使用启动脚本进行测试
./start_server.sh --test

语音交互

通过可选的音频工具支持实时语音通信。

前提条件

• 在OPENAI_API_KEY中设置OpenAI API密钥
• 安装语音依赖项：pip install race-mcp-server[voice]

示例用法

import asyncio
from race_mcp_server.openai_client import OpenAIClient
from race_mcp_server.voice_interface import VoiceInterface

async def main():
    client = OpenAIClient()
    voice = VoiceInterface(client)
    await voice.chat_once()

asyncio.run(main())

此代码会录制一段简短的麦克风音频，将其发送到OpenAI进行转录，并将模型的响应语音反馈给用户。

📚 详细文档

可用工具

1. get_telemetry

用途：获取当前遥测数据并进行高级分析

{
  "name": "get_telemetry",
  "arguments": {
    "include_analytics": true,
    "format": "detailed"
  }
}

返回值：完整的遥测数据，包括速度、转速、位置、G力和赛车线分析

2. spot_cars

用途：识别和分析附近车辆，以增强态势感知

{
  "name": "spot_cars",
  "arguments": {
    "radius_meters": 100,
    "include_predictions": true
  }
}

返回值：附近车辆列表，包含相对位置、速度和轨迹预测

3. get_racing_advice

用途：根据当前情况获取人工智能教练建议

{
  "name": "get_racing_advice", 
  "arguments": {
    "context": "在3号弯入弯速度上遇到困难",
    "focus_area": "弯道驾驶"
  }
}

返回值：个性化建议，包含优先级和具体推荐

4. analyze_lap

用途：详细分析圈速表现并给出改进建议

{
  "name": "analyze_lap",
  "arguments": {
    "lap_number": 5,
    "compare_to_best": true
  }
}

返回值：各赛段时间、赛车线效率、一致性评级和具体改进区域

5. track_session

用途：监测整个赛事进程和性能趋势

{
  "name": "track_session",
  "arguments": {
    "include_trends": true,
    "format": "summary"
  }
}

返回值：赛事统计数据、速度趋势、燃油消耗和轮胎磨损分析

实时资源

1. telemetry://live-stream

持续的遥测数据流式传输，实时更新

2. session://current-info

当前赛事信息，包括赛道、条件和赛事类型

3. track://layout-info

赛道特定信息，包括弯道位置和赛车线数据

人工智能提示

1. racing_coach

角色：专业赛车教练 重点：技术改进和战略建议 用例：一般赛车改进和学习

2. car_spotter

角色：经验丰富的监测员，专注于安全和定位 重点：交通管理和态势感知 用例：比赛情况和交通导航

3. setup_analyst

角色：技术调校工程师 重点：车辆调校优化和操控分析 用例：车辆调校和技术调整

测试

运行测试客户端

测试客户端提供了一种全面的方式来与服务器的所有功能进行交互：

# 测试服务器所有功能
python test_client.py

# 使用启动脚本进行自动化测试
./start_server.sh --test

测试客户端功能

• 工具测试：使用逼真的参数测试所有5种MCP工具
• 资源访问：验证所有3种实时资源
• 提示测试：测试所有3种人工智能教练提示
• 错误处理：测试服务器的弹性和错误响应
• 性能测试：显示响应时间和数据验证结果

手动服务器测试

# 手动启动服务器并使用直接的JSON - RPC调用进行测试
python -m race_mcp_server

# 在另一个终端中，您可以通过标准输入发送JSON - RPC消息
# （高级用法 - 使用test_client.py会更简单）

配置

环境变量

# 启用调试日志
export MCP_DEBUG=1

# 强制进入模拟模式
export RACE_MCP_SIMULATION=1

# 设置自定义iRacing数据路径（如果需要）
export IRSDK_PATH=/path/to/irsdk

服务器配置

修改src/race_mcp_server/main.py中的设置：

• 遥测数据更新间隔
• 模拟模式参数
• 日志级别
• 分析参数

启动脚本选项

./start_server.sh --help    # 显示所有可用选项
./start_server.sh --check   # 验证系统要求

故障排除

常见问题

1. “pyirsdk连接失败”

   • 确保iRacing正在运行且处于赛事会话中
   • 检查iRacing遥测数据输出是否已启用
   • 如果iRacing不可用，服务器将以模拟模式运行

2. “工具执行失败”

   • 检查服务器日志以获取详细错误消息
   • 验证工具参数是否符合预期模式
   • 尝试重启服务器

3. “资源访问失败”

   • 当iRacing未运行时，资源将返回模拟数据
   • 检查服务器是否正常启动
   • 验证资源URI是否正确

调试模式

# 启用详细日志记录
python -m race_mcp_server --debug

# 查看详细的遥测数据处理信息
export MCP_DEBUG=1 python -m race_mcp_server

日志文件

• 服务器日志：输出到控制台（如有需要可重定向到文件）
• iRacing连接状态：启动时记录
• 工具执行：每次请求都会记录

开发

项目结构

race-mcp/
├── src/race_mcp_server/
│   ├── __init__.py              # 包初始化
│   ├── __main__.py              # CLI入口点
│   ├── main.py                  # 核心MCP服务器（580 + 行）
│   └── telemetry_processor.py   # 高级分析引擎
├── start_server.sh              # 便捷的启动脚本
├── pyproject.toml               # 项目配置
├── test_client.py               # 全面的测试套件
└── README.md                    # 本文件

添加新功能

1. 新工具：在main.py的RaceMCPServer类中添加方法
2. 新资源：扩展资源处理程序
3. 增强分析：修改telemetry_processor.py
4. 新提示：在提示部分添加提示模板

测试新功能

# 修改后进行测试
python test_client.py

# 以调试输出模式进行测试
./start_server.sh --debug --test

贡献代码

1. 分叉仓库
2. 创建功能分支
3. 为新功能添加测试
4. 提交带有详细描述的拉取请求

要求

核心依赖项

mcp = ">=1.0.0"          # 模型上下文协议框架
pyirsdk = ">=1.3.0"      # iRacing SDK集成
pydantic = ">=2.0.0"     # 数据验证和序列化
aiofiles = ">=0.8.0"     # 异步文件操作

系统要求

• 操作系统：Windows、macOS或Linux
• Python：3.8及以上版本（已在3.10.12上测试）
• 内存：可用内存100MB以上
• iRacing：任何启用遥测数据的最新版本（可选 - 服务器在无iRacing时可在模拟模式下运行）

可选依赖项

• pytest：用于运行扩展测试套件
• MCP客户端：任何兼容MCP的客户端，用于集成

🔧 技术细节

架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   iRacing Sim   │───▶│  pyirsdk Stream │───▶│   MCP Server    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                        │
                                                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Claude/AI     │◀───│  MCP Protocol   │◀───│  Tool Handlers  │
└─────────────────┘    └─────────────────┘    └─────────────────┘

开发

# 运行测试
pytest

# 格式化代码
black src/
isort src/

# 类型检查
mypy src/

📄 许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。

🏆 致谢

• iRacing：提供了全面的遥测数据API
• MCP社区：提供了优秀的模型上下文协议框架
• 赛车社区：提供反馈和功能建议

---

准备好提升您的圈速了吗？启动服务器并运行测试客户端，见证它的强大功能！ 🏎️💨

配置

服务器可以通过环境变量进行配置：

• IRACING_TELEMETRY_INTERVAL - 遥测数据更新间隔（秒）（默认值：1.0）
• RACE_MCP_LOG_LEVEL - 日志级别（默认值：INFO）
• RACE_MCP_ENABLE_SPOTTING - 启用车辆监测功能（默认值：true）