Fred St Louis MCP

Instructions

Implementation Reference

• fred_mcp/tools.py:38-43 (handler)

  Main handler function for the geofred_request MCP tool. Decorated with @mcp.tool() to register it as an MCP tool. Accepts an endpoint path and JSON params string, parses the JSON, and delegates to _geofred_get helper to make the actual API call.

  @mcp.tool()
  @_tool_error_boundary
  async def geofred_request(endpoint: str, params_json: str = "{}") -> dict[str, Any]:
      """Call any GeoFRED API endpoint path directly."""
      params = _parse_json_object(params_json)
      return await _geofred_get(endpoint, params)

• fred_mcp/client.py:244-245 (helper)

  Helper function that makes HTTP GET requests to the GeoFRED API. Uses the GEOFRED_API_BASE URL (https://api.stlouisfed.org/geofred) and delegates to the generic _http_get_json function with retry logic and error handling.

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

• fred_mcp/client.py:64-71 (helper)

  Helper function that validates and parses the params_json input string. Ensures the input is valid JSON and that the parsed value is a dictionary object. Raises ValueError if validation fails.

  def _parse_json_object(raw: str) -> dict[str, Any]:
      try:
          parsed = json.loads(raw)
      except json.JSONDecodeError as exc:
          raise ValueError(f"Invalid JSON: {exc}") from exc
      if not isinstance(parsed, dict):
          raise ValueError("JSON value must be an object")
      return parsed

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

  Creates and configures the FastMCP server instance that provides the @mcp.tool() decorator used to register geofred_request as an MCP tool. The server is named 'fred-mcp' and includes instructions for querying FRED APIs.

  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/errors.py:41-67 (helper)

  Error boundary decorator applied to geofred_request via @_tool_error_boundary. Wraps the handler to catch and convert exceptions (FredServerError, ValueError, etc.) into structured error payloads for consistent error handling.

  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