Race MCP Server

Race MCP服务器

一个用于iRacing遥测数据的综合MCP（模型上下文协议）服务器，提供实时赛车建议、赛车定位、遥测分析以及关于赛车数据的对话交互。

🏁 概述

此MCP服务器通过以下方式将iRacing遥测数据转化为可操作的赛车见解：

• 实时遥测流 具有高级分析功能
• 人工智能驱动的赛车教练 基于驾驶模式
• 智能汽车定位 以及交通意识
• 详细的圈数分析 提出改进建议
• 会话监控 随着性能趋势
• 会话接口 用于自然赛车讨论

🚀 特性

核心能力

• 实时遥测处理：通过pyirsdk从iRacing获取实时数据
• 高级分析：重力计算、赛道分析、齿轮优化
• 赛车AI教练：根据驾驶风格和情况提供个性化建议
• 汽车定位系统：交通感知和定位智能
• 性能分析：逐圈细分并提出改进建议
• 会话跟踪：长期业绩趋势和统计数据

MCP集成

• 5互动工具：直接遥测访问和分析功能
• 3实时资源：用于持续监控的流式数据馈送
• 3个AI提示：专业教练（教练、观察员、设置分析师）
• JSON-RPC 2.0：符合标准MCP协议
• STDIO传输：已准备好与MCP客户端集成

📦 安装

先决条件

• Python 3.8+
• iRacing模拟器（用于实时遥测）
• 虚拟环境（推荐）

快速设置

# Clone the repository
git clone 
cd race-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package with dependencies
pip install -e .

手动依赖关系

如果您更喜欢手动安装：

pip install mcp pyirsdk pydantic aiofiles

🎮 用法

运行服务器

# Activate virtual environment
source .venv/bin/activate

# Run the MCP server directly
python -m race_mcp_server

# Or use the convenient startup script
./start_server.sh

# Run with debug logging
./start_server.sh --debug

# Run in simulation mode (no iRacing required)
./start_server.sh --simulation

模拟iRacing数据生成器

对于没有模拟器的开发，独立进程可以通过TCP发出逼真的iRacing式遥测。

# Start the mock telemetry stream on port 9000
python -m race_mcp_server.mock_iracing_stream --port 9000

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

使用GUI启动

安装后，您可以使用小型GUI启动服务器：

race-mcp-gui

GUI提供启动/停止控制，并显示服务器日志以进行快速比赛准备。

测试服务器

# Run comprehensive tests
python test_client.py

# Or use the startup script with testing
./start_server.sh --test

🎙 语音交互

通过可选的音频实用程序支持实时语音通信。

先决条件

• 在中设置了OpenAI API密钥 OPENAI_API_KEY
• 安装语音依赖项： 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"
  }
}

退货：完整的遥测数据，包括速度、转速、位置、重力和赛道分析

2. spot_cars

目的：识别和分析附近的汽车以获得态势感知

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

退货：具有相对位置、速度和轨迹预测的附近汽车列表

3. get_racing_advice

目的：根据当前情况获取人工智能指导建议

{
  "name": "get_racing_advice", 
  "arguments": {
    "context": "struggling with turn 3 entry speed",
    "focus_area": "cornering"
  }
}

退货：具有优先级别和具体建议的个性化建议

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

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

🤖 AI提示

1. racing_coach

人格：专业赛车教练 聚焦：技术改进和战略建议 用例：一般赛车改进和学习

2. car_spotter

人格：经验丰富的观察员，专注于安全和定位 聚焦：交通管理和态势感知\ 用例：比赛情况和交通导航

3. setup_analyst

人格：技术设置工程师 聚焦：车辆设置优化和操控分析 用例：汽车设置调整和技术调整

🧪 测试

运行测试客户端

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

# Test all server functionality
python test_client.py

# Use the startup script for automated testing
./start_server.sh --test

测试客户端功能

• 工具测试：使用真实参数测试所有5个MCP工具
• 资源访问：验证所有3个实时资源
• 快速测试：练习所有3个AI辅导提示
• 错误处理：测试服务器弹性和错误响应
• 演出：显示响应时间和数据验证

手动服务器测试

# Start server manually and test with direct JSON-RPC calls
python -m race_mcp_server

# In another terminal, you can send JSON-RPC messages via stdin
# (Advanced usage - test_client.py is much easier)

🔧 配置

环境变量

# Enable debug logging
export MCP_DEBUG=1

# Force simulation mode
export RACE_MCP_SIMULATION=1

# Set custom iRacing data path (if needed)
export IRSDK_PATH=/path/to/irsdk

服务器配置

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

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

启动脚本选项

./start_server.sh --help    # Show all available options
./start_server.sh --check   # Verify system requirements

🔍 故障排除

常见问题

1. “pyirsdk连接失败”

- 确保iRacing正在运行并处于会话中 - 检查iRacing遥测输出是否已启用 - 如果iRacing不可用，服务器将在模拟模式下运行

1. “工具执行失败”

- 检查服务器日志以获取详细的错误消息 - 验证工具参数是否与预期架构匹配 - 尝试重新启动服务器

1. “资源访问失败”

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

调试模式

# Enable verbose logging
python -m race_mcp_server --debug

# View detailed telemetry processing
export MCP_DEBUG=1 python -m race_mcp_server

日志文件

• 服务器日志：写入控制台（如果需要，重定向到文件）
• iRacing连接状态：启动时已记录
• 工具执行：记录每个请求

🏗 发展

项目结构

race-mcp/
├── src/race_mcp_server/
│   ├── __init__.py              # Package initialization
│   ├── __main__.py              # CLI entry point  
│   ├── main.py                  # Core MCP server (580+ lines)
│   └── telemetry_processor.py   # Advanced analytics engine
├── start_server.sh              # Convenient startup script
├── pyproject.toml               # Project configuration
├── test_client.py               # Comprehensive test suite
└── README.md                    # This file

添加新功能

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

测试新功能

# Test after making changes
python test_client.py

# Test with debug output
./start_server.sh --debug --test

贡献

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

📋 需求

核心依赖关系

mcp = ">=1.0.0"          # Model Context Protocol framework
pyirsdk = ">=1.3.0"      # iRacing SDK integration
pydantic = ">=2.0.0"     # Data validation and serialization
aiofiles = ">=0.8.0"     # Async file operations

系统要求

• 操作系统：Windows、macOS或Linux
• python：3.8+（用3.10.12测试）
• 记忆：100MB+可用
• iRacing：任何启用遥测的最新版本（可选-服务器在没有遥测的情况下以模拟模式运行）

可选依赖关系

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

📜 许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

🏆 致谢

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

______________________________________________________________________

准备好提高你的圈速了吗？启动服务器并运行测试客户端以查看其运行情况！ 🏎️💨

配置

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

• IRACING_TELEMETRY_INTERVAL -遥测更新间隔（秒）（默认值：1.0）
• RACE_MCP_LOG_LEVEL -日志记录级别（默认值：INFO）
• RACE_MCP_ENABLE_SPOTTING -启用汽车定位功能（默认值：true）

建筑

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

发展

# Run tests
pytest

# Format code
black src/
isort src/

# Type checking
mypy src/

许可证

MIT许可证