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"}