@cyanheads/whois-mcp-server 0.1.4 → 0.1.6

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.1.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/whois-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/whois-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/whois-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.1.6-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/whois-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.1.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/whois-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/whois-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -21,9 +21,11 @@
 
 ---
 
-## Tools
+## Overview
 
-Six tools covering domain intelligence, DNS, and IP/ASN resolution:
+Domain and network intelligence via RDAP and DNS-over-HTTPS. Look up domain registrations, check availability, fetch DNS records, and resolve IPs and ASNs to their registries — all via public, keyless data sources. Runs as a stdio process or a local Streamable HTTP server.
+
+### Tools
 
 | Tool | Description |
 |:-----|:------------|
@@ -34,97 +36,70 @@ Six tools covering domain intelligence, DNS, and IP/ASN resolution:
 | `whois_lookup_asn` | Resolve an ASN to its org name, country, and RIR source |
 | `whois_get_dossier` | One-call domain triage — registration + DNS in parallel, normalized into a single record with factual signals |
 
-### `whois_lookup_domain`
+---
 
-Look up a domain's full RDAP registration record.
+## Capability reference
 
-- RDAP-first via IANA auto-bootstrap — automatically selects the correct registry RDAP server per TLD
-- Returns registrar, creation/expiry dates, nameservers, EPP status codes, DNSSEC delegation flag
-- Surfaces `registrant_redacted: true` explicitly when privacy redaction is in effect (standard post-GDPR for gTLDs)
-- Returns `rdap_coverage: false` for TLDs without RDAP coverage rather than silently failing
-- Includes `last_update_of_rdap_db` event timestamp for data freshness transparency
+### `whois_lookup_domain` <sub>tool</sub>
 
----
+- Accepts a fully qualified domain name and selects the registry RDAP server through IANA bootstrap.
+- Returns registrar, registration dates, nameservers, EPP status, DNSSEC, and `registrant_redacted`; throws `rdap_no_coverage` or `domain_not_found` when no record can be returned.
 
-### `whois_check_availability`
+---
 
-Check whether a domain name is registered or available to register.
+### `whois_check_availability` <sub>tool</sub>
 
-- RDAP 404 = available (`available: true`) — exploits the RDAP spec's intended behavior
-- Returns `available: false` with `registrar` and `expiry_date` when registered
-- Returns `available: null` with `rdap_coverage: false` for TLDs without RDAP — cannot determine availability
-- Optimized for bulk name sweeps — thin response, no unnecessary fields
+- Accepts a fully qualified domain name for a registration check.
+- Returns `available: true` for RDAP 404, `false` with registrar and expiry for a registered domain, or `null` with `rdap_coverage: false` when coverage is absent.
 
 ---
 
-### `whois_get_dns`
-
-Fetch DNS records via DNS-over-HTTPS.
+### `whois_get_dns` <sub>tool</sub>
 
-- Cloudflare primary, NextDNS fallback (CAA records always use NextDNS — Cloudflare returns raw hex wire format for them)
-- Supports A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, PTR — multiple types in one call
-- Returns records with TTLs and the resolving source (`cloudflare` or `nextdns`)
-- `nxdomain: true` in result (not an error) when the domain doesn't exist in DNS
+- Accepts a hostname and optional nonempty `types`: A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, PTR; omission defaults to A, AAAA, MX, TXT, NS. Duplicate types are queried once.
+- Returns records with TTLs and ordered `query_sources: [{type, source}]`, including empty answers and NXDOMAIN. Legacy `source` is `cloudflare` if any query consumed a successful Cloudflare response, otherwise `nextdns`; a nonexistent domain returns `nxdomain: true` as data.
 
 ---
 
-### `whois_lookup_ip`
+### `whois_lookup_ip` <sub>tool</sub>
 
