mcp-www 0.1.4 → 0.2.0

package/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 
-**DNS-based MCP service discovery over UDP.**
+**DNS-based MCP service discovery and installation.**
 
 ## Problem
 
@@ -15,12 +15,12 @@ Agents need to discover MCP servers, but current approaches lean on centralized
 
 **mcp-www** is itself a standard MCP server. An agent connects to it the same way it connects to any other MCP server — no new client code, no special SDK, no registry signup.
 
-Once connected, the agent calls the `browse_domain` tool with a domain name. mcp-www performs a standard **UDP DNS TXT lookup** for `_mcp.{domain}`, parses the semicolon-delimited record, and returns structured metadata about the MCP servers published by that domain.
+Once connected, the agent calls `discover` with a domain name. mcp-www performs a standard **UDP DNS TXT lookup** for `_mcp.{domain}`, parses the records, and returns all advertised MCP servers. Then `browse` connects to those servers and retrieves their full manifests. Finally, `install` generates the config to permanently add a server to the user's MCP client.
 
 ```
-Agent  →  mcp-www (MCP server)  →  UDP DNS query for _mcp.example.com TXT
-                                    ←  "v=mcp1; src=https://mcp.example.com; ..."
-       ←  Structured JSON response
+Agent  →  mcp-www  →  discover("example.com")  →  DNS TXT lookup
+                   →  browse("example.com")     →  server card GET with MCP handshake fallback
+                   →  install("example.com")    →  config for Claude Desktop / VS Code / Cursor / Windsurf
 ```
 
 No HTTP registry in the loop. The DNS infrastructure **is** the registry.
@@ -55,92 +55,62 @@ Add to your MCP client config (e.g., `.mcp.json`):
 
 ## Try It
 
