Grok MCP

Implementation Reference

• src/server.py:189-232 (handler)

  Main handler function for chat_with_vision tool. Accepts prompt, session, model, image_paths, image_urls, and detail parameters. Loads chat history, processes images (base64 encoding for paths, URLs for remote images), creates XAI chat client, sends multimodal message with images and prompt, saves conversation history to session, and returns the AI response.

  @mcp.tool()
  async def chat_with_vision(
      prompt: str,
      session: Optional[str] = None,
      model: str = "grok-4",
      image_paths: Optional[List[str]] = None,
      image_urls: Optional[List[str]] = None,
      detail: str = "auto"
  ):
      history = load_history(session) if session else []
  
      client = Client(api_key=XAI_API_KEY)
      chat = client.chat.create(model=model, store_messages=False)
  
      for message in history:
          if message["role"] == "user":
              chat.append(user(message["content"]))
          elif message["role"] == "assistant":
              chat.append(assistant(message["content"]))
  
      user_content = []
      if image_paths:
          for path in image_paths:
              ext = Path(path).suffix.lower().replace('.', '')
              if ext not in ["jpg", "jpeg", "png"]:
                  raise ValueError(f"Unsupported image type: {ext}")
              base64_img = encode_image_to_base64(path)
              user_content.append(image(image_url=f"data:image/{ext};base64,{base64_img}", detail=detail))
  
      if image_urls:
          for url in image_urls:
              user_content.append(image(image_url=url, detail=detail))
  
      user_content.append(prompt)
      chat.append(user(*user_content))
      response = chat.sample()
      client.close()
  
      if session:
          history.append({"role": "user", "content": prompt, "time": datetime.now().strftime("%d.%m.%Y %H:%M:%S")})
          history.append({"role": "assistant", "content": response.content, "time": datetime.now().strftime("%d.%m.%Y %H:%M:%S")})
          save_history(session, history)
  
      return response.content

• src/server.py:189-189 (registration)

  Tool registration via @mcp.tool() decorator, which registers the chat_with_vision function as an MCP tool with the FastMCP server.

  @mcp.tool()

• src/utils.py:12-17 (helper)

  Helper function encode_image_to_base64 that reads an image file from disk and encodes it to base64 string for API transmission. Validates file existence and returns UTF-8 decoded base64 string.

  def encode_image_to_base64(image_path: str):
      path = Path(image_path)
      if not path.exists():
          raise FileNotFoundError(f"Image file not found: {image_path}")
      with open(image_path, "rb") as image_file:
          return base64.b64encode(image_file.read()).decode("utf-8")

• src/utils.py:39-43 (helper)

  Helper function load_history that loads chat session history from a JSON file in the chats/ directory. Returns empty list if session file doesn't exist.

  def load_history(session: str):
      path = Path("chats") / f"{session}.json"
      if path.exists():
          return json.loads(path.read_text())
      return []

• src/utils.py:46-48 (helper)

  Helper function save_history that persists chat conversation history to a JSON file in the chats/ directory. Creates the directory if it doesn't exist.

  def save_history(session: str, history: list):
      Path("chats").mkdir(exist_ok=True)
      (Path("chats") / f"{session}.json").write_text(json.dumps(history, indent=2, ensure_ascii=False))