-Look up an IP address or CIDR block via RIR RDAP.
-
-- Auto-routes to the correct RIR (ARIN, RIPE, APNIC, LACNIC, AFRINIC) via IANA IP bootstrap
-- Returns netblock CIDR, org name, country, abuse contact email
-- Fetches PTR (reverse DNS) via DoH as a best-effort step — `ptr: null` on failure, not an error
-- Validates and rejects private/reserved ranges (RFC 1918, loopback, link-local) with a clear error
+- Accepts a complete IPv4/IPv6 address with at most one decimal CIDR prefix (0–32 / 0–128); no whitespace, zone IDs, or brackets. Queries the base address and echoes the original `ip`. IPv4-mapped IPv6 uses the embedded IPv4 for policy, RDAP, and PTR; other IPv6 uses 32 reversed PTR nibbles.
+- Returns netblock CIDR, organization, country, abuse contact, and best-effort PTR (`null` on failure); throws `invalid_ip` for malformed input or `ip_not_found` on an RIR RDAP 404.
+- `private_range` enforces an explicit policy: IPv4 `0.0.0.0/8`, `10.0.0.0/8`, `100.64.0.0/10`, `127.0.0.0/8`, `169.254.0.0/16`, `172.16.0.0/12`, `192.168.0.0/16`, `255.0.0.0/8`; IPv6 `::1/128`, `fc00::/7`, `fe80::/10`. Other special-use addresses remain eligible for registry records or normal no-coverage/not-found outcomes.
 
 ---
 
-### `whois_lookup_asn`
-
-Resolve an ASN to its org name, country, and RIR.
+### `whois_lookup_asn` <sub>tool</sub>
 
-- Accepts `AS15169` or bare integer `15169` format
-- Routes to the correct RIR RDAP endpoint via IANA ASN bootstrap
-- Returns `name`, `org`, `country`, `rir`, `start_autnum`, `end_autnum`
+- Accepts a decimal ASN from 1 to 4294967295 with an optional case-insensitive `AS` prefix and leading `+` (e.g., `AS15169`, `AS 15169`, `+15169`). Outer whitespace and whitespace after `AS` are allowed; whitespace inside digits or after `+`, suffixes, decimals, and out-of-range values return `invalid_asn`.
+- Returns `name`, `org_name`, `country`, `rir`, `start_autnum`, and `end_autnum`; throws `asn_not_found` when no ASN record exists.
 
 ---
 
-### `whois_get_dossier`
+### `whois_get_dossier` <sub>tool</sub>
 
-One-call domain triage aggregating registration and DNS data in parallel.
-
-- Runs RDAP domain lookup and DoH (A, MX, NS, TXT) in parallel via `Promise.allSettled`
-- Inferred signals: `age_days`, `privacy_redacted`, `registrar`, `ns_provider` (from NS records), `mx_provider` (from MX records)
-- No synthesized risk scores — factual signals only; the agent decides the verdict
-- Partial results surfaced when one leg fails (`source_error` on the failed leg)
-- Both-legs-fail throws `ServiceUnavailable`; individual leg failures are data, not errors
+- Accepts a fully qualified domain name for parallel registration and A/MX/NS/TXT lookups.
+- Returns registration, DNS, domain age, privacy status, and inferred NS/MX providers. Individual failures remain partial data in `rdap_source_error` or `dns_source_error`; `both_legs_failed` means neither source succeeded.
 
 ---
 
 ## Features
 
-Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
-
-- Declarative tool definitions — single file per tool, framework handles registration and validation
-- Unified error handling — handlers throw, framework catches, classifies, and formats
-- Pluggable auth: `none`, `jwt`, `oauth`
-- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
-- Structured logging with optional OpenTelemetry tracing
-- STDIO and Streamable HTTP transports
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
 
-Domain and network intelligence:
+RDAP / DNS-specific:
 
-- RDAP over HTTPS — no port-43 TCP dependency, runs on Node, Bun, and Cloudflare Workers
-- IANA bootstrap auto-selection — correct registry RDAP server picked per TLD, RIR, or ASN range; bootstrap JSON cached (TTL 24h) in tenant state
-- DNS-over-HTTPS via Cloudflare and NextDNS — resilient dual-provider with per-type routing (NextDNS for CAA; Cloudflare for all others)
+- RDAP over HTTPS — no port-43 TCP dependency
+- IANA bootstrap auto-selection — correct registry RDAP server picked per TLD, RIR, or ASN range; bootstrap JSON cached in-memory for 24h
+- DNS-over-HTTPS via Cloudflare and NextDNS — dual-provider with per-type routing (NextDNS for CAA; Cloudflare for all others) and automatic fallback
 - No API keys required — all sources (IANA, registry RDAP endpoints, RIR RDAP, Cloudflare DoH, NextDNS DoH) are public and keyless
 
 Agent-friendly output:
 
-- Explicit coverage signals — `rdap_coverage: false` tells the agent the TLD lacks RDAP rather than returning a confusing error
+- Coverage signaled two ways — `rdap_coverage: false` returned as data by `whois_check_availability` and `whois_get_dossier`, while `whois_lookup_domain` throws `rdap_no_coverage` for the same case
 - Privacy redaction surfaced as a field — `registrant_redacted: true` rather than silently absent contact data
