@paulgit/mcp-dns-tools 2.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ofer Shapira
+Copyright (c) 2026 Paul Git
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# mcp-dns-tools
+
+[![CI](https://code.paulg.it/paulgit/mcp-dns-tools/actions/workflows/ci.yml/badge.svg)](https://code.paulg.it/paulgit/mcp-dns-tools/actions/workflows/ci.yml)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+DNS lookups, reverse DNS, and domain or IP registration checks from your AI assistant. No API keys, no config. Powered by Node.js built-in DNS, HTTPS RDAP, and public WHOIS fallback services.
+
+> Works with Claude Desktop, Cursor, VS Code Copilot, and any MCP client. Uses Node.js native `dns` module, so there's nothing to sign up for.
+
+Forked from [`ofershap/mcp-server-dns`](https://github.com/ofershap/mcp-server-dns) and renamed to `mcp-dns-tools` from v2.0.0 onwards.
+
+## Why
+
+DNS and registration lookups come up more often than you'd think during development. Debugging email delivery? You need MX records. Auditing certificate issuance? CAA records identify the certificate authorities permitted to issue for a domain. Setting up a new domain? Check the nameservers. Investigating a suspicious URL? Registration data identifies the registrar and public ownership details. The existing MCP options for this often require paid API keys. This server uses Node.js built-in DNS resolution, IANA-discovered RDAP services, and public WHOIS fallback services, so it works without accounts or credentials.
+
+## Tools
+
+| Tool                | What it does                                                              |
+| ------------------- | ------------------------------------------------------------------------- |
+| `dns_lookup`        | Resolve one requested non-NS record type, including A, MX, TXT, and CAA   |
+| `reverse_dns`       | Perform reverse DNS (PTR) lookup on an IP address                         |
+| `resolve_all`       | Resolve common record types for a DNS overview; not for one named type    |
+| `check_nameservers` | Resolve NS, nameserver, authoritative nameserver, and delegation requests |
+| `whois`             | Query domain registration data using RDAP, with WHOIS fallback            |
+| `ip_whois`          | Query IP allocation data using RDAP, with RIR WHOIS fallback              |
+
+### Registration lookup behaviour
+
+The existing `whois` and `ip_whois` tool names are retained for client compatibility, but both tools prefer Registration Data Access Protocol (RDAP):
+
+- Domain services are discovered from IANA's RDAP DNS bootstrap registry.
+- IP services use the longest matching prefix in IANA's IPv4 or IPv6 RDAP bootstrap registry.
+- Bootstrap data is cached in memory for 24 hours.
+- Domain lookups follow one advertised registrar RDAP link when available.
+- TLDs without working RDAP fall back to public port 43 WHOIS, with at most three queries so registry-to-registrar referrals are supported.
+- Unicode domains are converted to IDNA A-labels before lookup.
+- HTTPS redirects, response sizes, timeouts, referral destinations, and private or loopback addresses are bounded or rejected.
+
+RDAP is authoritative when it returns `404 Not Found`; the tools do not then fall back to potentially stale WHOIS data. On a transport failure, rate limit, or unusable RDAP response, WHOIS is attempted and the result includes a warning explaining the fallback.
+
+#### Failure reporting
+
+A valid lookup that cannot be completed is returned as MCP error content with separate details for each attempted protocol:
+
+```text
+Status: failed
+Domain: example.tld
+RDAP status: failed
+RDAP reason: RDAP_NOT_AVAILABLE
+RDAP detail: IANA has no RDAP bootstrap service for this TLD
+WHOIS status: failed
+WHOIS reason: WHOIS_CONNECTION_REFUSED
+WHOIS source: whois://whois.registry.example:43
+WHOIS detail: connect ECONNREFUSED
+Suggestion: Check outbound HTTPS and TCP port 43 access, then retry.
+```
+
+Stable reasons cover unavailable or missing RDAP, authoritative not-found responses, HTTP errors, rate limits, timeouts, DNS and connection failures, empty or invalid responses, retired or web-only WHOIS services, unsupported query formats, invalid encoding, response-size limits, and rejected, looping, or excessive referrals. Successful WHOIS fallback results retain the registration data and include the RDAP reason as a warning.
+
+## Install
+
+```bash
+npx -y @paulgit/mcp-dns-tools --transport stdio
+```
+
+Node.js 24 or later is required. The server uses stdio by default; `--transport stdio` makes the transport explicit in MCP client configuration.
+
+To build from source instead:
+
+```bash
+git clone https://code.paulg.it/paulgit/mcp-dns-tools.git
+cd mcp-dns-tools
+npm ci
+npm run build
+```
+
+## Optional Agent Skill
+
+The MCP server works without the bundled skill. If your client supports Agent Skills or an equivalent skill format, install the entire `skills/dns-lookup` directory using that client's skill installation mechanism.
+
+Generic copy:
+
+```bash
+cp -R skills/dns-lookup /path/to/client/skills/
+```
+
+Generic symlink for repository-based installations:
+
+```bash
+ln -s /absolute/path/to/mcp-dns-tools/skills/dns-lookup \
+  /path/to/client/skills/dns-lookup
+```
+
+Consult your client's documentation for its skills directory, then reload or restart the client. Clients without Agent Skills can skip this step; MCP tool descriptions and server instructions provide the essential routing guidance.
+
+## Quick Start
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "dns": {
+      "command": "npx",
+      "args": ["-y", "@paulgit/mcp-dns-tools", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "dns": {
+      "command": "npx",
+      "args": ["-y", "@paulgit/mcp-dns-tools", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+### VS Code
+
+Add to user settings or `.vscode/mcp.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "dns": {
+        "command": "npx",
+        "args": ["-y", "@paulgit/mcp-dns-tools", "--transport", "stdio"]
+      }
+    }
+  }
+}
+```
+
+## Examples
+
+- "What are the DNS records for example.com?"
+- "Do a reverse DNS lookup on 8.8.8.8"
+- "Show me the WHOIS info for github.com"
+- "Show me the registration data for nominet.uk"
+- "What nameservers does cloudflare.com use?"
+- "Resolve all record types for google.com"
+- "Check the MX records for my-company.com"
+- "Which certificate authorities can issue certificates for example.com?"
+- "Check the CAA records for example.com"
+- "Who owns the netblock for 8.8.8.8?"
+- "Show me the IP WHOIS for 2001:4860:4860::8888"
+
+## Troubleshooting
+
+### DNS lookups fail with "DNS server refused the query"
+
+Some local resolvers (e.g. Tailscale MagicDNS, some VPNs and corporate DNS) only answer A/AAAA queries and refuse other record types like MX, TXT, CAA, NS, SOA, or CNAME. The server uses Node's built-in resolver, which reads the system DNS configuration.
+
+To use a different resolver, set the `DNS_SERVERS` environment variable to a comma-separated list of IP addresses:
+
+```bash
+DNS_SERVERS=8.8.8.8,1.1.1.1 npx -y @paulgit/mcp-dns-tools --transport stdio
+```
+
+### Registration lookups fail on a restricted network
+
+RDAP requires outbound HTTPS. Legacy fallback also requires outbound TCP port 43, which many corporate firewalls block. The returned error reports both failures when neither protocol is reachable.
+
+## Development
+
+```bash
+npm test
+npm run build
+```
+
+### Tool routing smoke test
+
+After changing tool metadata, run these prompts in each supported MCP client with and without the optional skill installed:
+
+| Prompt                                            | Expected call                           |
+| ------------------------------------------------- | --------------------------------------- |
+| Check the CAA records for fastmail.com            | `dns_lookup`, `type: "CAA"`             |
+| Which CAs may issue certificates for example.com? | `dns_lookup`, `type: "CAA"`             |
+| Check the MX records for example.com              | `dns_lookup`, `type: "MX"`              |
+| Check the NS records for example.com              | `check_nameservers`                     |
+| What nameservers does example.com use?            | `check_nameservers`                     |
+| Show all DNS records for example.com              | `resolve_all`                           |
+| Give me a DNS overview for example.com            | `resolve_all`                           |
+| Check the CAA and MX records for example.com      | `resolve_all` or two `dns_lookup` calls |
+| Check the NS and MX records for example.com       | `resolve_all` or two specific calls     |
+| Who is the registrar for example.com?             | `whois`                                 |
+| Who owns the netblock for 8.8.8.8?                | `ip_whois`                              |
+
+Record the selected tool and arguments. Rebuild the server and reconnect the client before each test run so it refreshes MCP instructions and `tools/list` metadata.
+
+## License
+
+MIT © 2026 Ofer Shapira, 2026 Paul Git