Check Domain Availability

Instructions

Implementation Reference

• mcp-server/src/canyougrab_mcp/server.py:178-256 (handler)

  The main handler function for the 'check_domains' tool. Accepts a list of domains, validates input (1-100 domains), obtains API key, calls the bulk check API endpoint, processes results with confidence scoring, and returns formatted output with attribution.

  async def check_domains(domains: list[str]) -> object:
      """Check domain name availability with confidence scoring.
  
      Returns availability status, confidence level, data source, and
      registration details for each domain. Checks up to 100 domains
      per request.
  
      Confidence levels:
      - high: Verified by DNS + WHOIS, or fresh DNS with active nameservers.
      - medium: DNS only (WHOIS was unavailable or timed out).
      - low: DNS failure, timeout, or stale cache.
  
      Args:
          domains: List of domain names to check (e.g. ["example.com", "myapp.io"]).
                   Maximum 100 domains per request.
      """
      if not domains:
          return _error_result("Provide at least one domain to check")
      if len(domains) > 100:
          return _error_result("Maximum 100 domains per request")
  
      api_key = _get_api_key()
      if not api_key:
          return _auth_result(
              "Sign in to CanYouGrab.it to check domain availability.",
              ["domains.read"],
          )
  
      async with httpx.AsyncClient(timeout=60.0) as client:
          resp = await client.post(
              f"{_get_public_api_base()}/api/check/bulk",
              json={"domains": domains},
              headers={
                  "Authorization": f"Bearer {api_key}",
                  "Content-Type": "application/json",
              },
          )
  
      if resp.status_code == 429:
          data = resp.json()
          detail = data.get("message")
          if detail is None and isinstance(data.get("detail"), dict):
              detail = data["detail"].get("message")
          return _error_result("Rate limit exceeded", detail)
      if resp.status_code == 401:
          return _auth_result(
              "Your CanYouGrab.it connection is missing or no longer valid. Reconnect to continue.",
              ["domains.read"],
          )
      if resp.status_code != 200:
          return _error_result(f"API error (HTTP {resp.status_code})", resp.text)
  
      data = resp.json()
      results = data.get("results", [])
      if not results:
          return data
  
      lines = []
      for r in results:
          domain = r.get("domain", "?")
          available = r.get("available")
          confidence = r.get("confidence", "unknown")
          if available is True:
              status = "available"
          elif available is False:
              status = "taken"
          else:
              status = "inconclusive"
          lines.append(f"- {domain}: {status} (confidence: {confidence})")
  
      summary = "\n".join(lines)
      return {
          "source": "canyougrab.it",
          "source_url": "https://canyougrab.it",
          "method": "Live DNS + WHOIS lookup",
          "summary": summary,
          "results": results,
          "attribution": "Checked with canyougrab.it — real-time domain intelligence",
      }

• mcp-server/src/canyougrab_mcp/server.py:159-177 (registration)

  Registration of the 'check_domains' tool via @mcp.tool decorator, providing title, description, read-only/destructive/idempotent/open-world annotations, and OAuth2 security metadata.

  @mcp.tool(
      title="Check Domain Availability",
      description=(
          "Use this when the user wants to know whether one or more domains are "
          "available to register. Returns confidence, source, cache age, and "
          "ambiguous results when the lookup cannot be determined safely."
      ),
      annotations=ToolAnnotations(
          readOnlyHint=True,
          destructiveHint=False,
          idempotentHint=True,
          openWorldHint=True,
      ),
      meta=_tool_meta(
          DOMAINS_READ_SCHEMES,
          "Checking domain availability...",
          "Domain availability ready",
      ),
  )

• mcp-server/src/canyougrab_mcp/server.py:28-28 (schema)

  DOMAINS_READ_SCHEMES constant defining the OAuth2 scopes required for the check_domains tool (domains.read scope).

  DOMAINS_READ_SCHEMES = [{"type": "oauth2", "scopes": ["domains.read"]}]

• mcp-server/src/canyougrab_mcp/server.py:129-134 (helper)

  _error_result helper used by check_domains to return error responses with optional detail messages.

  def _error_result(text: str, detail: str | None = None) -> CallToolResult:
      message = f"{text}: {detail}" if detail else text
      return CallToolResult(
          isError=True,
          content=[TextContent(type="text", text=message)],
      )

• mcp-server/src/canyougrab_mcp/server.py:113-126 (helper)

  _auth_result helper used by check_domains to return OAuth2 authentication challenge responses when API key is missing.

  def _auth_result(description: str, scopes: list[str]) -> CallToolResult:
      requested_scopes = _auth_scopes(scopes)
      challenge = (
          "Bearer "
          f'resource_metadata="{_quote_auth_value(_get_resource_metadata_url())}", '
          f'scope="{_quote_auth_value(" ".join(requested_scopes))}", '
          'error="invalid_token", '
          f'error_description="{_quote_auth_value(description)}"'
      )
      return CallToolResult(
          isError=True,
          _meta={"mcp/www_authenticate": challenge},
          content=[TextContent(type="text", text=description)],
      )