Domain Registration Status Inquiry MCP Agent

This component furnishes a Model Context Protocol (MCP) endpoint engineered expressly for querying the availability of digital addresses utilizing deep WHOIS record retrieval. It facilitates seamless incorporation of domain status verification into automated assistants and other client workflows.

---

Executive Summary

Understanding MCP

Model Context Protocol (MCP) defines a standardized, secure mechanism enabling intelligent entities to interface with proprietary external services and data repositories. This agent implements the defined MCP specification to furnish authoritative domain registration data.

Core Capabilities

• Domain State Resolution: Employs the whoiser utility to execute comprehensive WHOIS queries, thereby determining if a domain is currently reserved or open for acquisition.
• MCP Interface Exposure: Offers the check-domain-availability function, callable by any compliant MCP client (e.g., generative AI agents).
• Command-Line Utility: Includes a console interface (domain-status-mcp check-domain-availability ...) for direct invocation and validation testing.
• Verbose Reporting: Generates detailed logs to support diagnostic review and operational oversight.
• Adaptability: Supports parameter adjustment via environmental variables or configuration files (.env).

---

Initiation Guide

Prerequisites

• Runtime Environment (Node.js >=18.x): Secure the necessary installer here.
• Version Control Utility (Git): Required for source code management.

---

Phase 1: Acquisition and Setup

# Retrieve the repository source
git clone https://github.com/vinsidious/whodis-mcp-server.git
cd whodis-mcp-server

# Install required dependencies
npm install

---

Phase 2: Launching the Development Endpoint

Initiate the server in debugging mode to enable interaction via the MCP Inspector interface:

npm run dev:server

This action deploys the MCP service and activates the visual inspection panel at http://localhost:5173, allowing interactive testing of the check-domain-availability mechanism.

---

Phase 3: Command Line Invocation Testing

Execute the domain status resolver directly from the terminal:

# Testing with CLI in development mode
npm run dev:cli -- check-domain-availability example.com non-existent-domain-12345.org

# Executing using the compiled production artifact
npm run start:cli -- check-domain-availability google.com my-unique-idea.dev

The CLI output will be a structured JSON object partitioning the inputs into available and unavailable lists.

---

System Structure

This service adheres to a modular structural design:

src/
├── cli/              # Console command execution modules
├── controllers/      # Core business logic governing status checks
├── services/         # Interfaces with the underlying whoiser library
├── tools/            # MCP tool definitions and input schema validation
├── types/            # Shared data structure definitions
├── utils/            # Helper modules (e.g., logging utilities, error handling)
└── index.ts          # Primary server bootstrap and CLI entry point

---

Development Workflows

Key Execution Scripts

# Start MCP endpoint (with Inspector support)
npm run dev:server

# Run CLI utilities in development context
npm run dev:cli -- check-domain-availability <domain_list...>

# Compile source code for distribution
npm run build

# Launch the server for production operations (expects an active MCP client)
npm run start:server

# Execute CLI utilities against the production build artifacts
npm run start:cli -- check-domain-availability <domain_list...>

Quality Assurance

# Execute the complete test suite
npm test

# Generate a report detailing test coverage metrics
npm run test:coverage

Code Standards

# Enforce code style rules via ESLint
npm run lint

# Standardize file formatting using Prettier
npm run format

---

MCP Function: check-domain-availability

• OBJECTIVE: Verifies the current registration status for one or multiple specified Internet addresses.
• INPUT: A list (array) of domain strings. json { "domains": ["acme-corp.info", "hypothetical-site.io"] }
• OUTPUT: A JSON object containing two distinct arrays: available (domains indicating no current record) and unavailable (domains confirming existing registration). json { "available": ["new-startup-name.biz"], "unavailable": ["microsoft.com"] } Caveat: Status outcomes are contingent upon WHOIS server responses and may not guarantee absolute accuracy across all Top-Level Domains (TLDs) or during transient network interruptions. Domains that result in lookup failure are intentionally excluded from the final output.
• RECOMMENDED USAGE: Invoke this function whenever ascertaining the immediate registration possibility of prospective domain assets is required.

---

Troubleshooting

Utilizing the MCP Inspector

The visual interface aids in function testing and tracing data flow:

1. Execute npm run dev:server
2. Navigate to http://localhost:5173 in any modern web browser.
3. Use the GUI to initiate calls against the check-domain-availability resource.

Service Logging

Activate verbose logging by setting the environment flag:

# Set debug flag for the execution session
DEBUG=true npm run dev:server

# Alternatively, update the .env configuration file

Detailed log files are archived persistently under ~/.mcp/data/whodis-mcp-server.*.log.

---

Distribution Process

To deploy updates to the npm registry:

1. Ensure all modifications are committed, adhering to semantic versioning commit messages (e.g., prefixes like feat:, fix:, chore:).
2. Push the committed changes to the primary branch (main).
3. The automated integration pipeline (ci-semantic-release.yml) will subsequently manage the full lifecycle: building, testing, version bumping, and publishing to npm.

---

Operational Covenant

ISC License