Grokipedia MCP Server

Instructions

Implementation Reference

• grokipedia_mcp/server.py:119-125 (registration)

  Registers the 'get_page' tool with the FastMCP server using the @mcp.tool decorator, specifying tool annotations indicating it is read-only, non-destructive, and idempotent.
  @mcp.tool( annotations=ToolAnnotations( readOnlyHint=True, destructiveHint=False, idempotentHint=True ) )
• grokipedia_mcp/server.py:126-207 (handler)

  The core handler function for the 'get_page' tool. It fetches the page using the Grokipedia API client, handles cases where the page is not found by suggesting alternatives, truncates long content, formats a markdown preview with metadata, citations summary, and returns a CallToolResult with both text and structured page data.
  async def get_page( slug: Annotated[str, Field(description="Unique slug identifier of the page to retrieve")], max_content_length: Annotated[int, Field(description="Maximum length of content to return (default: 5000)", ge=100)] = 5000, ctx: Context[ServerSession, AppContext] | None = None, ) -> CallToolResult: """Get complete page information including metadata, content preview, and citations summary.""" if ctx is None: raise ValueError("Context is required") await ctx.debug(f"Fetching page: '{slug}'") try: client = ctx.request_context.lifespan_context.client result = await client.get_page(slug=slug, include_content=True) if not result.found or result.page is None: await ctx.warning(f"Page not found: '{slug}', searching for alternatives") search_result = await client.search(query=slug, limit=5) if search_result.results: suggestions = [f"{r.title} ({r.slug})" for r in search_result.results[:3]] await ctx.info(f"Found {len(search_result.results)} similar pages") raise ValueError( f"Page not found: {slug}. Did you mean one of these? {', '.join(suggestions)}" ) raise ValueError(f"Page not found: {slug}") await ctx.info(f"Retrieved page: '{result.page.title}' ({slug})") page = result.page content_len = len(page.content) if page.content else 0 is_truncated = content_len > max_content_length text_parts = [ f"# {page.title}", "", f"**Slug:** {page.slug}", ] if page.description: text_parts.extend(["", f"**Description:** {page.description}", ""]) if page.content: preview_length = min(1000, max_content_length) text_parts.extend(["", "## Content Preview", "", page.content[:preview_length]]) if content_len > preview_length: text_parts.append(f"\n... (showing first {preview_length} of {content_len} chars)") if page.citations: text_parts.extend(["", f"## Citations ({len(page.citations)} total)", ""]) for i, citation in enumerate(page.citations[:5], 1): text_parts.append(f"{i}. {citation.title}: {citation.url}") if len(page.citations) > 5: text_parts.append(f"... and {len(page.citations) - 5} more") page_dict = page.model_dump() if is_truncated: page_dict["content"] = page.content[:max_content_length] page_dict["_content_truncated"] = True page_dict["_original_length"] = content_len await ctx.warning( f"Content truncated from {content_len} to {max_content_length} chars. " f"Use get_page_content tool for full content access." ) return CallToolResult( content=[TextContent(type="text", text="\n".join(text_parts))], structuredContent=page_dict, ) except GrokipediaNotFoundError as e: await ctx.error(f"Page not found: {e}") raise ValueError(f"Page not found: {slug}") from e except GrokipediaBadRequestError as e: await ctx.error(f"Bad request: {e}") raise ValueError(f"Invalid page slug: {e}") from e except GrokipediaNetworkError as e: await ctx.error(f"Network error: {e}") raise RuntimeError(f"Failed to connect to Grokipedia API: {e}") from e except GrokipediaAPIError as e: await ctx.error(f"API error: {e}") raise RuntimeError(f"Grokipedia API error: {e}") from e
• grokipedia_mcp/server.py:126-130 (schema)

  Input schema defined via Annotated parameters with Pydantic Field descriptions and constraints for the get_page tool.
  async def get_page( slug: Annotated[str, Field(description="Unique slug identifier of the page to retrieve")], max_content_length: Annotated[int, Field(description="Maximum length of content to return (default: 5000)", ge=100)] = 5000, ctx: Context[ServerSession, AppContext] | None = None, ) -> CallToolResult: