Grokipedia MCP Server

Instructions

Implementation Reference

• grokipedia_mcp/server.py:290-375 (handler)

  The core handler function for the 'get_page_citations' tool. It retrieves citations for a specified page slug via the Grokipedia API client, supports optional limiting, formats a human-readable markdown list of citations (with title, URL, description), provides structured JSON output including page details and citation data, logs debug/info/warning/error messages, and handles specific exceptions like not found, bad request, network, and API errors by raising appropriate ValueError or RuntimeError.

  async def get_page_citations(
      slug: Annotated[str, Field(description="Unique slug identifier of page to retrieve citations from")],
      limit: Annotated[int | None, Field(description="Maximum number of citations to return (optional, returns all if not specified)", ge=1)] = None,
      ctx: Context[ServerSession, AppContext] | None = None,
  ) -> CallToolResult:
      """Get the citations list for a specific page."""
      if ctx is None:
          raise ValueError("Context is required")
  
      await ctx.debug(f"Fetching citations for: '{slug}' (limit={limit})")
  
      try:
          client = ctx.request_context.lifespan_context.client
          result = await client.get_page(slug=slug, include_content=False)
  
          if not result.found or result.page is None:
              await ctx.warning(f"Page not found: '{slug}'")
              raise ValueError(f"Page not found: {slug}")
  
          page = result.page
          all_citations = page.citations or []
          total_count = len(all_citations)
          
          citations = all_citations[:limit] if limit else all_citations
          is_limited = limit and total_count > limit
          
          await ctx.info(
              f"Retrieved {len(citations)} of {total_count} citations for: '{page.title}'"
          )
          
          if not all_citations:
              text_output = f"# {page.title}\n\nNo citations found."
              structured = {
                  "slug": page.slug,
                  "title": page.title,
                  "citations": [],
                  "total_count": 0,
                  "returned_count": 0,
              }
          else:
              header = f"# {page.title}\n\n"
              if is_limited:
                  header += f"Showing {len(citations)} of {total_count} citations:\n"
              else:
                  header += f"Found {total_count} citations:\n"
              
              text_parts = [header]
              for i, citation in enumerate(citations, 1):
                  text_parts.append(f"{i}. **{citation.title}**")
                  text_parts.append(f"   URL: {citation.url}")
                  if citation.description:
                      text_parts.append(f"   Description: {citation.description}")
                  text_parts.append("")
              
              if is_limited:
                  text_parts.append(f"... and {total_count - len(citations)} more citations")
              
              text_output = "\n".join(text_parts)
              structured = {
                  "slug": page.slug,
                  "title": page.title,
                  "citations": [c.model_dump() for c in citations],
                  "total_count": total_count,
                  "returned_count": len(citations),
              }
              
              if is_limited:
                  structured["_limited"] = True
          
          return CallToolResult(
              content=[TextContent(type="text", text=text_output)],
              structuredContent=structured,
          )
  
      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:283-289 (registration)

  Registers the 'get_page_citations' tool with the MCP framework using the @mcp.tool decorator, specifying ToolAnnotations indicating it is read-only, non-destructive, and idempotent.

  @mcp.tool(
      annotations=ToolAnnotations(
          readOnlyHint=True,
          destructiveHint=False,
          idempotentHint=True
      )
  )

• grokipedia_mcp/server.py:291-294 (schema)

  Input schema defined via Annotated types with Pydantic Field metadata providing descriptions and validation (e.g., limit ge=1). Output type is CallToolResult with TextContent and structuredContent.

      slug: Annotated[str, Field(description="Unique slug identifier of page to retrieve citations from")],
      limit: Annotated[int | None, Field(description="Maximum number of citations to return (optional, returns all if not specified)", ge=1)] = None,
      ctx: Context[ServerSession, AppContext] | None = None,
  ) -> CallToolResult: