mcpboot 0.1.0

package/README.md

@@ -0,0 +1,221 @@
+# mcpboot
+
+Generate and serve an MCP server from a natural language prompt.
+
+Point mcpboot at API documentation (or just describe what you want), and it generates a working [MCP](https://modelcontextprotocol.io/) server. No SDK knowledge required. No boilerplate. No code to maintain.
+
+The LLM is used **only at startup** for code generation. At runtime, tool calls execute cached JavaScript with no LLM involvement and no per-call API costs.
+
+## Installation
+
+```bash
+npm install -g mcpboot
+```
+
+Requires Node.js 18+.
+
+## Quick Start
+
+```bash
+# Set your LLM API key
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Generate an MCP server for the Hacker News API
+mcpboot --prompt "Create MCP tools for the Hacker News API: https://github.com/HackerNews/API"
+```
+
+mcpboot fetches the API docs, generates tool handlers, and starts serving on `http://localhost:8000/mcp`.
+
+## Usage
+
+```
+mcpboot [options]
+
+Options:
+  --prompt <text>              Generation prompt (inline)
+  --prompt-file <path>         Generation prompt from file
+
+  --provider <name>            LLM provider: anthropic | openai (default: anthropic)
+  --model <id>                 LLM model ID (default: provider-specific)
+  --api-key <key>              LLM API key (env: ANTHROPIC_API_KEY | OPENAI_API_KEY)
+
+  --port <number>              HTTP server port (default: 8000)
+  --cache-dir <path>           Cache directory (default: .mcpboot-cache)
+  --no-cache                   Disable caching, regenerate on every startup
+  --verbose                    Verbose logging
+  --dry-run                    Show generation plan without starting server
+```
+
+### Examples
+
+```bash
+# Wrap the Hacker News API
+mcpboot --prompt "Create MCP tools for the Hacker News API: https://github.com/HackerNews/API"
+
+# Wrap an API from an OpenAPI spec
+mcpboot --prompt "Create MCP tools from https://petstore.swagger.io/v2/swagger.json"
+
+# Create specific tools from a known API
+mcpboot --prompt "Using the GitHub REST API (https://docs.github.com/en/rest), \
+  create tools for listing repos, creating issues, and searching code"
+
+# Create utility tools (no external API needed)
+mcpboot --prompt "Create tools for JSON manipulation: pretty-print, validate, diff, and JSONPath extraction"
+
+# Complex prompt from file
+mcpboot --prompt-file ./my-api-prompt.txt --port 9000
+
+# Preview what would be generated
+mcpboot --prompt "Create MCP tools for https://github.com/HackerNews/API" --dry-run
+```
+
+### Walkthrough: Hacker News API
+
+Here's a complete example of generating an MCP server for the [Hacker News API](https://github.com/HackerNews/API).
+
+**1. Start mcpboot:**
+
+```bash
+mcpboot --model claude-haiku-4-5 --port 8100 --verbose \
+  --prompt "Create MCP tools for the Hacker News API. The API docs are at
+    https://github.com/HackerNews/API . Figure out what tools are appropriate
+    to expose — things like getting top stories, new stories, getting an item
+    by ID, getting a user profile, etc."
+```
+
+mcpboot fetches the API docs from GitHub, uses the LLM to plan and compile 10 tools, and starts serving:
+
+```
+[mcpboot] Found 1 URL(s) in prompt
+[mcpboot] Fetching https://raw.githubusercontent.com/HackerNews/API/HEAD/README.md
+[mcpboot] Fetched 1 page(s)
+[mcpboot] Whitelist: github.com, firebase.google.com, hacker-news.firebaseio.com, ...
+[mcpboot] Cache miss — generating tools via LLM
+[mcpboot] Plan: 10 tool(s)
+[mcpboot] Compiling handler for tool: get_top_stories
+...
+[mcpboot] Compiled 10 handler(s)
+[mcpboot] Listening on http://localhost:8100/mcp
+[mcpboot] Serving 10 tool(s)
+```
+
+**2. Test with the MCP Inspector:**
+
+```bash
+npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:8100/mcp
+```
+
+Or test from the CLI with [mcporter](https://github.com/steipete/mcporter):
+
+```bash
+# List all generated tools
+npx mcporter list http://localhost:8100/mcp --schema --allow-http
+
+# Get the top 5 stories (returns story IDs)
+npx mcporter call 'http://localhost:8100/mcp.get_top_stories' limit=5 --allow-http
+
+# Fetch details for a story
+npx mcporter call 'http://localhost:8100/mcp.get_item_by_id' item_id=42345678 --allow-http
+
+# Look up a user profile
+npx mcporter call 'http://localhost:8100/mcp.get_user_profile' username=dang --allow-http
+```
+
+**Generated tools:** `get_top_stories`, `get_new_stories`, `get_best_stories`, `get_ask_stories`, `get_show_stories`, `get_job_stories`, `get_item_by_id`, `get_user_profile`, `get_max_item_id`, `get_recent_changes`
+
+Subsequent runs with the same prompt skip the LLM entirely and start instantly from cache.
+
+### Connecting from an MCP Host
+
+Once mcpboot is running, connect any MCP-compatible host to `http://localhost:8000/mcp`. For example, in Claude Desktop's config:
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+## How It Works
+
+mcpboot follows a two-phase startup, then serves tools at runtime:
+
+**Startup (LLM-assisted):**
+
+1. **Fetch** — Extract URLs from the prompt, fetch their content (API docs, READMEs, OpenAPI specs), and build a domain whitelist for runtime network access.
+2. **Plan** — Send the prompt and fetched docs to the LLM, which produces a structured generation plan: what tools to create, their schemas, which API endpoints they use.
+3. **Compile** — Send each planned tool back to the LLM, which generates a JavaScript handler function that calls the API, parses responses, and formats results.
+4. **Cache** — Store the plan and compiled handlers on disk, keyed by prompt hash + content hash. Subsequent startups with the same prompt and unchanged docs skip the LLM entirely.
+
+**Runtime (no LLM):**
+
+5. **Serve** — Expose the generated tools as an MCP server over StreamableHTTP. Tool calls execute the cached JavaScript handlers in a sandboxed `vm` with fetch access restricted to whitelisted domains.
+
+```
+Prompt + API Docs
+       │
+       ▼
+  URL Fetcher ──► Planner (LLM) ──► Compiler (LLM) ──► Cache
+                                                          │
+                                                          ▼
+  MCP Host ◄──► Exposed Server ◄──► Executor ◄──► Sandbox (vm + fetch)
+                                                          │
+                                                          ▼
+                                                    External APIs
+```
+
+### Security Model
+
+Generated handlers run in a Node.js `vm` sandbox with:
+
+- **Allowed:** Standard JS globals, `fetch` (whitelisted domains only), URL, URLSearchParams
+- **Blocked:** `require`, `import`, `process`, `fs`, `net`, `child_process`
+- **Timeout:** 30 seconds per tool call
+
+The domain whitelist is constructed automatically from URLs in the prompt and URLs discovered in the fetched documentation.
+
+## Comparison with mcpblox
+
+mcpboot and [mcpblox](https://github.com/vivekhaldar/mcpblox) are complementary:
+
+| | mcpblox | mcpboot |
+|--|---------|---------|
+| **Input** | Existing MCP server + transform prompt | Natural language prompt + optional API docs |
+| **Output** | Transformed MCP server | New MCP server from scratch |
+| **LLM generates** | Transform functions (input/output mappers) | Tool handler functions (full API integrations) |
+| **Use case** | Customize an existing server | Create a server that doesn't exist yet |
+
+They can be chained: use mcpboot to bootstrap a server, then mcpblox to transform it.
+
+```bash
+# Bootstrap an MCP server for the HN API
+mcpboot --prompt "Create MCP tools for https://github.com/HackerNews/API" --port 8001
+
+# Transform it with mcpblox to add higher-level tools
+mcpblox --upstream-url http://localhost:8001/mcp \
+  --prompt "Create a 'daily_digest' tool that gets top 10 stories with their top comments" \
+  --port 8002
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+
+# Run from source
+npx tsx src/index.ts --prompt "..."
+```
+
+## License
+
+Apache-2.0

package/dist/index.js

@@ -0,0 +1,997 @@
+#!/usr/bin/env node
+
+// src/config.ts
+import { Command } from "commander";
+import { readFileSync, existsSync } from "node:fs";
+function buildConfig(argv) {
+  const program = new Command().name("mcpboot").description(
+    "Generate and serve an MCP server from a natural language prompt"
+  ).option("--prompt <text>", "Generation prompt (inline)").option("--prompt-file <path>", "Generation prompt from file").option(
+    "--provider <name>",
+    "LLM provider: anthropic | openai",
+    "anthropic"
+  ).option("--model <id>", "LLM model ID").option("--api-key <key>", "LLM API key").option("--port <number>", "HTTP server port", "8000").option("--cache-dir <path>", "Cache directory", ".mcpboot-cache").option("--no-cache", "Disable caching").option("--verbose", "Verbose logging", false).option(
+    "--dry-run",
+    "Show generation plan without starting server",
+    false
+  ).exitOverride().configureOutput({
+    writeErr: () => {
+    },
+    writeOut: (str) => process.stdout.write(str)
+  });
+  try {
+    program.parse(argv);
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "commander.helpDisplayed") {
+      return null;
+    }
+    throw err;
+  }
+  const opts = program.opts();
+  if (opts.provider !== "anthropic" && opts.provider !== "openai") {
+    throw new Error("Error: --provider must be 'anthropic' or 'openai'");
+  }
+  let prompt;
+  if (opts.promptFile) {
+    if (opts.prompt) {
+      throw new Error(
+        "Error: Provide exactly one of --prompt or --prompt-file, not both"
+      );
+    }
+    if (!existsSync(opts.promptFile)) {
+      throw new Error(`Error: File not found: ${opts.promptFile}`);
+    }
+    prompt = readFileSync(opts.promptFile, "utf-8");
+  } else if (opts.prompt) {
+    prompt = opts.prompt;
+  } else {
+    throw new Error(
+      "Error: Provide --prompt or --prompt-file to specify the generation prompt"
+    );
+  }
+  if (!prompt.trim()) {
+    throw new Error("Error: Prompt is empty. Provide a non-empty generation prompt");
+  }
+  let apiKey = opts.apiKey;
+  if (!apiKey) {
+    if (opts.provider === "anthropic") {
+      apiKey = process.env.ANTHROPIC_API_KEY;
+    } else {
+      apiKey = process.env.OPENAI_API_KEY;
+    }
+  }
+  if (!apiKey) {
+    throw new Error(
+      "Error: No API key found. Provide --api-key or set ANTHROPIC_API_KEY / OPENAI_API_KEY"
+    );
+  }
+  const port = parseInt(opts.port, 10);
+  if (isNaN(port) || port < 0 || port > 65535) {
+    throw new Error(
+      "Error: --port must be a valid integer between 0 and 65535"
+    );
+  }
+  return {
+    prompt,
+    llm: {
+      provider: opts.provider,
+      model: opts.model,
+      apiKey
+    },
+    server: {
+      port
+    },
+    cache: {
+      enabled: opts.cache !== false,
+      dir: opts.cacheDir ?? ".mcpboot-cache"
+    },
+    dryRun: opts.dryRun ?? false,
+    verbose: opts.verbose ?? false
+  };
+}
+
+// src/log.ts
+var verboseEnabled = false;
+function setVerbose(enabled) {
+  verboseEnabled = enabled;
+}
+function log(msg) {
+  console.error(`[mcpboot] ${msg}`);
+}
+function warn(msg) {
+  console.error(`[mcpboot] WARN: ${msg}`);
+}
+function verbose(msg) {
+  if (verboseEnabled) console.error(`[mcpboot] ${msg}`);
+}
+
+// src/fetcher.ts
+var URL_REGEX = /(https?:\/\/[^\s"'<>)\]]+)/g;
+var GITHUB_REPO_REGEX = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/?$/;
+var MAX_CONTENT_LENGTH = 1e5;
+var FETCH_TIMEOUT_MS = 15e3;
+function extractUrls(prompt) {
+  const matches = prompt.match(URL_REGEX);
+  if (!matches) return [];
+  const cleaned = matches.map((url) => url.replace(/[.,;:!?)]+$/, ""));
+  return [...new Set(cleaned)];
+}
+function rewriteGitHubUrl(url) {
+  const match = url.match(GITHUB_REPO_REGEX);
+  if (!match) return null;
+  const [, owner, repo] = match;
+  return `https://raw.githubusercontent.com/${owner}/${repo}/HEAD/README.md`;
+}
+function stripHtml(html) {
+  let text = html;
+  text = text.replace(
+    /<(script|style|nav|header|footer)\b[^>]*>[\s\S]*?<\/\1>/gi,
+    ""
+  );
+  text = text.replace(/<[^>]+>/g, " ");
+  text = text.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, " ");
+  text = text.replace(/\s+/g, " ").trim();
+  return text;
+}
+function discoverUrls(content) {
+  return extractUrls(content);
+}
+function truncateContent(content, limit = MAX_CONTENT_LENGTH) {
+  if (content.length <= limit) return content;
+  return content.slice(0, limit);
+}
+async function fetchUrl(url) {
+  const fetchTarget = rewriteGitHubUrl(url) ?? url;
+  verbose(`Fetching ${fetchTarget}`);
+  const response = await fetch(fetchTarget, {
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    headers: {
+      "User-Agent": "mcpboot/1.0"
+    }
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Fetch failed for ${url}: ${response.status} ${response.statusText}`
+    );
+  }
+  const rawContentType = response.headers.get("content-type") ?? "text/plain";
+  const contentType = rawContentType.split(";")[0].trim();
+  let text = await response.text();
+  if (contentType === "text/html") {
+    text = stripHtml(text);
+  }
+  text = truncateContent(text);
+  const discovered = discoverUrls(text);
+  return {
+    url,
+    content: text,
+    contentType,
+    discoveredUrls: discovered
+  };
+}
+async function fetchUrls(urls) {
+  if (urls.length === 0) return [];
+  const results = await Promise.allSettled(urls.map((url) => fetchUrl(url)));
+  const contents = [];
+  for (const result of results) {
+    if (result.status === "fulfilled") {
+      contents.push(result.value);
+    } else {
+      warn(`Failed to fetch URL: ${result.reason}`);
+    }
+  }
+  return contents;
+}
+
+// src/whitelist.ts
+function extractDomain(url) {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return null;
+  }
+}
+function domainMatches(hostname, whitelistedDomain) {
+  if (hostname === whitelistedDomain) return true;
+  return hostname.endsWith("." + whitelistedDomain);
+}
+function buildWhitelist(promptUrls, contents) {
+  const domains = /* @__PURE__ */ new Set();
+  for (const url of promptUrls) {
+    const domain = extractDomain(url);
+    if (domain) domains.add(domain);
+  }
+  for (const content of contents) {
+    for (const url of content.discoveredUrls) {
+      const domain = extractDomain(url);
+      if (domain) domains.add(domain);
+    }
+  }
+  return {
+    domains,
+    allows(url) {
+      const hostname = extractDomain(url);
+      if (!hostname) return false;
+      for (const d of domains) {
+        if (domainMatches(hostname, d)) return true;
+      }
+      return false;
+    }
+  };
+}
+function createWhitelistedFetch(whitelist, realFetch = globalThis.fetch) {
+  return (url) => {
+    const hostname = extractDomain(url);
+    if (!hostname) {
+      return Promise.reject(
+        new Error(`Fetch blocked: invalid URL "${url}"`)
+      );
+    }
+    if (!whitelist.allows(url)) {
+      return Promise.reject(
+        new Error(
+          `Fetch blocked: domain "${hostname}" not in whitelist. Add it to your prompt to allow access.`
+        )
+      );
+    }
+    return realFetch(url);
+  };
+}
+
+// src/cache.ts
+import { createHash } from "node:crypto";
+import {
+  existsSync as existsSync2,
+  mkdirSync,
+  readFileSync as readFileSync2,
+  writeFileSync,
+  unlinkSync
+} from "node:fs";
+import { join } from "node:path";
+function hash(input) {
+  return createHash("sha256").update(input).digest("hex").slice(0, 16);
+}
+function cacheFilename(promptHash, contentHash) {
+  return `${promptHash}-${contentHash}.json`;
+}
+function serializeCompiled(compiled) {
+  const compiledTools = [];
+  for (const tool of compiled.tools.values()) {
+    compiledTools.push({
+      name: tool.name,
+      description: tool.description,
+      input_schema: tool.input_schema,
+      handler_code: tool.handler_code,
+      needs_network: tool.needs_network
+    });
+  }
+  return { compiledTools };
+}
+function deserializeCompiled(entry) {
+  const tools = /* @__PURE__ */ new Map();
+  for (const item of entry.compiledTools) {
+    tools.set(item.name, {
+      name: item.name,
+      description: item.description,
+      input_schema: item.input_schema,
+      handler_code: item.handler_code,
+      needs_network: item.needs_network
+    });
+  }
+  return {
+    tools,
+    whitelist_domains: entry.whitelist_domains
+  };
+}
+function createCache(config) {
+  return {
+    get(promptHash, contentHash) {
+      if (!config.enabled) return null;
+      const filepath = join(config.dir, cacheFilename(promptHash, contentHash));
+      if (!existsSync2(filepath)) return null;
+      verbose(`Cache lookup: ${filepath}`);
+      try {
+        const raw = readFileSync2(filepath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed.promptHash || !parsed.contentHash || !parsed.plan || !Array.isArray(parsed.compiledTools)) {
+          warn(`Corrupt cache file ${filepath}, removing`);
+          unlinkSync(filepath);
+          return null;
+        }
+        verbose(`Cache hit: ${filepath} (created ${parsed.createdAt})`);
+        return parsed;
+      } catch {
+        warn(`Failed to read cache file ${filepath}, removing`);
+        try {
+          unlinkSync(filepath);
+        } catch {
+        }
+        return null;
+      }
+    },
+    set(entry) {
+      if (!config.enabled) return;
+      mkdirSync(config.dir, { recursive: true });
+      const filepath = join(
+        config.dir,
+        cacheFilename(entry.promptHash, entry.contentHash)
+      );
+      writeFileSync(filepath, JSON.stringify(entry, null, 2));
+      verbose(`Cache written: ${filepath}`);
+    }
+  };
+}
+
+// src/llm.ts
+import { generateText } from "ai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAI } from "@ai-sdk/openai";
+var DEFAULT_MODELS = {
+  anthropic: "claude-sonnet-4-20250514",
+  openai: "gpt-4o"
+};
+function createLLMClient(config) {
+  const modelId = config.model ?? DEFAULT_MODELS[config.provider];
+  let model;
+  if (config.provider === "anthropic") {
+    const anthropic = createAnthropic({ apiKey: config.apiKey });
+    model = anthropic(modelId);
+  } else {
+    const openai = createOpenAI({ apiKey: config.apiKey });
+    model = openai(modelId);
+  }
+  return {
+    async generate(system, user) {
+      try {
+        const result = await generateText({
+          model,
+          system,
+          prompt: user,
+          maxTokens: 8192,
+          temperature: 0.2
+        });
+        return result.text;
+      } catch (error) {
+        const err = error;
+        if (err.statusCode === 404) {
+          throw new Error(
+            `Model "${modelId}" not found. Check the model ID \u2014 e.g. "claude-sonnet-4-20250514" or "claude-haiku-4-5" (note: dated variants like "claude-haiku-4-5-20241022" don't exist; use "claude-3-5-haiku-20241022" for the dated form)`
+          );
+        }
+        throw error;
+      }
+    }
+  };
+}
+
+// src/engine/planner.ts
+var TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+var SYSTEM_PROMPT = `You are an MCP tool planner. You receive a natural language description of desired tools, optionally with API documentation content, and you produce a STRUCTURED PLAN (as JSON) describing the tools to generate.
+
+OUTPUT FORMAT:
+Return ONLY valid JSON matching this exact schema (no markdown, no explanation):
+
+{
+  "tools": [
+    {
+      "name": "tool_name",
+      "description": "What the tool does",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "param_name": { "type": "string", "description": "Parameter description" }
+        },
+        "required": ["param_name"]
+      },
+      "endpoints_used": ["GET https://api.example.com/items"],
+      "implementation_notes": "Detailed description of how to implement this handler: what URL to call, how to parse the response, what to return",
+      "needs_network": true
+    }
+  ]
+}
+
+RULES:
+1. Tool names must be lowercase with underscores only (a-z, 0-9, _). Must start with a letter.
+2. Each tool must have a unique name.
+3. input_schema must be valid JSON Schema with "type": "object".
+4. endpoints_used lists the HTTP endpoints the tool will call. Use format "METHOD url".
+5. implementation_notes must be detailed enough for a code generator to write the handler.
+6. Set needs_network to true if the tool makes HTTP requests, false for pure computation.
+7. If API documentation is provided, base the tools on the actual API endpoints documented.
+8. Create focused, single-purpose tools. Prefer multiple simple tools over one complex tool.
+9. The endpoints_used URLs must use domains from the provided whitelist.
+10. For pure computation tools (no API calls), set endpoints_used to an empty array.`;
+function extractJSON(text) {
+  const fenceMatch = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+  if (fenceMatch) return fenceMatch[1].trim();
+  const jsonMatch = text.match(/\{[\s\S]*\}/);
+  if (jsonMatch) return jsonMatch[0];
+  return text.trim();
+}
+function validatePlan(plan) {
+  if (!plan.tools || !Array.isArray(plan.tools)) {
+    throw new Error("Invalid plan: missing or non-array 'tools' field");
+  }
+  if (plan.tools.length === 0) {
+    throw new Error("Invalid plan: 'tools' array is empty");
+  }
+  const names = /* @__PURE__ */ new Set();
+  for (const tool of plan.tools) {
+    if (!tool.name) {
+      throw new Error("Invalid plan: tool missing 'name'");
+    }
+    if (!TOOL_NAME_PATTERN.test(tool.name)) {
+      throw new Error(
+        `Invalid tool name "${tool.name}": must be lowercase letters, digits, and underscores, starting with a letter`
+      );
+    }
+    if (names.has(tool.name)) {
+      throw new Error(`Duplicate tool name: "${tool.name}"`);
+    }
+    names.add(tool.name);
+    if (!tool.description) {
+      throw new Error(`Tool "${tool.name}": description is required`);
+    }
+    if (!tool.input_schema || typeof tool.input_schema !== "object") {
+      throw new Error(`Tool "${tool.name}": input_schema is required`);
+    }
+    if (!tool.implementation_notes) {
+      throw new Error(`Tool "${tool.name}": implementation_notes is required`);
+    }
+    if (typeof tool.needs_network !== "boolean") {
+      throw new Error(`Tool "${tool.name}": needs_network must be a boolean`);
+    }
+    if (!Array.isArray(tool.endpoints_used)) {
+      throw new Error(`Tool "${tool.name}": endpoints_used must be an array`);
+    }
+  }
+}
+function validatePlanWhitelist(plan, whitelist) {
+  for (const tool of plan.tools) {
+    if (!tool.needs_network) continue;
+    for (const endpoint of tool.endpoints_used) {
+      const urlMatch = endpoint.match(/https?:\/\/[^\s]+/);
+      if (!urlMatch) continue;
+      if (!whitelist.allows(urlMatch[0])) {
+        throw new Error(
+          `Tool "${tool.name}" uses endpoint "${endpoint}" whose domain is not in the whitelist`
+        );
+      }
+    }
+  }
+}
+function buildUserPrompt(prompt, contents, whitelist) {
+  let userPrompt = `GENERATION PROMPT:
+${prompt}
+`;
+  if (contents.length > 0) {
+    userPrompt += "\nFETCHED API DOCUMENTATION:\n";
+    for (const content of contents) {
+      userPrompt += `
+--- Source: ${content.url} ---
+${content.content}
+`;
+    }
+  }
+  const domains = [...whitelist.domains];
+  if (domains.length > 0) {
+    userPrompt += `
+ALLOWED DOMAINS (whitelist):
+${domains.join("\n")}
+`;
+    userPrompt += "\nGenerated tools may only make HTTP requests to these domains.\n";
+  } else {
+    userPrompt += "\nNo domains are whitelisted. Generate only pure computation tools (needs_network: false).\n";
+  }
+  return userPrompt;
+}
+async function generatePlan(llm, prompt, contents, whitelist) {
+  const userPrompt = buildUserPrompt(prompt, contents, whitelist);
+  let lastError = null;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let response;
+    try {
+      response = await llm.generate(SYSTEM_PROMPT, userPrompt);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`LLM error during planning: ${message}`);
+    }
+    const jsonText = extractJSON(response);
+    let parsed;
+    try {
+      parsed = JSON.parse(jsonText);
+    } catch {
+      lastError = new Error(
+        `Failed to parse plan JSON from LLM response: ${jsonText.slice(0, 200)}`
+      );
+      if (attempt === 0) {
+        warn("Invalid JSON from LLM, retrying...");
+        continue;
+      }
+      throw lastError;
+    }
+    try {
+      validatePlan(parsed);
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (attempt === 0) {
+        warn(`Invalid plan from LLM (${lastError.message}), retrying...`);
+        continue;
+      }
+      throw lastError;
+    }
+    try {
+      validatePlanWhitelist(parsed, whitelist);
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (attempt === 0) {
+        warn(
+          `Plan whitelist violation (${lastError.message}), retrying...`
+        );
+        continue;
+      }
+      throw lastError;
+    }
+    verbose(`Generated plan:
+${JSON.stringify(parsed, null, 2)}`);
+    return parsed;
+  }
+  throw lastError ?? new Error("Plan generation failed");
+}
+
+// src/engine/compiler.ts
+var SYSTEM_PROMPT_NETWORK = `You are a JavaScript code generator for MCP tool handlers. You write async function BODIES (not full function declarations) that:
+
+- Receive \`args\` (the tool call arguments object) and \`fetch\` (a whitelisted fetch function) as parameters
+- Make HTTP calls using \`fetch\` to the specified API endpoints
+- Parse responses
+- Return \`{ content: [{ type: "text", text: "..." }] }\`
+- Handle errors gracefully with try/catch and meaningful error messages
+
+Available globals: JSON, Math, String, Number, Boolean, Array, Object, Map, Set, Date, RegExp, Promise, URL, URLSearchParams, TextEncoder, TextDecoder, Headers, Response, fetch, console.log, parseInt, parseFloat, isNaN, isFinite
+
+NOT available: require, import, process, fs, net, http, Buffer, setTimeout, setInterval
+
+OUTPUT FORMAT:
+Return ONLY the function body code. No function declaration, no exports, no imports. The code will be wrapped in \`(async function(args, fetch) { YOUR_CODE_HERE })(inputArgs, fetchFn)\`.
+
+Example output:
+\`\`\`javascript
+const url = "https://api.example.com/items?limit=" + (args.limit || 10);
+const res = await fetch(url);
+if (!res.ok) {
+  return { content: [{ type: "text", text: "Error: " + res.status + " " + res.statusText }], isError: true };
+}
+const data = await res.json();
+return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+\`\`\``;
+var SYSTEM_PROMPT_PURE = `You are a JavaScript code generator for MCP tool handlers. You write async function BODIES (not full function declarations) that:
+
+- Receive \`args\` (the tool call arguments object) as a parameter
+- Perform computation using the provided arguments
+- Return \`{ content: [{ type: "text", text: "..." }] }\`
+- Handle errors gracefully with try/catch and meaningful error messages
+
+This tool does NOT have network access. Do NOT use fetch.
+
+Available globals: JSON, Math, String, Number, Boolean, Array, Object, Map, Set, Date, RegExp, Promise, URL, URLSearchParams, TextEncoder, TextDecoder, console.log, parseInt, parseFloat, isNaN, isFinite
+
+NOT available: require, import, process, fs, net, http, Buffer, setTimeout, setInterval, fetch
+
+OUTPUT FORMAT:
+Return ONLY the function body code. No function declaration, no exports, no imports. The code will be wrapped in \`(async function(args) { YOUR_CODE_HERE })(inputArgs)\`.
+
+Example output:
+\`\`\`javascript
+const result = args.a + args.b;
+return { content: [{ type: "text", text: String(result) }] };
+\`\`\``;
+function extractCode(text) {
+  const fenceMatch = text.match(
+    /```(?:javascript|js|typescript|ts)?\s*\n?([\s\S]*?)\n?```/
+  );
+  if (fenceMatch) return fenceMatch[1].trim();
+  return text.trim();
+}
+function validateCode(code) {
+  if (/\bimport\s+/.test(code)) {
+    throw new Error("Generated code must not use import statements");
+  }
+  if (/\brequire\s*\(/.test(code)) {
+    throw new Error("Generated code must not use require()");
+  }
+  try {
+    new Function(`return (async function(args, fetch) { ${code} });`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid JavaScript syntax: ${message}`);
+  }
+}
+function buildHandlerPrompt(prompt, tool, contents) {
+  let userPrompt = `ORIGINAL PROMPT:
+${prompt}
+`;
+  userPrompt += `
+TOOL TO IMPLEMENT:
+`;
+  userPrompt += `Name: ${tool.name}
+`;
+  userPrompt += `Description: ${tool.description}
+`;
+  userPrompt += `Input Schema: ${JSON.stringify(tool.input_schema, null, 2)}
+`;
+  userPrompt += `Implementation Notes: ${tool.implementation_notes}
+`;
+  if (tool.needs_network) {
+    userPrompt += `
+Endpoints Used:
+`;
+    for (const endpoint of tool.endpoints_used) {
+      userPrompt += `  - ${endpoint}
+`;
+    }
+  } else {
+    userPrompt += `
+This tool does NOT need network access. Do not use fetch.
+`;
+  }
+  if (contents.length > 0) {
+    userPrompt += `
+API DOCUMENTATION:
+`;
+    for (const content of contents) {
+      userPrompt += `
+--- Source: ${content.url} ---
+${content.content}
+`;
+    }
+  }
+  return userPrompt;
+}
+async function compilePlan(llm, plan, contents) {
+  const tools = /* @__PURE__ */ new Map();
+  for (const plannedTool of plan.tools) {
+    verbose(`Compiling handler for tool: ${plannedTool.name}`);
+    const systemPrompt = plannedTool.needs_network ? SYSTEM_PROMPT_NETWORK : SYSTEM_PROMPT_PURE;
+    const userPrompt = buildHandlerPrompt("", plannedTool, contents);
+    let lastError = null;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      let response;
+      try {
+        response = await llm.generate(systemPrompt, userPrompt);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `LLM error while compiling "${plannedTool.name}": ${message}`
+        );
+      }
+      const code = extractCode(response);
+      try {
+        validateCode(code);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt === 0) {
+          warn(
+            `Invalid code for "${plannedTool.name}" (${lastError.message}), retrying...`
+          );
+          continue;
+        }
+        throw new Error(
+          `Failed to compile handler for "${plannedTool.name}": ${lastError.message}`
+        );
+      }
+      tools.set(plannedTool.name, {
+        name: plannedTool.name,
+        description: plannedTool.description,
+        input_schema: plannedTool.input_schema,
+        handler_code: code,
+        needs_network: plannedTool.needs_network
+      });
+      verbose(`Compiled handler for "${plannedTool.name}" (${code.length} chars)`);
+      break;
+    }
+  }
+  return { tools, whitelist_domains: [] };
+}
+
+// src/engine/executor.ts
+function createExecutor(compiled, sandbox) {
+  return {
+    async execute(toolName, args) {
+      const tool = compiled.tools.get(toolName);
+      if (!tool) {
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${toolName}` }],
+          isError: true
+        };
+      }
+      try {
+        return await sandbox.runHandler(tool.handler_code, args);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: `Handler error: ${message}` }],
+          isError: true
+        };
+      }
+    },
+    getExposedTools() {
+      return Array.from(compiled.tools.values()).map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.input_schema
+      }));
+    }
+  };
+}
+
+// src/engine/sandbox.ts
+import vm from "node:vm";
+var HANDLER_TIMEOUT_MS = 3e4;
+function createSandbox(whitelistedFetch, timeoutMs = HANDLER_TIMEOUT_MS) {
+  return {
+    async runHandler(code, args) {
+      const context = vm.createContext({
+        // Safe data-manipulation globals
+        JSON,
+        Math,
+        String,
+        Number,
+        Boolean,
+        Array,
+        Object,
+        Map,
+        Set,
+        Date,
+        RegExp,
+        parseInt,
+        parseFloat,
+        isNaN,
+        isFinite,
+        structuredClone,
+        Promise,
+        // URL handling
+        URL,
+        URLSearchParams,
+        TextEncoder,
+        TextDecoder,
+        Headers,
+        Response,
+        // Network access (whitelisted)
+        fetch: whitelistedFetch,
+        // Logging (redirected to stderr)
+        console: {
+          log: (...logArgs) => console.error("[sandbox]", ...logArgs)
+        },
+        // Injected per-call
+        inputArgs: structuredClone(args),
+        fetchFn: whitelistedFetch
+      });
+      const wrappedCode = `(async function(args, fetch) { ${code} })(inputArgs, fetchFn)`;
+      const script = new vm.Script(wrappedCode);
+      const resultPromise = script.runInContext(context, {
+        timeout: timeoutMs
+      });
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(
+          () => reject(new Error("Handler timed out")),
+          timeoutMs
+        );
+      });
+      const result = await Promise.race([resultPromise, timeoutPromise]);
+      if (!result || !Array.isArray(result.content)) {
+        throw new Error("Handler must return {content: [...]}");
+      }
+      return result;
+    }
+  };
+}
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import http from "node:http";
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => {
+      try {
+        const body = JSON.parse(Buffer.concat(chunks).toString());
+        resolve(body);
+      } catch (e) {
+        reject(e);
+      }
+    });
+    req.on("error", reject);
+  });
+}
+function createExposedServer(config, executor) {
+  const httpServer = http.createServer(async (req, res) => {
+    if (req.method === "POST" && req.url === "/mcp") {
+      const mcpServer = new Server(
+        { name: "mcpboot", version: "0.1.0" },
+        { capabilities: { tools: {} } }
+      );
+      mcpServer.setRequestHandler(ListToolsRequestSchema, async () => {
+        const tools = executor.getExposedTools();
+        return {
+          tools: tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema
+          }))
+        };
+      });
+      mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        return executor.execute(name, args ?? {});
+      });
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: void 0
+      });
+      try {
+        const body = await readBody(req);
+        await mcpServer.connect(transport);
+        await transport.handleRequest(req, res, body);
+        res.on("close", () => {
+          transport.close();
+          mcpServer.close();
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        warn(`HTTP request error: ${message}`);
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(
+            JSON.stringify({
+              jsonrpc: "2.0",
+              error: { code: -32603, message: "Internal server error" },
+              id: null
+            })
+          );
+        }
+      }
+    } else if (req.method === "GET" && req.url === "/health") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          status: "ok",
+          tools: executor.getExposedTools().length
+        })
+      );
+    } else {
+      res.writeHead(404);
+      res.end("Not found");
+    }
+  });
+  return {
+    start() {
+      return new Promise((resolve, reject) => {
+        httpServer.on("error", reject);
+        httpServer.listen(config.port, () => {
+          const addr = httpServer.address();
+          const actualPort = typeof addr === "object" && addr !== null ? addr.port : config.port;
+          resolve(actualPort);
+        });
+      });
+    },
+    stop() {
+      return new Promise((resolve, reject) => {
+        httpServer.close((err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+    }
+  };
+}
+
+// src/index.ts
+function buildContentHash(contents) {
+  const sorted = [...contents].sort((a, b) => a.url.localeCompare(b.url));
+  const joined = sorted.map((c) => c.content).join("\n---\n");
+  return hash(joined);
+}
+function reconstructWhitelist(domains) {
+  const domainSet = new Set(domains);
+  return {
+    domains: domainSet,
+    allows(url) {
+      let hostname;
+      try {
+        hostname = new URL(url).hostname;
+      } catch {
+        return false;
+      }
+      for (const d of domainSet) {
+        if (hostname === d || hostname.endsWith("." + d)) return true;
+      }
+      return false;
+    }
+  };
+}
+async function main(argv = process.argv) {
+  const config = buildConfig(argv);
+  if (!config) return;
+  setVerbose(config.verbose);
+  const urls = extractUrls(config.prompt);
+  log(`Found ${urls.length} URL(s) in prompt`);
+  const contents = await fetchUrls(urls);
+  log(`Fetched ${contents.length} page(s)`);
+  if (urls.length > 0 && contents.length === 0) {
+    warn(
+      "All URL fetches failed. Proceeding with prompt text only \u2014 generated tools may be less accurate"
+    );
+  }
+  const whitelist = buildWhitelist(urls, contents);
+  const whitelistDomains = [...whitelist.domains];
+  verbose(`Whitelist: ${whitelistDomains.join(", ") || "(empty)"}`);
+  const cache = createCache(config.cache);
+  const promptHash = hash(config.prompt);
+  const contentHash = buildContentHash(contents);
+  let compiled;
+  let activeWhitelist;
+  const cached = cache.get(promptHash, contentHash);
+  if (cached) {
+    log("Cache hit \u2014 loading generated tools");
+    compiled = deserializeCompiled(cached);
+    activeWhitelist = reconstructWhitelist(cached.whitelist_domains);
+  } else {
+    log("Cache miss \u2014 generating tools via LLM");
+    const llm = createLLMClient(config.llm);
+    const plan = await generatePlan(llm, config.prompt, contents, whitelist);
+    log(`Plan: ${plan.tools.length} tool(s)`);
+    if (config.dryRun) {
+      console.log(JSON.stringify(plan, null, 2));
+      return;
+    }
+    compiled = await compilePlan(llm, plan, contents);
+    compiled.whitelist_domains = whitelistDomains;
+    log(`Compiled ${compiled.tools.size} handler(s)`);
+    const { compiledTools } = serializeCompiled(compiled);
+    cache.set({
+      promptHash,
+      contentHash,
+      plan,
+      compiledTools,
+      whitelist_domains: whitelistDomains,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    activeWhitelist = whitelist;
+  }
+  if (config.dryRun) {
+    log(`${compiled.tools.size} cached tool(s) available`);
+    const toolNames = Array.from(compiled.tools.keys());
+    console.log(JSON.stringify({ cached: true, tools: toolNames }, null, 2));
+    return;
+  }
+  const whitelistedFetch = createWhitelistedFetch(activeWhitelist);
+  const sandbox = createSandbox(whitelistedFetch);
+  const executor = createExecutor(compiled, sandbox);
+  const server = createExposedServer(config.server, executor);
+  const port = await server.start();
+  log(`Listening on http://localhost:${port}/mcp`);
+  log(`Serving ${executor.getExposedTools().length} tool(s)`);
+  const shutdown = async () => {
+    log("Shutting down...");
+    await server.stop();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+if (process.env.VITEST !== "true") {
+  main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[mcpboot] Fatal: ${message}`);
+    process.exit(1);
+  });
+}
+export {
+  main
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "mcpboot",
+  "version": "0.1.0",
+  "description": "Generate and serve an MCP server from a natural language prompt",
+  "type": "module",
+  "bin": {
+    "mcpboot": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external --banner:js='#!/usr/bin/env node'",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "server",
+    "llm",
+    "tools",
+    "generate"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^1.2.12",
+    "@ai-sdk/openai": "^1.3.22",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ai": "^4.3.16",
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "esbuild": "^0.25.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  }
+}