Fred St Louis MCP

Instructions

Implementation Reference

• fred_mcp/tools.py:30-35 (handler)

  The fred_request tool handler function. It takes an endpoint string and optional JSON params, parses the params, and delegates to _fred_get to make the FRED API v1 call. Decorated with @mcp.tool() for MCP registration and @_tool_error_boundary for error handling.

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

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

  The _fred_get helper function that makes the actual HTTP call to the FRED API v1 base URL. Called by the fred_request handler.

  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/client.py:64-71 (helper)

  The _parse_json_object helper function that parses the params_json string argument into a dictionary. Validates that the JSON is an object.

  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 the FastMCP instance named 'fred-mcp' which is imported and used via @mcp.tool() decorator to register tools like fred_request.

  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)

  The _tool_error_boundary decorator that wraps the fred_request handler to catch exceptions (FredServerError, ValueError, etc.) and convert them to error payload dictionaries for graceful 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