mcpboot 0.1.0 → 0.1.2

package/README.md

@@ -42,7 +42,8 @@ Options:
   --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
+  --verbose                    Verbose logging (structured JSON to stderr)
+  --log-file <path>            Write full verbose log to file (JSON lines, untruncated)
   --dry-run                    Show generation plan without starting server
 ```
 
@@ -87,18 +88,23 @@ mcpboot fetches the API docs from GitHub, uses the LLM to plan and compile 10 to
 
 ```
 [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)
 ```
 
+With `--verbose`, each step also emits structured JSON events to stderr — one JSON object per line — with timestamps, request correlation IDs, and detailed payloads:
+
+```json
+{"ts":"...","event":"llm_call_start","req_id":"startup","call_id":1,"provider":"anthropic","model":"claude-haiku-4-5",...}
+{"ts":"...","event":"llm_call_end","req_id":"startup","call_id":1,"elapsed_ms":2100,"prompt_tokens":1240,"completion_tokens":892,...}
+```
+
+Use `--log-file mcpboot.log` to capture the full untruncated output (stderr truncates long strings to 500 chars).
+
 **2. Test with the MCP Inspector:**
 
 ```bash

package/dist/index.js

@@ -3,14 +3,14 @@
 // src/config.ts
 import { Command } from "commander";
 import { readFileSync, existsSync } from "node:fs";
-function buildConfig(argv) {
+function buildConfig(argv, pipeOverride) {
   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(
+  ).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("--log-file <path>", "Write full verbose log to file (JSON lines)").option(
     "--dry-run",
     "Show generation plan without starting server",
     false
@@ -65,7 +65,9 @@ function buildConfig(argv) {
       "Error: No API key found. Provide --api-key or set ANTHROPIC_API_KEY / OPENAI_API_KEY"
     );
   }
-  const port = parseInt(opts.port, 10);
+  const pipe = pipeOverride ?? { stdoutIsPipe: !process.stdout.isTTY };
+  const portExplicit = program.getOptionValueSource("port") === "cli";
+  const port = !portExplicit && pipe.stdoutIsPipe ? 0 : 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"
@@ -85,24 +87,105 @@ function buildConfig(argv) {
       enabled: opts.cache !== false,
       dir: opts.cacheDir ?? ".mcpboot-cache"
     },
+    pipe,
     dryRun: opts.dryRun ?? false,
-    verbose: opts.verbose ?? false
+    verbose: opts.verbose ?? false,
+    logFile: opts.logFile
   };
 }
 
 // src/log.ts
+import { appendFileSync, writeFileSync } from "node:fs";
 var verboseEnabled = false;
+var logFilePath;
+var currentRequestId;
+var stats = {
+  llmCalls: 0,
+  llmTotalMs: 0,
+  promptTokens: 0,
+  completionTokens: 0,
+  fetchCalls: 0,
+  fetchTotalMs: 0,
+  sandboxCalls: 0,
+  sandboxTotalMs: 0
+};
 function setVerbose(enabled) {
   verboseEnabled = enabled;
 }
+function setLogFile(path) {
+  logFilePath = path;
+  writeFileSync(path, "");
+}
+function setRequestId(id) {
+  currentRequestId = id;
+}
 function log(msg) {
   console.error(`[mcpboot] ${msg}`);
 }
 function warn(msg) {
   console.error(`[mcpboot] WARN: ${msg}`);
 }