-🤖 Use your agent for easy `mcp-www` installation or follow the manual steps above.  Simply ask it to install mcp-www from npm (many clients require a restart for a new server.)
-
-🚀 **Publish your own MCP server via _dns TXT record** - or -
-
 **[korm.co](https://korm.co)** publishes a live `_mcp` TXT record. You can discover and interact with it end-to-end:
 
 ```
-browse_discover("korm.co")      → discovers server, returns tools + resources + prompts
-browse_server("https://mcp.korm.co")  → inspects tools, resources, and prompts
-call_remote_tool("https://mcp.korm.co", "list_articles")  → returns blog articles
-read_remote_resource("https://mcp.korm.co", "korm://bio")  → reads author bio
-get_remote_prompt("https://mcp.korm.co", "recommend-post", { "topic": "AI" })  → gets prompt
+discover("korm.co")            → DNS lookup, returns all _mcp TXT records
+discover_browse("korm.co")     → DNS + server card in one call, init as fallback
+browse({ domain: "korm.co" })  → server card first, MCP handshake as fallback
+call_remote_tool("https://mcp.korm.co", "browse_posts")  → returns blog articles
+read_remote_resource("https://mcp.korm.co", "korm://bio") → reads author bio
+get_remote_prompt("https://mcp.korm.co", "recommend-post", { "topic": "AI" }) → gets prompt
+install({ domain: "korm.co" }) → generates config to add to your MCP client
 ```
-⚠️ korm.co is a construction zone of new services so pardon any dust or temporary infra outages, thanks for your patience.
-
 
 ## Key Design Points
 
-- **Uses UDP DNS (port 53) for lookups** — the lightest possible network primitive. No TCP handshake, no TLS negotiation, no HTTP overhead. A single UDP packet out, a single packet back.
+- **Uses UDP DNS (port 53) for lookups** — the lightest possible network primitive. A single UDP packet out, a single packet back.
 - **The DNS infrastructure IS the registry** — no additional servers to deploy, no uptime to maintain, no accounts to create. If you can publish a TXT record, you can advertise your MCP server.
-- **mcp-www is a standard MCP server** — any MCP-compliant agent can use it with zero new client code. It's just another server in your agent's config.
-- **Supports the `_mcp` TXT record convention** — records follow a semicolon-delimited format:
+- **mcp-www is a standard MCP server** — any MCP-compliant agent can use it with zero new client code.
+- **Multiple TXT records supported** — a domain can advertise multiple MCP servers via separate `_mcp` TXT records.
+- **Supports the `_mcp` TXT record convention:**
   ```
   v=mcp1; src=https://mcp.example.com; auth=oauth2
   ```
-- **Works with split-horizon DNS** — enterprise and private networks can publish internal `_mcp` records visible only inside their network, enabling private service discovery without exposing anything to the public internet.
+- **Works with split-horizon DNS** — enterprise and private networks can publish internal `_mcp` records visible only inside their network.
+- Allows overriding the default system DNS resolver via environment variable: `MCP_DNS_SERVER=192.168.68.133:5335 npx mcp-www`
 
-## Tools Exposed
+## Tools
 
-### `browse_domain`
+### `discover`
 
-Lookup `_mcp.{domain}` TXT records and return a parsed list of discovered MCP servers.
+DNS-only lookup. Returns all `_mcp.{domain}` TXT records — there can be multiple, each advertising a different MCP server. Supports single domain or batch lookup.
 
 ```json
-{
-  "tool": "browse_domain",
-  "arguments": {
-    "domain": "example.com"
-  }
-}
+{ "tool": "discover", "arguments": { "domain": "example.com" } }
+{ "tool": "discover", "arguments": { "domains": ["example.com", "acme.org"] } }
 ```
 
-Returns structured server metadata: server URL, protocol version, auth requirements, and any additional fields published in the TXT record.
-
-### `browse_discover`
+### `discover_browse`
 
-Discover and inspect in one step. Looks up `_mcp.{domain}` TXT records, connects to the advertised server URL, and retrieves its full manifest — tools, resources, and prompts.
+DNS lookup + server card in one call. Looks up all `_mcp.{domain}` TXT records, then fetches `.well-known/mcp.json` for server metadata. Only falls back to MCP initialize if no server card is found.
 
 ```json
-{
-  "tool": "browse_discover",
-  "arguments": {
-    "domain": "example.com"
-  }
-}
-```
-
-### `browse_server`
-
-Given a discovered server URL, connect to it and retrieve its full manifest: tools, resources, and prompts. Lets the agent inspect what a discovered server actually offers before deciding to connect.
-
-```json
-{
-  "tool": "browse_server",
-  "arguments": {
-    "url": "https://mcp.example.com"
-  }
-}
+{ "tool": "discover_browse", "arguments": { "domain": "example.com" } }
 ```
 
-### `browse_multi`
+### `browse`
 
-Batch lookup across multiple domains in a single call. Useful for scanning a list of known domains or performing broad discovery.
+Inspect a domain or server URL. Tries `.well-known/mcp.json` (server card) first, only falls back to MCP initialize handshake if no server card is found. For domains: also performs DNS lookup for `_mcp` TXT records.
 
 ```json
-{
-  "tool": "browse_multi",
-  "arguments": {
-    "domains": ["example.com", "acme.org", "internal.corp"]
-  }
-}
+{ "tool": "browse", "arguments": { "domain": "example.com" } }
+{ "tool": "browse", "arguments": { "url": "https://mcp.example.com" } }
 ```
 
 ### `call_remote_tool`
 
-Call a tool on a remote MCP server. Use `browse_server` first to discover available tools, then use this to execute them. Handles the JSON-RPC initialize handshake and `tools/call` request.
+Call a tool on a remote MCP server. Use `browse` first to discover available tools, then use this to execute them.
 
 ```json
 {
@@ -155,7 +125,7 @@ Call a tool on a remote MCP server. Use `browse_server` first to discover availa
 
 ### `read_remote_resource`
 
-Read a resource from a remote MCP server. Use `browse_server` or `browse_discover` first to see available resources, then use this to read one by its URI.
+Read a resource from a remote MCP server by its URI.
 
 ```json
 {
@@ -169,7 +139,7 @@ Read a resource from a remote MCP server. Use `browse_server` or `browse_discove
 
 ### `get_remote_prompt`
 
-Get a prompt from a remote MCP server. Use `browse_server` or `browse_discover` first to see available prompts, then use this to retrieve one with optional arguments.
+Get a prompt from a remote MCP server with optional arguments.
 
 ```json
 {
@@ -182,13 +152,44 @@ Get a prompt from a remote MCP server. Use `browse_server` or `browse_discover`
 }
 ```
 
+### `install`
+
+Generate client configuration to permanently add a discovered MCP server. Returns config file paths and JSON entries for Claude Desktop, VS Code, Cursor, and Windsurf. The agent reads the target config file, merges the entry, and writes it back.
+
+```json
+{ "tool": "install", "arguments": { "domain": "example.com" } }
+{ "tool": "install", "arguments": { "url": "https://mcp.example.com", "name": "my-server" } }
+```
 
 ## Status
 
-**Working.** The server implements DNS-based discovery, server inspection, remote tool calling, resource reading, and prompt retrieval over the Streamable HTTP transport.
+**Working.** The server implements DNS-based discovery, server inspection, remote tool calling, resource reading, prompt retrieval, and client installation over the Streamable HTTP transport.
 
 Feedback, criticism, and alternative approaches are welcome — open an issue or start a discussion.
 
+## Security
+
+### DNS-based trust model
+
+Because mcp-www uses DNS TXT records for discovery, domain ownership is enforced by DNS infrastructure itself — only the domain owner (or their DNS provider) can publish `_mcp` TXT records. This is inherently stronger than centralized registries, which introduce a single point of compromise.
+
+### IDN homograph attack detection
+
+mcp-www detects [IDN homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack) on all domain lookups. These attacks use visually identical characters from different Unicode scripts (e.g., Cyrillic "a" vs Latin "a") to spoof legitimate domains.
+
+Detection covers:
+- **Punycode-encoded domains** — labels starting with `xn--` (the ASCII encoding of internationalized domain names)
+- **Mixed-script labels** — a single label containing characters from multiple scripts (e.g., Latin + Cyrillic)
+- **Non-Latin labels** — fully Cyrillic/Greek labels that could visually mimic common Latin domains
+
+When detected, a prominent warning is surfaced as a separate content block, instructing the agent to verify the domain with the user before proceeding. Lookups are not blocked — the warning is informational.
+
+### Additional considerations
+
+- **No implicit trust** — mcp-www discovers and inspects remote servers, but tool execution (`call_remote_tool`) is always an explicit agent action.
+- **Split-horizon DNS** — private/internal `_mcp` records are only resolvable within the network they're published on.
+- **Unicode normalization** — all domain inputs are NFC-normalized before lookup.
+
 ## Related
 
 - [Model Context Protocol Specification](https://modelcontextprotocol.io/specification)

package/dist/index.js

@@ -15,6 +15,11 @@ const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const node_dns_1 = __importDefault(require("node:dns"));
 const node_util_1 = require("node:util");
+// Allow overriding the DNS resolver via environment variable.
+// Supports "host:port" format (e.g., "192.168.68.133:5335").
+if (process.env.MCP_DNS_SERVER) {
+    node_dns_1.default.setServers([process.env.MCP_DNS_SERVER]);
+}
 const resolveTxt = (0, node_util_1.promisify)(node_dns_1.default.resolveTxt);
 // --- IDN Homograph Detection ---
 function detectHomograph(domain) {
@@ -25,7 +30,6 @@ function detectHomograph(domain) {
         return `Domain contains punycode-encoded label(s): ${punycodeLabels.join(", ")}. This may be an IDN homograph attack — visually similar characters from different scripts (e.g., Cyrillic) can make a domain look identical to a legitimate one.`;
     }
     // Check for mixed Unicode scripts within a single label
-    // Common confusable scripts: Cyrillic, Greek, Latin
     for (const label of labels) {
         let hasLatin = false;
         let hasNonLatin = false;
@@ -45,14 +49,10 @@ function detectHomograph(domain) {
                 if (!detectedScripts.includes("Greek"))
                     detectedScripts.push("Greek");
             }
-            else if (code >= 0x0100 && code <= 0x024f) {
-                // Latin Extended — not suspicious on its own but flag with others
-            }
         }
         if (hasLatin && hasNonLatin) {
             return `Domain label "${label}" mixes Latin with ${detectedScripts.join("/")} characters. This is a strong indicator of an IDN homograph attack.`;
         }
-        // Fully non-Latin label (e.g., all Cyrillic) pretending to be a common domain
         if (hasNonLatin && !hasLatin && detectedScripts.length > 0) {
             return `Domain label "${label}" uses ${detectedScripts.join("/")} script characters that may visually mimic Latin characters. Verify this is the intended domain.`;
         }
@@ -72,49 +72,44 @@ function formatHomographWarning(warning) {
     };
 }
 // --- TXT Record Parser ---
-function parseMcpTxtRecord(txtRecords) {
-    // TXT records come as arrays of strings (chunked), join them
-    const fullRecord = txtRecords.map((chunks) => chunks.join("")).join("");
+function parseSingleTxtRecord(chunks) {
+    const fullRecord = chunks.join("");
     const result = {};
-    // Parse semicolon-delimited key=value pairs
-    // e.g. "v=mcp1; endpoint=https://...; public=true"
     const pairs = fullRecord.split(";").map((s) => s.trim()).filter(Boolean);
     for (const pair of pairs) {
         const eqIndex = pair.indexOf("=");
         if (eqIndex > 0) {
-            const key = pair.slice(0, eqIndex).trim();
-            const value = pair.slice(eqIndex + 1).trim();
-            result[key] = value;
+            result[pair.slice(0, eqIndex).trim()] = pair.slice(eqIndex + 1).trim();
         }
     }
     return result;
 }
-// --- DNS Lookup ---
+// --- DNS Lookup (returns ALL TXT records) ---
 async function lookupMcpDomain(domain) {
-    // Normalize Unicode and detect homograph attacks
     const normalized = domain.normalize("NFC");
     const warning = detectHomograph(normalized);
     const mcpDomain = `_mcp.${normalized}`;
     try {
-        const records = await resolveTxt(mcpDomain);
-        if (records.length === 0) {
-            return { record: null, ...(warning && { homograph_warning: warning }) };
+        const rawRecords = await resolveTxt(mcpDomain);
+        if (rawRecords.length === 0) {
+            return { records: [], ...(warning && { homograph_warning: warning }) };
         }
-        return { record: parseMcpTxtRecord(records), ...(warning && { homograph_warning: warning }) };
+        const parsed = rawRecords.map((chunks) => parseSingleTxtRecord(chunks));
+        return { records: parsed, ...(warning && { homograph_warning: warning }) };
     }
     catch (err) {
         if (err.code === "ENODATA" || err.code === "ENOTFOUND") {
-            return { record: null, ...(warning && { homograph_warning: warning }) };
+            return { records: [], ...(warning && { homograph_warning: warning }) };
         }
         throw err;
     }
 }
-// --- MCP Server Inspection ---
+// --- MCP Server Inspection (initialize + list tools/resources/prompts) ---
 async function inspectMcpServer(url) {
-    // Initialize handshake
     const initResponse = await fetch(url, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
+        signal: AbortSignal.timeout(15000),
         body: JSON.stringify({
             jsonrpc: "2.0",
             id: 1,
@@ -122,7 +117,7 @@ async function inspectMcpServer(url) {
             params: {
                 protocolVersion: "2024-11-05",
                 capabilities: {},
-                clientInfo: { name: "mcp-www", version: "0.1.0" },
+                clientInfo: { name: "mcp-www", version: "0.2.0" },
             },
         }),
     });
@@ -154,24 +149,69 @@ async function inspectMcpServer(url) {
         prompts: promptsResult?.prompts || [],
     };
 }
-// --- Combined Discovery + Inspection ---
-async function discoverMcpDomain(domain) {
-    const { record, homograph_warning } = await lookupMcpDomain(domain);
-    const base = { domain, ...(homograph_warning && { homograph_warning }) };
-    if (record === null) {
-        return { ...base, found: false, message: `No _mcp.${domain} TXT record found` };
+// --- Server Card (.well-known/mcp.json) ---
+async function fetchServerCard(domain) {
+    try {
+        const response = await fetch(`https://${domain}/.well-known/mcp.json`, {
+            signal: AbortSignal.timeout(10000),
+            headers: { "Accept": "application/json" },
+        });
+        if (!response.ok)
+            return null;
+        return await response.json();
     }
