@rog0x/mcp-network-tools 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# mcp-network-tools
+
+Network diagnostics tools for AI agents, exposed via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `dns_lookup` | Resolve domains to DNS records (A, AAAA, MX, TXT, NS, CNAME, SOA). Reverse DNS. Propagation check across public DNS servers. |
+| `ip_info` | Geolocation and network info for an IP address — country, city, ISP, ASN, coordinates. IPv4 and IPv6. |
+| `ssl_check` | Inspect SSL/TLS certificates — validity, issuer, expiry, SANs, certificate chain, cipher, protocol. |
+| `whois_lookup` | WHOIS data for a domain — registrar, creation/expiry dates, nameservers, status. |
+| `http_ping` | Measure HTTP response time over N requests. Returns avg, min, max, p95 latency and success rate. |
+
+## Setup
+
+```bash
+npm install
+npm run build
+```
+
+## Usage with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "network-tools": {
+      "command": "node",
+      "args": ["D:/products/mcp-servers/mcp-network-tools/dist/index.js"]
+    }
+  }
+}
+```
+
+## Dependencies
+
+- **@modelcontextprotocol/sdk** — MCP server framework
+- **Node.js built-in modules** — `dns`, `tls`, `net`, `https`, `http` (no external runtime dependencies beyond MCP SDK)
+- **ip-api.com** — free geolocation API (no API key required)
+
+## Examples
+
+### DNS Lookup
+```
+dns_lookup({ domain: "example.com", record_types: ["A", "MX"] })
+```
+
+### Reverse DNS
+```
+dns_lookup({ domain: "8.8.8.8", mode: "reverse" })
+```
+
+### DNS Propagation Check
+```
+dns_lookup({ domain: "example.com", mode: "propagation" })
+```
+
+### IP Info
+```
+ip_info({ ip: "1.1.1.1" })
+```
+
+### SSL Check
+```
+ssl_check({ host: "example.com" })
+```
+
+### WHOIS Lookup
+```
+whois_lookup({ domain: "example.com" })
+```
+
+### HTTP Ping
+```
+http_ping({ url: "https://example.com", count: 10 })
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const dns_lookup_js_1 = require("./tools/dns-lookup.js");
+const ip_info_js_1 = require("./tools/ip-info.js");
+const ssl_checker_js_1 = require("./tools/ssl-checker.js");
+const whois_lookup_js_1 = require("./tools/whois-lookup.js");
+const ping_tool_js_1 = require("./tools/ping-tool.js");
+const server = new index_js_1.Server({
+    name: "mcp-network-tools",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "dns_lookup",
+            description: "Resolve a domain name to DNS records (A, AAAA, MX, TXT, NS, CNAME, SOA). Supports reverse DNS and propagation checking.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    domain: {
+                        type: "string",
+                        description: "Domain name to look up (e.g. example.com)",
+                    },
+                    record_types: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Record types to query (default: all). Options: A, AAAA, MX, TXT, NS, CNAME, SOA",
+                    },
+                    mode: {
+                        type: "string",
+                        enum: ["resolve", "reverse", "propagation"],
+                        description: "Mode: 'resolve' (default) for forward DNS, 'reverse' for reverse DNS (pass IP in domain), 'propagation' to check across public DNS servers",
+                    },
+                },
+                required: ["domain"],
+            },
+        },
+        {
+            name: "ip_info",
+            description: "Get geolocation and network information for an IP address: country, city, ISP, ASN, coordinates. Supports IPv4 and IPv6.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    ip: {
+                        type: "string",
+                        description: "IPv4 or IPv6 address to look up",
+                    },
+                },
+                required: ["ip"],
+            },
+        },
+        {
+            name: "ssl_check",
+            description: "Check the SSL/TLS certificate of a host: validity, issuer, expiry date, days until expiry, subject alternative names, certificate chain, cipher, and protocol.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    host: {
+                        type: "string",
+                        description: "Hostname to check (e.g. example.com)",
+                    },
+                    port: {
+                        type: "number",
+                        description: "Port number (default: 443)",
+                    },
+                },
+                required: ["host"],
+            },
+        },
+        {
+            name: "whois_lookup",
+            description: "Look up WHOIS information for a domain: registrar, creation date, expiry date, nameservers, and domain status.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    domain: {
+                        type: "string",
+                        description: "Domain name to look up (e.g. example.com)",
+                    },
+                },
+                required: ["domain"],
+            },
+        },
+        {
+            name: "http_ping",
+            description: "Measure HTTP response time to a URL over multiple requests. Returns per-request latency and statistics: average, min, max, p95, and success rate.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    url: {
+                        type: "string",
+                        description: "URL to ping (e.g. https://example.com)",
+                    },
+                    count: {
+                        type: "number",
+                        description: "Number of requests to send (default: 5, max: 20)",
+                    },
+                    timeout_ms: {
+                        type: "number",
+                        description: "Timeout per request in milliseconds (default: 10000)",
+                    },
+                },
+                required: ["url"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "dns_lookup": {
+                const domain = args?.domain;
+                const mode = args?.mode || "resolve";
+                const recordTypes = args?.record_types;
+                let result;
+                switch (mode) {
+                    case "reverse":
+                        result = await (0, dns_lookup_js_1.reverseDns)(domain);
+                        break;
+                    case "propagation":
+                        result = await (0, dns_lookup_js_1.checkPropagation)(domain, recordTypes?.[0] || "A");
+                        break;
+                    default:
+                        result = await (0, dns_lookup_js_1.dnsLookup)(domain, recordTypes);
+                        break;
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "ip_info": {
+                const result = await (0, ip_info_js_1.getIpInfo)(args?.ip);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "ssl_check": {
+                const port = args?.port || 443;
+                const result = await (0, ssl_checker_js_1.checkSsl)(args?.host, port);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "whois_lookup": {
+                const result = await (0, whois_lookup_js_1.whoisLookup)(args?.domain);
+                // Return parsed data without the full raw WHOIS by default to save tokens
+                const { raw, ...summary } = result;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ ...summary, rawLength: raw.length }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "http_ping": {
+                const count = args?.count || 5;
+                const timeoutMs = args?.timeout_ms || 10000;
+                const result = await (0, ping_tool_js_1.httpPing)(args?.url, count, timeoutMs);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP Network Tools server running on stdio");
+}
+main().catch(console.error);
+//# sourceMappingURL=index.js.map

package/dist/tools/dns-lookup.d.ts

@@ -0,0 +1,20 @@
+interface DnsLookupResult {
+    domain: string;
+    records: Record<string, unknown>;
+    timestamp: string;
+}
+interface ReverseDnsResult {
+    ip: string;
+    hostnames: string[];
+    timestamp: string;
+}
+export declare function dnsLookup(domain: string, recordTypes?: string[]): Promise<DnsLookupResult>;
+export declare function reverseDns(ip: string): Promise<ReverseDnsResult>;
+export declare function checkPropagation(domain: string, recordType?: string): Promise<{
+    domain: string;
+    recordType: string;
+    servers: Record<string, unknown>;
+    consistent: boolean;
+    timestamp: string;
+}>;
+export {};

package/dist/tools/dns-lookup.js

@@ -0,0 +1,132 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dnsLookup = dnsLookup;
+exports.reverseDns = reverseDns;
+exports.checkPropagation = checkPropagation;
+const dns = __importStar(require("node:dns"));
+const node_util_1 = require("node:util");
+const resolve4 = (0, node_util_1.promisify)(dns.resolve4);
+const resolve6 = (0, node_util_1.promisify)(dns.resolve6);
+const resolveMx = (0, node_util_1.promisify)(dns.resolveMx);
+const resolveTxt = (0, node_util_1.promisify)(dns.resolveTxt);
+const resolveNs = (0, node_util_1.promisify)(dns.resolveNs);
+const resolveCname = (0, node_util_1.promisify)(dns.resolveCname);
+const resolveSoa = (0, node_util_1.promisify)(dns.resolveSoa);
+const reverseLookup = (0, node_util_1.promisify)(dns.reverse);
+async function safeResolve(fn) {
+    try {
+        return await fn();
+    }
+    catch {
+        return null;
+    }
+}
+async function dnsLookup(domain, recordTypes) {
+    const types = recordTypes?.map((t) => t.toUpperCase()) ?? [
+        "A",
+        "AAAA",
+        "MX",
+        "TXT",
+        "NS",
+        "CNAME",
+        "SOA",
+    ];
+    const records = {};
+    const resolvers = {
+        A: () => resolve4(domain),
+        AAAA: () => resolve6(domain),
+        MX: () => resolveMx(domain),
+        TXT: () => resolveTxt(domain),
+        NS: () => resolveNs(domain),
+        CNAME: () => resolveCname(domain),
+        SOA: () => resolveSoa(domain),
+    };
+    await Promise.all(types.map(async (type) => {
+        const resolver = resolvers[type];
+        if (resolver) {
+            const result = await safeResolve(resolver);
+            if (result !== null) {
+                records[type] = result;
+            }
+        }
+    }));
+    return {
+        domain,
+        records,
+        timestamp: new Date().toISOString(),
+    };
+}
+async function reverseDns(ip) {
+    const hostnames = await reverseLookup(ip);
+    return {
+        ip,
+        hostnames,
+        timestamp: new Date().toISOString(),
+    };
+}
+async function checkPropagation(domain, recordType = "A") {
+    const dnsServers = {
+        "Google": "8.8.8.8",
+        "Cloudflare": "1.1.1.1",
+        "OpenDNS": "208.67.222.222",
+        "Quad9": "9.9.9.9",
+    };
+    const resolver = new dns.Resolver();
+    const resolveWithServer = (0, node_util_1.promisify)(resolver.resolve.bind(resolver));
+    const results = {};
+    const allRecords = [];
+    for (const [name, server] of Object.entries(dnsServers)) {
+        try {
+            resolver.setServers([server]);
+            const records = await resolveWithServer(domain, recordType);
+            results[name] = { server, records };
+            allRecords.push(JSON.stringify(records));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            results[name] = { server, error: message };
+        }
+    }
+    const uniqueResults = new Set(allRecords);
+    return {
+        domain,
+        recordType,
+        servers: results,
+        consistent: uniqueResults.size <= 1,
+        timestamp: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=dns-lookup.js.map

package/dist/tools/ip-info.d.ts

@@ -0,0 +1,20 @@
+interface IpInfoResult {
+    ip: string;
+    country: string;
+    countryCode: string;
+    region: string;
+    regionName: string;
+    city: string;
+    zip: string;
+    lat: number;
+    lon: number;
+    timezone: string;
+    isp: string;
+    org: string;
+    as: string;
+    asn: string;
+    query: string;
+    timestamp: string;
+}
+export declare function getIpInfo(ip: string): Promise<IpInfoResult>;
+export {};

package/dist/tools/ip-info.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getIpInfo = getIpInfo;
+const node_http_1 = __importDefault(require("node:http"));
+function httpGet(url) {
+    return new Promise((resolve, reject) => {
+        const req = node_http_1.default.get(url, { timeout: 10000 }, (res) => {
+            let data = "";
+            res.on("data", (chunk) => {
+                data += chunk.toString();
+            });
+            res.on("end", () => resolve(data));
+            res.on("error", reject);
+        });
+        req.on("error", reject);
+        req.on("timeout", () => {
+            req.destroy();
+            reject(new Error("Request timed out"));
+        });
+    });
+}
+async function getIpInfo(ip) {
+    const url = `http://ip-api.com/json/${encodeURIComponent(ip)}?fields=status,message,country,countryCode,region,regionName,city,zip,lat,lon,timezone,isp,org,as,query`;
+    const raw = await httpGet(url);
+    const data = JSON.parse(raw);
+    if (data.status === "fail") {
+        throw new Error(`IP lookup failed: ${data.message}`);
+    }
+    const asString = data.as || "";
+    const asnMatch = asString.match(/^AS(\d+)/);
+    return {
+        ip,
+        country: data.country ?? "",
+        countryCode: data.countryCode ?? "",
+        region: data.region ?? "",
+        regionName: data.regionName ?? "",
+        city: data.city ?? "",
+        zip: data.zip ?? "",
+        lat: data.lat ?? 0,
+        lon: data.lon ?? 0,
+        timezone: data.timezone ?? "",
+        isp: data.isp ?? "",
+        org: data.org ?? "",
+        as: asString,
+        asn: asnMatch ? `AS${asnMatch[1]}` : "",
+        query: data.query ?? ip,
+        timestamp: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=ip-info.js.map

package/dist/tools/ping-tool.d.ts

@@ -0,0 +1,19 @@
+interface PingResult {
+    url: string;
+    requests: number;
+    results: Array<{
+        attempt: number;
+        statusCode: number;
+        latencyMs: number;
+    }>;
+    stats: {
+        avgMs: number;
+        minMs: number;
+        maxMs: number;
+        p95Ms: number;
+        successRate: number;
+    };
+    timestamp: string;
+}
+export declare function httpPing(url: string, count?: number, timeoutMs?: number): Promise<PingResult>;
+export {};

package/dist/tools/ping-tool.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpPing = httpPing;
+const node_https_1 = __importDefault(require("node:https"));
+const node_http_1 = __importDefault(require("node:http"));
+const node_url_1 = require("node:url");
+function singlePing(url, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const parsed = new node_url_1.URL(url);
+        const client = parsed.protocol === "https:" ? node_https_1.default : node_http_1.default;
+        const start = performance.now();
+        const req = client.get(url, {
+            timeout: timeoutMs,
+            headers: {
+                "User-Agent": "mcp-network-tools/1.0",
+            },
+        }, (res) => {
+            const latencyMs = Math.round((performance.now() - start) * 100) / 100;
+            // Consume response data to free memory
+            res.resume();
+            res.on("end", () => {
+                resolve({
+                    statusCode: res.statusCode || 0,
+                    latencyMs,
+                });
+            });
+        });
+        req.on("error", (err) => {
+            reject(err);
+        });
+        req.on("timeout", () => {
+            req.destroy();
+            reject(new Error("Request timed out"));
+        });
+    });
+}
+function percentile(sorted, p) {
+    const index = Math.ceil((p / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, index)];
+}
+async function httpPing(url, count = 5, timeoutMs = 10000) {
+    const safeCount = Math.min(Math.max(1, count), 20);
+    const results = [];
+    for (let i = 0; i < safeCount; i++) {
+        try {
+            const { statusCode, latencyMs } = await singlePing(url, timeoutMs);
+            results.push({ attempt: i + 1, statusCode, latencyMs });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            results.push({ attempt: i + 1, statusCode: 0, latencyMs: -1 });
+        }
+    }
+    const successfulLatencies = results
+        .filter((r) => r.latencyMs >= 0)
+        .map((r) => r.latencyMs)
+        .sort((a, b) => a - b);
+    const successCount = successfulLatencies.length;
+    const stats = {
+        avgMs: successCount > 0
+            ? Math.round((successfulLatencies.reduce((a, b) => a + b, 0) / successCount) *
+                100) / 100
+            : -1,
+        minMs: successCount > 0 ? successfulLatencies[0] : -1,
+        maxMs: successCount > 0 ? successfulLatencies[successCount - 1] : -1,
+        p95Ms: successCount > 0 ? percentile(successfulLatencies, 95) : -1,
+        successRate: Math.round((successCount / safeCount) * 10000) / 100,
+    };
+    return {
+        url,
+        requests: safeCount,
+        results,
+        stats,
+        timestamp: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=ping-tool.js.map

package/dist/tools/ssl-checker.d.ts

@@ -0,0 +1,23 @@
+interface CertificateInfo {
+    host: string;
+    valid: boolean;
+    issuer: Record<string, string>;
+    subject: Record<string, string>;
+    validFrom: string;
+    validTo: string;
+    daysUntilExpiry: number;
+    serialNumber: string;
+    fingerprint: string;
+    fingerprint256: string;
+    subjectAltNames: string[];
+    protocol: string;
+    cipher: string;
+    chain: Array<{
+        subject: string;
+        issuer: string;
+        validTo: string;
+    }>;
+    timestamp: string;
+}
+export declare function checkSsl(host: string, port?: number): Promise<CertificateInfo>;
+export {};