@prefecthq/fastmcp-ts 1.5.2 → 1.7.0

package/dist/server.js

@@ -74,7 +74,7 @@ function resolveSensitiveHeaders(options) {
   for (const h of options?.exposeHeaders ?? []) set.delete(h.toLowerCase());
   return set;
 }
-function buildHttpRequestContext(req, sensitiveHeaders) {
+function buildHttpRequestContext(req, sensitiveHeaders, logger) {
   const headers = new Headers();
   const redacted = [];
   req.headers.forEach((value, name) => {
@@ -89,7 +89,8 @@ function buildHttpRequestContext(req, sensitiveHeaders) {
   try {
     const u = new URL(req.url);
     url = u.pathname + u.search;
-  } catch {
+  } catch (err) {
+    logger?.debug("request URL parse failed; using origin-form as-is", { component: "http", error: err });
     url = req.url;
   }
   return { headers, redactedHeaderNames: redacted, method: req.method, url };
@@ -147,7 +148,7 @@ var SESSION_CLOSE_CALLBACKS_KEY = "__fastmcp_session_close_callbacks";
 var SESSION_STATE_MODERN_HTTP_ERROR = "[fastmcp] Session state is not available on modern HTTP requests (protocol revision 2026-07-28). Each request runs statelessly with no shared session store. Use ctx.requestState() to read per-request state. Use ctx.mintRequestState() to carry state across a multi-round-trip flow.";
 var SESSION_STATE_STATELESS_HTTP_ERROR = "[fastmcp] Session state is not available on a stateless HTTP server (RunOptions.stateless or FASTMCP_STATELESS_HTTP). Each request runs against a fresh store that is discarded when the request ends. Use ctx.requestState() to read per-request state. Use ctx.mintRequestState() to carry state across a multi-round-trip flow. Turn stateless off to use session state, or keep state in your own external store.";
 var SERVER_INITIATED_STATELESS_HTTP_ERROR = "[fastmcp] Server-initiated requests (ctx.elicit, ctx.sample, ctx.listRoots) are not available on a stateless HTTP server (RunOptions.stateless or FASTMCP_STATELESS_HTTP). They need a session: client capabilities are negotiated once at initialize, and the client replies on a separate request. Return inputRequired({ requestState }) to carry a multi-round-trip flow without a session; the embedded-request form of inputRequired needs a session too. Turn stateless off to use server-initiated requests.";
-function createContext(server, sdkCtx, auth, sessionState, requestStateCodec, stateless, sensitiveHeaders) {
+function createContext(server, sdkCtx, auth, sessionState, requestStateCodec, stateless, sensitiveHeaders, logger) {
   const requestId = String(sdkCtx.mcpReq.id);
   const progressToken = sdkCtx.mcpReq._meta?.progressToken;
   const isModernEra = sdkCtx.mcpReq.envelope !== void 0;
@@ -165,16 +166,16 @@ function createContext(server, sdkCtx, auth, sessionState, requestStateCodec, st
   return {
     auth,
     requestId,
-    http: httpReq ? buildHttpRequestContext(httpReq, sensitive) : void 0,
+    http: httpReq ? buildHttpRequestContext(httpReq, sensitive, logger) : void 0,
     log,
-    debug: (msg, logger) => log("debug", msg, logger),
-    info: (msg, logger) => log("info", msg, logger),
-    notice: (msg, logger) => log("notice", msg, logger),
-    warning: (msg, logger) => log("warning", msg, logger),
-    error: (msg, logger) => log("error", msg, logger),
-    critical: (msg, logger) => log("critical", msg, logger),
-    alert: (msg, logger) => log("alert", msg, logger),
-    emergency: (msg, logger) => log("emergency", msg, logger),
+    debug: (msg, logger2) => log("debug", msg, logger2),
+    info: (msg, logger2) => log("info", msg, logger2),
+    notice: (msg, logger2) => log("notice", msg, logger2),
+    warning: (msg, logger2) => log("warning", msg, logger2),
+    error: (msg, logger2) => log("error", msg, logger2),
+    critical: (msg, logger2) => log("critical", msg, logger2),
+    alert: (msg, logger2) => log("alert", msg, logger2),
+    emergency: (msg, logger2) => log("emergency", msg, logger2),
     async reportProgress(progress, total, message) {
       if (progressToken === void 0) return;
       await sdkCtx.mcpReq.notify({
@@ -256,9 +257,16 @@ function createContext(server, sdkCtx, auth, sessionState, requestStateCodec, st
     requestState: () => sdkCtx.mcpReq.requestState(),
     async mintRequestState(payload) {
       if (requestStateCodec) return requestStateCodec.mint(payload, sdkCtx);
-      console.warn(
-        "[fastmcp] ctx.mintRequestState() called without FastMCPOptions.requestState configured \u2014 the resulting requestState is unsigned. Configure FastMCPOptions.requestState for any state that influences authorization, resource access, or business logic."
-      );
+      if (logger) {
+        logger.warn(
+          "ctx.mintRequestState() called without FastMCPOptions.requestState configured; the resulting requestState is unsigned. Configure FastMCPOptions.requestState for any state that influences authorization, resource access, or business logic.",
+          { component: "context" }
+        );
+      } else {
+        console.warn(
+          "[fastmcp] ctx.mintRequestState() called without FastMCPOptions.requestState configured \u2014 the resulting requestState is unsigned. Configure FastMCPOptions.requestState for any state that influences authorization, resource access, or business logic."
+        );
+      }
       return JSON.stringify(payload);
     },
     getState: (key) => {
@@ -296,7 +304,7 @@ var CustomRouteRegistry = class {
     }
     if (methods.includes("OPTIONS")) {
       throw new Error(
-        `customRoute ${path}: OPTIONS cannot be routed \u2014 the CORS preflight handler answers OPTIONS before route dispatch`
+        `customRoute ${path}: OPTIONS cannot be routed \u2014 it is reserved for the CORS preflight and never dispatches to routes`
       );
     }
     if (this._routes.has(path)) {
@@ -355,13 +363,14 @@ function resolveHealth(health) {
   }
   return { path, status, body };
 }
-async function serveCustomRouteNode(handler, req, res) {
+async function serveCustomRouteNode(handler, req, res, logger) {
   const { toWebRequest } = await import("@modelcontextprotocol/node");
   let response;
   try {
     response = await handler(await toWebRequest(req));
   } catch (error) {
-    console.error("[fastmcp] custom route handler failed:", error);
+    if (logger) logger.error("custom route handler failed", { component: "routes", error });
+    else console.error("[fastmcp] custom route handler failed:", error);
     res.writeHead(500, { "Content-Type": "application/json" }).end(JSON.stringify({ error: "Internal Server Error" }));
     return;
   }
@@ -369,7 +378,8 @@ async function serveCustomRouteNode(handler, req, res) {
   if (response.body) {
     const stream = Readable.fromWeb(response.body);
     stream.on("error", (error) => {
-      console.error("[fastmcp] custom route response stream failed:", error);
+      if (logger) logger.error("custom route response stream failed", { component: "routes", error });
+      else console.error("[fastmcp] custom route response stream failed:", error);
       res.destroy();
     });
     stream.pipe(res);
@@ -428,21 +438,68 @@ function runMiddlewareChain(middleware, method, request, mcpContext, handler) {
   return dispatch(0);
 }
 var LoggingMiddleware = class {
-  constructor(emit = console.log) {
+  constructor(emit) {
     this.emit = emit;
   }
   emit;
+  logger;
+  /** @internal Called by FastMCP when this middleware is attached. */
+  _bindLogger(logger) {
+    if (!this.emit) this.logger = logger;
+  }
+  // Three output paths, each shaped for its audience:
+  // - explicit `emit`: byte-identical to the pre-logger-injection format
+  //   (arrows and the ✗ glyph), since callers may already parse it.
+  // - `this.logger` (the LOGGER branch): the spec invariant that injected
+  //   loggers receive no symbols — plain text plus structured meta.
+  // - stderr fallback (detached from a server): presentation output, like
+  //   DefaultSink, so it keeps the arrow/glyph format too.
+  emitRequest(method) {
+    if (this.emit) {
+      this.emit(`[fastmcp] \u2192 ${method}`);
+      return;
+    }
+    if (this.logger) {
+      this.logger.info(`request ${method}`);
+      return;
+    }
+    process.stderr.write(`[fastmcp] \u2192 ${method}
+`);
+  }
+  emitResponse(method, ms) {
+    if (this.emit) {
+      this.emit(`[fastmcp] \u2190 ${method} (${ms}ms)`);
+      return;
+    }
+    if (this.logger) {
+      this.logger.info(`response ${method}`, { ms });
+      return;
+    }
+    process.stderr.write(`[fastmcp] \u2190 ${method} (${ms}ms)
+`);
+  }
+  emitFailure(method, ms, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (this.emit) {
+      this.emit(`[fastmcp] \u2717 ${method} (${ms}ms): ${message}`);
+      return;
+    }
+    if (this.logger) {
+      this.logger.warn(`request failed ${method}`, { ms, error: err });
+      return;
+    }
+    process.stderr.write(`[fastmcp] \u2717 ${method} (${ms}ms): ${message}
+`);
+  }
   async onRequest(ctx, next) {
     const t0 = Date.now();
-    this.emit(`[fastmcp] \u2192 ${ctx.method}`);
+    this.emitRequest(ctx.method);
     try {
       const result = await next();
-      this.emit(`[fastmcp] \u2190 ${ctx.method} (${Date.now() - t0}ms)`);
+      this.emitResponse(ctx.method, Date.now() - t0);
       return result;
     } catch (err) {
-      this.emit(
-        `[fastmcp] \u2717 ${ctx.method} (${Date.now() - t0}ms): ${err instanceof Error ? err.message : String(err)}`
-      );
+      this.emitFailure(ctx.method, Date.now() - t0, err);
       throw err;
     }
   }
@@ -744,7 +801,7 @@ var ToolResult = class {
   }
   result;
 };
-function convertResult(value, stateless) {
+function convertResult(value, stateless, logger) {
   if (isInputRequiredResult(value)) {
     assertInputRequestsAllowedStateless(value, stateless);
     return value;
@@ -781,9 +838,16 @@ function convertResult(value, stateless) {
     return { content: [] };
   }
   if (Array.isArray(value)) {
-    console.warn(
-      "[fastmcp] Tool returned an array \u2014 structuredContent will not be set (MCP spec requires a plain object). Wrap in an object or use ToolResult to suppress this warning."
-    );
+    if (logger) {
+      logger.warn(
+        "Tool returned an array; structuredContent will not be set (MCP spec requires a plain object). Wrap in an object or use ToolResult to suppress this warning.",
+        { component: "tool" }
+      );
+    } else {
+      console.warn(
+        "[fastmcp] Tool returned an array \u2014 structuredContent will not be set (MCP spec requires a plain object). Wrap in an object or use ToolResult to suppress this warning."
+      );
+    }
     return {
       content: [{ type: "text", text: JSON.stringify(value) }]
     };
@@ -799,7 +863,7 @@ function convertResult(value, stateless) {
     content: [{ type: "text", text: String(value) }]
   };
 }
-async function toJsonSchema(schema, context) {
+async function toJsonSchema(schema, context, logger) {
   const maybeNative = schema;
   if (typeof maybeNative.toJsonSchema === "function") {
     try {
@@ -807,7 +871,8 @@ async function toJsonSchema(schema, context) {
       if (result !== null && typeof result === "object") {
         return result;
       }
-    } catch {
+    } catch (err) {
+      logger?.debug("toJsonSchema strategy failed", { component: "tool", strategy: "native", error: err });
     }
   }
   try {
@@ -815,12 +880,13 @@ async function toJsonSchema(schema, context) {
     return z.toJSONSchema(
       schema
     );
-  } catch {
+  } catch (err) {
+    logger?.debug("toJsonSchema strategy failed", { component: "tool", strategy: "zod-v4", error: err });
   }
   const where = context ? ` for ${context}` : "";
-  console.warn(
-    `[fastmcp] Could not auto-generate JSON schema${where}. Sending { type: 'object' } to clients. Provide an explicit 'inputSchema' in ToolConfig to suppress this warning.`
-  );
+  const message = `Could not auto-generate JSON schema${where}. Sending { type: 'object' } to clients. Provide an explicit 'inputSchema' in ToolConfig to suppress this warning.`;
+  if (logger) logger.warn(message, { component: "tool" });
+  else console.warn(`[fastmcp] ${message}`);
   return { type: "object" };
 }
 async function validateInput(schema, input, throwAsProtocolError = false) {
@@ -986,6 +1052,366 @@ function normalizeCompletion(raw) {
 }
 var EMPTY_COMPLETION = { values: [] };
 
+// src/server/cors.ts
+var DEFAULT_CORS_METHODS = ["GET", "POST", "DELETE", "OPTIONS"];
+var DEFAULT_CORS_ALLOWED_HEADERS = [
+  "Content-Type",
+  "Authorization",
+  "Mcp-Session-Id",
+  "MCP-Protocol-Version",
+  "Mcp-Method",
+  "Mcp-Name"
+];
+var DEFAULT_CORS_EXPOSED_HEADERS = ["Mcp-Session-Id"];
+function hasInvalidHeaderChar(value) {
+  return /\s/.test(value) || [...value].some((ch) => ch.charCodeAt(0) < 32 || ch.charCodeAt(0) === 127);
+}
+function mergedHeaderList(defaults, extra, option) {
+  if (extra !== void 0 && !Array.isArray(extra)) {
+    throw new Error(`Invalid cors.${option}: must be an array of header names, got: ${JSON.stringify(extra)}`);
+  }
+  const merged = [...defaults];
+  const seen = new Set(defaults.map((h) => h.toLowerCase()));
+  for (const header of extra ?? []) {
+    if (typeof header !== "string" || header.trim() === "") {
+      throw new Error(`Invalid cors.${option}: entries must be non-empty strings, got: ${JSON.stringify(header)}`);
+    }
+    if (hasInvalidHeaderChar(header)) {
+      throw new Error(
+        `Invalid cors.${option}: entries must not contain whitespace or control characters, got: ${JSON.stringify(header)}`
+      );
+    }
+    if (!seen.has(header.toLowerCase())) {
+      seen.add(header.toLowerCase());
+      merged.push(header);
+    }
+  }
+  return merged.join(", ");
+}
+function resolveOriginMode(origin) {
+  if (origin === void 0 || origin === "*") return { kind: "any" };
+  if (typeof origin === "function") return { kind: "predicate", test: origin };
+  const list = typeof origin === "string" ? [origin] : origin;
+  if (!Array.isArray(list) || list.length === 0) {
+    throw new Error(
+      `Invalid cors.origin: expected '*', an origin, a non-empty array of origins, or a function, got: ${JSON.stringify(origin)}`
+    );
+  }
+  for (const entry of list) {
+    if (typeof entry !== "string" || entry === "") {
+      throw new Error(`Invalid cors.origin: entries must be non-empty strings, got: ${JSON.stringify(entry)}`);
+    }
+    if (entry === "*") {
+      throw new Error(
+        "Invalid cors.origin: '*' inside an origin array never matches (browsers never send it as a literal Origin); use origin: '*' (the string) for wildcard"
+      );
+    }
+    if (entry.endsWith("/")) {
+      throw new Error(
+        `Invalid cors.origin "${entry}": an Origin header never carries a trailing slash, so this entry can never match; drop the trailing slash`
+      );
+    }
+  }
+  return { kind: "list", origins: new Set(list) };
+}
+function resolveCors(cors) {
+  if (cors === false) return null;
+  const opts = cors === void 0 || cors === true ? {} : cors;
+  if (typeof opts !== "object" || opts === null || Array.isArray(opts)) {
+    throw new Error(`Invalid cors option: expected boolean or object, got ${typeof cors}`);
+  }
+  const originMode = resolveOriginMode(opts.origin);
+  if (opts.credentials !== void 0 && typeof opts.credentials !== "boolean") {
+    throw new Error(`Invalid cors.credentials: must be a boolean, got: ${JSON.stringify(opts.credentials)}`);
+  }
+  if (opts.credentials === true && originMode.kind === "any") {
+    throw new Error(
+      "Invalid cors config: credentials: true requires an explicit origin \u2014 browsers reject 'Access-Control-Allow-Origin: *' on credentialed requests; set cors.origin to your site origin(s)"
+    );
+  }
+  let methods = DEFAULT_CORS_METHODS;
+  if (opts.methods !== void 0) {
+    if (!Array.isArray(opts.methods) || opts.methods.length === 0) {
+      throw new Error("Invalid cors.methods: must be a non-empty array of method names");
+    }
+    methods = [
+      ...new Set(
+        opts.methods.map((m) => {
+          if (typeof m !== "string" || m.trim() === "") {
+            throw new Error(`Invalid cors.methods: entries must be non-empty strings, got: ${JSON.stringify(m)}`);
+          }
+          if (hasInvalidHeaderChar(m)) {
+            throw new Error(
+              `Invalid cors.methods: entries must not contain whitespace or control characters, got: ${JSON.stringify(m)}`
+            );
+          }
+          return m.toUpperCase();
+        })
+      )
+    ];
+  }
+  const maxAge = opts.maxAge ?? null;
+  if (maxAge !== null && (!Number.isInteger(maxAge) || maxAge < 0)) {
+    throw new Error(`Invalid cors.maxAge: must be a non-negative integer (seconds), got: ${JSON.stringify(opts.maxAge)}`);
+  }
+  return {
+    originMode,
+    methods: methods.join(", "),
+    allowedHeaders: mergedHeaderList(DEFAULT_CORS_ALLOWED_HEADERS, opts.allowedHeaders, "allowedHeaders"),
+    exposedHeaders: mergedHeaderList(DEFAULT_CORS_EXPOSED_HEADERS, opts.exposedHeaders, "exposedHeaders"),
+    credentials: opts.credentials === true,
+    maxAge
+  };
+}
+function allowOriginValue(cors, requestOrigin, logger) {
+  switch (cors.originMode.kind) {
+    case "any":
+      return "*";
+    case "list":
+      return requestOrigin !== void 0 && cors.originMode.origins.has(requestOrigin) ? requestOrigin : null;
+    case "predicate": {
+      if (requestOrigin === void 0) return null;
+      try {
+        return cors.originMode.test(requestOrigin) ? requestOrigin : null;
+      } catch (err) {
+        if (logger) logger.error("cors.origin predicate threw; denying origin", { component: "cors", error: err });
+        else console.error("[fastmcp] cors.origin predicate threw; denying origin:", err);
+        return null;
+      }
+    }
+  }
+}
+function baseHeaders(cors, requestOrigin, logger) {
+  const headers = {};
+  if (cors.originMode.kind !== "any") headers["Vary"] = "Origin";
+  const origin = allowOriginValue(cors, requestOrigin, logger);
+  if (origin === null) return headers;
+  headers["Access-Control-Allow-Origin"] = origin;
+  if (cors.credentials) headers["Access-Control-Allow-Credentials"] = "true";
+  return headers;
+}
+function corsPreflightHeaders(cors, requestOrigin, logger) {
+  const headers = baseHeaders(cors, requestOrigin, logger);
+  if (headers["Access-Control-Allow-Origin"] === void 0) return headers;
+  headers["Access-Control-Allow-Methods"] = cors.methods;
+  headers["Access-Control-Allow-Headers"] = cors.allowedHeaders;
+  if (cors.maxAge !== null) headers["Access-Control-Max-Age"] = String(cors.maxAge);
+  return headers;
+}
+function corsResponseHeaders(cors, requestOrigin, logger) {
+  const headers = baseHeaders(cors, requestOrigin, logger);
+  if (headers["Access-Control-Allow-Origin"] === void 0) return headers;
+  headers["Access-Control-Expose-Headers"] = cors.exposedHeaders;
+  return headers;
+}
+
+// src/shared/terminal.ts
+import chalk from "chalk";
+var theme = {
+  primary: chalk.bold.cyan,
+  success: chalk.green,
+  warning: chalk.yellow,
+  error: chalk.red,
+  muted: chalk.dim.gray,
+  value: chalk.white,
+  label: chalk.bold,
+  url: chalk.cyan.underline,
+  code: chalk.dim.white
+};
+var isUnicode = process.env["TERM"] !== "dumb" && !process.env["CI"];
+var symbols = {
+  success: isUnicode ? "\u2713" : "\u221A",
+  failure: isUnicode ? "\u2717" : "x",
+  info: isUnicode ? "\u25C6" : "*",
+  pointer: isUnicode ? "\u2192" : ">",
+  warning: isUnicode ? "\u26A0" : "!",
+  pending: isUnicode ? "\u25CB" : "-",
+  active: isUnicode ? "\u25CF" : "*",
+  ellipsis: isUnicode ? "\u2026" : "...",
+  reload: isUnicode ? "\u21BA" : "~",
+  separator: isUnicode ? "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500" : "----------------------------------"
+};
+
+// src/server/logger.ts
+var FRAMEWORK_LOG_LEVELS = ["debug", "info", "warn", "error", "silent"];
+var LEVEL_ORDER = { debug: 10, info: 20, warn: 30, error: 40, silent: 50 };
+function isFrameworkLogLevel(value) {
+  return typeof value === "string" && FRAMEWORK_LOG_LEVELS.includes(value);
+}
+function envLogLevel() {
+  const raw = process.env["FASTMCP_LOG_LEVEL"];
+  if (raw === void 0 || raw.trim() === "") return void 0;
+  const normalized = raw.trim().toLowerCase();
+  if (!isFrameworkLogLevel(normalized)) {
+    throw new Error(
+      `[fastmcp] FASTMCP_LOG_LEVEL must be one of debug/info/warn/error/silent (case-insensitive). Received: ${JSON.stringify(raw)}`
+    );
+  }
+  return normalized;
+}
+function formatMetaValue(value) {
+  if (value instanceof Error) return value.stack ?? String(value);
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function jsonMeta(meta) {
+  const plain = Object.fromEntries(Object.entries(meta).map(([k, v]) => [k, v instanceof Error ? String(v) : v]));
+  try {
+    return JSON.stringify(plain);
+  } catch {
+    return String(plain);
+  }
+}
+var DefaultSink = class {
+  mode;
+  constructor(mode) {
+    this.mode = mode ?? (process.stderr.isTTY === true && process.env["NO_COLOR"] === void 0 ? "pretty" : "plain");
+  }
+  write(line) {
+    process.stderr.write(`${line}
+`);
+  }
+  plainLine(level, message, meta) {
+    const metaStr = meta && Object.keys(meta).length > 0 ? ` ${jsonMeta(meta)}` : "";
+    return `[fastmcp] ${level.toUpperCase()} ${message}${metaStr}`;
+  }
+  prettyMeta(meta) {
+    if (!meta || Object.keys(meta).length === 0) return "";
+    const pairs = Object.entries(meta).map(([k, v]) => `${k}=${formatMetaValue(v)}`).join(" ");
+    return ` ${theme.muted(pairs)}`;
+  }
+  emit(level, message, meta) {
+    if (this.mode === "plain") {
+      this.write(this.plainLine(level, message, meta));
+      return;
+    }
+    switch (level) {
+      case "debug":
+        this.write(theme.muted(`\xB7 ${message}`) + this.prettyMeta(meta));
+        break;
+      case "info":
+        this.write(`${theme.muted(symbols.info)} ${message}${this.prettyMeta(meta)}`);
+        break;
+      case "warn":
+        this.write(`${theme.warning(symbols.warning)} ${theme.warning(message)}${this.prettyMeta(meta)}`);
+        break;
+      case "error":
+        this.write(`${theme.error(symbols.failure)} ${theme.error(message)}${this.prettyMeta(meta)}`);
+        break;
+    }
+  }
+  debug(message, meta) {
+    this.emit("debug", message, meta);
+  }
+  info(message, meta) {
+    this.emit("info", message, meta);
+  }
+  warn(message, meta) {
+    this.emit("warn", message, meta);
+  }
+  error(message, meta) {
+    this.emit("error", message, meta);
+  }
+  /** Startup card (pretty) or single plain info line. Mirrors the CLI's
+   * output.kv/section look (src/cli/ui/output.ts). */
+  banner(fields) {
+    if (this.mode === "plain") {
+      this.info(`starting ${fields.name} v${fields.version} (${fields.transport})`, fields.url !== void 0 ? { url: fields.url } : void 0);
+      return;
+    }
+    const kv = (key, value) => `  ${theme.label(key.padEnd(12))} ${theme.value(value)}`;
+    const rows = [
+      "",
+      `  ${theme.primary("FastMCP")}  ${theme.value(fields.name)} ${theme.muted(`v${fields.version}`)}`,
+      `  ${theme.muted(symbols.separator)}`,
+      kv("transport", fields.transport),
+      ...fields.url !== void 0 ? [kv("url", fields.url)] : [],
+      ""
+    ];
+    this.write(rows.join("\n"));
+  }
+  listening(url) {
+    if (this.mode === "plain") {
+      this.info(`listening on ${url}`);
+      return;
+    }
+    this.write(`${theme.success(symbols.success)} listening on ${theme.url(url)}`);
+  }
+};
+var ResolvedLogger = class {
+  constructor(sink, level) {
+    this.sink = sink;
+    this.level = level;
+  }
+  sink;
+  level;
+  enabled(level) {
+    return LEVEL_ORDER[level] >= LEVEL_ORDER[this.level];
+  }
+  // meta stays an omitted argument (not `undefined` passed explicitly) when the
+  // caller left it out: a sink like `console` prints a literal "undefined" for a
+  // second argument that is present but empty, and console.info/console.debug
+  // write to stdout, so a stray argument there is a stdio protocol-safety bug too.
+  debug(message, meta) {
+    if (!this.enabled("debug")) return;
+    if (meta === void 0) this.sink.debug(message);
+    else this.sink.debug(message, meta);
+  }
+  info(message, meta) {
+    if (!this.enabled("info")) return;
+    if (meta === void 0) this.sink.info(message);
+    else this.sink.info(message, meta);
+  }
+  warn(message, meta) {
+    if (!this.enabled("warn")) return;
+    if (meta === void 0) this.sink.warn(message);
+    else this.sink.warn(message, meta);
+  }
+  error(message, meta) {
+    if (!this.enabled("error")) return;
+    if (meta === void 0) this.sink.error(message);
+    else this.sink.error(message, meta);
+  }
+  /** Server-start card. Pretty DefaultSink renders a banner block;
+   * every other sink gets one plain info line. Gated as info. */
+  startupBanner(fields) {
+    if (!this.enabled("info")) return;
+    if (this.sink instanceof DefaultSink) {
+      this.sink.banner(fields);
+      return;
+    }
+    this.info(`starting ${fields.name} v${fields.version} (${fields.transport})`, fields.url !== void 0 ? { url: fields.url } : void 0);
+  }
+  /** Listening confirmation. The word "listening" is load-bearing: the CLI's
+   * run command detects a successful start by sniffing stderr for it. */
+  listening(url) {
+    if (!this.enabled("info")) return;
+    if (this.sink instanceof DefaultSink) {
+      this.sink.listening(url);
+      return;
+    }
+    this.info(`listening on ${url}`);
+  }
+};
+function resolveLogger(logger, logLevel) {
+  if (logLevel !== void 0 && !isFrameworkLogLevel(logLevel)) {
+    throw new Error(`Invalid logLevel: must be one of debug/info/warn/error/silent, got: ${JSON.stringify(logLevel)}`);
+  }
+  if (logger !== void 0) {
+    for (const method of ["debug", "info", "warn", "error"]) {
+      if (typeof logger[method] !== "function") {
+        throw new Error(`Invalid logger: must implement debug/info/warn/error methods; missing ${method}()`);
+      }
+    }
+  }
+  const level = logLevel ?? envLogLevel() ?? "info";
+  return new ResolvedLogger(logger ?? new DefaultSink(), level);
+}
+
 // src/server/FastMCP.ts
 function prefixResourceUri(uri, prefix) {
   const idx = uri.indexOf("://");
@@ -1013,7 +1439,7 @@ function toAccessToken(authInfo) {
   };
 }
 var _cliEnvToken;
-async function resolveCliEnvToken(verifier) {
+async function resolveCliEnvToken(verifier, logger) {
   if (!verifier || !("verify" in verifier)) return void 0;
   if (_cliEnvToken !== void 0) return _cliEnvToken ?? void 0;
   const raw = process.env["FASTMCP_CLI_AUTH_TOKEN"];
@@ -1024,7 +1450,8 @@ async function resolveCliEnvToken(verifier) {
   try {
     _cliEnvToken = await verifier.verify(raw);
     return _cliEnvToken;
-  } catch {
+  } catch (err) {
+    logger?.debug("FASTMCP_CLI_AUTH_TOKEN verification failed; continuing unauthenticated", { component: "auth", error: err });
     _cliEnvToken = null;
     return void 0;
   }
@@ -1044,6 +1471,9 @@ var FastMCP = class {
   name;
   version;
   _auth;
+  /** @internal Framework logger; used by same-package modules (proxy, openapi). Not public API. */
+  _logger;
+  _cors;
   _oauth;
   _sensitiveHeaders;
   _toolsPageSize;
@@ -1097,13 +1527,16 @@ var FastMCP = class {
   constructor(options) {
     this.name = options.name;
     this.version = options.version ?? "0.0.1";
+    this._logger = resolveLogger(options.logger, options.logLevel);
     this._auth = options.auth;
+    this._cors = resolveCors(options.http?.cors);
     this._oauth = options.oauth;
     this._sensitiveHeaders = resolveSensitiveHeaders(options.http);
     this._toolsPageSize = options.toolsPageSize ?? 50;
     this._resourcesPageSize = options.resourcesPageSize ?? 50;
     this._promptsPageSize = options.promptsPageSize ?? 50;
     this._middleware = options.middleware ? [...options.middleware] : [];
+    for (const mw of this._middleware) if (mw instanceof LoggingMiddleware) mw._bindLogger(this._logger);
     this._transforms = options.transforms ? [...options.transforms] : [];
     this._cacheHints = options.cacheHints;
     this._requestStateCodec = options.requestState ? createRequestStateCodec(options.requestState) : void 0;
@@ -1167,12 +1600,12 @@ var FastMCP = class {
     return server;
   }
   async _resolveToken(authInfo) {
-    return toAccessToken(authInfo) ?? await resolveCliEnvToken(this._auth);
+    return toAccessToken(authInfo) ?? await resolveCliEnvToken(this._auth, this._logger);
   }
   _setupHandlers(server, sessionState, opts) {
     server.setRequestHandler("tools/list", async (req, sdkCtx) => {
       const token = await this._resolveToken(sdkCtx.http?.authInfo);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders, this._logger);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "tools/list", req.params, ctx, async () => {
@@ -1223,8 +1656,8 @@ var FastMCP = class {
                 };
               }
               const t = entry.config;
-              const inputSchema = t.inputSchema ?? (t.input ? await toJsonSchema(t.input, `tool "${t.name}" input`) : { type: "object" });
-              const outputSchema = t.outputSchema ?? (t.output ? await toJsonSchema(t.output, `tool "${t.name}" output`) : void 0);
+              const inputSchema = t.inputSchema ?? (t.input ? await toJsonSchema(t.input, `tool "${t.name}" input`, this._logger) : { type: "object" });
+              const outputSchema = t.outputSchema ?? (t.output ? await toJsonSchema(t.output, `tool "${t.name}" output`, this._logger) : void 0);
               const uiMeta = clientIsUiCapable && t.ui ? {
                 resourceUri: t.ui.resourceUri ?? `ui://${t.name}`,
                 ...t.ui.visibility ? { visibility: t.ui.visibility } : {}
@@ -1252,7 +1685,7 @@ var FastMCP = class {
       const synthTool = synthesizedList.find((s) => s.name === requestedName);
       if (synthTool) {
         if (synthTool.auth) await runAuthCheck(synthTool.auth, token);
-        const ctx2 = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders);
+        const ctx2 = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders, this._logger);
         try {
           return await contextStore.run(
             ctx2,
@@ -1273,7 +1706,7 @@ var FastMCP = class {
                   () => clearTimeout(timer)
                 );
               }
-              return convertResult(await executePromise, opts?.stateless);
+              return convertResult(await executePromise, opts?.stateless, this._logger);
             })
           );
         } catch (err) {
@@ -1305,7 +1738,7 @@ var FastMCP = class {
       if (tool.config.auth) await runAuthCheck(tool.config.auth, token);
       const resolvedTool = tool;
       const rawArgs = req.params.arguments ?? {};
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders, this._logger);
       try {
         return await contextStore.run(
           ctx,
@@ -1327,7 +1760,7 @@ var FastMCP = class {
             }
             let resultValue = await executePromise;
             if (resolvedTool.config.output) resultValue = await validateInput(resolvedTool.config.output, resultValue);
-            const callResult = convertResult(resultValue, opts?.stateless);
+            const callResult = convertResult(resultValue, opts?.stateless, this._logger);
             if (resolvedTool.config.ui) {
               const clientIsUi = isUiCapable(server.getClientCapabilities());
               if (!clientIsUi && callResult.structuredContent !== void 0) {
@@ -1347,7 +1780,7 @@ var FastMCP = class {
     });
     server.setRequestHandler("resources/list", async (req, sdkCtx) => {
       const token = await this._resolveToken(sdkCtx.http?.authInfo);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders, this._logger);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "resources/list", req.params, ctx, async () => {
@@ -1394,7 +1827,7 @@ var FastMCP = class {
     });
     server.setRequestHandler("resources/templates/list", async (req, sdkCtx) => {
       const token = await this._resolveToken(sdkCtx.http?.authInfo);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders, this._logger);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "resources/templates/list", req.params, ctx, async () => {
@@ -1446,7 +1879,7 @@ var FastMCP = class {
       const resource = resolved.resource;
       const templateParams = resolved.templateParams;
       if (resource.config.auth) await runAuthCheck(resource.config.auth, token);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders, this._logger);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "resources/read", req.params, ctx, async () => {
@@ -1480,7 +1913,7 @@ var FastMCP = class {
       }
       const resource = resolved.resource;
       if (resource.config.auth) await runAuthCheck(resource.config.auth, token);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders, this._logger);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "resources/subscribe", req.params, ctx, async () => {
@@ -1498,7 +1931,7 @@ var FastMCP = class {
       if (opts?.stateless) throw new ProtocolError3(ProtocolErrorCode3.MethodNotFound, STATELESS_SUBSCRIBE_ERROR);
       const uri = req.params.uri;
       const token = await this._resolveToken(sdkCtx.http?.authInfo);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders, this._logger);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "resources/unsubscribe", req.params, ctx, async () => {
@@ -1510,7 +1943,7 @@ var FastMCP = class {
     });
     server.setRequestHandler("prompts/list", async (req, sdkCtx) => {
       const token = await this._resolveToken(sdkCtx.http?.authInfo);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders, this._logger);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "prompts/list", req.params, ctx, async () => {
@@ -1590,7 +2023,7 @@ var FastMCP = class {
           );
         }
       }
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders, this._logger);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "prompts/get", req.params, ctx, async () => {
@@ -1614,7 +2047,7 @@ var FastMCP = class {
     });
     server.setRequestHandler("completion/complete", async (req, sdkCtx) => {
       const token = await this._resolveToken(sdkCtx.http?.authInfo);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless, this._sensitiveHeaders, this._logger);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "completion/complete", req.params, ctx, async () => {
@@ -1928,7 +2361,7 @@ var FastMCP = class {
           }
           let resultValue = await executePromise;
           if (tool.config.output) resultValue = await validateInput(tool.config.output, resultValue);
-          return convertResult(resultValue);
+          return convertResult(resultValue, void 0, this._logger);
         })
       );
     } catch (err) {
@@ -2205,6 +2638,7 @@ var FastMCP = class {
    */
   use(mw) {
     this._middleware.push(mw);
+    if (mw instanceof LoggingMiddleware) mw._bindLogger(this._logger);
     mw.setup?.(this._primaryServer);
     return this;
   }
@@ -2280,6 +2714,7 @@ var FastMCP = class {
     this._stateless = options?.stateless ?? envBool("FASTMCP_STATELESS_HTTP") ?? false;
     const resolvedHealth = resolveHealth(options?.health);
     if (transport === "stdio") {
+      this._logger.startupBanner({ name: this.name, version: this.version, transport: "stdio" });
       const { StdioServerTransport, serveStdio } = await import("@modelcontextprotocol/server/stdio");
       const stdioTransport = new StdioServerTransport(options?.stdin, options?.stdout);
       this._stdioHandle = serveStdio(
@@ -2345,7 +2780,7 @@ var FastMCP = class {
     if (!this._statelessLegacyHandler) {
       this._statelessLegacyHandler = legacyStatelessFallback(
         () => this._makeServer(/* @__PURE__ */ new Map(), { stateless: true }),
-        (error) => console.error("[fastmcp] stateless legacy serving failed:", error)
+        (error) => this._logger.error("stateless legacy serving failed", { component: "http", error })
       );
     }
     return this._statelessLegacyHandler;
@@ -2404,6 +2839,7 @@ var FastMCP = class {
         retryInterval: LEGACY_SSE_RETRY_MS,
         onsessioninitialized: (id) => {
           this._sessions.set(id, { transport: mcpTransport, server: sessionServer, state: sessionState });
+          this._logger.debug("session opened", { component: "http", sessionId: id });
         },
         onsessionclosed: (id) => {
           const session = this._sessions.get(id);
@@ -2412,6 +2848,7 @@ var FastMCP = class {
             for (const cb of callbacks) cb();
           }
           this._sessions.delete(id);
+          this._logger.debug("session closed", { component: "http", sessionId: id });
         }
       });
       await sessionServer.connect(mcpTransport);
@@ -2427,8 +2864,9 @@ var FastMCP = class {
     const opt = this._dnsRebindingOptions;
     if (opt === void 0 && !isLoopbackHost(host) && !_dnsRebindingWarned) {
       _dnsRebindingWarned = true;
-      console.warn(
-        "[fastmcp] This HTTP server accepts requests from any Host or Origin. Set dnsRebinding in FastMCPOptions to protect local deployments against DNS rebinding."
+      this._logger.warn(
+        "This HTTP server accepts requests from any Host or Origin. Set dnsRebinding in FastMCPOptions to protect local deployments against DNS rebinding.",
+        { component: "http" }
       );
     }
     const hasExplicitAllowlist = opt?.allowedHosts !== void 0 || opt?.allowedOrigins !== void 0;
@@ -2448,11 +2886,24 @@ var FastMCP = class {
     const { requireBearerAuth } = await import("@modelcontextprotocol/server-legacy/auth");
     const oauth = this._oauth;
     const app = express();
+    if (this._cors) {
+      const cors = this._cors;
+      app.use((req, res, next) => {
+        if (req.method === "OPTIONS") {
+          res.writeHead(204, corsPreflightHeaders(cors, req.headers.origin, this._logger)).end();
+          return;
+        }
+        if (req.path === path) {
+          for (const [k, v] of Object.entries(corsResponseHeaders(cors, req.headers.origin, this._logger))) res.setHeader(k, v);
+        }
+        next();
+      });
+    }
     app.use((req, res, next) => {
       const match = this._customRoutes.match(req.path, req.method ?? "");
       if (!match) return next();
       if (match.kind === "method-mismatch") return writeMethodNotAllowed(res, match.allow);
-      void serveCustomRouteNode(match.handler, req, res);
+      void serveCustomRouteNode(match.handler, req, res, this._logger);
     });
     const httpServer = await new Promise((resolve, reject) => {
       const srv = app.listen(port, host, () => resolve(srv));
@@ -2476,39 +2927,34 @@ var FastMCP = class {
     );
     this._httpServer = httpServer;
     this._address = { host: bound.address, port: bound.port, path };
+    const url = `http://${bound.address}:${bound.port}${path}`;
+    this._logger.startupBanner({ name: this.name, version: this.version, transport: "http", url });
+    this._logger.listening(url);
   }
   async _runHttpSimple(port, host, path) {
     this._resolveDnsRebindingGuards(host);
     const { createServer } = await import("http");
     const auth = this._auth;
-    const corsHeaders = {
-      "Access-Control-Allow-Origin": "*",
-      "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
-      // Mcp-Session-Id: legacy (2025-era) session routing, still served alongside
-      // modern traffic. MCP-Protocol-Version/Mcp-Method/Mcp-Name: required standard
-      // headers for 2026-07-28 requests (SEP-2243). Mcp-Param-* (tool-argument
-      // mirroring) is deliberately not listed: browser clients skip that mirroring
-      // entirely (dynamically named headers cannot be statically allow-listed for
-      // credentialed CORS), so no browser ever needs to send it.
-      "Access-Control-Allow-Headers": "Content-Type, Authorization, Mcp-Session-Id, MCP-Protocol-Version, Mcp-Method, Mcp-Name"
-    };
+    const cors = this._cors;
     const httpServer = createServer(async (req, res) => {
-      if (req.method === "OPTIONS") {
-        res.writeHead(204, corsHeaders).end();
+      if (req.method === "OPTIONS" && cors) {
+        res.writeHead(204, corsPreflightHeaders(cors, req.headers.origin, this._logger)).end();
         return;
       }
       const pathname = req.url?.split("?")[0] ?? "";
       const routeMatch = this._customRoutes.match(pathname, req.method ?? "");
       if (routeMatch) {
         if (routeMatch.kind === "method-mismatch") writeMethodNotAllowed(res, routeMatch.allow);
-        else await serveCustomRouteNode(routeMatch.handler, req, res);
+        else await serveCustomRouteNode(routeMatch.handler, req, res, this._logger);
         return;
       }
       if (pathname !== path) {
         res.writeHead(404).end();
         return;
       }
-      for (const [k, v] of Object.entries(corsHeaders)) res.setHeader(k, v);
+      if (cors) {
+        for (const [k, v] of Object.entries(corsResponseHeaders(cors, req.headers.origin, this._logger))) res.setHeader(k, v);
+      }
       if (auth) {
         if (isRequestVerifier(auth)) {
           let accessToken;
@@ -2523,8 +2969,9 @@ var FastMCP = class {
             return;
           }
           if (!accessToken.token) {
-            console.error(
-              "[fastmcp] RequestVerifier.verifyRequest must set AccessToken.token to a stable, non-empty per-identity value. It keys response-cache partitioning and downstream identity."
+            this._logger.error(
+              "RequestVerifier.verifyRequest must set AccessToken.token to a stable, non-empty per-identity value. It keys response-cache partitioning and downstream identity.",
+              { component: "auth" }
             );
             res.writeHead(500, { "Content-Type": "application/json" }).end(JSON.stringify({ error: "verifyRequest returned an AccessToken with an empty token" }));
             return;
@@ -2572,6 +3019,9 @@ var FastMCP = class {
     });
     const bound = httpServer.address();
     this._address = { host: bound.address, port: bound.port, path };
+    const url = `http://${bound.address}:${bound.port}${path}`;
+    this._logger.startupBanner({ name: this.name, version: this.version, transport: "http", url });
+    this._logger.listening(url);
   }
   async close() {
     await Promise.all(this._proxyCloseCallbacks.map((cb) => cb().catch(() => {
@@ -2916,12 +3366,26 @@ function oauthProxy(options) {
 // src/server/proxy.ts
 import { Client } from "@modelcontextprotocol/client";
 import { parseTemplate } from "url-template";
+function logProbeFailure(logger, what, err) {
+  const code = err?.code;
+  if (code === -32601) {
+    logger.debug(`proxied server does not support ${what}`, { component: "proxy" });
+  } else {
+    logger.warn(`proxied server ${what} probe failed; serving none`, { component: "proxy", error: err });
+  }
+}
 async function buildProxyFromClient(client, options) {
   const cacheTtl = options?.cacheTtl ?? 3e4;
   const serverInfo = client.getServerVersion();
   const proxyName = options?.name ?? serverInfo?.name ?? "proxy";
   const proxyVersion = serverInfo?.version ?? "0.0.1";
-  const proxy = new FastMCP({ name: proxyName, version: proxyVersion });
+  const proxy = new FastMCP({
+    name: proxyName,
+    version: proxyVersion,
+    ...options?.logger !== void 0 ? { logger: options.logger } : {},
+    ...options?.logLevel !== void 0 ? { logLevel: options.logLevel } : {}
+  });
+  const logger = proxy._logger;
   const proxiedTools = /* @__PURE__ */ new Set();
   const proxiedResources = /* @__PURE__ */ new Set();
   const proxiedPrompts = /* @__PURE__ */ new Set();
@@ -2982,7 +3446,8 @@ async function buildProxyFromClient(client, options) {
           proxiedResources.add(resource.uri);
         }
       }
-    } catch {
+    } catch (err) {
+      logProbeFailure(logger, "resources", err);
     }
     try {
       const { resourceTemplates } = await client.listResourceTemplates();
@@ -3009,7 +3474,8 @@ async function buildProxyFromClient(client, options) {
           proxiedResources.add(uriTemplate);
         }
       }
-    } catch {
+    } catch (err) {
+      logProbeFailure(logger, "resource templates", err);
     }
     for (const uri of proxiedResources) {
       if (!incoming.has(uri)) {
@@ -3116,7 +3582,12 @@ async function createProxy(config, name) {
     { capabilities: {} }
   );
   await client.connect(transport);
-  return buildProxyFromClient(client, { cacheTtl: config.cacheTtl, name });
+  return buildProxyFromClient(client, {
+    cacheTtl: config.cacheTtl,
+    name,
+    logger: config.logger,
+    logLevel: config.logLevel
+  });
 }
 
 // src/server/openapi/internal.ts
@@ -3143,8 +3614,9 @@ function deepEqual(a, b) {
   }
   return false;
 }
-function warn(message) {
-  console.warn(`[fastmcp] ${message}`);
+function warn(message, logger) {
+  if (logger) logger.warn(message, { component: "openapi" });
+  else console.warn(`[fastmcp] ${message}`);
 }
 
 // src/server/openapi/parser.ts
@@ -4088,7 +4560,7 @@ var STYLE_DELIMITERS = {
   spaceDelimited: " ",
   pipeDelimited: "|"
 };
-function unflattenArguments(route, flatArgs) {
+function unflattenArguments(route, flatArgs, logger) {
   const pathParams = {};
   const queryParams = {};
   const headerParams = {};
@@ -4106,7 +4578,7 @@ function unflattenArguments(route, flatArgs) {
       if (value === null || value === void 0) continue;
       const mapping = route.parameterMap[argName];
       if (mapping === void 0) {
-        warn(`Argument '${argName}' not found in parameter map for ${route.operationId ?? route.path}`);
+        warn(`Argument '${argName}' not found in parameter map for ${route.operationId ?? route.path}`, logger);
         continue;
       }
       buckets[mapping.location][mapping.openapiName] = value;
@@ -4203,10 +4675,11 @@ function buildUrl(pathTemplate, pathParams, baseUrl) {
   const base = `${baseUrl.replace(/\/+$/, "")}/`;
   return new URL(urlPath.replace(/^\/+/, ""), base).toString();
 }
-function buildRequest(route, flatArgs, baseUrl) {
+function buildRequest(route, flatArgs, baseUrl, logger) {
   const { pathParams, queryParams, headerParams, cookieParams, body } = unflattenArguments(
     route,
-    flatArgs
+    flatArgs,
+    logger
   );
   const serializedQuery = serializeQueryParams(route, queryParams);
   const url = new URL(buildUrl(route.path, pathParams, baseUrl));
@@ -4320,11 +4793,11 @@ function resolveClient(options, spec) {
 function isTimeoutError(error) {
   return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
 }
-async function sendRequest(client, route, args) {
+async function sendRequest(client, route, args, logger) {
   let url;
   let init;
   try {
-    const directed = buildRequest(route, args, client.baseUrl);
+    const directed = buildRequest(route, args, client.baseUrl, logger);
     const authHeaders = client.auth ? await client.auth.getHeaders() : {};
     const headers = {};
     for (const source of [client.headers, authHeaders, directed.headers]) {
@@ -4363,13 +4836,14 @@ async function sendRequest(client, route, args) {
   }
   return response;
 }
-async function runToolRequest(client, route, args, outputSchema) {
-  const response = await sendRequest(client, route, args);
+async function runToolRequest(client, route, args, outputSchema, logger) {
+  const response = await sendRequest(client, route, args, logger);
   const text = await response.text();
   let result;
   try {
     result = JSON.parse(text);
   } catch {
+    logger?.debug("openapi response was not JSON; returning raw text", { component: "openapi" });
     return new ToolResult({ content: [{ type: "text", text }] });
   }
   let structured;
@@ -4388,8 +4862,8 @@ async function runToolRequest(client, route, args, outputSchema) {
     structuredContent: structured
   });
 }
-async function readResourceRequest(client, route, args, uri, mimeType) {
-  const response = await sendRequest(client, route, args);
+async function readResourceRequest(client, route, args, uri, mimeType, logger) {
+  const response = await sendRequest(client, route, args, logger);
   const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
   if (contentType.includes("application/json")) {
     const result = JSON.parse(await response.text());
@@ -4484,7 +4958,8 @@ function createOpenAPIServer(options) {
         }
       } catch (error) {
         warn(
-          `Error in routeMapFn for ${route.method} ${route.path}: ${error.message}. Using mapped type.`
+          `Error in routeMapFn for ${route.method} ${route.path}: ${error.message}. Using mapped type.`,
+          server._logger
         );
       }
     }
@@ -4502,13 +4977,14 @@ function createOpenAPIServer(options) {
   }
   return server;
 }
-function applyComponentFn(componentFn, route, component) {
+function applyComponentFn(componentFn, route, component, logger) {
   if (componentFn === void 0) return;
   try {
     componentFn(route, component);
   } catch (error) {
     warn(
-      `Error in componentFn for ${component.kind} '${component.name}': ${error.message}`
+      `Error in componentFn for ${component.kind} '${component.name}': ${error.message}`,
+      logger
     );
   }
 }
@@ -4533,7 +5009,7 @@ function createTool(server, client, route, name, tags, registry, validateOutput,
     ...outputSchema !== null ? { outputSchema } : {},
     tags
   };
-  applyComponentFn(componentFn, route, component);
+  applyComponentFn(componentFn, route, component, server._logger);
   server.tool(
     {
       name: component.name,
@@ -4542,7 +5018,7 @@ function createTool(server, client, route, name, tags, registry, validateOutput,
       ...component.outputSchema !== void 0 ? { outputSchema: component.outputSchema } : {},
       tags: component.tags
     },
-    async (args) => runToolRequest(client, route, isPlainObject(args) ? args : {}, component.outputSchema)
+    async (args) => runToolRequest(client, route, isPlainObject(args) ? args : {}, component.outputSchema, server._logger)
   );
 }
 function createResource(server, client, route, name, tags, registry, componentFn) {
@@ -4555,7 +5031,7 @@ function createResource(server, client, route, name, tags, registry, componentFn
     mimeType: extractMimeTypeFromRoute(route),
     tags
   };
-  applyComponentFn(componentFn, route, component);
+  applyComponentFn(componentFn, route, component, server._logger);
   server.resource(
     {
       uri: component.uri,
@@ -4564,7 +5040,7 @@ function createResource(server, client, route, name, tags, registry, componentFn
       mimeType: component.mimeType,
       tags: component.tags
     },
-    async () => readResourceRequest(client, route, {}, component.uri, component.mimeType)
+    async () => readResourceRequest(client, route, {}, component.uri, component.mimeType, server._logger)
   );
 }
 function createTemplate(server, client, route, name, tags, registry, componentFn) {
@@ -4596,7 +5072,7 @@ function createTemplate(server, client, route, name, tags, registry, componentFn
     parameters: parametersSchema,
     tags
   };
-  applyComponentFn(componentFn, route, component);
+  applyComponentFn(componentFn, route, component, server._logger);
   server.resource(
     {
       uri: component.uriTemplate,
@@ -4613,7 +5089,8 @@ function createTemplate(server, client, route, name, tags, registry, componentFn
         route,
         templateArguments(route, matched),
         concreteUri,
-        component.mimeType
+        component.mimeType,
+        server._logger
       );
     }
   );
@@ -5081,7 +5558,7 @@ var FormInput = class {
     this.server.tool(
       { name, description, ui: { visibility: ["model", "app"] } },
       async () => {
-        const jsonSchema = await toJsonSchema(schema, `form "${name}"`);
+        const jsonSchema = await toJsonSchema(schema, `form "${name}"`, this.server._logger);
         const properties = jsonSchema.properties ?? {};
         const required = jsonSchema.required ?? [];
         const fields = Object.entries(properties).map(