-    const serverUrl = record.src || record.endpoint;
-    if (!serverUrl) {
-        return { ...base, found: true, record, server: null, message: "No server URL (src/endpoint) in TXT record" };
+    catch {
+        return null;
     }
-    try {
-        const serverInfo = await inspectMcpServer(serverUrl);
-        return { ...base, found: true, record, server: { url: serverUrl, ...serverInfo } };
+}
+// --- Browse: server card first, MCP init as fallback ---
+async function browseDomain(domain) {
+    const normalized = domain.normalize("NFC");
+    const warning = detectHomograph(normalized);
+    const { records } = await lookupMcpDomain(normalized);
+    const serverUrls = records
+        .map((r) => r.src || r.endpoint)
+        .filter(Boolean);
+    // Try server card first (cheap HTTP GET)
+    const serverCard = await fetchServerCard(normalized);
+    if (serverCard) {
+        return {
+            domain: normalized,
+            ...(warning && { homograph_warning: warning }),
+            dns_records: records,
+            server_card: serverCard,
+            server_urls: serverUrls,
+        };
     }
-    catch (err) {
-        return { ...base, found: true, record, server: { url: serverUrl, error: err.message } };
+    // Fallback: MCP initialize handshake on DNS-advertised servers
+    const serverResults = await Promise.all(serverUrls.map(async (url) => {
+        try {
+            const info = await inspectMcpServer(url);
+            return { url, ...info };
+        }
+        catch (err) {
+            return { url, error: err.message };
+        }
+    }));
+    return {
+        domain: normalized,
+        ...(warning && { homograph_warning: warning }),
+        dns_records: records,
+        server_card: null,
+        servers: serverResults,
+    };
+}
+// --- Browse by URL: server card from hostname, init as fallback ---
+async function browseUrl(url) {
+    // Try to derive domain for server card
+    const hostname = new URL(url).hostname;
+    const serverCard = await fetchServerCard(hostname);
+    if (serverCard) {
+        return { url, server_card: serverCard };
     }
+    // Fallback: MCP init
+    const info = await inspectMcpServer(url);
+    return { url, ...info };
 }
 // --- Remote Server Helpers ---
 async function initRemoteServer(url) {
@@ -185,7 +225,7 @@ async function initRemoteServer(url) {
             params: {
                 protocolVersion: "2024-11-05",
                 capabilities: {},
-                clientInfo: { name: "mcp-www", version: "0.1.0" },
+                clientInfo: { name: "mcp-www", version: "0.2.0" },
             },
         }),
     });
