mindmeister_get_map_image

Instructions

Implementation Reference

• src/mindmeister_mcp/server.py:236-282 (handler)

  Handler function for mindmeister_get_map_image tool. Fetches a map image/thumbnail from GET /map_images/{id}, returns base64-encoded PNG data (or JSON if API returns JSON).

  @mcp.tool(
      name="mindmeister_get_map_image",
      annotations={
          "title": "Get MindMeister Map Image",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )
  async def mindmeister_get_map_image(params: GetMapImageInput) -> str:
      """Get the image/thumbnail for a MindMeister map.
  
      Retrieves the map image via GET /map_images/{id}. Returns the
      image as base64-encoded data along with metadata.
  
      Args:
          params: GetMapImageInput with map_id (str).
  
      Returns:
          str: JSON with "map_id", "content_type", "content_base64",
               and "size_bytes".
      """
      try:
          resp = await api_request(
              _token(),
              "GET",
              f"/map_images/{params.map_id}",
              accept="image/png",
              timeout=60.0,
          )
          content_type = resp.headers.get("content-type", "image/png")
  
          # If the API returns JSON (e.g. a URL), return as-is
          if "json" in content_type:
              return _json_response(resp.json())
  
          encoded = base64.b64encode(resp.content).decode("ascii")
          result = {
              "map_id": params.map_id,
              "content_type": content_type,
              "content_base64": encoded,
              "size_bytes": len(resp.content),
          }
          return _json_response(result)
      except MindMeisterAPIError as exc:
          return f"Error: {exc}"

• src/mindmeister_mcp/server.py:236-245 (registration)

  Registration of mindmeister_get_map_image as an MCP tool via the @mcp.tool decorator with annotations.

  @mcp.tool(
      name="mindmeister_get_map_image",
      annotations={
          "title": "Get MindMeister Map Image",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )

• src/mindmeister_mcp/models.py:66-75 (schema)

  Pydantic schema/input model for mindmeister_get_map_image. Defines a single required field: map_id (non-empty string).

  class GetMapImageInput(BaseModel):
      """Input for retrieving a map's image/thumbnail."""
  
      model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
  
      map_id: str = Field(
          ...,
          description="The MindMeister map ID",
          min_length=1,
      )

• src/mindmeister_mcp/server.py:45-53 (helper)

  Helper functions used by the handler: _token() for auth, _json_response() for formatting output.

  def _token() -> str:
      """Return the current token (re-read env each call for flexibility)."""
      return os.environ.get("MINDMEISTER_API_TOKEN", "") or MINDMEISTER_API_TOKEN
  
  
  def _json_response(data: Any) -> str:
      """Serialize data to a pretty-printed JSON string."""
      return json.dumps(data, indent=2, ensure_ascii=False)

• src/mindmeister_mcp/client.py:40-97 (helper)

  HTTP client helper that performs the actual API call to MindMeister API v2, with auth token, custom Accept header, and timeout support.

  async def api_request(
      token: str,
      method: str,
      path: str,
      *,
      params: Optional[Dict[str, Any]] = None,
      headers_extra: Optional[Dict[str, str]] = None,
      accept: str = "application/json",
      timeout: float = DEFAULT_TIMEOUT,
  ) -> httpx.Response:
      """Execute an authenticated request against MindMeister API v2.
  
      Returns the raw httpx.Response so callers can handle both JSON
      and binary (file export / image) responses.
  
      Raises:
          MindMeisterAPIError: on any HTTP or network error with an
              actionable message.
      """
      if not token:
          raise MindMeisterAPIError(
              "MINDMEISTER_API_TOKEN is not set. "
              "Export a personal access token from MindMeister "
              "(Account → API → Personal Access Tokens) and set it as an "
              "environment variable."
          )
  
      url = f"{BASE_URL}{path}"
      request_headers: Dict[str, str] = {
          "Authorization": f"Bearer {token}",
          "Accept": accept,
      }
      if headers_extra:
          request_headers.update(headers_extra)
  
      try:
          async with httpx.AsyncClient(timeout=timeout) as client:
              response = await client.request(
                  method,
                  url,
                  params=params,
                  headers=request_headers,
              )
              response.raise_for_status()
              return response
      except httpx.HTTPStatusError as exc:
          raise MindMeisterAPIError(
              _handle_http_error(exc), status_code=exc.response.status_code
          ) from exc
      except httpx.TimeoutException as exc:
          raise MindMeisterAPIError(
              "Request timed out. The MindMeister API may be slow — try again."
          ) from exc
      except httpx.RequestError as exc:
          raise MindMeisterAPIError(
              f"Network error: {type(exc).__name__}. Check your internet connection."
          ) from exc