-- Partial failure model — `whois_get_dossier` marks individual legs with `source_error` and continues; only both-legs-fail escalates to an error
-- Factual signals, not scores — `age_days`, `privacy_redacted`, `ns_provider`, `mx_provider` are real data; agents chain into threat-intel or risk servers for enrichment
+- Partial failure model — `whois_get_dossier` marks individual legs with a `source_error` field and continues; only both-legs-fail escalates to an error
+- Factual signals, not scores — `age_days`, `privacy_redacted`, `ns_provider`, `mx_provider` are real data, not synthesized risk scores
 
 ---
 
@@ -193,7 +168,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
 
 ### Prerequisites
 
-- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).
+- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
 - No API keys required — all data sources are public.
 
 ### Installation
@@ -279,7 +254,8 @@ The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `
 
 | Path | Purpose |
 |:-----|:--------|
-| `src/index.ts` | `createApp()` entry point — registers tools and inits services. |
+| `src/index.ts` | Entry point — starts the app. |
+| `src/app.ts` | `createApp()` options — registers tools, inits services, declares the session mode. |
 | `src/config/` | Server-specific environment variable parsing and validation (Zod). |
 | `src/services/rdap/` | RDAP client — IANA bootstrap cache, domain/IP/ASN lookup, retry. |
 | `src/services/doh/` | DNS-over-HTTPS client — Cloudflare primary, NextDNS fallback. |
@@ -294,15 +270,15 @@ The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `
 See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
 
 - Handlers throw, framework catches — no `try/catch` in tool logic
-- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage (IANA bootstrap cache)
-- Register new tools via `src/index.ts` tools array
+- Use `ctx.log` for request-scoped logging
+- Register new tools via `src/app.ts`'s `tools` array
 - Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
 
 ---
 
 ## Contributing
 
-Issues and pull requests are welcome. Run checks and tests before submitting:
+Issues are welcome. Run checks and tests before submitting:
 
 ```sh
 bun run devcheck

package/changelog/0.1.x/0.1.5.md

@@ -0,0 +1,35 @@
+---
+summary: "Adopt mcp-ts-core 0.13.6 — the server resolves to a stateless session posture however it is launched, and an out-of-schema argument fails as InvalidParams (-32602) with a Recovery line instead of ValidationError (-32007). The Bun floor rises to 1.4.0."
+breaking: true
+security: false
+---
+
+# 0.1.5 — 2026-09-20
+
+## Added
+
+- **`.github/FUNDING.yml`** — GitHub Sponsors and Buy Me a Coffee.
+- **`bun run audit:fix`** — `bun audit fix`, the first response to a transitive advisory, ahead of `audit:refresh`.
+- **`devcheck.config.json` `lint` block** — where `lint.truncationAllowlist` now lives, in place of a per-script `MCP_LINT_TRUNCATION_ALLOWLIST` env var.
+- **`tests/app.test.ts`** — asserts the resolved session posture and the registered tool surface against a live `createApp()`.
+
+## Changed
+
+- **The session mode is `stateless` however the server is launched** ([#11](https://github.com/cyanheads/whois-mcp-server/issues/11)). `src/app.ts` declares `createApp({ sessionMode: 'stateless' })` and `.env.example` sets the variable actively, so the `Dockerfile` line restates the posture rather than overriding it; previously only the container was stateless and a `bunx`, `npm start`, or from-source run resolved to `stateful`. No tool holds per-session state or calls `ctx.requestInput`.
+- **An out-of-schema argument now fails as `InvalidParams` (`-32602`), not `ValidationError` (`-32007`).** The rejection carries `data.reason: "invalid_arguments"` and its text ends with a `Recovery: …` line naming the field to fix. A client branching on the old code needs updating.
+- **Tool error text closes with `(reason <reason> · not retryable)`** whenever the error carries a `reason` or a boolean `retryable`. `structuredContent` is unchanged.
+- **A caller that disconnects mid-call classifies as `RequestCancelled` (`-32011`)** rather than `InternalError`, and logs at `info`. An upstream 500 on a DNS-over-HTTPS query now retries instead of failing on the first attempt.
+- **Bun engines floor `>=1.3.0` → `>=1.4.0`**, required by the framework.
+- **`whois_lookup_ip` and `whois_lookup_asn` mark their service-thrown contract entries `thrownBy: 'service'`** — `private_range`, `ip_not_found`, `invalid_asn`, `asn_not_found` (lint-only metadata; the advertised error surface is unchanged).
+- **The framework skill tree moved from `skills/` to `framework-skills/`** — Claude Code and Codex auto-load a plugin's root `skills/`, so this server's plugin manifests no longer hand its development skills to every agent that installs it.
+- **`createApp()` options live in `src/app.ts` as `appOptions`**; `src/index.ts` is the entry point that starts them.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.12.3` → `^0.13.6`
+- `zod` `^4.4.3` → `^4.6.5`
+- `vitest` (dev) `^4.1.11` → `^5.0.1`
+- `@biomejs/biome` (dev) `^2.5.9` → `^2.5.14`
+- `@types/node` (dev) `^26` → `^26.6.1`
+- `ignore` (dev) `^7.0.6` → `^7.0.9`
+- `tsc-alias` (dev) `^1.9.2` → `^1.9.5`