@@ -213,117 +253,169 @@ async function jsonRpcCall(url, id, method, params, sessionId) {
     }
     return result.result;
 }
-// --- Remote Tool Calling ---
 async function callRemoteTool(url, toolName, toolArgs = {}) {
     const sessionId = await initRemoteServer(url);
     return jsonRpcCall(url, 2, "tools/call", { name: toolName, arguments: toolArgs }, sessionId);
 }
-// --- Remote Resource Reading ---
 async function readRemoteResource(url, uri) {
     const sessionId = await initRemoteServer(url);
     return jsonRpcCall(url, 2, "resources/read", { uri }, sessionId);
 }
-// --- Remote Prompt Getting ---
 async function getRemotePrompt(url, promptName, promptArgs = {}) {
     const sessionId = await initRemoteServer(url);
     return jsonRpcCall(url, 2, "prompts/get", { name: promptName, arguments: promptArgs }, sessionId);
 }
-// --- Response Formatting ---
-function formatServerResult(serverData, url) {
-    const content = [];
-    // Surface instructions as natural language guidance the model will follow
-    if (serverData.instructions) {
-        content.push({
-            type: "text",
-            text: `[Server Instructions from ${serverData.serverInfo?.name || url}]\n` +
-                `${serverData.instructions}\n` +
-                `Use call_remote_tool with url "${url}" to execute any of the tools listed below.`,
-        });
+// --- Discover + Browse (lightweight: DNS + server card, init as fallback) ---
+async function discoverBrowse(domain) {
+    const normalized = domain.normalize("NFC");
+    const warning = detectHomograph(normalized);
+    const { records } = await lookupMcpDomain(normalized);
+    const base = {
+        domain: normalized,
+        ...(warning && { homograph_warning: warning }),
+        dns_records: records,
+    };
+    if (records.length === 0) {
+        return { ...base, found: false, message: `No _mcp.${normalized} TXT record found` };
+    }
+    // Take the first server URL
+    const serverUrl = records.map((r) => r.src || r.endpoint).find(Boolean);
+    if (!serverUrl) {
+        return { ...base, found: true, server: null, message: "No server URL (src/endpoint) in TXT records" };
+    }
+    // Try server card first (cheap HTTP GET)
+    const serverCard = await fetchServerCard(normalized);
+    if (serverCard) {
+        return { ...base, found: true, server_url: serverUrl, server_card: serverCard };
+    }
+    // Fallback: MCP initialize handshake
+    try {
+        const serverInfo = await inspectMcpServer(serverUrl);
+        return { ...base, found: true, server_url: serverUrl, server: serverInfo };
+    }
+    catch (err) {
+        return { ...base, found: true, server_url: serverUrl, server: { error: err.message } };
     }
-    // Add the structured data
-    content.push({
-        type: "text",
-        text: JSON.stringify({ url, ...serverData }, null, 2),
-    });
-    return content;
+}
+// --- Server Registration ---
+function generateRegistrationConfig(url, serverName) {
+    const platform = process.platform;
+    const homeDir = process.env.HOME || process.env.USERPROFILE || "~";
+    const appData = process.env.APPDATA || "";
+    const configs = {
+        claude_desktop: {
+            config_path: platform === "win32"
+                ? `${appData}\\Claude\\claude_desktop_config.json`
+                : platform === "darwin"
+                    ? `${homeDir}/Library/Application Support/Claude/claude_desktop_config.json`
+                    : `${homeDir}/.config/Claude/claude_desktop_config.json`,
+            entry: { [serverName]: { url } },
+            merge_at: "mcpServers",
+        },
+        vscode: {
+            config_path: ".vscode/mcp.json",
+            entry: { [serverName]: { url } },
+            merge_at: "servers",
+        },
+        cursor: {
+            config_path: `${homeDir}/.cursor/mcp.json`,
+            entry: { [serverName]: { url } },
+            merge_at: "mcpServers",
+        },
+        windsurf: {
+            config_path: `${homeDir}/.windsurf/mcp.json`,
+            entry: { [serverName]: { url } },
+            merge_at: "mcpServers",
+        },
+    };
+    return {
+        server_name: serverName,
+        server_url: url,
+        platform,
+        configs,
+        instructions: "To register this server: read the config file for the target client, " +
+            "parse as JSON, add the entry object under the merge_at key, and write it back. " +
+            "If the file doesn't exist, create it with { [merge_at]: entry }. " +
+            "Do not overwrite existing server entries unless the user confirms.",
+    };
+}
+function deriveServerName(domain) {
+    return domain
+        .replace(/^mcp\./, "")
+        .replace(/\./g, "-")
+        .replace(/[^a-z0-9-]/gi, "")
+        .toLowerCase();
 }
 // --- Server Setup ---
 const server = new index_js_1.Server({
     name: "mcp-www",
-    version: "0.1.0",
+    version: "0.2.0",
 }, {
     capabilities: {
         tools: {},
     },
-    instructions: "When a user mentions a domain name, company, or website — or when you need to find tools and services related to a domain — use mcp-www first. " +
-        "Start with browse_discover to look up the domain and inspect what MCP services it offers in a single step. " +
-        "If you already have a server URL, use browse_server to see its tools, resources, and prompts. " +
-        "Then use call_remote_tool to execute tools on discovered servers.",
+    instructions: "When a user mentions a domain name, company, or website — or when you need to find tools and services related to a domain — use mcp-www. " +
+        "Start with discover_browse for a quick one-step DNS + server card lookup. " +
+        "Use browse for full MCP handshake and complete server manifest. " +
+        "Use call_remote_tool to execute tools on discovered servers. " +
+        "Use install to permanently add a discovered server to the user's MCP client.",
 });
 // --- Tool Definitions ---
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
     return {
         tools: [
             {
-                name: "browse_domain",
-                description: "Lookup _mcp.{domain} DNS TXT records and return parsed MCP server metadata. Uses standard UDP DNS queries.",
+                name: "discover",
+                description: "DNS-only lookup. Returns all _mcp.{domain} TXT records — there can be multiple, each advertising a different MCP server. Fast, cheap, no HTTP calls. Supports single domain or batch lookup across multiple domains.",
                 inputSchema: {
                     type: "object",
                     properties: {
                         domain: {
                             type: "string",
-                            description: "The domain to look up (e.g., 'example.com')",
+                            description: "A single domain to look up (e.g., 'example.com')",
                         },
-                    },
-                    required: ["domain"],
-                },
-            },
-            {
-                name: "browse_server",
-                description: "Connect to a discovered MCP server URL and retrieve its full manifest: tools, resources, and prompts. Lets you inspect what a server offers before deciding to use it.",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        url: {
-                            type: "string",
-                            description: "The MCP server URL (e.g., 'https://mcp.example.com')",
+                        domains: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Multiple domains to look up in parallel",
                         },
                     },
-                    required: ["url"],
                 },
             },
             {
-                name: "browse_multi",
-                description: "Batch lookup across multiple domains in a single call. Returns MCP server metadata for each domain that has _mcp TXT records.",
+                name: "discover_browse",
+                description: "DNS lookup + server card in one call. Looks up all _mcp.{domain} TXT records, then fetches .well-known/mcp.json for server metadata. Only falls back to MCP initialize if no server card is found. Lighter than browse — no MCP session unless needed.",
                 inputSchema: {
                     type: "object",
                     properties: {
-                        domains: {
-                            type: "array",
-                            items: { type: "string" },
-                            description: "Array of domains to look up",
+                        domain: {
+                            type: "string",
+                            description: "The domain to discover and browse (e.g., 'example.com')",
                         },
                     },
-                    required: ["domains"],
+                    required: ["domain"],
                 },
             },
             {
-                name: "browse_discover",
-                description: "Start here when a user mentions any domain name or website. Looks up _mcp.{domain} DNS TXT records, then connects to the advertised server URL to retrieve its full manifest (tools, resources, and prompts) — all in one step.",
+                name: "browse",
+                description: "Inspect a domain or server URL. Tries .well-known/mcp.json (server card) first, only falls back to MCP initialize handshake if no server card is found. For domains: also performs DNS lookup for _mcp TXT records.",
                 inputSchema: {
                     type: "object",
                     properties: {
                         domain: {
                             type: "string",
-                            description: "The domain to discover (e.g., 'example.com')",
+                            description: "Domain to browse (e.g., 'example.com') — runs parallel server card + MCP handshake",
+                        },
+                        url: {
+                            type: "string",
+                            description: "Direct MCP server URL to inspect (e.g., 'https://mcp.example.com')",
                         },
                     },
-                    required: ["domain"],
                 },
             },
             {
                 name: "call_remote_tool",
-                description: "Call a tool on a remote MCP server. Use browse_server first to discover available tools, then use this to execute them.",
+                description: "Call a tool on a remote MCP server. Use browse first to discover available tools, then use this to execute them.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -346,7 +438,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
             },
             {
                 name: "read_remote_resource",
-                description: "Read a resource from a remote MCP server. Use browse_server or browse_discover first to see available resources, then use this to read one by its URI.",
+                description: "Read a resource from a remote MCP server. Use browse first to see available resources, then use this to read one by its URI.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -364,7 +456,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
             },
             {
                 name: "get_remote_prompt",
-                description: "Get a prompt from a remote MCP server. Use browse_server or browse_discover first to see available prompts, then use this to retrieve one with optional arguments.",
+                description: "Get a prompt from a remote MCP server. Use browse first to see available prompts, then use this to retrieve one with optional arguments.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -385,6 +477,27 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
                     required: ["url", "prompt"],
                 },
             },
+            {
+                name: "install",
+                description: "Generate client configuration to permanently register a discovered MCP server. Returns config file paths and JSON entries for Claude Desktop, VS Code, Cursor, and Windsurf. The agent should then read the target config file, merge the entry, and write it back. Accepts a server URL directly or a domain (runs discovery first).",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        url: {
+                            type: "string",
+                            description: "The MCP server URL to register (e.g., 'https://mcp.example.com')",
+                        },
+                        domain: {
+                            type: "string",
+                            description: "Domain to discover first, then register the found server URL",
+                        },
+                        name: {
+                            type: "string",
+                            description: "Friendly name for the server entry (auto-derived from domain/URL if omitted)",
+                        },
+                    },
+                },
+            },
         ],
     };
 });
