Race MCP

🚀 Race MCP Server

このRace MCP Serverは、iRacingのテレメトリデータを活用した包括的なMCP（Model Context Protocol）サーバーです。リアルタイムのレースアドバイス、車両の監視、テレメトリ分析、そしてレースデータに関する会話型インタラクションを提供します。

🚀 クイックスタート

このサーバーを使うことで、iRacingのテレメトリデータからアクション可能なレースの洞察を得ることができます。以下の手順でサーバーを起動し、機能を試してみましょう。

✨ 主な機能

コア機能

• ライブテレメトリ処理：pyirsdkを通じてiRacingからのリアルタイムデータを取得
• 高度な分析：G力計算、レースライン分析、ギア最適化
• レースAIコーチ：運転スタイルと状況に基づいたパーソナライズされたアドバイス
• 車両監視システム：交通状況の把握と位置情報の提供
• パフォーマンス分析：ラップごとのブレイクダウンと改善提案
• セッション追跡：長期的なパフォーマンス傾向と統計情報

MCP統合

• 5つのインタラクティブツール：直接的なテレメトリアクセスと分析機能
• 3つのライブリソース：継続的な監視のためのストリーミングデータフィード
• 3つのAIプロンプト：専門的なコーチングパーソナリティ（コーチ、スポッター、セットアップアナリスト）
• 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

クライアントは指定されたホストとポートに接続し、実際のiRacingストリームと同じ構造の改行区切りのJSONテレメトリフレームを受信できます。

GUIでの起動

インストール後、小さなGUIを使用してサーバーを起動できます。

race-mcp-gui

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

戻り値：速度、RPM、位置、G力、レースライン分析を含む完全なテレメトリデータ

2. spot_cars

目的：状況認識のために近くの車両を識別して分析

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

戻り値：相対位置、速度、軌道予測を含む近くの車両のリスト

3. get_racing_advice

目的：現在の状況に基づいてAIによるコーチングアドバイスを取得

{
  "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

ターンの位置とレースラインデータを含むトラック固有の情報

🤖 AIプロンプト

1. racing_coach

パーソナリティ：プロのレースインストラクター 焦点：技術の改善と戦略的なアドバイス ユースケース：一般的なレースの改善と学習

2. car_spotter

パーソナリティ：安全と位置決めに重点を置いた経験豊富なスポッター 焦点：交通管理と状況認識 ユースケース：レース状況と交通のナビゲーション

3. setup_analyst

パーソナリティ：技術的なセットアップエンジニア 焦点：車両のセットアップ最適化とハンドリング分析 ユースケース：車両のセットアップ調整と技術的な調整

🧪 テスト

テストクライアントの実行

テストクライアントは、サーバーのすべての機能と対話する包括的な方法を提供します。

# サーバーのすべての機能をテスト
python test_client.py

# 自動テスト用の起動スクリプトを使用
./start_server.sh --test

テストクライアントの機能

• ツールテスト：現実的なパラメータですべての5つのMCPツールをテスト
• リソースアクセス：すべての3つのライブリソースを検証
• プロンプトテスト：すべての3つのAIコーチングプロンプトを実行
• エラーハンドリング：サーバーの回復力とエラー応答をテスト
• パフォーマンス：応答時間とデータ検証を表示

手動でのサーバーテスト

# 手動でサーバーを起動し、直接のJSON - RPC呼び出しでテスト
python -m race_mcp_server

# 別のターミナルで、stdinを介して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 connection failed"

   • iRacingが実行中でセッションに入っていることを確認
   • iRacingのテレメトリ出力が有効になっていることを確認
   • iRacingが利用できない場合、サーバーはシミュレーションモードで実行されます

2. "Tool execution failed"

   • サーバーログで詳細なエラーメッセージを確認
   • ツールの引数が期待されるスキーマと一致することを確認
   • サーバーを再起動してみる

3. "Resource access failed"

   • 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"          # Model Context Protocolフレームワーク
pyirsdk = ">=1.3.0"      # iRacing SDK統合
pydantic = ">=2.0.0"     # データ検証とシリアライゼーション
aiofiles = ">=0.8.0"     # 非同期ファイル操作

システム要件

• OS：Windows、macOS、またはLinux
• Python：3.8以上（3.10.12でテスト済み）
• メモリ：100MB以上の空き容量
• iRacing：テレメトリが有効な最近のバージョン（オプション - なしでもサーバーはシミュレーションモードで実行されます）

オプションの依存関係

• pytest：拡張テストスイートの実行用
• MCP Client：統合用のMCP互換クライアント

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細はLICENSEファイルを参照してください。

🏆 謝辞

• iRacing：包括的なテレメトリAPIの提供
• MCP Community：優れたModel Context Protocolフレームワーク
• Racing Community：フィードバックと機能提案

ラップタイムを改善したいですか？サーバーを起動し、テストクライアントを実行して実際に動作を確認してみましょう！🏎️💨

設定

サーバーは環境変数を通じて設定できます。

• 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  │
└─────────────────┘    └─────────────────┘    └─────────────────┘

開発

# テストを実行
pytest

# コードをフォーマット
black src/
isort src/

# 型チェック
mypy src/

ライセンス

MITライセンス