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）