@@ -392,124 +505,121 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
 server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     switch (name) {
-        case "browse_domain": {
-            const domain = args.domain;
-            try {
-                const { record, homograph_warning } = await lookupMcpDomain(domain);
-                const warningBlock = homograph_warning ? [formatHomographWarning(homograph_warning)] : [];
-                if (record === null) {
-                    return {
-                        content: [
-                            ...warningBlock,
-                            {
-                                type: "text",
-                                text: JSON.stringify({ domain, found: false, message: `No _mcp.${domain} TXT record found` }, null, 2),
-                            },
-                        ],
-                    };
-                }
-                return {
-                    content: [
-                        ...warningBlock,
-                        {
-                            type: "text",
-                            text: JSON.stringify({ domain, found: true, record }, null, 2),
-                        },
-                    ],
-                };
-            }
-            catch (err) {
+        case "discover": {
+            const { domain, domains } = args;
+            const domainList = domains || (domain ? [domain] : []);
+            if (domainList.length === 0) {
                 return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({ domain, error: err.message }, null, 2),
-                        },
-                    ],
+                    content: [{ type: "text", text: "Provide either 'domain' (string) or 'domains' (array)." }],
                     isError: true,
                 };
             }
-        }
-        case "browse_server": {
-            const url = args.url;
-            try {
-                const result = await inspectMcpServer(url);
-                return { content: formatServerResult(result, url) };
-            }
-            catch (err) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({ url, error: err.message }, null, 2),
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-        }
-        case "browse_multi": {
-            const domains = args.domains;
             const results = {};
             const warnings = [];
-            await Promise.all(domains.map(async (domain) => {
+            await Promise.all(domainList.map(async (d) => {
                 try {
-                    const { record, homograph_warning } = await lookupMcpDomain(domain);
-                    results[domain] = record !== null
-                        ? { found: true, record }
-                        : { found: false };
+                    const { records, homograph_warning } = await lookupMcpDomain(d);
+                    results[d] = records.length > 0
+                        ? { found: true, records }
+                        : { found: false, message: `No _mcp.${d} TXT record found` };
                     if (homograph_warning)
-                        warnings.push({ domain, warning: homograph_warning });
+                        warnings.push(formatHomographWarning(`[${d}] ${homograph_warning}`));
                 }
                 catch (err) {
-                    results[domain] = { error: err.message };
+                    results[d] = { error: err.message };
                 }
             }));
-            const warningBlocks = warnings.map((w) => formatHomographWarning(`[${w.domain}] ${w.warning}`));
-            return {
-                content: [
-                    ...warningBlocks,
-                    {
-                        type: "text",
-                        text: JSON.stringify(results, null, 2),
-                    },
-                ],
-            };
+            const content = [
+                ...warnings,
+                { type: "text", text: JSON.stringify(domainList.length === 1 ? results[domainList[0]] : results, null, 2) },
+            ];
+            // Suggest browse for domains that have records
+            const domainsWithRecords = domainList.filter((d) => results[d]?.found);
+            if (domainsWithRecords.length > 0) {
+                content.push({
+                    type: "text",
+                    text: `Use browse to connect and inspect ${domainsWithRecords.length === 1 ? `${domainsWithRecords[0]}` : "these domains"}.`,
+                });
+            }
+            return { content };
         }
-        case "browse_discover": {
+        case "discover_browse": {
             const domain = args.domain;
             try {
-                const result = await discoverMcpDomain(domain);
-                const warningBlock = result.homograph_warning ? [formatHomographWarning(result.homograph_warning)] : [];
-                // If we got server data with instructions, surface them prominently
-                if (result.server && !result.server.error && result.server.instructions) {
-                    const content = formatServerResult(result.server, result.server.url);
-                    // Prepend warning + discovery context
-                    content.unshift({
+                const result = await discoverBrowse(domain);
+                const content = [];
+                if (result.homograph_warning) {
+                    content.push(formatHomographWarning(result.homograph_warning));
+                }
+                content.push({
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                });
+                if (result.server_url) {
+                    content.push({
                         type: "text",
-                        text: `Discovered MCP server for ${domain} via DNS lookup of _mcp.${domain}`,
+                        text: `Use browse to get the full server manifest, or install to add this server to your MCP client.`,
                     });
-                    content.unshift(...warningBlock);
-                    return { content };
                 }
+                return { content };
+            }
+            catch (err) {
                 return {
-                    content: [
-                        ...warningBlock,
-                        {
-                            type: "text",
-                            text: JSON.stringify(result, null, 2),
-                        },
-                    ],
+                    content: [{ type: "text", text: JSON.stringify({ domain, error: err.message }, null, 2) }],
+                    isError: true,
                 };
             }
-            catch (err) {
+        }
+        case "browse": {
+            const { domain, url } = args;
+            if (!domain && !url) {
                 return {
-                    content: [
-                        {
+                    content: [{ type: "text", text: "Provide either 'domain' or 'url'." }],
+                    isError: true,
+                };
+            }
+            try {
+                let result;
+                if (url) {
+                    result = await browseUrl(url);
+                }
+                else {
+                    result = await browseDomain(domain);
+                }
+                const content = [];
+                const warningText = result.homograph_warning;
+                if (warningText) {
+                    content.push(formatHomographWarning(warningText));
+                }
+                // Surface instructions from any successfully connected server
+                const servers = result.servers || (result.url ? [result] : []);
+                for (const srv of servers) {
+                    if (srv.instructions) {
+                        content.push({
                             type: "text",
-                            text: JSON.stringify({ domain, error: err.message }, null, 2),
-                        },
-                    ],
+                            text: `[Server Instructions from ${srv.serverInfo?.name || srv.url}]\n` +
+                                `${srv.instructions}\n` +
+                                `Use call_remote_tool with url "${srv.url}" to execute any of the tools listed below.`,
+                        });
+                    }
+                }
+                content.push({
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                });
+                // Suggest register for servers that connected successfully
+                const connectedUrls = servers.filter((s) => !s.error && s.serverInfo).map((s) => s.url);
+                if (connectedUrls.length > 0) {
+                    content.push({
+                        type: "text",
+                        text: `To permanently add ${connectedUrls.length === 1 ? "this server" : "these servers"} to the user's MCP client, use install.`,
+                    });
+                }
+                return { content };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ domain, url, error: err.message }, null, 2) }],
                     isError: true,
                 };
             }
@@ -526,12 +636,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             }
             catch (err) {
                 return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({ url, tool, error: err.message }, null, 2),
-                        },
-                    ],
+                    content: [{ type: "text", text: JSON.stringify({ url, tool, error: err.message }, null, 2) }],
                     isError: true,
                 };
             }
