Street View MCP

Instructions

Implementation Reference

• src/street_view_mcp/server.py:22-86 (handler)

  The main handler function for the 'get_street_view' MCP tool. It parses inputs, calls the helper function to fetch the image from Google Street View API, converts it to bytes, and returns it as a FastMCP Image object.

  @mcp.tool()
  def get_street_view(
      filename: str,
      location: Optional[str] = None,
      lat_lng: Optional[str] = None,
      pano_id: Optional[str] = None,
      size: str = "600x400",
      heading: int = 0,
      pitch: int = 0,
      fov: int = 90,
      radius: int = 50,
      source: str = "default",
  ) -> Image:
      """
      Fetch a Street View image based on location, coordinates, or panorama ID and save to file.
      
      Args:
          filename: Required filename to save the image (must not already exist in output directory)
          location: The address to get Street View image for (e.g., "Empire State Building, NY")
          lat_lng: Comma-separated latitude and longitude (e.g., "40.748817,-73.985428")
          pano_id: Specific panorama ID to fetch
          size: Image dimensions as "widthxheight" (e.g., "600x400")
          heading: Camera heading in degrees (0-360)
          pitch: Camera pitch in degrees (-90 to 90)
          fov: Field of view in degrees (zoom level, 10-120)
          radius: Search radius in meters when using location or coordinates
          source: Limit Street View searches to selected sources ("default" or "outdoor")
          
      Returns:
          Image: The Street View image
          
      Raises:
          ValueError: If filename already exists in output directory
      """
      # Parse lat_lng string to tuple if provided
      lat_lng_tuple = None
      if lat_lng:
          try:
              lat, lng = map(float, lat_lng.split(','))
              lat_lng_tuple = (lat, lng)
          except (ValueError, TypeError):
              raise ValueError("Invalid lat_lng format. Use format: '40.714728,-73.998672'")
              
      # Fetch the image and save it
      pil_image = get_street_view_image(
          location=location,
          lat_lng=lat_lng_tuple,
          pano_id=pano_id,
          size=size,
          heading=heading,
          pitch=pitch,
          fov=fov,
          radius=radius,
          source=source,
          return_error_code=True,
          filename=filename,
      )
      
      # Convert PIL Image to bytes
      buffer = io.BytesIO()
      pil_image.save(buffer, format="JPEG")
      img_bytes = buffer.getvalue()
      
      # Return using FastMCP's Image helper
      return Image(data=img_bytes, format="jpeg")

• src/street_view_mcp/street_view.py:23-113 (helper)

  Helper function that performs the actual API call to Google Maps Street View Static API, handles parameters, saves the image if filename provided, and returns the PIL Image.

  def get_street_view_image(
      location: Optional[str] = None,
      lat_lng: Optional[Tuple[float, float]] = None,
      pano_id: Optional[str] = None,
      size: str = "600x400",
      heading: int = 0,
      pitch: int = 0,
      fov: int = 90,
      radius: int = 50,
      source: str = "default",
      return_error_code: bool = True,
      filename: Optional[str] = None,
  ):
      """
      Fetch a Street View image using various location specifiers.
      
      Args:
          location (str, optional): The address to get Street View image for
          lat_lng (tuple, optional): Latitude and longitude coordinates as (lat, lng)
          pano_id (str, optional): Specific panorama ID to fetch
          size (str): The size of the image in pixels as 'widthxheight'
          heading (int): Camera heading in degrees relative to true north
          pitch (int): Camera pitch in degrees, relative to the street view vehicle
          fov (int): Field of view in degrees (zoom level)
          radius (int): Search radius in meters (when using location or lat_lng)
          source (str): Limits Street View searches to selected sources (default, outdoor)
          return_error_code (bool): Whether to return error codes instead of generic images
          filename (str, optional): If provided, save the image to this filename in the output directory
          
      Returns:
          PIL.Image: The Street View image
          
      Raises:
          ValueError: If no location method is provided or multiple are provided, or if filename already exists
          Exception: If the API request fails
      """
      # If filename is provided, check if it exists in output directory
      if filename:
          output_path = OUTPUT_DIR / filename
          if output_path.exists():
              raise ValueError(f"File {output_path} already exists")
      
      # Validate input: exactly one location method must be provided
      location_methods = sum(1 for m in [location, lat_lng, pano_id] if m is not None)
      if location_methods == 0:
          raise ValueError("Must provide one of: location, lat_lng, or pano_id")
      if location_methods > 1:
          raise ValueError("Provide only one of: location, lat_lng, or pano_id")
      
      base_url = "https://maps.googleapis.com/maps/api/streetview"
      
      params = {
          "size": size,
          "heading": heading,
          "pitch": pitch,
          "fov": fov,
          "radius": radius,
          "source": source,
          "return_error_code": str(return_error_code).lower(),
          "key": API_KEY,
      }
      
      # Set the location parameter based on what was provided
      if location:
          params["location"] = location
      elif lat_lng:
          params["location"] = f"{lat_lng[0]},{lat_lng[1]}"
      elif pano_id:
          params["pano"] = pano_id
          # Remove radius when using pano_id as it's not applicable
          if "radius" in params:
              del params["radius"]
      
      response = requests.get(base_url, params=params)
      
      if response.status_code == 200:
          if response.headers.get('content-type', '').startswith('image/'):
              image = Image.open(BytesIO(response.content))
              
              # Save to file if filename is provided
              if filename:
                  # Ensure output directory exists
                  output_path.parent.mkdir(parents=True, exist_ok=True)
                  image.save(output_path)
                  
              return image
          else:
              raise Exception("Received non-image response from API")
      else:
          raise Exception(f"Error fetching Street View image: {response.status_code}")

• src/street_view_mcp/server.py:22-22 (registration)

  The @mcp.tool() decorator registers the get_street_view function as an MCP tool.

  @mcp.tool()

• src/street_view_mcp/server.py:23-34 (schema)

  Function signature defines the input schema (parameters with types and defaults) and output type for the tool.

  def get_street_view(
      filename: str,
      location: Optional[str] = None,
      lat_lng: Optional[str] = None,
      pano_id: Optional[str] = None,
      size: str = "600x400",
      heading: int = 0,
      pitch: int = 0,
      fov: int = 90,
      radius: int = 50,
      source: str = "default",
  ) -> Image: