list_country_cities_in_region

Instructions

{
    "cities": [
        {
            "id": 118557,
            "name": "Ottawa-Hull, ON",
            "area_code": "613800",
            "count": 81
        }
    ]
}

Implementation Reference

• src/didlogic_mcp/tools/purchase.py:155-205 (handler)

  The handler function decorated with @mcp.tool() that implements the tool logic: accepts country_id, region_id, optional sms_enabled; constructs API params; calls base.call_didlogic_api with GET to /v2/buy/countries/{country_id}/regions/{region_id}/cities; returns the response text (JSON). Includes input schema via Pydantic Field descriptions.

  @mcp.tool()
  async def list_country_cities_in_region(
      ctx: Context,
      country_id: int = Field(description="Country ID"),
      region_id: int = Field(description="Region ID"),
      sms_enabled: Optional[bool] = Field(
          description="Filter for sms enabled numbers", default=None
      )
  ) -> str:
      """
          List of Cities with available DID in a region of a country
  
          Args:
              country_id: ID of country for search
              region_id: ID of region in a country
              sms_enabled: search for DID with SMS functionality
  
          Returns a JSON object with available cities for purchase DIDs.
          Returned cities list have following fields:
              id: ID of city
              name: Name of city in DIDLogic
              area_code: Area code within country
              count: count of available DIDs for purchasing
  
          403 error indicates disabled API calls for purchase.
  
          Example:
          ```
          {
              "cities": [
                  {
                      "id": 118557,
                      "name": "Ottawa-Hull, ON",
                      "area_code": "613800",
                      "count": 81
                  }
              ]
          }
          ```
      """
      params = {}
      if sms_enabled is not None:
          params["sms_enabled"] = int(sms_enabled)
  
      response = await base.call_didlogic_api(
          ctx,
          "GET",
          f"/v2/buy/countries/{country_id}/regions/{region_id}/cities",
          params=params
      )
      return response.text

• src/didlogic_mcp/server.py:99-105 (registration)

  Calls register_tools on the purchase module (line 103), which defines and registers the list_country_cities_in_region tool via @mcp.tool() decorator inside its register_tools function.

  tools.balance.register_tools(mcp)
  tools.sip_accounts.register_tools(mcp)
  tools.allowed_ips.register_tools(mcp)
  tools.purchases.register_tools(mcp)
  tools.purchase.register_tools(mcp)
  tools.calls.register_tools(mcp)
  tools.transactions.register_tools(mcp)

• src/didlogic_mcp/tools/base.py:9-53 (helper)

  Shared helper function used by the tool handler to make authenticated HTTP requests to the Didlogic API, handling auth based on transport mode (stdio or http/sse).

  async def call_didlogic_api(
      ctx: Context,
      method: str,
      path: str,
      params: Optional[Dict] = None,
      data: Optional[Dict] = None,
      json: Optional[Dict] = None
  ) -> httpx.Response:
      """
      Make a call to the Didlogic API.
  
      In HTTP/SSE mode, extracts Bearer token from request context and adds it
      to the Authorization header for each API call.
      In STDIO mode, uses the API key already configured in the client headers.
      """
      client = ctx.request_context.lifespan_context.client
  
      # In HTTP/SSE mode, get API key from request.state (set by middleware)
      extra_headers = {}
  
      # Check if we have a request object (indicates HTTP/SSE mode)
      request = getattr(ctx.request_context, "request", None)
  
      if request and hasattr(request, 'state') and hasattr(request.state, 'didlogic_api_key'):
          # HTTP/SSE mode: extract API key from request state
          api_key = request.state.didlogic_api_key
          if api_key:
              extra_headers["Authorization"] = f"Bearer {api_key}"
              logger.debug(f"Using API key from request state: {api_key[:8]}...")
          else:
              logger.warning("No API key found in request state")
      else:
          # STDIO mode: API key already in client headers from lifespan
          logger.debug("Using API key from client headers (STDIO mode)")
  
      response = await client.request(
          method=method,
          url=path,
          params=params,
          data=data,
          json=json,
          headers=extra_headers
      )
      response.raise_for_status()
      return response