@@ -551,12 +656,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             }
             catch (err) {
                 return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({ url, uri, error: err.message }, null, 2),
-                        },
-                    ],
+                    content: [{ type: "text", text: JSON.stringify({ url, uri, error: err.message }, null, 2) }],
                     isError: true,
                 };
             }
@@ -566,22 +666,68 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             try {
                 const result = await getRemotePrompt(url, prompt, promptArgs || {});
                 return {
-                    content: [
-                        { type: "text", text: JSON.stringify(result, null, 2) },
-                    ],
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
                 };
             }
             catch (err) {
                 return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({ url, prompt, error: err.message }, null, 2),
-                        },
-                    ],
+                    content: [{ type: "text", text: JSON.stringify({ url, prompt, error: err.message }, null, 2) }],
+                    isError: true,
+                };
+            }
+        }
+        case "install": {
+            const { url, domain, name: serverName } = args;
+            if (!url && !domain) {
+                return {
+                    content: [{ type: "text", text: "Provide either 'url' (server URL) or 'domain' (to discover first)." }],
                     isError: true,
                 };
             }
+            let serverUrl = url;
+            let discoveredDomain = domain;
+            // If domain provided, discover the server URL first
+            if (!serverUrl && domain) {
+                try {
+                    const { records } = await lookupMcpDomain(domain);
+                    const firstUrl = records.map((r) => r.src || r.endpoint).find(Boolean);
+                    if (firstUrl) {
+                        serverUrl = firstUrl;
+                    }
+                }
+                catch (err) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({ domain, error: `Discovery failed: ${err.message}` }, null, 2) }],
+                        isError: true,
+                    };
+                }
+                if (!serverUrl) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({ domain, error: "No MCP server URL found for this domain. Cannot register." }, null, 2) }],
+                        isError: true,
+                    };
+                }
+            }
+            const derivedName = serverName || deriveServerName(discoveredDomain || new URL(serverUrl).hostname);
+            const config = generateRegistrationConfig(serverUrl, derivedName);
+            const content = [];
+            if (discoveredDomain) {
+                content.push({
+                    type: "text",
+                    text: `Discovered server at ${serverUrl} via DNS lookup of _mcp.${discoveredDomain}`,
+                });
+            }
+            content.push({
+                type: "text",
+                text: JSON.stringify(config, null, 2),
+            });
+            content.push({
+                type: "text",
+                text: `To complete registration, read the config file for the target client, ` +
+                    `merge the entry under the "${config.configs.claude_desktop.merge_at}" key, and write it back. ` +
+                    `If the file doesn't exist, create it.`,
+            });
+            return { content };
         }
         default:
             throw new Error(`Unknown tool: ${name}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-www",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Lightweight MCP server for DNS-based agent service discovery over UDP. No registry needed.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",