list_dids_in_country_city

Instructions

{
    "dids": {
        "pagination": {
            "total": 52,
            "total_pages": 1,
            "current_page": 1
        },
        "dids": [
            {
                "id": 112370,
                "country": "Canada",
                "city": "Edmonton, AB",
                "sms_enabled": false,
                "no_local_cli": false,
                "channels": 4,
                "free_min": 0,
                "cnam": null,
                "activation": 1.0,
                "monthly": 1.0,
                "per_minute": 0.01,
                "origination_per_min": null,
                "required_documents": [],
                "state": "Alberta",
                "country_short_name": "CA",
                "number": "17806999999"
            }
        ]
    }
}

Implementation Reference

• src/didlogic_mcp/tools/purchase.py:207-301 (handler)

  The core handler function implementing the 'list_dids_in_country_city' tool. It validates inputs using Pydantic Fields (serving as schema), constructs query parameters, calls the shared base.call_didlogic_api helper to fetch available DIDs from the DIDLogic /v2/buy/countries/{country_id}/cities/{city_id}/dids endpoint, and returns the JSON response.

  @mcp.tool()
  async def list_dids_in_country_city(
      ctx: Context,
      country_id: int = Field(description="Country ID"),
      city_id: int = Field(description="City ID"),
      sms_enabled: Optional[bool] = Field(
          description="Filter for sms enabled numbers", default=None
      ),
      page: Optional[int] = Field(description="Search page", default=None),
      per_page: Optional[int] = Field(
          description="Search per page", default=None
      )
  ) -> str:
      """
          List of available DID in a city of a country
  
          Args:
              country_id: ID of country for search
              city_id: ID of city in a country
              sms_enabled: search for DID with SMS functionality
              page: page of result starting with 1
              per_page: how many results should be on per page
  
          Returns a JSON object with available DIDs where:
              dids: Array of DID available for purchasing where:
                  id: ID of DID
                  country: Country name
                  city: City name
                  sms_enabled: Is number capable of receiving SMS
                  channels: How many parallel channels have DID
                  free_min: How many free minutes per month DID have
                  activation: Activation cost for DID in USD
                  monthly: Monthly fee for DID
                  per_minute: Per minute cost for DID
                  origination_per_min: per minute cost if origin based rate applied
                  required_documents: required documents for activating number, where:
                      1 = Any form of ID
                      2 = Proof of address
                      3 = Proof of local address
                  number: DID Number in E164 format
              pagination: Pagination details for results
                  page: current page of results
                  total_pages: total pages results
                  total: total query records
  
          403 error indicates disabled API calls for purchase.
  
          Example:
          ```
          {
              "dids": {
                  "pagination": {
                      "total": 52,
                      "total_pages": 1,
                      "current_page": 1
                  },
                  "dids": [
                      {
                          "id": 112370,
                          "country": "Canada",
                          "city": "Edmonton, AB",
                          "sms_enabled": false,
                          "no_local_cli": false,
                          "channels": 4,
                          "free_min": 0,
                          "cnam": null,
                          "activation": 1.0,
                          "monthly": 1.0,
                          "per_minute": 0.01,
                          "origination_per_min": null,
                          "required_documents": [],
                          "state": "Alberta",
                          "country_short_name": "CA",
                          "number": "17806999999"
                      }
                  ]
              }
          }
          ```
      """
  
      params = {}
      if sms_enabled is not None:
          params["sms_enabled"] = int(sms_enabled)
      if page is not None:
          params["page"] = page
      if per_page is not None:
          params["per_page"] = per_page
      response = await base.call_didlogic_api(
          ctx,
          "GET",
          f"/v2/buy/countries/{country_id}/cities/{city_id}/dids",
          params=params
      )
      return response.text

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

  Registers all tools from the purchase module (including list_dids_in_country_city) by invoking the module's register_tools function on the FastMCP server instance.

  tools.purchase.register_tools(mcp)

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

  Shared utility function called by the handler to perform 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