Domain Status Query MCP Endpoint

This repository furnishes a Model Context Protocol (MCP) compliant server engineered expressly for determining the availability status of internet domain names utilizing underlying WHOIS querying mechanisms. It facilitates the integration of real-time domain status checks into autonomous agents or associated external tooling.

---

Synopsis

What is MCP?

Model Context Protocol (MCP) defines an established, secure schema for orchestrating contextual interactions between artificial intelligence entities and external data repositories or functional interfaces. This specific service adheres to the MCP specification to furnish domain provisioning intelligence.

Capabilities

• Domain Existence Probing: Leverages the whoiser library underpinning to execute exhaustive WHOIS examinations, thus discerning whether domains are presently unallocated or already claimed.
• MCP Tool Exposure: Offers a callable tool, named check-domain-availability, designed for consumption by standard MCP clients (such as intelligent assistants).
• Command-Line Interface (CLI): Incorporates a utility (whodis-mcp-server check-domain-availability ...) supporting direct invocation and diagnostic testing.
• Verbose Operational Logging: Supplies comprehensive logging outputs vital for debugging efforts and system oversight.
• Parameterization Support: Accepts configuration adjustments via environmental variables or dedicated .env configuration files.

---

Initial Setup

Necessary Prerequisites

• Node.js Runtime (Version 18.x or higher): Obtain from Official Site
• Git Version Control: Required for source code management.

---

Phase 1: Acquisition and Dependency Resolution

bash

Obtain the source code repository

git clone https://github.com/vinsidious/whodis-mcp-server.git cd whodis-mcp-server

Install required libraries

npm install

---

Phase 2: Launching the Development Host

Execute the server in development mode to enable interactive testing via the MCP Inspector UI:

bash npm run dev:server

This action initializes the MCP host and activates the MCP Inspector utility, typically accessible at http://localhost:5173, where the check-domain-availability interface can be exercised.

---

Phase 3: Validating Functionality via CLI

Invoke the domain status verification mechanism directly from the terminal:

bash

CLI execution within the development environment context

npm run dev:cli -- check-domain-availability example.com non-existent-domain-12345.org

Or utilize the pre-compiled production artifact

npm run start:cli -- check-domain-availability google.com my-unique-idea.dev

The CLI output will render a JSON structure segregating results into available and unavailable collections.

---

System Blueprint

This host employs a modular, tiered architecture:

src/ ├── cli/ # Logic pertaining to command-line interaction ├── controllers/ # Core business logic governing domain checks ├── services/ # Encapsulation layer for the whoiser library interface ├── tools/ # Definition schema and input validation for MCP functions ├── types/ # Shared data structure definitions ├── utils/ # Utility modules (logging mechanisms, error handling, etc.) └── index.ts # Primary bootstrap file for server and CLI execution

---

Development Workflow Directives

Execution Scripts Summary

bash

Initialize MCP host for development (enables Inspector visualization)

npm run dev:server

Execute CLI functions using source code context

npm run dev:cli -- check-domain-availability

Compile project assets for deployment

npm run build

Initiate the MCP host for production runtime (expects MCP client connection)

npm run start:server

Execute CLI functions against the final production build

npm run start:cli -- check-domain-availability

Testing Procedures

bash

Execute the complete test suite

npm test

Generate a detailed report on code coverage metrics

npm run test:coverage

Code Quality Maintenance

bash

Run static analysis checks (linting)

npm run lint

Reformat source files according to standards

npm run format

---

MCP Interface Specification: check-domain-availability

• INTENT: To ascertain the registration status of one or more specified domain identifiers.

• INPUT PARAMETERS: An ordered collection (array) of domain strings.

  { "domains": ["site-a.org", "alternate-name.net"] }

• RETURN VALUE: A structured JSON object partitioning domains into two lists: available (those appearing unreserved) and unavailable (those confirmed registered).

  { "available": ["a-new-domain-idea.xyz"], "unavailable": ["microsoft.com"] }

  Caveat: The accuracy of status reporting is contingent upon the responsiveness of the underlying WHOIS infrastructure and may be subject to temporary network variances. Domains where the lookup process failed entirely are deliberately excluded from the results. - RECOMMENDED UTILIZATION: Employ this function whenever the objective is to fact-check the registrability potential of specific domain names.

