Obenan MCP Server

Instructions

Implementation Reference

• src/obenan_mcp_server/server.py:169-289 (handler)

  The handler function that executes the "get_location_details" tool.

  async def handle_location_details(
      arguments: dict[str, Any] | None
  ) -> list[types.TextContent]:
      # Get location ID from arguments
      location_id = arguments.get("location_id")
      if not location_id:
          return [types.TextContent(
              type="text", 
              text="❌ Error: Location ID is required to get location details"
          )]
      
      # Get token from environment variable or from arguments
      access_token = os.environ.get("OBENAN_LOGIN_ACCESS_TOKEN")
      if not access_token:
          return [types.TextContent(
              type="text", 
              text="❌ Error: Access token is required. Either provide it as an argument or set the OBENAN_LOGIN_ACCESS_TOKEN environment variable."
          )]
      
      try:
          # Make API call to get location details - updated URL to correct endpoint
          url = f"https://stagingapi.obenan.com/api/v1/location/{location_id}"
          headers = {
              "Authorization": f"Bearer {access_token}",
              "Origin": "https://stagingapp.obenan.com"
          }
          
          response = requests.get(url, headers=headers)
          
          if response.status_code == 200:
              data = response.json()
              
              # Format the response for better readability
              formatted_response = f"✅ Location Details for ID: {location_id}\n\n"
              
              # Extract and format key information based on the actual response structure
              if data and isinstance(data, dict) and "data" in data:
                  # Check if data.data is a dict with location fields or if it has a nested 'result' field
                  location_data = data["data"]
                  
                  # If location_data has a 'result' field, use that instead
                  if isinstance(location_data, dict) and "result" in location_data:
                      location_data = location_data["result"]
                  
                  # Basic information
                  name = location_data.get("name", "Unknown")
                  formatted_response += f"Name: {name}\n"
                  internal_name = location_data.get("internalName", "Unknown")
                  formatted_response += f"Internal Name: {internal_name}\n"
                  
                  # Address information
                  address_line1 = location_data.get("addressLine1", "")
                  address_line2 = location_data.get("addressLine2", "")
                  city = location_data.get("city", "")
                  postal_code = location_data.get("postalCode", "")
                  country_code = location_data.get("countryCode", "")
                  
                  address_parts = []
                  if address_line1:
                      address_parts.append(address_line1)
                  if address_line2 and address_line2 != "null":
                      address_parts.append(address_line2)
                  if city:
                      address_parts.append(city)
                  if postal_code:
                      address_parts.append(postal_code)
                  if country_code:
                      address_parts.append(country_code)
                  
                  address_str = ", ".join(filter(None, address_parts))
                  formatted_response += f"Address: {address_str}\n"
                  
                  # Contact information
                  formatted_response += f"Phone: {location_data.get('telephone', 'N/A')}\n"
                  formatted_response += f"Email: {location_data.get('businessEmail', 'N/A')}\n"
                  formatted_response += f"Website: {location_data.get('website', 'N/A')}\n\n"
                  
                  # Status and dates
                  formatted_response += f"Status: {location_data.get('status', 'N/A')}\n"
                  formatted_response += f"Created: {location_data.get('createdAt', 'N/A')}\n"
                  formatted_response += f"Updated: {location_data.get('updatedAt', 'N/A')}\n\n"
                  
                  # Category information
                  formatted_response += f"Category: {location_data.get('category', 'N/A')}\n"
                  formatted_response += f"Google Category: {location_data.get('googleCategory', 'N/A')}\n\n"
                  
                  # Additional details
                  formatted_response += f"Reporting Enabled: {location_data.get('reportingEnabled', 'N/A')}\n"
                  formatted_response += f"SoConnect Status: {location_data.get('soconnect_connectivity_status', 'N/A')}\n"
                  
                  # Company information if available
                  company = location_data.get('company', {})
                  if isinstance(company, dict) and company.get('name'):
                      formatted_response += f"Company: {company.get('name', 'N/A')}\n\n"
                  
                  # Add debug information about the data structure
                  formatted_response += "===DATA STRUCTURE===\n"
                  if "result" in data.get("data", {}):
                      formatted_response += "Response contains nested 'result' object\n\n"
                  else:
                      formatted_response += "Response contains direct location data\n\n"
                  
                  # Include full JSON response for reference (truncated for readability)
                  formatted_response += f"===FULL RESPONSE (TRUNCATED)===\n{json.dumps(data, indent=2)[:1000]}...\n"
              else:
                  formatted_response += "No data found in response.\n"
              
              return [types.TextContent(type="text", text=formatted_response)]
              
          else:
              # Include full error response
              error_msg = f"❌ Failed to fetch location details: HTTP {response.status_code}\n{response.text}"
              return [types.TextContent(type="text", text=error_msg)]
              
      except Exception as e:
          error_trace = traceback.format_exc()
          return [types.TextContent(
              type="text",
              text=f"🚨 Error fetching location details: {str(e)}\n\nURL: {url}\n\n{error_trace}"
          )]

• src/obenan_mcp_server/server.py:39-50 (registration)

  Registration of the "get_location_details" tool in the server's list_tools function.

  types.Tool(
      name="get_location_details",
      description="Get detailed information about a specific location by ID",
      inputSchema={
          "type": "object",
          "properties": {
              "location_id": {"type": "string", "description": "ID of the location to get details for"},
              "access_token": {"type": "string", "description": "Access token for Obenan API. Optional if OBENAN_LOGIN_ACCESS_TOKEN environment variable is set."}
          },
          "required": ["location_id"]
      },
  ),