list_countries
Retrieve available countries for purchasing virtual phone numbers (DIDs) with optional SMS functionality. Returns JSON data including country ID, name, ISO code, and province/state availability.
Instructions
List available countries with DID for purchase on DIDLogic
Args: sms_enabled: search for DID with SMS functionality
Returns a JSON object with available countries for purchase. Returned countries list have following fields: id: ID of country name: Name of country in DIDLogic short_name: ISO code of country has_provinces_or_states: do country have provinces or states which can be queried by list_country_regions tool.
403 error indicates disabled API calls for purchase.
Example:
{
"countries": [
{
"id": 8669,
"name": "Argentina",
"short_name": "AR",
"has_provinces_or_states": false
}
]
}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sms_enabled | No | Filter for sms enabled numbers |
Implementation Reference
- src/didlogic_mcp/tools/purchase.py:8-56 (handler)The handler function that implements the logic for the 'list_countries' tool. It accepts an optional sms_enabled filter, constructs API parameters, calls the DIDLogic /v2/buy/countries endpoint via base.call_didlogic_api, and returns the response text.@mcp.tool() async def list_countries( ctx: Context, sms_enabled: Optional[bool] = Field( description="Filter for sms enabled numbers", default=None ) ) -> str: """ List available countries with DID for purchase on DIDLogic Args: sms_enabled: search for DID with SMS functionality Returns a JSON object with available countries for purchase. Returned countries list have following fields: id: ID of country name: Name of country in DIDLogic short_name: ISO code of country has_provinces_or_states: do country have provinces or states which can be queried by list_country_regions tool. 403 error indicates disabled API calls for purchase. Example: ``` { "countries": [ { "id": 8669, "name": "Argentina", "short_name": "AR", "has_provinces_or_states": false } ] } ``` """ params = {} if sms_enabled is not None: params["sms_enabled"] = int(sms_enabled) response = await base.call_didlogic_api( ctx, "GET", "/v2/buy/countries", params=params ) return response.text
- src/didlogic_mcp/server.py:103-103 (registration)Top-level registration of the purchase tools module, which includes the list_countries tool, by invoking its register_tools function on the MCP server instance.tools.purchase.register_tools(mcp)
- Pydantic schema definition for the input parameter 'sms_enabled' used in the list_countries tool.sms_enabled: Optional[bool] = Field( description="Filter for sms enabled numbers", default=None )
- src/didlogic_mcp/tools/base.py:9-53 (helper)The supporting helper function call_didlogic_api used by the list_countries handler to perform the actual HTTP request to the DIDLogic API, handling authentication based on the transport mode.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