-function verbose(msg) {
-  if (verboseEnabled) console.error(`[mcpboot] ${msg}`);
+function truncateValue(val, limit) {
+  if (typeof val === "string" && val.length > limit) {
+    return val.slice(0, limit) + `...(${val.length} total)`;
+  }
+  if (Array.isArray(val)) {
+    return val.map((v) => truncateValue(v, limit));
+  }
+  if (val && typeof val === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(val)) {
+      out[k] = truncateValue(v, limit);
+    }
+    return out;
+  }
+  return val;
+}
+function logEvent(event, data = {}) {
+  if (!verboseEnabled && !logFilePath) return;
+  const entry = {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    event,
+    ...currentRequestId ? { req_id: currentRequestId } : {},
+    ...data
+  };
+  if (logFilePath) {
+    try {
+      appendFileSync(logFilePath, JSON.stringify(entry) + "\n");
+    } catch {
+    }
+  }
+  if (verboseEnabled) {
+    const truncated = truncateValue(entry, 500);
+    console.error(JSON.stringify(truncated));
+  }
+}
+function trackLLM(elapsed_ms, prompt_tokens, completion_tokens) {
+  stats.llmCalls++;
+  stats.llmTotalMs += elapsed_ms;
+  if (prompt_tokens != null) stats.promptTokens += prompt_tokens;
+  if (completion_tokens != null) stats.completionTokens += completion_tokens;
+}
+function trackFetch(elapsed_ms) {
+  stats.fetchCalls++;
+  stats.fetchTotalMs += elapsed_ms;
+}
+function trackSandbox(elapsed_ms) {
+  stats.sandboxCalls++;
+  stats.sandboxTotalMs += elapsed_ms;
+}
+function logSummary() {
+  logEvent("session_summary", {
+    llm_calls: stats.llmCalls,
+    llm_total_ms: Math.round(stats.llmTotalMs),
+    llm_prompt_tokens: stats.promptTokens,
+    llm_completion_tokens: stats.completionTokens,
+    llm_total_tokens: stats.promptTokens + stats.completionTokens,
+    fetch_calls: stats.fetchCalls,
+    fetch_total_ms: Math.round(stats.fetchTotalMs),
+    sandbox_calls: stats.sandboxCalls,
+    sandbox_total_ms: Math.round(stats.sandboxTotalMs)
+  });
 }
 
 // src/fetcher.ts
