list_purchases

Instructions

pagination: Pagination details for results
    page: current page of results
    per_page: results per page
    total_pages: total pages results
    total_records: total query records (maximum 5000)

{
    "purchases": [
        {
            "number": "441172999999",
            "channels": 2,
            "country": "United Kingdom",
            "area": "Bristol",
            "codec": "G711",
            "activation": 0.0,
            "monthly_fee": 0.99,
            "per_minute": 0.001,
            "check_state": "checked",
            "free_minutes": 0
        }
    ],
    "pagination": {
        "pages": 1,
        "page": 1,
        "per_page": 100,
        "total_records": 50
    }
}

Implementation Reference

• src/didlogic_mcp/tools/purchases.py:8-80 (handler)

  The main handler function for the 'list_purchases' tool. It defines the input parameters with descriptions (schema), documentation, and executes the API call to list purchases with pagination.

  @mcp.tool()
  async def list_purchases(
      ctx: Context,
      page: Optional[int] = Field(
          description="Page for purchases", default=None
      ),
      per_page: Optional[int] = Field(
          description="Results per page", default=None
      )
  ) -> str:
      """
          List purchased DIDs in DIDLogic
  
          Args:
              page: page of result starting with 1
              per_page: how many results should be on per page
  
          Returns a JSON object with a call history results where:
              purchases: List of purchased DIDs
                  number: Number of DID
                  channels: How many parallel channels DID have
                  country: Country name
                  area: City name
                  free_minutes: How many free minutes per month DID have
                  activation: Activation cost for DID in USD
                  monthly_fee: Monthly fee for DID
                  per_minute: Per minute cost for DID
                  codec: what SIP codec is preferred for this number
                  check_state: DID state
  
              pagination: Pagination details for results
                  page: current page of results
                  per_page: results per page
                  total_pages: total pages results
                  total_records: total query records (maximum 5000)
  
          Example response:
          ```
          {
              "purchases": [
                  {
                      "number": "441172999999",
                      "channels": 2,
                      "country": "United Kingdom",
                      "area": "Bristol",
                      "codec": "G711",
                      "activation": 0.0,
                      "monthly_fee": 0.99,
                      "per_minute": 0.001,
                      "check_state": "checked",
                      "free_minutes": 0
                  }
              ],
              "pagination": {
                  "pages": 1,
                  "page": 1,
                  "per_page": 100,
                  "total_records": 50
              }
          }
          ```
      """
      params = {}
      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",
          "/v1/purchases",
          params=params
      )
      return response.text

• src/didlogic_mcp/tools/purchases.py:10-17 (schema)

  Input schema for the list_purchases tool defined using Pydantic Field with descriptions for page and per_page parameters.

      ctx: Context,
      page: Optional[int] = Field(
          description="Page for purchases", default=None
      ),
      per_page: Optional[int] = Field(
          description="Results per page", default=None
      )
  ) -> str:

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

  Registration block where tools.purchases.register_tools(mcp) is called to register the list_purchases tool among others.

  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/purchases.py:7-7 (registration)

  The register_tools function in the purchases module that defines and registers the tool using @mcp.tool() decorator.

  def register_tools(mcp: FastMCP):