Fatebook MCP Server

Instructions

Implementation Reference

• src/fatebook_mcp/__main__.py:87-125 (handler)

  The handler function for the 'get_question' tool. It makes an API call to Fatebook's getQuestion endpoint, adds the question ID, parses the response into a Question model, and returns it. Registered via @mcp.tool() decorator.

  @mcp.tool()
  async def get_question(ctx: Context, questionId: str, apiKey: str = "") -> Question:
      """Get detailed information about a specific Fatebook question
  
      Returns a structured Question object with all available fields.
      """
  
      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: ParamsType = {"apiKey": api_key, "questionId": questionId}
  
      await ctx.debug(f"Making API request for question {questionId}")
  
      try:
          async with httpx.AsyncClient() as client:
              response = await client.get("https://fatebook.io/api/v0/getQuestion", params=params)
              response.raise_for_status()
  
              question_data = response.json()
              await ctx.info(f"Successfully retrieved question {questionId}")
  
              # Add the ID to the data since the API doesn't return it
              question_data["id"] = questionId
  
              # Parse as Question model and return it
              question = Question(**question_data)
              return question
  
      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:73-114 (schema)

  Pydantic model defining the input/output schema for the Question object returned by the get_question tool. Includes core fields, timestamps, resolution info, related data (forecasts, tags, comments), and API-specific fields.

  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:128-146 (helper)

  Supporting MCP resource handler for accessing question data via URI 'question://{question_id}', similar logic to the tool handler.

  @mcp.resource("question://{question_id}")
  async def get_question_resource(question_id: str) -> Question:
      """Get detailed information about a specific Fatebook question as a resource
  
      Provides read-only access to question data for loading into LLM context.
      """
      api_key = os.getenv("FATEBOOK_API_KEY")
      if not api_key:
          raise ValueError("API key is required (set FATEBOOK_API_KEY environment variable)")
      params: ParamsType = {"apiKey": api_key, "questionId": question_id}
      async with httpx.AsyncClient() as client:
          response = await client.get("https://fatebook.io/api/v0/getQuestion", params=params)
          response.raise_for_status()
          question_data = response.json()
          # Add the ID to the data since the API doesn't return it
          question_data["id"] = question_id
          question = Question(**question_data)
          return question