package/changelog/0.1.x/0.1.6.md

@@ -0,0 +1,41 @@
+---
+summary: "Lookup inputs are validated whole before any request, DNS results attribute each query to its resolver, and the dossier renders every TXT record and labels providers by domain."
+breaking: false
+security: false
+---
+
+# 0.1.6 — 2026-09-30
+
+## Added
+
+- **`whois_get_dns` `query_sources`** ([#10](https://github.com/cyanheads/whois-mcp-server/issues/10)) — one `{type, source}` entry per requested type, in request order, naming the resolver whose response was consumed, empty answers and NXDOMAIN included. Duplicate types are queried once; `source` stays the aggregate (`cloudflare` when any query used Cloudflare, otherwise `nextdns`).
+- **Contract tests over the real services** — `tests/helpers/upstream.ts` replaces only outbound HTTP, and `tests/fixtures/` holds captured IANA, ARIN, and APNIC responses that the IP suite replays.
+
+## Changed
+
+- **Framework `@cyanheads/mcp-ts-core` `^0.13.6` → `^0.13.10`** — tool errors carry `data.requestId` and their text closes with `request <id>`, an integer sent for a string argument is repaired to its digits, and framework-built errors keep stack traces and request context out of `data`.
+- **Recovery hints reach the wire through the framework's contract fill** — throws whose `errors[]` entry supplies the hint no longer forward `ctx.recoveryFor`.
+- **Docker image** — production dependencies and the OpenTelemetry peers install in a `deps` stage on the build platform through `scripts/install-otel.ts`, at the framework's declared peer ranges, so no target-platform stage runs Bun while building. The unread `MCP_FORCE_CONSOLE_LOGGING` is gone.
+- **Packaging** — `package.json` `files` carries `!dist/*.mcpb`, keeping a built bundle out of the npm tarball, and `.mcpbignore` excludes `docs/idea.md` and `logs/` from the bundle.
+- **Tooling synced from the framework** — `lint:packaging` checks the bundle exclusion, `manifest.json` version parity, and the Dockerfile build platform; `lint:mcp` fails on a definition it cannot import; `release:github -- --check` validates the tag annotation.
+- **Docs** — README tool sections state each tool's input and output contract, `docs/design.md` records the IP exclusion policy, and `CLAUDE.md` / `AGENTS.md` plus 31 framework skills follow the 0.13.10 templates.
+
+## Fixed
+
+- **`whois_lookup_asn` validates the whole token** ([#5](https://github.com/cyanheads/whois-mcp-server/issues/5)) — a decimal ASN from 1 to 4294967295 with an optional `AS` prefix and leading `+`. `AS15169abc`, `1.5`, and out-of-range values fail as `invalid_asn` before any request instead of resolving a truncated number.
+- **`whois_lookup_ip` parses IP and CIDR input completely** ([#6](https://github.com/cyanheads/whois-mcp-server/issues/6)) — extra slashes, trailing text, whitespace, zone IDs, brackets, and malformed IPv6 fail as `invalid_ip` before any request. A CIDR prefix is one decimal within 0–32 or 0–128.
+- **`private_range` follows the numeric address** — equivalent IPv6 spellings classify alike (`0:0:0:0:0:0:0:1`, `fe90::1`), `::10` is no longer excluded, and the tool description lists the excluded ranges.
+- **IPv6 with a dotted IPv4 tail is accepted** — `2001:db8::192.0.2.1` resolves with a 32-nibble PTR name, and IPv4-mapped addresses (`::ffff:8.8.8.8`) are classified, routed, and PTR-resolved as their embedded IPv4.
+- **`whois_get_dossier` renders every TXT value** ([#8](https://github.com/cyanheads/whois-mcp-server/issues/8)) — `content[]` dropped values past the third. Each value now sits in its own fence, longer than any backtick run inside it.
+- **`whois_get_dns` rejects `types: []`** ([#9](https://github.com/cyanheads/whois-mcp-server/issues/9)) — it fails as `InvalidParams` (`-32602`) before any query instead of reporting a NextDNS lookup that never ran. Omitting `types` still fetches A, AAAA, MX, TXT, NS.
+- **Provider and registry labels match whole domains** ([#12](https://github.com/cyanheads/whois-mcp-server/issues/12)) — `ns_provider` and `mx_provider` compare hostnames at label boundaries with the MX priority removed, and `rdap_source` / `rir` read only the self link's hostname. `ns1.hostname.com` no longer reads as Name.com; Fastmail's `messagingengine.com` is recognized.
+- **`whois_lookup_domain` description** — a TLD without RDAP coverage throws `rdap_no_coverage`; the description previously promised `rdap_coverage: false`.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.13.6` → `^0.13.10`
+- `@socketsecurity/bun-security-scanner` (dev) `^1.1.2` → `^1.1.3`
+- `@types/node` (dev) `^26.6.1` → `^26.6.3`
+- `ignore` (dev) `^7.0.9` → `^7.0.10`
+- `vitest` (dev) `^5.0.1` → `^5.0.2`
+- Bun `1.4.0` → `1.4.2` (`packageManager`, Docker base images)

package/changelog/template.md

@@ -6,8 +6,8 @@
 
 # Required. One-line GitHub Release-style headline. 350 character cap — a
 # ceiling, not a target. Default short and scannable. Don't pad, don't stitch
-# unrelated changes with commas/semicolons into an inventory — pick the
-# headline, like a tag's theme line. Quotes required: unquoted YAML treats
+# unrelated changes with commas/semicolons into an inventory — pick the one
+# headline the release is about. Quotes required: unquoted YAML treats
 # `: ` inside the value as a key separator and fails GitHub's strict parser.
 summary: ""
 
@@ -117,30 +117,13 @@ security: false
   in that unrelated item's metadata.
 
   TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
-  via `gh release create --notes-from-tag`. The tag is a derivative of this
-  changelog entry — a condensed, scannable version, not a copy. Format:
-
-    <theme — omit version number, GitHub prepends it>
-                                                          ← blank line
-    <1-2 sentence context: what this release does>
-                                                          ← blank line
-    Dependency bumps:                                     ← section header
-                                                          ← blank line
-    - `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6          ← bullet
-                                                          ← blank line
-    Changed:                                              ← only sections with entries
-                                                          ← blank line
-    - `format()` output includes `query` in text mode
-                                                          ← blank line
-    Added:
-                                                          ← blank line
-    - `manifest.json` scaffolded for MCPB bundle support
-    - Install badges (Claude Desktop, Cursor, VS Code)
-                                                          ← blank line
-    <N> tests pass; `bun run devcheck` clean.             ← footer
-
-  Never a flat comma-separated string. Always structured markdown with
-  sections. The tag must scan well as a rendered GitHub Release page.
+  via `gh release create --notes-from-tag`. It is a condensed digest of this
+  entry, never a copy, and its format is owned by the `release-and-publish`
+  skill (step 4, "Create the annotated tag"): a short subject line without the
+  version, flat headline bullets — no Keep-a-Changelog section headers, no
+  gates line — at most one deps line, issue backlinks, and the changelog link
+  last. In release-PR mode the `git-wrapup` skill authors those bullets as the
+  PR body's `## Changes` and the tag copies them.
 -->
 
 ## Added

package/dist/app.d.ts

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview whois-mcp-server application wiring — the `createApp()` options
+ * the entry point starts and tests assert against.
+ * @module app
+ */
+export declare const appOptions: {
+    name: string;
+    title: string;
+    /**
+     * No per-session state, and no handler calls `ctx.requestInput` — the session
+     * store and the per-session `McpServer` allocation are pure overhead, and the
+     * process scales horizontally without them. Declared here so the posture holds
+     * however the server is launched; a deployment's `MCP_SESSION_MODE` still wins
+     * when it carries a meaningful value.
+     */
+    sessionMode: "stateless";
+    tools: (import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+        domain: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        domain: import("zod").ZodString;
+        available: import("zod").ZodNullable<import("zod").ZodBoolean>;
+        rdap_coverage: import("zod").ZodBoolean;
+        registrar: import("zod").ZodOptional<import("zod").ZodString>;
+        expiry_date: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>, readonly [{
+        readonly reason: "invalid_domain";
+        readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+        readonly when: "Input is not a valid FQDN.";
+        readonly recovery: "Provide a valid fully-qualified domain name like \"example.com\" or \"sub.example.org\".";
+    }], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+        domain: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        domain: import("zod").ZodString;
+        rdap_coverage: import("zod").ZodNullable<import("zod").ZodBoolean>;
+        registered: import("zod").ZodNullable<import("zod").ZodBoolean>;
+        registrar: import("zod").ZodOptional<import("zod").ZodString>;
+        created_date: import("zod").ZodOptional<import("zod").ZodString>;
+        expiry_date: import("zod").ZodOptional<import("zod").ZodString>;
+        age_days: import("zod").ZodNullable<import("zod").ZodNumber>;
+        dnssec_signed: import("zod").ZodNullable<import("zod").ZodBoolean>;
+        privacy_redacted: import("zod").ZodNullable<import("zod").ZodBoolean>;
+        status: import("zod").ZodArray<import("zod").ZodString>;
+        nameservers: import("zod").ZodArray<import("zod").ZodString>;
+        a_records: import("zod").ZodArray<import("zod").ZodString>;
+        mx_records: import("zod").ZodArray<import("zod").ZodString>;
+        ns_records: import("zod").ZodArray<import("zod").ZodString>;
+        txt_records: import("zod").ZodArray<import("zod").ZodString>;
+        dns_nxdomain: import("zod").ZodNullable<import("zod").ZodBoolean>;
+        ns_provider: import("zod").ZodNullable<import("zod").ZodString>;
+        mx_provider: import("zod").ZodNullable<import("zod").ZodString>;
+        rdap_source_error: import("zod").ZodOptional<import("zod").ZodString>;
+        dns_source_error: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>, readonly [{
+        readonly reason: "invalid_domain";
+        readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+        readonly when: "Input is not a valid FQDN.";
+        readonly recovery: "Provide a valid fully-qualified domain name like \"example.com\" or \"sub.example.org\".";
+    }, {
+        readonly reason: "both_legs_failed";
+        readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
+        readonly when: "Both RDAP and DoH legs failed — no data could be retrieved.";
+        readonly recovery: "Both RDAP and DNS services are unavailable. Retry in a few minutes or check network connectivity.";
+    }], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+        domain: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        domain: import("zod").ZodString;
+        rdap_coverage: import("zod").ZodBoolean;
+        handle: import("zod").ZodOptional<import("zod").ZodString>;
+        registrar: import("zod").ZodOptional<import("zod").ZodString>;
+        registrar_iana_id: import("zod").ZodOptional<import("zod").ZodString>;
+        created_date: import("zod").ZodOptional<import("zod").ZodString>;
+        updated_date: import("zod").ZodOptional<import("zod").ZodString>;
+        expiry_date: import("zod").ZodOptional<import("zod").ZodString>;
+        rdap_last_updated: import("zod").ZodOptional<import("zod").ZodString>;
+        status: import("zod").ZodArray<import("zod").ZodString>;
+        nameservers: import("zod").ZodArray<import("zod").ZodString>;
+        dnssec_signed: import("zod").ZodBoolean;
+        registrant_org: import("zod").ZodOptional<import("zod").ZodString>;
+        registrant_redacted: import("zod").ZodBoolean;
+    }, import("zod/v4/core").$strip>, readonly [{
+        readonly reason: "invalid_domain";
+        readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+        readonly when: "Input is not a valid FQDN.";
+        readonly recovery: "Provide a valid fully-qualified domain name like \"example.com\" or \"sub.example.org\".";
+    }, {
+        readonly reason: "rdap_no_coverage";
+        readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+        readonly when: "TLD has no RDAP server in the IANA bootstrap — cannot perform lookup.";
+        readonly recovery: "This TLD has no RDAP coverage. Use whois_check_availability to test registration status when possible.";
+    }, {
+        readonly reason: "domain_not_found";
+        readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+        readonly when: "RDAP server returned 404 — domain is not registered.";
+        readonly recovery: "The domain is not registered. Use whois_check_availability to confirm availability for registration.";
+    }], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+        domain: import("zod").ZodString;
+        types: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodEnum<{
+            A: "A";
+            AAAA: "AAAA";
+            CAA: "CAA";
+            CNAME: "CNAME";
+            MX: "MX";
+            NS: "NS";
+            PTR: "PTR";
+            SOA: "SOA";
+            TXT: "TXT";
+        }>>>;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        domain: import("zod").ZodString;
+        nxdomain: import("zod").ZodBoolean;
+        records: import("zod").ZodArray<import("zod").ZodObject<{
+            type: import("zod").ZodEnum<{
+                A: "A";
+                AAAA: "AAAA";
+                CAA: "CAA";
+                CNAME: "CNAME";
+                MX: "MX";
+                NS: "NS";
+                PTR: "PTR";
+                SOA: "SOA";
+                TXT: "TXT";
+            }>;
+            name: import("zod").ZodString;
+            ttl: import("zod").ZodNumber;
+            data: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>>;
+        source: import("zod").ZodEnum<{
+            cloudflare: "cloudflare";
+            nextdns: "nextdns";
+        }>;
+        query_sources: import("zod").ZodArray<import("zod").ZodObject<{
+            type: import("zod").ZodEnum<{
+                A: "A";
+                AAAA: "AAAA";
+                CAA: "CAA";
+                CNAME: "CNAME";
+                MX: "MX";
+                NS: "NS";
+                PTR: "PTR";
+                SOA: "SOA";
+                TXT: "TXT";
+            }>;
+            source: import("zod").ZodEnum<{
+                cloudflare: "cloudflare";
+                nextdns: "nextdns";
+            }>;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>, readonly [{
+        readonly reason: "invalid_domain";
+        readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+        readonly when: "Input is not a valid FQDN.";
+        readonly recovery: "Provide a valid fully-qualified domain name like \"example.com\" or \"sub.example.org\".";
+    }], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+        ip: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        ip: import("zod").ZodString;
+        handle: import("zod").ZodOptional<import("zod").ZodString>;
+        start_address: import("zod").ZodOptional<import("zod").ZodString>;
+        end_address: import("zod").ZodOptional<import("zod").ZodString>;
+        cidr: import("zod").ZodOptional<import("zod").ZodString>;
+        ip_version: import("zod").ZodOptional<import("zod").ZodString>;
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        type: import("zod").ZodOptional<import("zod").ZodString>;
+        country: import("zod").ZodOptional<import("zod").ZodString>;
+        org_name: import("zod").ZodOptional<import("zod").ZodString>;
+        abuse_email: import("zod").ZodOptional<import("zod").ZodString>;
+        ptr: import("zod").ZodNullable<import("zod").ZodString>;
+        rdap_source: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>, readonly [{
+        readonly reason: "invalid_ip";
+        readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+        readonly when: "Input is not a valid IPv4, IPv6, or CIDR address.";
+        readonly recovery: "Provide a valid IPv4 (e.g., \"8.8.8.8\"), IPv6 (e.g., \"2001:db8::1\"), or CIDR (e.g., \"192.0.2.0/24\").";
+    }, {
+        readonly reason: "private_range";
+        readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+        readonly when: "The numeric address falls within the server’s explicit excluded ranges.";
+        readonly recovery: "Choose an address outside the excluded ranges listed in this tool’s description.";
+        readonly thrownBy: "service";
+    }, {
+        readonly reason: "ip_not_found";
+        readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+        readonly when: "RIR RDAP returned 404 — no netblock record for this address.";
+        readonly recovery: "The IP address is not found in any RIR RDAP database. Try a different IP or verify it is globally routable.";
+        readonly thrownBy: "service";
+    }], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+        asn: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        asn: import("zod").ZodString;
+        handle: import("zod").ZodOptional<import("zod").ZodString>;
+        start_autnum: import("zod").ZodOptional<import("zod").ZodNumber>;
+        end_autnum: import("zod").ZodOptional<import("zod").ZodNumber>;
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        type: import("zod").ZodOptional<import("zod").ZodString>;
+        country: import("zod").ZodOptional<import("zod").ZodString>;
+        org_name: import("zod").ZodOptional<import("zod").ZodString>;
+        rir: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>, readonly [{
+        readonly reason: "invalid_asn";
+        readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+        readonly when: "The complete token is not a decimal ASN from 1 to 4294967295.";
+        readonly recovery: "Provide a decimal integer from 1 to 4294967295, optionally prefixed with AS and +, such as \"AS15169\" or \"+15169\".";
+        readonly thrownBy: "service";
+    }, {
+        readonly reason: "asn_not_found";
+        readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+        readonly when: "RDAP returned 404 — ASN not found in any RIR.";
+        readonly recovery: "The ASN is not found in any RIR RDAP database. Verify the ASN number is correct and assigned.";
+        readonly thrownBy: "service";
+    }], undefined>)[];
+    resources: never[];
+    prompts: never[];
+    instructions: string;
+    setup(core: import("@cyanheads/mcp-ts-core").CoreServices<object>): void;
+};
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,eAAO,MAAM,UAAU;;;IAGrB;;;;;;OAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwBuB,CAAC"}

package/dist/app.js

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview whois-mcp-server application wiring — the `createApp()` options
+ * the entry point starts and tests assert against.
+ * @module app
+ */
+import { whoisCheckAvailability } from './mcp-server/tools/definitions/whois-check-availability.tool.js';
+import { whoisGetDns } from './mcp-server/tools/definitions/whois-get-dns.tool.js';
+import { whoisGetDossier } from './mcp-server/tools/definitions/whois-get-dossier.tool.js';
+import { whoisLookupAsn } from './mcp-server/tools/definitions/whois-lookup-asn.tool.js';
+import { whoisLookupDomain } from './mcp-server/tools/definitions/whois-lookup-domain.tool.js';
+import { whoisLookupIp } from './mcp-server/tools/definitions/whois-lookup-ip.tool.js';
+import { initDohService } from './services/doh/doh-service.js';
+import { initRdapService } from './services/rdap/rdap-service.js';
+export const appOptions = {
+    name: 'whois-mcp-server',
+    title: 'whois-mcp-server',
+    /**
+     * No per-session state, and no handler calls `ctx.requestInput` — the session
+     * store and the per-session `McpServer` allocation are pure overhead, and the
+     * process scales horizontally without them. Declared here so the posture holds
+     * however the server is launched; a deployment's `MCP_SESSION_MODE` still wins
+     * when it carries a meaningful value.
+     */
+    sessionMode: 'stateless',
+    tools: [
+        whoisLookupDomain,
+        whoisCheckAvailability,
+        whoisGetDns,
+        whoisLookupIp,
+        whoisLookupAsn,
+        whoisGetDossier,
+    ],
+    resources: [],
+    prompts: [],
+    instructions: 'whois-mcp-server: domain and IP intelligence via RDAP and DNS-over-HTTPS. No API keys required.\n' +
+        '- whois_lookup_domain: full registration record (registrar, dates, status, nameservers)\n' +
+        '- whois_check_availability: is a domain available to register? (RDAP 404 = available)\n' +
+        '- whois_get_dns: DNS records for any hostname (A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, PTR)\n' +
+        '- whois_lookup_ip: IP/CIDR netblock, org, abuse contact, and PTR via RIR RDAP\n' +
+        '- whois_lookup_asn: ASN to org/RIR resolution\n' +
+        '- whois_get_dossier: one-call domain triage — registration + DNS in parallel with inferred signals',
+    setup(core) {
+        initRdapService(core.config, core.storage);
+        initDohService(core.config, core.storage);
+    },
+};
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,iEAAiE,CAAC;AACzG,OAAO,EAAE,WAAW,EAAE,MAAM,sDAAsD,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,4DAA4D,CAAC;AAC/F,OAAO,EAAE,aAAa,EAAE,MAAM,wDAAwD,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,IAAI,EAAE,kBAAkB;IACxB,KAAK,EAAE,kBAAkB;IACzB;;;;;;OAMG;IACH,WAAW,EAAE,WAAW;IACxB,KAAK,EAAE;QACL,iBAAiB;QACjB,sBAAsB;QACtB,WAAW;QACX,aAAa;QACb,cAAc;QACd,eAAe;KAChB;IACD,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,YAAY,EACV,mGAAmG;QACnG,2FAA2F;QAC3F,yFAAyF;QACzF,8FAA8F;QAC9F,iFAAiF;QACjF,iDAAiD;QACjD,oGAAoG;IACtG,KAAK,CAAC,IAAI;QACR,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3C,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC;CACyB,CAAC"}