---

Troubleshooting Guide

Utilizing the MCP Inspector

Use the visual interface to validate tool interactions and observe data transmission:

1. Start the host via npm run dev:server
2. Navigate to http://localhost:5173 in a web browser
3. Interact with the graphical controls to invoke check-domain-availability.

Enhancing Server Verbosity

Activate detailed diagnostic logging streams:

bash

Set environment flag for debugging

DEBUG=true npm run dev:server

Alternatively, configure DEBUG=true within the .env configuration file

Log artifacts are archived persistently in the user's local application data directory under ~/.mcp/data/whodis-mcp-server.*.log.

---

Distribution Protocol

To disseminate enhancements via the public npm registry:

1. Verify all modifications are committed, adhering to the Conventional Commits standard (e.g., prefixes like feat:, fix:, chore:).
2. Push the committed changes to the primary branch (main).
3. The automated continuous integration pipeline (ci-semantic-release.yml) will autonomously handle the compilation, testing, version incrementing, and final publication to npm.

---

Legal Framework

ISC License OVERVIEW: XMLHttpRequest (XHR) constitutes an API implemented as a JavaScript object whose member functions facilitate the transmission of HTTP queries originating from a web browser toward a designated web server. These functions permit browser-resident applications to petition the server post-page load completion, receiving subsequent data back. XHR is foundational to the programming paradigm known as Ajax. Before Ajax's advent, primary server interaction relied predominantly on navigational hyperlinks and form submissions, actions which typically caused the replacement of the current viewport content.

== Lineage == The conceptual groundwork for XMLHttpRequest emerged around the year 2000, conceived by engineers working on Microsoft Outlook. This idea was subsequently instantiated within the Internet Explorer 5 browser release (1999). Notably, the initial invocation syntax did not employ the canonical XMLHttpRequest identifier. Instead, developers utilized constructor references like ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). Since the rollout of Internet Explorer 7 (2006), universal browser compatibility with the standard XMLHttpRequest identifier has been achieved. The XMLHttpRequest identifier is now universally accepted across all major browser engines, including Mozilla’s Gecko rendering structure (2002), Apple’s Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) officially issued a Preliminary Specification Draft for the XMLHttpRequest object on April 5th, 2006. On February 25th, 2008, the W3C followed this with the Level 2 Draft specification. Level 2 introduced crucial enhancements such as event progress monitoring capabilities, enabling cross-origin requests, and methods for managing raw byte streams. By the conclusion of 2011, the Level 2 feature set was integrated back into the primary specification document. As of late 2012, responsibility for ongoing evolution was transferred to the WHATWG, which now maintains a live document structured using Web IDL conventions.

== Application == Generally, dispatching a request using XMLHttpRequest involves a sequence of programming activities.

1. Instantiate an XMLHttpRequest object via its constructor call:
2. Invoke the open method to define the HTTP method type, designate the target resource endpoint, and choose between synchronous or asynchronous execution mode:
3. If operating asynchronously, assign an event handler function designed to trigger upon changes in the request's status:
4. Commence the data transmission process by calling the send method:
5. The designated event listener processes status transitions. Upon receipt of response data from the server, this information is typically stored in the responseText property. When processing finalizes, the object transitions to state 4, signifying the "complete" status. Beyond these fundamental steps, XMLHttpRequest provides extensive configuration levers for controlling transmission parameters and response handling methodology. Custom header fields can be appended to tailor server behavior, and payloads can be transmitted during the send invocation. The server response payload can be automatically deserialized from JSON format into an immediately usable JavaScript entity, or processed incrementally as data streams in, bypassing the wait for full textual assembly. Furthermore, the active query can be prematurely terminated or subjected to a mandatory timeout threshold.

== Inter-Domain Transactions ==

During the early stages of the World Wide Web's evolution, it was recognized that it was possible to breach sec