@@ -142,7 +225,12 @@ function truncateContent(content, limit = MAX_CONTENT_LENGTH) {
 }
 async function fetchUrl(url) {
   const fetchTarget = rewriteGitHubUrl(url) ?? url;
-  verbose(`Fetching ${fetchTarget}`);
+  logEvent("fetch_start", {
+    url,
+    target_url: fetchTarget,
+    rewritten: fetchTarget !== url
+  });
+  const start = performance.now();
   const response = await fetch(fetchTarget, {
     signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
     headers: {
@@ -150,6 +238,15 @@ async function fetchUrl(url) {
     }
   });
   if (!response.ok) {
+    const elapsed_ms2 = Math.round(performance.now() - start);
+    trackFetch(elapsed_ms2);
+    logEvent("fetch_error", {
+      url,
+      target_url: fetchTarget,
+      status: response.status,
+      status_text: response.statusText,
+      elapsed_ms: elapsed_ms2
+    });
     throw new Error(
       `Fetch failed for ${url}: ${response.status} ${response.statusText}`
     );
@@ -157,11 +254,24 @@ async function fetchUrl(url) {
   const rawContentType = response.headers.get("content-type") ?? "text/plain";
   const contentType = rawContentType.split(";")[0].trim();
   let text = await response.text();
+  const rawLength = text.length;
   if (contentType === "text/html") {
     text = stripHtml(text);
   }
   text = truncateContent(text);
   const discovered = discoverUrls(text);
+  const elapsed_ms = Math.round(performance.now() - start);
+  trackFetch(elapsed_ms);
+  logEvent("fetch_end", {
+    url,
+    target_url: fetchTarget,
+    status: response.status,
+    content_type: contentType,
+    raw_length: rawLength,
+    final_length: text.length,
+    discovered_urls: discovered.length,
+    elapsed_ms
+  });
   return {
     url,
     content: text,
@@ -220,7 +330,7 @@ function buildWhitelist(promptUrls, contents) {
   };
 }
 function createWhitelistedFetch(whitelist, realFetch = globalThis.fetch) {
-  return (url) => {
+  return async (url) => {
     const hostname = extractDomain(url);
     if (!hostname) {
       return Promise.reject(
@@ -234,7 +344,29 @@ function createWhitelistedFetch(whitelist, realFetch = globalThis.fetch) {
         )
       );
     }
-    return realFetch(url);
+    logEvent("sandbox_fetch_start", { url, domain: hostname });
+    const start = performance.now();
+    try {
+      const response = await realFetch(url);
+      const elapsed_ms = Math.round(performance.now() - start);
+      logEvent("sandbox_fetch_end", {
+        url,
+        domain: hostname,
+        status: response.status,
+        elapsed_ms
+      });
+      return response;
+    } catch (error) {
+      const elapsed_ms = Math.round(performance.now() - start);
+      const message = error instanceof Error ? error.message : String(error);
+      logEvent("sandbox_fetch_error", {
+        url,
+        domain: hostname,
+        error: message,
+        elapsed_ms
+      });
+      throw error;
+    }
   };
 }
 
@@ -244,7 +376,7 @@ import {
   existsSync as existsSync2,
   mkdirSync,
   readFileSync as readFileSync2,
-  writeFileSync,
+  writeFileSync as writeFileSync2,
   unlinkSync
 } from "node:fs";
 import { join } from "node:path";
@@ -289,7 +421,7 @@ function createCache(config) {
       if (!config.enabled) return null;
       const filepath = join(config.dir, cacheFilename(promptHash, contentHash));
       if (!existsSync2(filepath)) return null;
-      verbose(`Cache lookup: ${filepath}`);
+      logEvent("cache_lookup", { filepath });
       try {
         const raw = readFileSync2(filepath, "utf-8");
         const parsed = JSON.parse(raw);
@@ -298,7 +430,7 @@ function createCache(config) {
           unlinkSync(filepath);
           return null;
         }
-        verbose(`Cache hit: ${filepath} (created ${parsed.createdAt})`);
+        logEvent("cache_hit", { filepath, created_at: parsed.createdAt });
         return parsed;
       } catch {
         warn(`Failed to read cache file ${filepath}, removing`);
@@ -316,8 +448,8 @@ function createCache(config) {
         config.dir,
         cacheFilename(entry.promptHash, entry.contentHash)
       );
-      writeFileSync(filepath, JSON.stringify(entry, null, 2));
-      verbose(`Cache written: ${filepath}`);
+      writeFileSync2(filepath, JSON.stringify(entry, null, 2));
+      logEvent("cache_written", { filepath });
     }
   };
 }
@@ -330,6 +462,7 @@ var DEFAULT_MODELS = {
   anthropic: "claude-sonnet-4-20250514",
   openai: "gpt-4o"
 };
+var callCount = 0;
 function createLLMClient(config) {
   const modelId = config.model ?? DEFAULT_MODELS[config.provider];
   let model;
@@ -340,8 +473,20 @@ function createLLMClient(config) {
     const openai = createOpenAI({ apiKey: config.apiKey });
     model = openai(modelId);
   }
+  logEvent("llm_init", { provider: config.provider, model: modelId });
   return {
     async generate(system, user) {
+      const callId = ++callCount;
+      logEvent("llm_call_start", {
+        call_id: callId,
+        provider: config.provider,
+        model: modelId,
+        max_tokens: 8192,
+        temperature: 0.2,
+        system_prompt: system,
+        user_prompt: user
+      });
+      const start = performance.now();
       try {
         const result = await generateText({
           model,
@@ -350,9 +495,29 @@ function createLLMClient(config) {
           maxTokens: 8192,
           temperature: 0.2
         });
+        const elapsed_ms = Math.round(performance.now() - start);
+        const prompt_tokens = result.usage?.promptTokens;
+        const completion_tokens = result.usage?.completionTokens;
+        trackLLM(elapsed_ms, prompt_tokens, completion_tokens);
+        logEvent("llm_call_end", {
+          call_id: callId,
+          elapsed_ms,
+          prompt_tokens,
+          completion_tokens,
+          total_tokens: (prompt_tokens ?? 0) + (completion_tokens ?? 0),
+          finish_reason: result.finishReason,
+          response: result.text
+        });
         return result.text;
       } catch (error) {
+        const elapsed_ms = Math.round(performance.now() - start);
         const err = error;
+        logEvent("llm_call_error", {
+          call_id: callId,
+          elapsed_ms,
+          error: err.message ?? String(error),
+          status_code: err.statusCode
+        });
         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)`
@@ -368,6 +533,8 @@ function createLLMClient(config) {
 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.
 
+IMPORTANT: The tool descriptions and schemas you produce will be consumed by downstream AI/LLM systems to understand each tool's behavior, generate web UIs, and produce correct tool calls. Descriptions and schemas must therefore be thorough, self-contained, and richly annotated.
+
 OUTPUT FORMAT:
 Return ONLY valid JSON matching this exact schema (no markdown, no explanation):
 
@@ -375,11 +542,16 @@ Return ONLY valid JSON matching this exact schema (no markdown, no explanation):
   "tools": [
     {
       "name": "tool_name",
-      "description": "What the tool does",
+      "description": "A comprehensive, multi-paragraph description (see DESCRIPTION GUIDELINES below)",
       "input_schema": {
         "type": "object",
         "properties": {
-          "param_name": { "type": "string", "description": "Parameter description" }
+          "param_name": {
+            "type": "string",
+            "description": "Detailed parameter description including purpose, format, and constraints",
+            "default": "optional default value if applicable",
+            "examples": ["example_value_1", "example_value_2"]
+          }
         },
         "required": ["param_name"]
       },
@@ -390,6 +562,51 @@ Return ONLY valid JSON matching this exact schema (no markdown, no explanation):
   ]
 }
 
+DESCRIPTION GUIDELINES:
+Each tool's "description" field must be a rich, self-contained documentation string. Include ALL of the following sections, separated by blank lines:
+
+1. SUMMARY: A clear one-sentence summary of what the tool does.
+2. DETAILS: When to use this tool, how it relates to other tools, any important behavioral notes or caveats.
+3. RESPONSE FORMAT: Describe the structure and fields of a successful response. Include a concrete JSON example.
+4. EXAMPLE: Show at least one realistic usage example with sample parameter values and a corresponding example response.
+5. ERRORS: List common error scenarios (e.g., invalid input, resource not found, rate limits).
+
+Example of a good description:
+
+"Retrieves the full details of a specific Hacker News item (story, comment, job, poll, or pollopt) by its unique numeric ID.\\n\\nUse this tool when you have an item ID (e.g. from get_top_stories) and need its title, author, score, URL, or child comments. Each item type returns slightly different fields.\\n\\nResponse format:\\nReturns a JSON object with the item details. Fields vary by type. Stories include: id, type, by, title, url, score, time, descendants, kids. Comments include: id, type, by, text, parent, time, kids.\\n\\nExample response:\\n{\\n  \\"id\\": 8863,\\n  \\"type\\": \\"story\\",\\n  \\"by\\": \\"dhouston\\",\\n  \\"title\\": \\"My YC app: Dropbox\\",\\n  \\"url\\": \\"http://www.getdropbox.com/u/2/screencast.html\\",\\n  \\"score\\": 111,\\n  \\"time\\": 1175714200,\\n  \\"descendants\\": 71\\n}\\n\\nExample usage:\\n- Input: { \\"id\\": 8863 }\\n- Returns the full item object for story 8863\\n\\nErrors:\\n- Returns an error if the item ID does not exist or the API is unreachable."
+
+INPUT SCHEMA GUIDELINES:
+Use the full power of JSON Schema to describe each parameter precisely:
+- Every property MUST have a "description" explaining its purpose, expected format, and constraints.
+- Use "default" to document the default value when a parameter is optional.
+- Use "examples" (array) to provide 2-3 realistic example values.
+- Use "minimum" / "maximum" for numeric bounds when applicable.
+- Use "enum" for parameters with a fixed set of allowed values.
+- Use "pattern" for string parameters with a specific format (e.g., date patterns).
+- Use "minLength" / "maxLength" for string length constraints when applicable.
+
+Example of a good input_schema:
+{
+  "type": "object",
+  "properties": {
+    "limit": {
+      "type": "number",
+      "description": "Maximum number of story IDs to return. The API provides up to 500 stories; this parameter caps the result to the specified count.",
+      "default": 10,
+      "minimum": 1,
+      "maximum": 500,
+      "examples": [5, 10, 50]
+    },
+    "id": {
+      "type": "number",
+      "description": "The unique numeric Hacker News item ID. Item IDs are positive integers assigned sequentially. Obtain item IDs from tools like get_top_stories or get_new_stories.",
+      "minimum": 1,
+      "examples": [8863, 37052586]
+    }
+  },
+  "required": ["id"]
+}
+
 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.
@@ -488,7 +705,14 @@ ${domains.join("\n")}
 async function generatePlan(llm, prompt, contents, whitelist) {
   const userPrompt = buildUserPrompt(prompt, contents, whitelist);
   let lastError = null;
+  logEvent("plan_start", {
+    doc_count: contents.length,
+    whitelist: [...whitelist.domains]
+  });
   for (let attempt = 0; attempt < 2; attempt++) {
+    if (attempt > 0) {
+      logEvent("plan_retry", { attempt: attempt + 1 });
+    }
     let response;
     try {
       response = await llm.generate(SYSTEM_PROMPT, userPrompt);
@@ -496,6 +720,7 @@ async function generatePlan(llm, prompt, contents, whitelist) {
       const message = error instanceof Error ? error.message : String(error);
       throw new Error(`LLM error during planning: ${message}`);
     }
+    logEvent("plan_llm_response", { response, attempt: attempt + 1 });
     const jsonText = extractJSON(response);
     let parsed;
     try {
@@ -532,8 +757,11 @@ async function generatePlan(llm, prompt, contents, whitelist) {
       }
       throw lastError;
     }
-    verbose(`Generated plan:
-${JSON.stringify(parsed, null, 2)}`);
+    logEvent("plan_end", {
+      tool_count: parsed.tools.length,
+      tool_names: parsed.tools.map((t) => t.name),
+      plan: parsed
+    });
     return parsed;
   }
   throw lastError ?? new Error("Plan generation failed");
@@ -650,12 +878,22 @@ ${content.content}
 }
 async function compilePlan(llm, plan, contents) {
   const tools = /* @__PURE__ */ new Map();
+  logEvent("compile_start", { tool_count: plan.tools.length });
   for (const plannedTool of plan.tools) {
-    verbose(`Compiling handler for tool: ${plannedTool.name}`);
+    logEvent("compile_tool_start", {
+      tool_name: plannedTool.name,
+      needs_network: plannedTool.needs_network
+    });
     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++) {
+      if (attempt > 0) {
+        logEvent("compile_tool_retry", {
+          tool_name: plannedTool.name,
+          attempt: attempt + 1
+        });
+      }
       let response;
       try {
         response = await llm.generate(systemPrompt, userPrompt);
@@ -665,6 +903,11 @@ async function compilePlan(llm, plan, contents) {
           `LLM error while compiling "${plannedTool.name}": ${message}`
         );
       }
+      logEvent("compile_tool_llm_response", {
+        tool_name: plannedTool.name,
+        response,
+        attempt: attempt + 1
+      });
       const code = extractCode(response);
       try {
         validateCode(code);
@@ -687,7 +930,11 @@ async function compilePlan(llm, plan, contents) {
         handler_code: code,
         needs_network: plannedTool.needs_network
       });
-      verbose(`Compiled handler for "${plannedTool.name}" (${code.length} chars)`);
+      logEvent("compile_tool_end", {
+        tool_name: plannedTool.name,
+        code_length: code.length,
+        handler_code: code
+      });
       break;
     }
   }
@@ -700,15 +947,34 @@ function createExecutor(compiled, sandbox) {
     async execute(toolName, args) {
       const tool = compiled.tools.get(toolName);
       if (!tool) {
+        logEvent("executor_unknown_tool", { tool_name: toolName });
         return {
           content: [{ type: "text", text: `Unknown tool: ${toolName}` }],
           isError: true
         };
       }
+      logEvent("executor_start", { tool_name: toolName, args });
+      const start = performance.now();
       try {
-        return await sandbox.runHandler(tool.handler_code, args);
+        const result = await sandbox.runHandler(tool.handler_code, args);
+        const elapsed_ms = Math.round(performance.now() - start);
+        trackSandbox(elapsed_ms);
+        logEvent("executor_end", {
+          tool_name: toolName,
+          result,
+          elapsed_ms,
+          is_error: false
+        });
+        return result;
       } catch (error) {
+        const elapsed_ms = Math.round(performance.now() - start);
+        trackSandbox(elapsed_ms);
         const message = error instanceof Error ? error.message : String(error);
+        logEvent("executor_error", {
+          tool_name: toolName,
+          error: message,
+          elapsed_ms
+        });
         return {
           content: [{ type: "text", text: `Handler error: ${message}` }],
           isError: true
@@ -795,6 +1061,7 @@ import {
   CallToolRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import http from "node:http";
+import { randomBytes } from "node:crypto";
 function readBody(req) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -812,6 +1079,9 @@ function readBody(req) {
 }
 function createExposedServer(config, executor) {
   const httpServer = http.createServer(async (req, res) => {
+    const reqId = randomBytes(6).toString("hex");
+    setRequestId(reqId);
+    logEvent("http_request", { method: req.method, url: req.url });
     if (req.method === "POST" && req.url === "/mcp") {
       const mcpServer = new Server(
         { name: "mcpboot", version: "0.1.0" },
@@ -819,6 +1089,7 @@ function createExposedServer(config, executor) {
       );
       mcpServer.setRequestHandler(ListToolsRequestSchema, async () => {
         const tools = executor.getExposedTools();
+        logEvent("mcp_list_tools", { tool_count: tools.length });
         return {
           tools: tools.map((t) => ({
             name: t.name,
@@ -829,16 +1100,31 @@ function createExposedServer(config, executor) {
       });
       mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
-        return executor.execute(name, args ?? {});
+        logEvent("mcp_call_tool_start", {
+          tool_name: name,
+          args: args ?? {}
+        });
+        const start = performance.now();
+        const result = await executor.execute(name, args ?? {});
+        const elapsed_ms = Math.round(performance.now() - start);
+        logEvent("mcp_call_tool_end", {
+          tool_name: name,
+          result,
+          elapsed_ms,
+          is_error: result.isError ?? false
+        });
+        return result;
       });
       const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: void 0
       });
       try {
         const body = await readBody(req);
+        logEvent("mcp_request_body", { body });
         await mcpServer.connect(transport);
         await transport.handleRequest(req, res, body);
         res.on("close", () => {
+          setRequestId(void 0);
           transport.close();
           mcpServer.close();
         });
@@ -857,6 +1143,9 @@ function createExposedServer(config, executor) {
         }
       }
     } else if (req.method === "GET" && req.url === "/health") {
+      logEvent("health_check", {
+        tool_count: executor.getExposedTools().length
+      });
       res.writeHead(200, { "Content-Type": "application/json" });
       res.end(
         JSON.stringify({
@@ -865,9 +1154,11 @@ function createExposedServer(config, executor) {
         })
       );
     } else {
+      logEvent("unknown_route", { method: req.method, url: req.url });
       res.writeHead(404);
       res.end("Not found");
     }
+    setRequestId(void 0);
   });
   return {
     start() {
@@ -891,6 +1182,11 @@ function createExposedServer(config, executor) {
   };
 }
 
+// src/pipe.ts
+function writeOwnUrl(url, output = process.stdout) {
+  output.write(url + "\n");
+}
+
 // src/index.ts
 function buildContentHash(contents) {
   const sorted = [...contents].sort((a, b) => a.url.localeCompare(b.url));
@@ -919,6 +1215,17 @@ async function main(argv = process.argv) {
   const config = buildConfig(argv);
   if (!config) return;
   setVerbose(config.verbose);
+  if (config.logFile) {
+    setLogFile(config.logFile);
+  }
+  setRequestId("startup");
+  logEvent("session_start", {
+    prompt_length: config.prompt.length,
+    provider: config.llm.provider,
+    model: config.llm.model,
+    cache_enabled: config.cache.enabled,
+    dry_run: config.dryRun
+  });
   const urls = extractUrls(config.prompt);
   log(`Found ${urls.length} URL(s) in prompt`);
   const contents = await fetchUrls(urls);
@@ -930,7 +1237,7 @@ async function main(argv = process.argv) {
   }
   const whitelist = buildWhitelist(urls, contents);
   const whitelistDomains = [...whitelist.domains];
-  verbose(`Whitelist: ${whitelistDomains.join(", ") || "(empty)"}`);
+  logEvent("whitelist_built", { domains: whitelistDomains });
   const cache = createCache(config.cache);
   const promptHash = hash(config.prompt);
   const contentHash = buildContentHash(contents);
@@ -939,15 +1246,18 @@ async function main(argv = process.argv) {
   const cached = cache.get(promptHash, contentHash);
   if (cached) {
     log("Cache hit \u2014 loading generated tools");
+    logEvent("cache_hit", { prompt_hash: promptHash, content_hash: contentHash });
     compiled = deserializeCompiled(cached);
     activeWhitelist = reconstructWhitelist(cached.whitelist_domains);
   } else {
     log("Cache miss \u2014 generating tools via LLM");
+    logEvent("cache_miss", { prompt_hash: promptHash, content_hash: contentHash });
     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));
+      logSummary();
       return;
     }
     compiled = await compilePlan(llm, plan, contents);
@@ -968,8 +1278,10 @@ async function main(argv = process.argv) {
     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));
+    logSummary();
     return;
   }
+  setRequestId(void 0);
   const whitelistedFetch = createWhitelistedFetch(activeWhitelist);
   const sandbox = createSandbox(whitelistedFetch);
   const executor = createExecutor(compiled, sandbox);
@@ -977,13 +1289,23 @@ async function main(argv = process.argv) {
   const port = await server.start();
   log(`Listening on http://localhost:${port}/mcp`);
   log(`Serving ${executor.getExposedTools().length} tool(s)`);
+  logEvent("server_ready", {
+    port,
+    tool_count: executor.getExposedTools().length,
+    tool_names: executor.getExposedTools().map((t) => t.name)
+  });
+  if (config.pipe.stdoutIsPipe) {
+    writeOwnUrl(`http://localhost:${port}/mcp`);
+  }
   const shutdown = async () => {
     log("Shutting down...");
+    logSummary();
     await server.stop();
     process.exit(0);
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
+  process.on("SIGPIPE", shutdown);
 }
 if (process.env.VITEST !== "true") {
   main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpboot",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Generate and serve an MCP server from a natural language prompt",
   "type": "module",
   "bin": {