Fred St Louis MCP

Instructions

Implementation Reference

• fred_mcp/tools.py:58-82 (handler)

  The main handler function for the 'get_category' MCP tool. Decorated with @mcp.tool() for registration and @_tool_error_boundary for error handling. Calls _fred_get to fetch category data from FRED API and returns the first category or an error payload if not found.

  @mcp.tool()
  @_tool_error_boundary
  async def get_category(
      category_id: int = 0,
      realtime_start: str | None = None,
      realtime_end: str | None = None,
  ) -> dict[str, Any]:
      """fred/category"""
      data = await _fred_get(
          "category",
          {
              "category_id": category_id,
              "realtime_start": realtime_start,
              "realtime_end": realtime_end,
          },
      )
      categories = data.get("categories", [])
      if not categories:
          return _error_payload(
              f"Category '{category_id}' not found",
              code="not_found",
              error_type="not_found",
              details={"resource": "category", "resource_id": category_id},
          )
      return categories[0]

• fred_mcp/app.py:1-8 (registration)

  Creates the FastMCP instance 'mcp' which provides the @mcp.tool() decorator used to register the get_category function as an MCP tool.

  from mcp.server.fastmcp import FastMCP
  
  mcp = FastMCP(
      "fred-mcp",
      instructions=(
          "Query FRED API v1, GeoFRED maps API, and FRED API v2 release observations."
      ),
  )

• fred_mcp/client.py:240-241 (helper)

  The _fred_get helper function that makes the actual HTTP request to the FRED API. Called by get_category to fetch category data.

  async def _fred_get(endpoint: str, params: dict[str, Any]) -> dict[str, Any]:
      return await _http_get_json(FRED_API_BASE, endpoint, params)

• fred_mcp/errors.py:41-67 (helper)

  The _tool_error_boundary decorator that wraps the get_category handler to catch and convert exceptions (FredServerError, ValueError, etc.) into standardized error payloads.

  def _tool_error_boundary(
      func: Callable[..., Awaitable[dict[str, Any]]],
  ) -> Callable[..., Awaitable[dict[str, Any]]]:
      @wraps(func)
      async def wrapper(*args: Any, **kwargs: Any) -> dict[str, Any]:
          try:
              return await func(*args, **kwargs)
          except asyncio.CancelledError:
              raise
          except FredServerError as exc:
              return exc.payload
          except ValueError as exc:
              return _error_payload(
                  str(exc),
                  code="validation_error",
                  error_type="validation_error",
              )
          except Exception as exc:
              logger.exception("Unhandled tool error in '%s'", func.__name__)
              return _error_payload(
                  "Internal server error",
                  code="internal_error",
                  error_type="internal_error",
                  details={"exception_type": type(exc).__name__},
              )
  
      return wrapper

• fred_mcp/errors.py:15-38 (helper)

  The _error_payload helper function that creates standardized error response dictionaries. Used by get_category when a category is not found.

  def _error_payload(
      message: str,
      *,
      code: str,
      error_type: str,
      base_url: str | None = None,
      endpoint: str | None = None,
      status_code: int | None = None,
      retryable: bool = False,
      details: dict[str, Any] | None = None,
  ) -> dict[str, Any]:
      # Keep top-level "error" for backwards compatibility with existing clients.
      return {
          "error": message,
          "error_details": {
              "type": error_type,
              "code": code,
              "base_url": base_url,
              "endpoint": endpoint.strip("/") if endpoint else None,
              "status_code": status_code,
              "retryable": retryable,
              "details": details or {},
          },
      }