ens-mcp

Instructions

Implementation Reference

• main.py:162-227 (handler)

  Handler function decorated with @mcp.tool(), which registers the tool and infers input schema from type annotations (domain: str). Executes the core logic to fetch and format ENS domain details using the query_ens_domain helper.

  @mcp.tool()
  async def get_domain_details(domain: str) -> str:
      """Fetch detailed information for an ENS domain, including its address."""
      domain_data = await query_ens_domain(domain)
      if not domain_data:
          return f"No data found for ENS domain: {domain}"
      
      # Get address
      address = (domain_data["resolvedAddress"]["id"] if domain_data["resolvedAddress"]
                 else domain_data["resolver"]["addr"]["id"] if domain_data["resolver"] and domain_data["resolver"]["addr"]
                 else "None")
      
      # Format dates
      expiry = (datetime.datetime.fromtimestamp(int(domain_data["expiryDate"]))
                .strftime("%Y-%m-%d %H:%M:%S") if domain_data["expiryDate"]
                else "None")
      created = (datetime.datetime.fromtimestamp(int(domain_data["createdAt"]))
                 .strftime("%Y-%m-%d %H:%M:%S") if domain_data["createdAt"]
                 else "None")
      
      # Registration details
      registration_info = (
          f"Registration Date: {datetime.datetime.fromtimestamp(int(domain_data['registration']['registrationDate'])).strftime('%Y-%m-%d %H:%M:%S')}\n"
          f"Registration Expiry: {datetime.datetime.fromtimestamp(int(domain_data['registration']['expiryDate'])).strftime('%Y-%m-%d %H:%M:%S')}\n"
          f"Registration Cost: {domain_data['registration']['cost'] or 'Unknown'} Wei\n"
          f"Registrant: {domain_data['registration']['registrant']['id']}"
          if domain_data["registration"]
          else "No Registration"
      )
      
      # Wrapped domain details
      wrapped_info = (
          f"Wrapped Name: {domain_data['wrappedDomain']['name']}\n"
          f"Wrapped Owner: {domain_data['wrappedDomain']['owner']['id']}\n"
          f"Wrapped Expiry: {datetime.datetime.fromtimestamp(int(domain_data['wrappedDomain']['expiryDate'])).strftime('%Y-%m-%d %H:%M:%S')}\n"
          f"Fuses: {domain_data['wrappedDomain']['fuses']}"
          if domain_data["wrappedDomain"]
          else "Not Wrapped"
      )
      
      # Resolver details
      resolver_info = (
          f"Resolver Address: {domain_data['resolver']['address']}\n"
          f"Content Hash: {domain_data['resolver']['contentHash'] or 'None'}\n"
          f"Text Records: {', '.join(domain_data['resolver']['texts']) if domain_data['resolver']['texts'] else 'None'}"
          if domain_data["resolver"]
          else "No Resolver"
      )
      
      return (
          f"ENS Domain: {domain_data['name']}\n"
          f"Address: {address}\n"
          f"Label Name: {domain_data['labelName'] or 'None'}\n"
          f"Label Hash: {domain_data['labelhash'] or 'None'}\n"
          f"Subdomain Count: {domain_data['subdomainCount']}\n"
          f"Owner: {domain_data['owner']['id']}\n"
          f"Registrant: {domain_data['registrant']['id'] if domain_data['registrant'] else 'None'}\n"
          f"Wrapped Owner: {domain_data['wrappedOwner']['id'] if domain_data['wrappedOwner'] else 'None'}\n"
          f"Expiry Date: {expiry}\n"
          f"TTL: {domain_data['ttl'] or 'None'} seconds\n"
          f"Is Migrated: {domain_data['isMigrated']}\n"
          f"Created At: {created}\n"
          f"Registration: {registration_info}\n"
          f"Wrapped Domain: {wrapped_info}\n"
          f"Resolver: {resolver_info}"
      )

• main.py:27-82 (helper)

  Supporting helper utility that queries the ENS subgraph via GraphQL for detailed domain data, which is then processed by the get_domain_details handler.

  async def query_ens_domain(name: str) -> Optional[Dict[str, Any]]:
      """Query the ENS Subgraph for domain details."""
      query = gql("""
          query GetDomain($name: String!) {
            domains(where: { name: $name }) {
              id
              name
              labelName
              labelhash
              subdomainCount
              resolvedAddress {
                id
              }
              resolver {
                address
                addr {
                  id
                }
                contentHash
                texts
              }
              ttl
              isMigrated
              createdAt
              owner {
                id
              }
              registrant {
                id
              }
              wrappedOwner {
                id
              }
              expiryDate
              registration {
                registrationDate
                expiryDate
                cost
                registrant {
                  id
                }
                labelName
              }
              wrappedDomain {
                expiryDate
                fuses
                owner {
                  id
                }
                name
              }
            }
          }
      """)
      result = await graphql_client.execute_async(query, variable_values={"name": name})
      return result["domains"][0] if result["domains"] else None