list_country_cities_in_region
Retrieve a list of cities within a specific region of a country where DIDs are available for purchase, including area codes and DID counts. Filter results based on SMS functionality requirements.
Instructions
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
}
]
}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| country_id | Yes | Country ID | |
| region_id | Yes | Region ID | |
| sms_enabled | No | Filter for sms enabled numbers |
Implementation Reference
- 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