JVLink MCP Server

Instructions

Implementation Reference

• src/jvlink_mcp_server/database/high_level_api.py:458-508 (handler)

  `_horse_history_impl` function in `high_level_api.py` implements the actual database querying logic to retrieve horse race history for both JRA and NAR records.

  def _horse_history_impl(
      db_connection,
      horse_name: str,
      year_from: Optional[str] = None,
      source: str = 'jra'
  ) -> pd.DataFrame:
      """馬の戦績の共通実装（JRA/NAR兼用）"""
      tables = _SOURCE_TABLES[source]
      # Bameiカラムのインデックスを自動作成（未作成の場合）
      _ensure_bamei_index(db_connection, tables['se'])
      venue_map = ALL_VENUE_NAMES if source == 'nar' else VENUE_NAMES
  
      conditions = [
          "s.Bamei LIKE ?",
          "s.KakuteiJyuni IS NOT NULL",
          "s.KakuteiJyuni > 0"
      ]
      query_params: List = ['%' + horse_name + '%']
  
      if year_from:
          year_val = _validate_year(year_from)
          conditions.append("s.Year >= ?")
          query_params.append(year_val)
  
      where_clause = " AND ".join(conditions)
  
      query = f"""
      SELECT s.Year || '-' || s.MonthDay as race_date, s.JyoCD as venue_code,
          r.Hondai as race_name, r.Kyori as distance,
          s.KakuteiJyuni as finish, s.Ninki as popularity,
          s.KisyuRyakusyo as jockey, s.Time as time, s.Bamei as horse_name
      FROM {tables['se']} s
      JOIN {tables['ra']} r
          ON s.Year = r.Year AND s.MonthDay = r.MonthDay AND s.JyoCD = r.JyoCD
          AND s.Kaiji = r.Kaiji AND s.Nichiji = r.Nichiji AND s.RaceNum = r.RaceNum
      WHERE {where_clause}
      ORDER BY s.Year DESC, s.MonthDay DESC
      """
  
      df = db_connection.execute_safe_query(query, params=tuple(query_params))
  
      if df.empty:
          return pd.DataFrame(columns=['race_date', 'venue', 'race_name', 'distance',
                                      'finish', 'popularity', 'jockey', 'time'])
  
      df['venue'] = df['venue_code'].map(venue_map)
      df = df.drop(columns=['venue_code'])
      df['finish'] = df['finish'].astype(str).str.lstrip('0').replace('', '0').astype(int)
      df['popularity'] = df['popularity'].astype(str).str.lstrip('0').replace('', '0').astype(int)
      df.attrs['query'] = query
      return df

• src/jvlink_mcp_server/server.py:524-540 (registration)

  The tool `horse_history` is registered in `server.py` and maps to `get_horse_race_history` which invokes the `_get_horse_history` high-level API function.

  @mcp.tool(name="horse_history")
  def get_horse_race_history(
      horse_name: str,
      year_from: Optional[str] = None
  ) -> dict:
      """特定の馬の過去レース戦績を取得
  
      馬名を指定して、過去の出走履歴・着順・タイムなどを一覧できます。
      """
      with DatabaseConnection() as db:
          df = _get_horse_history(db, horse_name=horse_name, year_from=year_from)
          return {
              "horse_name": horse_name,
              "total_races": len(df),
              "data": df.to_dict(orient="records"),
              "columns": df.columns.tolist()
          }