mcp-www 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# mcp-browse
+
+**DNS-based MCP service discovery over UDP.**
+
+## Problem
+
+Agents need to discover MCP servers, but current approaches lean on centralized registries or hardcoded configurations. This creates single points of failure, adds deployment overhead, and forces agents into walled gardens. There should be a way to discover MCP services using infrastructure that already exists everywhere: DNS.
+
+## How It Works
+
+**mcp-browse** 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-browse 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.
+
+```
+Agent  →  mcp-browse (MCP server)  →  UDP DNS query for _mcp.example.com TXT
+                                    ←  "v=mcp1; src=https://mcp.example.com; ..."
+       ←  Structured JSON response
+```
+
+No HTTP registry in the loop. The DNS infrastructure **is** the registry.
+
+## 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.
+- **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-browse 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:
+  ```
+  v=mcp1; src=https://mcp.example.com; public=true; auth=oauth2; version=2024.1
+  ```
+- **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.
+
+## Tools Exposed
+
+### `browse_domain`
+
+Lookup `_mcp.{domain}` TXT records and return a parsed list of discovered MCP servers.
+
+```json
+{
+  "tool": "browse_domain",
+  "arguments": {
+    "domain": "example.com"
+  }
+}
+```
+
+Returns structured server metadata: server URL, protocol version, auth requirements, and any additional fields published in the TXT record.
+
+### `browse_discover`
+
+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.
+
+```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"
+  }
+}
+```
+
+### `browse_multi`
+
+Batch lookup across multiple domains in a single call. Useful for scanning a list of known domains or performing broad discovery.
+
+```json
+{
+  "tool": "browse_multi",
+  "arguments": {
+    "domains": ["example.com", "acme.org", "internal.corp"]
+  }
+}
+```
+
+### `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.
+
+```json
+{
+  "tool": "call_remote_tool",
+  "arguments": {
+    "url": "https://mcp.example.com",
+    "tool": "list_articles",
+    "arguments": { "limit": 5 }
+  }
+}
+```
+
+### `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.
+
+```json
+{
+  "tool": "read_remote_resource",
+  "arguments": {
+    "url": "https://mcp.example.com",
+    "uri": "korm://bio"
+  }
+}
+```
+
+### `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.
+
+```json
+{
+  "tool": "get_remote_prompt",
+  "arguments": {
+    "url": "https://mcp.example.com",
+    "prompt": "recommend-post",
+    "arguments": { "topic": "AI vision" }
+  }
+}
+```
+
+## Try It
+
+**[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
+```
+
+## Status
+
+**Working.** The server implements DNS-based discovery, server inspection, remote tool calling, resource reading, and prompt retrieval over the Streamable HTTP transport.
+
+Feedback, criticism, and alternative approaches are welcome — open an issue or start a discussion.
+
+## Related
+
+- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io)
+- [MCP Discussion #2334](https://github.com/modelcontextprotocol/specification/discussions/2334)
+- [MCP PR #2127](https://github.com/modelcontextprotocol/specification/pull/2127)
+- [MCP SEP #1959](https://github.com/nicobailon/mcp-seps/blob/main/SEP/1959/README.md)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * mcp-browse
+ *
+ * A lightweight MCP server that performs DNS-based discovery of MCP services
+ * using UDP lookups. No registry server needed.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,517 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * mcp-browse
+ *
+ * A lightweight MCP server that performs DNS-based discovery of MCP services
+ * using UDP lookups. No registry server needed.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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 node_dns_1 = __importDefault(require("node:dns"));
+const node_util_1 = require("node:util");
+const resolveTxt = (0, node_util_1.promisify)(node_dns_1.default.resolveTxt);
+// --- TXT Record Parser ---
+function parseMcpTxtRecord(txtRecords) {
+    // TXT records come as arrays of strings (chunked), join them
+    const fullRecord = txtRecords.map((chunks) => chunks.join("")).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;
+        }
+    }
+    return result;
+}
+// --- DNS Lookup ---
+async function lookupMcpDomain(domain) {
+    const mcpDomain = `_mcp.${domain}`;
+    try {
+        const records = await resolveTxt(mcpDomain);
+        if (records.length === 0) {
+            return null;
+        }
+        return parseMcpTxtRecord(records);
+    }
+    catch (err) {
+        if (err.code === "ENODATA" || err.code === "ENOTFOUND") {
+            return null; // No TXT record found
+        }
+        throw err;
+    }
+}
+// --- MCP Server Inspection ---
+async function inspectMcpServer(url) {
+    // Initialize handshake
+    const initResponse = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2024-11-05",
+                capabilities: {},
+                clientInfo: { name: "mcp-browse", version: "0.1.0" },
+            },
+        }),
+    });
+    if (!initResponse.ok) {
+        throw new Error(`Server returned ${initResponse.status}`);
+    }
+    const initResult = await initResponse.json();
+    const jsonRpcPost = (id, method) => fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id, method, params: {} }),
+    }).then(async (r) => (r.ok ? (await r.json()).result : null));
+    const [toolsResult, resourcesResult, promptsResult] = await Promise.all([
+        jsonRpcPost(2, "tools/list"),
+        jsonRpcPost(3, "resources/list").catch(() => null),
+        jsonRpcPost(4, "prompts/list").catch(() => null),
+    ]);
+    return {
+        serverInfo: initResult.result?.serverInfo || null,
+        protocolVersion: initResult.result?.protocolVersion || null,
+        instructions: initResult.result?.instructions || null,
+        tools: toolsResult?.tools || [],
+        resources: resourcesResult?.resources || [],
+        prompts: promptsResult?.prompts || [],
+    };
+}
+// --- Combined Discovery + Inspection ---
+async function discoverMcpDomain(domain) {
+    const record = await lookupMcpDomain(domain);
+    if (record === null) {
+        return { domain, found: false, message: `No _mcp.${domain} TXT record found` };
+    }
+    const serverUrl = record.src || record.endpoint;
+    if (!serverUrl) {
+        return { domain, found: true, record, server: null, message: "No server URL (src/endpoint) in TXT record" };
+    }
+    try {
+        const serverInfo = await inspectMcpServer(serverUrl);
+        return { domain, found: true, record, server: { url: serverUrl, ...serverInfo } };
+    }
+    catch (err) {
+        return { domain, found: true, record, server: { url: serverUrl, error: err.message } };
+    }
+}
+// --- Remote Server Helpers ---
+async function initRemoteServer(url) {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2024-11-05",
+                capabilities: {},
+                clientInfo: { name: "mcp-browse", version: "0.1.0" },
+            },
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Server returned ${response.status} during initialization`);
+    }
+}
+async function jsonRpcCall(url, id, method, params) {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id, method, params }),
+    });
+    if (!response.ok) {
+        throw new Error(`Server returned ${response.status} during ${method}`);
+    }
+    const result = await response.json();
+    if (result.error) {
+        throw new Error(result.error.message || JSON.stringify(result.error));
+    }
+    return result.result;
+}
+// --- Remote Tool Calling ---
+async function callRemoteTool(url, toolName, toolArgs = {}) {
+    await initRemoteServer(url);
+    return jsonRpcCall(url, 2, "tools/call", { name: toolName, arguments: toolArgs });
+}
+// --- Remote Resource Reading ---
+async function readRemoteResource(url, uri) {
+    await initRemoteServer(url);
+    return jsonRpcCall(url, 2, "resources/read", { uri });
+}
+// --- Remote Prompt Getting ---
+async function getRemotePrompt(url, promptName, promptArgs = {}) {
+    await initRemoteServer(url);
+    return jsonRpcCall(url, 2, "prompts/get", { name: promptName, arguments: promptArgs });
+}
+// --- 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.`,
+        });
+    }
+    // Add the structured data
+    content.push({
+        type: "text",
+        text: JSON.stringify({ url, ...serverData }, null, 2),
+    });
+    return content;
+}
+// --- Server Setup ---
+const server = new index_js_1.Server({
+    name: "mcp-browse",
+    version: "0.1.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-browse 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.",
+});
+// --- 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.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        domain: {
+                            type: "string",
+                            description: "The 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')",
+                        },
+                    },
+                    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.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        domains: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Array of domains to look up",
+                        },
+                    },
+                    required: ["domains"],
+                },
+            },
+            {
+                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.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        domain: {
+                            type: "string",
+                            description: "The domain to discover (e.g., '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.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        url: {
+                            type: "string",
+                            description: "The MCP server URL (e.g., 'https://mcp.example.com')",
+                        },
+                        tool: {
+                            type: "string",
+                            description: "The name of the tool to call on the remote server",
+                        },
+                        arguments: {
+                            type: "object",
+                            description: "Arguments to pass to the remote tool",
+                            additionalProperties: true,
+                        },
+                    },
+                    required: ["url", "tool"],
+                },
+            },
+            {
+                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.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        url: {
+                            type: "string",
+                            description: "The MCP server URL (e.g., 'https://mcp.example.com')",
+                        },
+                        uri: {
+                            type: "string",
+                            description: "The resource URI to read (e.g., 'file:///path/to/file')",
+                        },
+                    },
+                    required: ["url", "uri"],
+                },
+            },
+            {
+                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.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        url: {
+                            type: "string",
+                            description: "The MCP server URL (e.g., 'https://mcp.example.com')",
+                        },
+                        prompt: {
+                            type: "string",
+                            description: "The name of the prompt to get",
+                        },
+                        arguments: {
+                            type: "object",
+                            description: "Arguments to pass to the prompt",
+                            additionalProperties: { type: "string" },
+                        },
+                    },
+                    required: ["url", "prompt"],
+                },
+            },
+        ],
+    };
+});
+// --- Tool Handlers ---
+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 result = await lookupMcpDomain(domain);
+                if (result === null) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ domain, found: false, message: `No _mcp.${domain} TXT record found` }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ domain, found: true, record: result }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ domain, error: err.message }, null, 2),
+                        },
+                    ],
+                    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 = {};
+            await Promise.all(domains.map(async (domain) => {
+                try {
+                    const record = await lookupMcpDomain(domain);
+                    results[domain] = record !== null ? { found: true, record } : { found: false };
+                }
+                catch (err) {
+                    results[domain] = { error: err.message };
+                }
+            }));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(results, null, 2),
+                    },
+                ],
+            };
+        }
+        case "browse_discover": {
+            const domain = args.domain;
+            try {
+                const result = await discoverMcpDomain(domain);
+                // 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 the discovery context
+                    content.unshift({
+                        type: "text",
+                        text: `Discovered MCP server for ${domain} via DNS lookup of _mcp.${domain}`,
+                    });
+                    return { content };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ domain, error: err.message }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        case "call_remote_tool": {
+            const { url, tool, arguments: remoteArgs } = args;
+            try {
+                const result = await callRemoteTool(url, tool, remoteArgs || {});
+                return {
+                    content: result?.content || [
+                        { type: "text", text: JSON.stringify(result, null, 2) },
+                    ],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ url, tool, error: err.message }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        case "read_remote_resource": {
+            const { url, uri } = args;
+            try {
+                const result = await readRemoteResource(url, uri);
+                return {
+                    content: result?.contents?.map((c) => ({
+                        type: "text",
+                        text: typeof c.text === "string" ? c.text : JSON.stringify(c, null, 2),
+                    })) || [
+                        { type: "text", text: JSON.stringify(result, null, 2) },
+                    ],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ url, uri, error: err.message }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        case "get_remote_prompt": {
+            const { url, prompt, arguments: promptArgs } = args;
+            try {
+                const result = await getRemotePrompt(url, prompt, promptArgs || {});
+                return {
+                    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),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+});
+// --- Start Server ---
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("mcp-browse server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "mcp-www",
+  "version": "0.1.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",
+  "bin": {
+    "mcp-browse": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "dns",
+    "service-discovery",
+    "udp",
+    "model-context-protocol",
+    "agent"
+  ],
+  "author": "kormco",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "ts-node": "^10.9.0",
+    "@types/node": "^20.0.0"
+  }
+}