Fatebook MCP Server

Instructions

Implementation Reference

• src/fatebook_mcp/__main__.py:20-85 (handler)

  The primary handler function for the 'list_questions' tool. Decorated with @mcp.tool() for registration and execution. Fetches questions from Fatebook API, parses with Pydantic, and returns structured list.

  @mcp.tool()
  async def list_questions(
      ctx: Context,
      apiKey: str = "",
      resolved: bool = False,
      unresolved: bool = False,
      searchString: str = "",
      limit: int = 100,
      cursor: str = "",
      detailed: bool = False,
  ) -> QuestionsList:
      """List Fatebook questions with optional filtering
  
      Returns a list of Question objects. By default returns core fields only.
      Set detailed=True to include all available fields (forecasts, comments, etc.).
      """
  
      await ctx.info(
          f"list_questions called with resolved={resolved}, unresolved={unresolved}, searchString='{searchString}', limit={limit}, detailed={detailed}"
      )
  
      api_key = apiKey or os.getenv("FATEBOOK_API_KEY")
      if not api_key:
          await ctx.error("API key is required but not provided")
          raise ValueError(
              "API key is required (provide as parameter or set FATEBOOK_API_KEY environment variable)"
          )
  
      params: dict[str, Any] = {"apiKey": api_key}
  
      # Add optional parameters
      if resolved:
          params["resolved"] = resolved
      if unresolved:
          params["unresolved"] = unresolved
      if searchString:
          params["searchString"] = searchString
      params["limit"] = limit
      if cursor:
          params["cursor"] = cursor
  
      await ctx.debug(f"Making API request with params: {params}")
  
      try:
          async with httpx.AsyncClient() as client:
              response = await client.get("https://fatebook.io/api/v0/getQuestions", params=params)
              response.raise_for_status()
  
              data = response.json()
  
              # Parse response using Pydantic model
              questions_response = QuestionsResponse(**data)
              questions = questions_response.items
  
              await ctx.info(f"Successfully retrieved {len(questions)} questions")
  
              # Return as QuestionsList with 'result' field to match MCP schema expectations
              return QuestionsList(result=questions)
  
      except httpx.HTTPError as e:
          await ctx.error(f"HTTP error occurred: {e}")
          raise
      except Exception as e:
          await ctx.error(f"Unexpected error occurred: {e}")
          raise

• src/fatebook_mcp/models.py:187-202 (schema)

  Pydantic schemas used by list_questions: QuestionsResponse parses API data, QuestionsList wraps result for MCP tool response.

  class QuestionsResponse(BaseModel):
      """Response from getQuestions endpoint"""
  
      items: List[Question]
      cursor: Optional[str] = None
  
  
  class QuestionsList(BaseModel):
      """List of questions for MCP responses - matches expected MCP schema"""
  
      result: List[Question]
  
      class Config:
          populate_by_name = True
          by_alias = True

• src/fatebook_mcp/models.py:73-114 (schema)

  Core Question Pydantic model used in list_questions responses, defining structure for individual questions with fields, validators, and formatting methods.

  class Question(BaseModel):
      """Fatebook question model with optional fields for detailed responses"""
  
      # Core fields (id is optional since getQuestion doesn't return it)
      id: Optional[str] = None
      title: str
      type: Literal["BINARY", "NUMERIC", "MULTIPLE_CHOICE"] = "BINARY"
      resolved: bool = False
  
      # Timestamps
      created_at: datetime = Field(alias="createdAt")
      resolve_by: datetime = Field(alias="resolveBy")
      resolved_at: Optional[datetime] = Field(None, alias="resolvedAt")
  
      # Resolution information
      resolution: Optional[Literal["YES", "NO", "AMBIGUOUS"]] = None
  
      # Additional content (typically in detailed view)
      notes: Optional[str] = None
  
      # Related data (typically in detailed view)
      forecasts: Optional[List[Forecast]] = Field(
          default=None, description="List of forecasts on this question"
      )
      tags: Optional[List[Tag]] = Field(default=None, description="Tags associated with the question")
      comments: Optional[List[Comment]] = Field(default=None, description="Comments on the question")
  
      # Visibility settings (typically in detailed view)
      shared_publicly: Optional[bool] = Field(None, alias="sharedPublicly")
      unlisted: Optional[bool] = None
      hide_forecasts_until: Optional[datetime] = Field(None, alias="hideForecastsUntil")
      share_with_lists: Optional[List[str]] = Field(None, alias="shareWithLists")
      share_with_email: Optional[List[str]] = Field(None, alias="shareWithEmail")
  
      # Additional fields from getQuestion endpoint
      your_latest_prediction: Optional[str] = Field(None, alias="yourLatestPrediction")
      question_scores: Optional[List] = Field(None, alias="questionScores")
  
      class Config:
          populate_by_name = True
          by_alias = True  # Use aliases when serializing

• src/fatebook_mcp/__main__.py:9-20 (registration)

  Import of schema models required for list_questions tool.

  from .models import Question, QuestionReference, QuestionsList, QuestionsResponse
  
  load_dotenv()
  
  mcp = FastMCP("Fatebook MCP Server")
  
  
  # Type alias for httpx params to handle mypy type checking
  ParamsType = dict[str, str | int | float | bool | None]
  
  
  @mcp.tool()

• test_client.py:120-120 (helper)

  Test file referencing list_questions as an expected registered tool.

  expected_tools = {"list_questions", "create_question", "count_forecasts"}