Fred St Louis MCP

Instructions

Implementation Reference

• fred_mcp/tools.py:46-51 (handler)

  The main handler function for the fred_v2_request tool. It is decorated with @mcp.tool() to register it as an MCP tool and @_tool_error_boundary for error handling. Takes endpoint and params_json parameters, parses the JSON params, and delegates to _fred_v2_get to make the actual API call.

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

• fred_mcp/client.py:248-255 (helper)

  The _fred_v2_get helper function that executes the HTTP request to the FRED API v2 endpoint. It calls _http_get_json with the FRED_V2_API_BASE URL, passes the API key via headers (instead of query params), and handles the actual API communication with retry logic and error handling.

  async def _fred_v2_get(endpoint: str, params: dict[str, Any]) -> dict[str, Any]:
      return await _http_get_json(
          FRED_V2_API_BASE,
          endpoint,
          params,
          headers={"api_key": _fred_api_key()},
          include_api_key_query=False,
      )

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

  The _parse_json_object helper function that validates and parses the params_json string input. It ensures the JSON is valid and is a dictionary object, raising a ValueError if either condition is not met.

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

  The _tool_error_boundary decorator that wraps tool handlers with comprehensive error handling. Catches FredServerError, ValueError, and other exceptions, returning appropriate error payloads. Ensures CancelledError propagates correctly and logs unhandled exceptions.

  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/app.py:3-8 (registration)

  The FastMCP instance creation that provides the @mcp.tool() decorator used to register fred_v2_request as an MCP tool. The instance is configured with the name 'fred-mcp' and instructions describing the available API endpoints.

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