e-Stat MCP

Instructions

Implementation Reference

• e_stats_mcp/tools/stats.py:68-111 (handler)

  The core handler function implementing the get_stats_list tool. It constructs parameters using _build_stats_list_params and calls the e-Stat API endpoint 'json/getStatsList' via _make_request.

  async def get_stats_list(
      search_word: str | None = None,
      survey_years: str | None = None,
      stats_field: str | None = None,
      stats_code: str | None = None,
      gov_code: str | None = None,
      open_years: str | None = None,
      stats_name_list: str | None = None,
      start_position: int | None = None,
      updated_date: str | None = None,
      limit: int = 10,
  ) -> dict:
      """統計表情報を検索する.
  
      Args:
          search_word: 検索キーワード（統計表名、調査名など）
          survey_years: 調査年（YYYY形式、範囲指定はYYYY-YYYY）
          stats_field: 統計分野コード（2桁）
          stats_code: 政府統計コード（5桁または8桁）
          gov_code: 政府機関コード
          open_years: 公開年（YYYY形式、範囲指定はYYYY-YYYY）
          stats_name_list: 調査・集計の種類
          start_position: データ取得開始位置
          updated_date: 更新日（YYYY-MM-DD）
          limit: 取得件数（デフォルト10件、最大100件）
  
      Returns:
          統計表情報のリスト
      """
      params = _build_stats_list_params(
          search_word=search_word,
          survey_years=survey_years,
          stats_field=stats_field,
          stats_code=stats_code,
          gov_code=gov_code,
          open_years=open_years,
          stats_name_list=stats_name_list,
          start_position=start_position,
          updated_date=updated_date,
          limit=limit,
      )
  
      response = await _make_request("json/getStatsList", params)
      return cast(dict[str, Any], response)

• e_stats_mcp/main.py:46-46 (registration)

  Registers the get_stats_list function as an MCP tool using the FastMCP decorator.

  mcp.tool()(get_stats_list)

• e_stats_mcp/tools/stats.py:114-152 (helper)

  Helper function to build query parameters specifically for the getStatsList API endpoint.

  def _build_stats_list_params(
      *,
      search_word: str | None = None,
      survey_years: str | None = None,
      stats_field: str | None = None,
      stats_code: str | None = None,
      gov_code: str | None = None,
      open_years: str | None = None,
      stats_name_list: str | None = None,
      start_position: int | None = None,
      updated_date: str | None = None,
      limit: int = 10,
  ) -> dict:
      """getStatsList系の共通パラメータを組み立てる."""
      params = {
          "lang": "J",
          "limit": str(min(limit, 100)),
      }
  
      if search_word:
          params["searchWord"] = search_word
      if survey_years:
          params["surveyYears"] = survey_years
      if stats_field:
          params["statsField"] = stats_field
      if stats_code:
          params["statsCode"] = stats_code
      if gov_code:
          params["governmentCode"] = gov_code
      if open_years:
          params["openYears"] = open_years
      if stats_name_list:
          params["statsNameList"] = stats_name_list
      if start_position:
          params["startPosition"] = str(start_position)
      if updated_date:
          params["updatedDate"] = updated_date
  
      return params

• e_stats_mcp/tools/stats.py:17-66 (helper)

  General helper function to make HTTP requests to the e-Stat API, used by get_stats_list.

  async def _make_request(
      endpoint: str,
      params: dict | None = None,
      *,
      method: str = "GET",
      format: str = "json",
      data: dict | None = None,
  ) -> dict[str, Any] | str:
      """e-Stat APIへのリクエストを実行する.
  
      Args:
          endpoint: APIエンドポイント（例: \"json/getStatsList\"）
          params: クエリパラメータ
          method: HTTPメソッド（GET/POST）
          format: レスポンス形式（\"json\" または \"csv\"）
          data: POST時のフォームデータ
  
      Returns:
          JSONの場合はdict、CSVの場合は文字列
  
      Raises:
          ValueError: APIキーが設定されていない場合
          httpx.HTTPError: API通信エラー
      """
      settings = get_settings()
      if not settings.E_STAT_APP_ID:
          raise ValueError(
              "E_STAT_APP_ID環境変数が設定されていません。"
              "https://www.e-stat.go.jp/api/ からアプリケーションIDを取得してください。"
          )
  
      url = f"{E_STAT_API_BASE}/{endpoint}"
      request_params = {"appId": settings.E_STAT_APP_ID, **(params or {})}
      http_method = method.upper()
  
      async with httpx.AsyncClient() as client:
          if http_method == "POST":
              response = await client.post(
                  url, params=request_params, data=data, timeout=DEFAULT_TIMEOUT
              )
          else:
              response = await client.get(
                  url, params=request_params, timeout=DEFAULT_TIMEOUT
              )
  
          response.raise_for_status()
          if format == "csv":
              return response.text
          return response.json()

• e_stats_mcp/main.py:46-47 (registration)

  Tool registration block including get_stats_list and related CSV variant.

  mcp.tool()(get_stats_list)
  mcp.tool()(get_stats_list_csv)