machine-bridge-mcp 0.2.1 → 0.2.4

package/README.md

@@ -28,8 +28,8 @@ Source checkout:
 3. Generates a stable MCP connection password and daemon secret.
 4. Checks `wrangler whoami`; if needed, opens `wrangler login`.
 5. Deploys the hosted Worker relay with `wrangler deploy --secrets-file`.
-6. Installs login autostart for the local daemon and default local API provider.
-7. Starts the local daemon and local OpenAI-compatible API provider.
+6. Installs login autostart for the local daemon and default local API.
+7. Starts the local daemon and local OpenAI-compatible API.
 8. Prints MCP connection details on first run, plus local API settings:
 
 ```text
@@ -47,45 +47,48 @@ The command is safe to run repeatedly:
 npm install -g machine-bridge-mcp@latest && machine-mcp
 ```
 
-On repeat runs, the CLI reuses existing state and secrets unless you request rotation, skips Worker redeploys when the deployed Worker is healthy and Worker source/config/secrets are unchanged, refreshes the autostart entry, stops any currently loaded autostart daemon before starting the foreground daemon, and refuses to start a second daemon for the same workspace if another foreground instance is already running. Local-only package, CLI, logging, and API-provider changes do not by themselves force a Worker redeploy.
+On repeat runs, the CLI reuses existing state and secrets unless you request rotation, skips Worker redeploys when the deployed Worker is healthy and Worker source/config/secrets are unchanged, refreshes the autostart entry, stops any currently loaded autostart daemon before starting the foreground daemon, and refuses to start a second daemon for the same workspace if another foreground instance is already running. Local-only package, CLI, logging, and local API changes do not by themselves force a Worker redeploy.
 
 MCP connection details are printed on first run, after secret rotation, when the MCP URL changes, or when you explicitly pass `--print-mcp-credentials`. Routine runs print that MCP details are unchanged.
 
-## Local OpenAI-compatible API provider
+## Local OpenAI-compatible API
 
-`machine-bridge-mcp` exposes a local OpenAI-compatible API provider by default for desktop AI clients such as Cherry Studio, Chatbox, Continue, or other apps that accept an OpenAI-style base URL and API key. No extra command is needed; the recommended `machine-mcp` command starts both the Remote MCP daemon and the local API provider.
+The project exposes two connected integration surfaces:
 
-Start the normal daemon and API provider:
+- **ChatGPT web / ChatGPT apps:** use the Remote MCP Server URL and MCP connection password printed by `machine-mcp`. In this mode, ChatGPT calls tools on your machine through the Worker + local daemon bridge.
+- **Desktop clients such as Cherry Studio, Chatbox, or Continue:** use the optional local OpenAI-compatible `/v1` API. `POST /v1/chat/completions` is backed by MCP sampling: the local API asks the hosted Worker to send `sampling/createMessage` to the already-connected ChatGPT MCP client, then wraps the MCP sampling result as an OpenAI-compatible chat completion response.
+
+No separate model API setup is required or used in this path; the local API never asks for a model base URL or model API key. Generation depends on the ChatGPT-side MCP client actually being connected and able to receive server-to-client sampling requests. If ChatGPT is not connected, has no open MCP stream for server-to-client messages, or did not advertise the MCP `sampling` capability, generation returns an explicit OpenAI-shaped error saying that the missing piece is the MCP client stream or sampling capability.
+
+Start the normal daemon and local API:
 
 ```zsh
 machine-mcp
 ```
 
-Start only the local API service, without the Remote MCP daemon:
+Start only the local API from remembered state:
 
 ```zsh
 machine-mcp api
 ```
 
-Disable the default local API provider for a daemon run:
+Disable the default local API for a daemon run:
 
 ```zsh
 machine-mcp --no-api
 ```
 
-The CLI prints client settings like:
+When the API is running, the CLI prints client settings like:
 
 ```text
 API Base URL: http://127.0.0.1:8765/v1
 API key: local_api_key_...
 Client type: OpenAI-compatible
+Model: chatgpt-mcp
+Backend: ChatGPT MCP sampling via the connected ChatGPT app
 ```
 
-Use these values in the local AI client:
-
-- Base URL: `http://127.0.0.1:8765/v1`
-- API key: the `local_api_key_...` printed by the CLI
-- Model: the model shown by `GET /v1/models` or your configured `--api-model`
+Use the API Base URL, API key, and model in your desktop client. Separately, connect ChatGPT to the printed MCP Server URL/password so the Worker has an MCP client stream that can receive `sampling/createMessage`.
 
 If port `8765` conflicts with another local app, choose a different port explicitly:
 
@@ -100,34 +103,23 @@ machine-mcp api --api-port 8766
 machine-mcp api --port 8766
 ```
 
-By default, the local API binds to `127.0.0.1`, starts with `machine-mcp`, and stores a per-workspace local API key in the same owner-only state profile used by the MCP credentials. Explicit `--api-host`, `--api-port`, `--api-model`, and `--api-upstream-url` values are persisted for the workspace so autostart uses the same non-secret API settings; upstream API keys are not written to state. Rotate the local API key with:
+By default, the local API binds to `127.0.0.1`, starts with `machine-mcp`, and stores a per-workspace local API key in the same owner-only state profile used by the MCP credentials. Explicit `--api-host`, `--api-port`, and `--api-model` values are persisted for the workspace so autostart uses the same API settings. `--api-model` only controls the local model id advertised by `GET /v1/models`; the actual model is chosen by the connected MCP client, and any different `model` value in a chat-completions request is passed as an MCP model preference hint.
 
-```zsh
-machine-mcp api --rotate-api-key
-```
-
-Configure an upstream OpenAI-compatible provider:
+Rotate the local desktop-client API key with:
 
 ```zsh
-machine-mcp api \
-  --api-upstream-url https://api.openai.com/v1 \
-  --api-upstream-key "$OPENAI_API_KEY" \
-  --api-model gpt-4.1
+machine-mcp api --rotate-api-key
 ```
 
-Environment variables are also supported: `MBM_API_HOST`, `MBM_API_PORT`, `MBM_API_KEY`, `MBM_API_UPSTREAM_URL`, `MBM_API_UPSTREAM_KEY`, `MBM_API_MODEL`, plus common OpenAI names such as `OPENAI_API_KEY`, `OPENAI_BASE_URL`, and `OPENAI_MODEL`.
+Environment variables supported for the current process: `MBM_API_HOST`, `MBM_API_PORT`, `MBM_API_KEY`, and `MBM_API_MODEL`. Environment overrides are not persisted to state; use `--api-host`, `--api-port`, `--api-key`, or `--api-model` when you want a setting saved for future runs and autostart.
 
 Supported local API routes:
 
 - `GET /health` without authentication
 - `GET /v1/models` with `Authorization: Bearer <local_api_key>` or `x-api-key`
 - `POST /v1/chat/completions`
-- `POST /v1/responses`
-- `POST /v1/embeddings`
-- `POST /v1/completions`
-
-Model-producing routes proxy to the configured upstream provider. If no upstream key is configured, the API still starts and `/v1/models` works, but generation endpoints return a clear `503 upstream_not_configured` error. Logs record route, status, latency, and safe configuration metadata; request and response bodies and API keys are not logged.
 
+`POST /v1/responses`, `POST /v1/completions`, and `POST /v1/embeddings` return `501 unsupported_endpoint`; MCP sampling is a chat-message path and does not expose embeddings or the full Responses API. Logs record route, status, latency, and safe configuration metadata; request and response bodies and API keys are not logged.
 
 ## Re-select workspace
 
@@ -262,13 +254,15 @@ machine-mcp --state-dir /path/to/state
 
 ```mermaid
 flowchart LR
-  C["Remote MCP client"] -- "HTTPS /mcp + OAuth" --> W["Hosted Worker relay"]
+  C["ChatGPT / MCP client"] -- "HTTPS /mcp + OAuth" --> W["Hosted Worker relay"]
+  C -- "GET SSE stream for server-to-client MCP" --> W
   W --> DO["Durable Object broker"]
   D["Local daemon"] -- "outbound WebSocket" --> W
   D --> M["Local filesystem and shell"]
-  API["Default local /v1 API"] -- "OpenAI-compatible HTTP" --> U["Configured upstream provider"]
+  API["Local /v1/chat/completions"] -- "POST /api/mcp/sampling" --> W
+  DO -- "sampling/createMessage" --> C
   CLI["machine-mcp CLI"] --> API
-  CLI["machine-mcp CLI"] --> W
+  CLI --> W
   CLI --> D
   CLI --> S["Autostart service"]
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "description": "One-command hosted Remote MCP bridge to a local machine daemon.",
   "type": "module",
   "license": "MIT",

package/src/local/api-server.mjs

@@ -1,36 +1,14 @@
 import http from "node:http";
 import { createHash, randomUUID } from "node:crypto";
-import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
 import { createLogger } from "./log.mjs";
 
 export const DEFAULT_API_HOST = "127.0.0.1";
 export const DEFAULT_API_PORT = 8765;
-export const DEFAULT_UPSTREAM_URL = "https://api.openai.com/v1";
-export const DEFAULT_API_MODEL = "machine-bridge-mcp";
+export const DEFAULT_API_MODEL = "chatgpt-mcp";
 export const DEFAULT_API_MAX_BODY_BYTES = 32 * 1024 * 1024;
+export const DEFAULT_SAMPLING_TIMEOUT_MS = 180_000;
 
-const PROXY_ROUTES = new Set([
-  "/v1/chat/completions",
-  "/v1/responses",
-  "/v1/embeddings",
-  "/v1/completions",
-]);
-
-const HOP_BY_HOP_HEADERS = new Set([
-  "connection",
-  "keep-alive",
-  "proxy-authenticate",
-  "proxy-authorization",
-  "te",
-  "trailer",
-  "transfer-encoding",
-  "upgrade",
-  "host",
-  "content-length",
-  "authorization",
-  "x-api-key",
-]);
+const CHAT_COMPLETIONS_PATH = "/v1/chat/completions";
 
 export function parseApiPort(value, fallback = DEFAULT_API_PORT) {
   if (value === undefined || value === null || value === true || value === "") return fallback;
@@ -43,38 +21,25 @@ export function normalizeApiHost(value, fallback = DEFAULT_API_HOST) {
   if (value === undefined || value === null || value === true || value === "") return fallback;
   const host = String(value).trim();
   if (!host) return fallback;
-  if (/[/\\\s]/.test(host)) throw new Error(`Invalid API host: ${value}`);
+  if (/[\\/\s]/.test(host)) throw new Error(`Invalid API host: ${value}`);
   return host;
 }
 
-export function normalizeBaseUrl(value, fallback = DEFAULT_UPSTREAM_URL) {
-  const raw = value === undefined || value === null || value === true || value === "" ? fallback : String(value).trim();
-  let parsed;
-  try {
-    parsed = new URL(raw);
-  } catch {
-    throw new Error("Invalid upstream API URL.");
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error(`Invalid upstream API URL protocol: ${parsed.protocol}`);
-  if (parsed.username || parsed.password) throw new Error("Upstream API URL must not contain credentials; pass keys with --api-upstream-key or environment variables.");
-  if (parsed.search || parsed.hash) throw new Error("Upstream API URL must be a base URL without query strings or fragments.");
-  return parsed.toString().replace(/\/+$/, "");
-}
-
 export async function startLocalApiServer(options = {}) {
   const logger = options.logger || createLogger({ component: "api", quiet: options.quiet });
   const host = normalizeApiHost(options.host);
   const port = parseApiPort(options.port);
   const apiKey = String(options.apiKey || "");
-  const upstreamUrl = normalizeBaseUrl(options.upstreamUrl);
-  const upstreamKey = String(options.upstreamKey || "");
   const model = String(options.model || DEFAULT_API_MODEL);
+  const workerUrl = String(options.workerUrl || "").replace(/\/+$/, "");
+  const daemonSecret = String(options.daemonSecret || "");
   const maxBodyBytes = Number(options.maxBodyBytes || DEFAULT_API_MAX_BODY_BYTES);
+  const samplingTimeoutMs = Number(options.samplingTimeoutMs || DEFAULT_SAMPLING_TIMEOUT_MS);
 
   if (!apiKey) throw new Error("Local API key is missing");
 
   const server = http.createServer((req, res) => {
-    void handleRequest(req, res, { logger, apiKey, upstreamUrl, upstreamKey, model, maxBodyBytes });
+    void handleRequest(req, res, { logger, apiKey, model, workerUrl, daemonSecret, maxBodyBytes, samplingTimeoutMs });
   });
 
   server.keepAliveTimeout = 65_000;
@@ -99,7 +64,7 @@ export async function startLocalApiServer(options = {}) {
   const actualPort = typeof address === "object" && address ? address.port : port;
   const urlHost = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
   const baseUrl = `http://${urlHost}:${actualPort}/v1`;
-  logger.success("local OpenAI-compatible API started", { baseUrl, model, upstream: upstreamUrl, upstreamConfigured: Boolean(upstreamKey) });
+  logger.success("local OpenAI-compatible API started", { baseUrl, model, backend: "chatgpt-mcp", mcpBridgeConfigured: Boolean(workerUrl && daemonSecret) });
 
   return {
     server,
@@ -107,6 +72,8 @@ export async function startLocalApiServer(options = {}) {
     port: actualPort,
     baseUrl,
     url: `http://${urlHost}:${actualPort}`,
+    apiKey,
+    model,
     close() {
       return new Promise(resolve => server.close(() => resolve()));
     },
@@ -121,66 +88,199 @@ async function handleRequest(req, res, context) {
 
   try {
     if (req.method === "OPTIONS") return sendEmpty(res, 204);
-    if (req.method === "GET" && url.pathname === "/health") return sendJson(res, 200, { ok: true, service: "machine-bridge-mcp-local-api", api_key_sha256: sha256String(context.apiKey) });
+    if (req.method === "GET" && url.pathname === "/health") {
+      return sendJson(res, 200, {
+        ok: true,
+        service: "machine-bridge-mcp-local-api",
+        backend: "chatgpt-mcp",
+        api_key_sha256: sha256String(context.apiKey),
+        mcp_bridge_configured: Boolean(context.workerUrl && context.daemonSecret),
+        model: context.model,
+      });
+    }
 
     if (!isAuthorized(req, context.apiKey)) return sendOpenAiError(res, 401, "invalid_api_key", "Missing or invalid local API key.");
 
     if (req.method === "GET" && url.pathname === "/v1/models") {
       context.logger.info("request completed", { requestId, method: req.method, path: url.pathname, status: 200, durationMs: Date.now() - started });
-      return sendJson(res, 200, modelsPayload(context.model));
+      return sendJson(res, 200, modelsPayload(context));
+    }
+
+    if (req.method === "POST" && ["/v1/responses", "/v1/completions", "/v1/embeddings"].includes(url.pathname)) {
+      return sendOpenAiError(res, 501, "unsupported_endpoint", "Only /v1/chat/completions is available through the ChatGPT MCP-backed local API. Embeddings, legacy completions, and Responses API are not exposed by MCP sampling.");
     }
 
-    if (req.method === "POST" && PROXY_ROUTES.has(url.pathname)) {
-      if (!context.upstreamKey) {
-        return sendOpenAiError(res, 503, "upstream_not_configured", "No upstream API key is configured. Set --api-upstream-key or MBM_API_UPSTREAM_KEY/OPENAI_API_KEY.");
+    if (req.method === "POST" && url.pathname === CHAT_COMPLETIONS_PATH) {
+      if (!context.workerUrl || !context.daemonSecret) {
+        return sendOpenAiError(res, 503, "mcp_bridge_not_configured", "Local API is not connected to a Remote MCP bridge yet. Run `machine-mcp` normally so the Worker URL and MCP daemon secret exist, then reconnect ChatGPT to the printed MCP Server URL.");
       }
-      context.logger.info("proxy request started", { requestId, path: url.pathname, upstream: context.upstreamUrl });
-      await proxyRequest(req, res, url, context);
-      context.logger.info("proxy request completed", { requestId, path: url.pathname, status: res.statusCode, durationMs: Date.now() - started });
+      const payload = await readJsonBody(req, context.maxBodyBytes);
+      const { params: samplingRequest, modelHint } = samplingRequestFromOpenAiChat(payload, context.model);
+      context.logger.info("MCP sampling request started", { requestId, path: url.pathname, modelHint: modelHint || null });
+      const result = await requestMcpSampling(context, samplingRequest);
+      const text = extractSamplingText(result);
+      const model = String(result?.model || modelHint || context.model);
+      const finishReason = finishReasonFromSampling(result);
+      if (payload.stream === true) sendChatCompletionStream(res, { text, model, finishReason });
+      else sendJson(res, 200, chatCompletionPayload({ text, model, finishReason }));
+      context.logger.info("MCP sampling request completed", { requestId, path: url.pathname, status: res.statusCode, durationMs: Date.now() - started });
       return;
     }
 
     return sendOpenAiError(res, 404, "not_found", `Unknown local API endpoint: ${url.pathname}`);
   } catch (error) {
-    context.logger.error("request failed", { requestId, path: url.pathname, error: error.message, durationMs: Date.now() - started });
+    context.logger.error("request failed", safeErrorLogFields(error, { requestId, path: url.pathname, durationMs: Date.now() - started }));
     if (!res.headersSent) {
       if (error?.code === "BODY_TOO_LARGE") return sendOpenAiError(res, 413, "request_too_large", error.message);
-      return sendOpenAiError(res, 502, "upstream_error", error.message || "Local API request failed.");
+      if (error instanceof ApiError) return sendOpenAiError(res, error.status, error.code, error.message);
+      return sendOpenAiError(res, 502, "mcp_sampling_error", error.message || "Local API request failed.");
     }
     res.destroy(error);
   }
 }
 
-async function proxyRequest(req, res, url, context) {
-  const body = await readBody(req, context.maxBodyBytes);
-  const upstreamTarget = `${context.upstreamUrl}${url.pathname.slice(3)}${url.search}`;
-  const headers = copyProxyHeaders(req.headers, context.upstreamKey);
-  const response = await fetch(upstreamTarget, {
-    method: "POST",
-    headers,
-    body,
-    signal: AbortSignal.timeout(10 * 60 * 1000),
-  });
+function samplingRequestFromOpenAiChat(payload, advertisedModel) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) throw new ApiError(400, "invalid_request_error", "Request body must be a JSON object.");
+  if (!Array.isArray(payload.messages)) throw new ApiError(400, "invalid_request_error", "messages must be an array.");
+  const requestedModel = typeof payload.model === "string" && payload.model.trim() ? payload.model.trim() : "";
+  const modelHint = requestedModel && requestedModel !== advertisedModel ? requestedModel : "";
+  const messages = [];
+  const systemParts = [];
+  for (const message of payload.messages) {
+    const role = normalizeRole(message?.role);
+    const text = contentToText(message?.content);
+    if (!text) continue;
+    if (role === "system") systemParts.push(text);
+    else messages.push({ role, content: { type: "text", text } });
+  }
+  if (!messages.length) throw new ApiError(400, "invalid_request_error", "No user/assistant message content was provided.");
+  const params = {
+    messages,
+    systemPrompt: systemParts.join("\n\n") || undefined,
+    maxTokens: clampInt(payload.max_tokens ?? payload.max_completion_tokens ?? payload.max_output_tokens, 1024, 1, 128000),
+    stopSequences: Array.isArray(payload.stop) ? payload.stop.map(String) : typeof payload.stop === "string" ? [payload.stop] : undefined,
+  };
+  if (typeof payload.temperature === "number" && Number.isFinite(payload.temperature)) params.temperature = payload.temperature;
+  if (modelHint) params.modelPreferences = { hints: [{ name: modelHint }] };
+  return { params: removeUndefined(params), modelHint };
+}
 
-  res.statusCode = response.status;
-  for (const [key, value] of response.headers) {
-    if (!HOP_BY_HOP_HEADERS.has(key.toLowerCase())) res.setHeader(key, value);
+async function requestMcpSampling(context, samplingRequest) {
+  let response;
+  try {
+    response = await fetch(`${context.workerUrl}/api/mcp/sampling`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "X-Bridge-Token": context.daemonSecret,
+      },
+      body: JSON.stringify({ ...samplingRequest, timeout_ms: context.samplingTimeoutMs }),
+      signal: AbortSignal.timeout(context.samplingTimeoutMs + 5_000),
+    });
+  } catch (error) {
+    if (error?.name === "TimeoutError" || error?.name === "AbortError") {
+      throw new ApiError(504, "mcp_sampling_timeout", "Timed out waiting for the Worker and connected MCP client to complete sampling/createMessage.");
+    }
+    throw error;
+  }
+  const body = await response.json().catch(() => null);
+  if (!response.ok) {
+    throw new ApiError(response.status, String(body?.error || "mcp_sampling_error"), String(body?.message || `MCP sampling request failed with HTTP ${response.status}`));
   }
-  if (!res.hasHeader("content-type")) res.setHeader("content-type", "application/json");
-  if (response.body) await pipeline(Readable.fromWeb(response.body), res);
-  else res.end();
+  return body?.result ?? body;
+}
+
+function extractSamplingText(result) {
+  const content = result?.content;
+  if (typeof content === "string") return content;
+  if (content?.type === "text" && typeof content.text === "string") return content.text;
+  if (Array.isArray(content)) return content.map(item => item?.type === "text" ? item.text : "").filter(Boolean).join("\n");
+  if (typeof result?.text === "string") return result.text;
+  return JSON.stringify(result ?? {});
+}
+
+function finishReasonFromSampling(result) {
+  const reason = String(result?.stopReason || "").toLowerCase();
+  if (reason === "maxtokens" || reason === "max_tokens" || reason === "length") return "length";
+  if (reason === "tooluse" || reason === "tool_use") return "tool_calls";
+  return "stop";
+}
+
+function chatCompletionPayload({ text, model, finishReason }) {
+  return {
+    id: `chatcmpl-${randomUUID()}`,
+    object: "chat.completion",
+    created: Math.floor(Date.now() / 1000),
+    model,
+    choices: [{ index: 0, message: { role: "assistant", content: text }, finish_reason: finishReason }],
+    usage: null,
+  };
 }
 
-function copyProxyHeaders(source, upstreamKey) {
-  const out = new Headers();
-  for (const [key, value] of Object.entries(source)) {
-    if (HOP_BY_HOP_HEADERS.has(key.toLowerCase())) continue;
-    if (Array.isArray(value)) out.set(key, value.join(", "));
-    else if (value !== undefined) out.set(key, String(value));
+function sendChatCompletionStream(res, { text, model, finishReason }) {
+  res.statusCode = 200;
+  res.setHeader("content-type", "text/event-stream; charset=utf-8");
+  res.setHeader("cache-control", "no-cache");
+  const id = `chatcmpl-${randomUUID()}`;
+  const created = Math.floor(Date.now() / 1000);
+  const first = { id, object: "chat.completion.chunk", created, model, choices: [{ index: 0, delta: { role: "assistant", content: text }, finish_reason: null }] };
+  const done = { id, object: "chat.completion.chunk", created, model, choices: [{ index: 0, delta: {}, finish_reason: finishReason }] };
+  res.write(`data: ${JSON.stringify(first)}\n\n`);
+  res.write(`data: ${JSON.stringify(done)}\n\n`);
+  res.write("data: [DONE]\n\n");
+  res.end();
+}
+
+function modelsPayload(context) {
+  return {
+    object: "list",
+    data: [{ id: context.model, object: "model", created: 0, owned_by: "chatgpt-mcp" }],
+  };
+}
+
+function normalizeRole(role) {
+  if (role === "assistant") return "assistant";
+  if (role === "system" || role === "developer") return "system";
+  return "user";
+}
+
+function contentToText(content) {
+  if (content === undefined || content === null) return "";
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return content.map(contentPartToText).filter(Boolean).join("\n");
+  return contentPartToText(content);
+}
+
+function contentPartToText(content) {
+  if (content === undefined || content === null) return "";
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return content.map(contentPartToText).filter(Boolean).join("\n");
+  if (typeof content === "object") {
+    if ((content.type === "text" || content.type === "input_text") && typeof content.text === "string") return content.text;
+    if (typeof content.text === "string") return content.text;
+    if (typeof content.content === "string") return content.content;
+    if (content.type === "text" && typeof content.value === "string") return content.value;
+    if (typeof content.type === "string" && content.type) {
+      throw new ApiError(400, "unsupported_content", `Only text message content is supported by this MCP-backed local chat API; unsupported content part: ${content.type}.`);
+    }
+    return "";
   }
-  out.set("authorization", `Bearer ${upstreamKey}`);
-  if (!out.has("content-type")) out.set("content-type", "application/json");
-  return out;
+  return String(content);
+}
+
+function removeUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+
+function readJsonBody(req, maxBytes) {
+  return readBody(req, maxBytes).then(buffer => {
+    try {
+      const text = buffer.toString("utf8");
+      return text.trim() ? JSON.parse(text) : {};
+    } catch {
+      throw new ApiError(400, "invalid_json", "Request body is not valid JSON.");
+    }
+  });
 }
 
 function readBody(req, maxBytes) {
@@ -214,18 +314,6 @@ function isAuthorized(req, expectedKey) {
   return typeof apiKey === "string" && apiKey === expectedKey;
 }
 
-function modelsPayload(model) {
-  return {
-    object: "list",
-    data: [{
-      id: model,
-      object: "model",
-      created: 0,
-      owned_by: "machine-bridge-mcp",
-    }],
-  };
-}
-
 function sendOpenAiError(res, status, code, message) {
   return sendJson(res, status, { error: { message, type: "invalid_request_error", param: null, code } });
 }
@@ -249,6 +337,12 @@ function setCorsHeaders(res) {
   res.setHeader("access-control-allow-headers", "authorization,content-type,x-api-key,openai-beta,openai-organization,openai-project");
 }
 
+function safeErrorLogFields(error, fields) {
+  if (error instanceof ApiError) return { ...fields, status: error.status, code: error.code };
+  if (error?.code === "BODY_TOO_LARGE") return { ...fields, status: 413, code: "request_too_large" };
+  return { ...fields, error: error?.name || "Error" };
+}
+
 function withPortHint(error, port) {
   if (error?.code === "EADDRINUSE") {
     error.message = `Local API port ${port} is already in use. Re-run with \`machine-mcp --api-port <free_port>\` or \`machine-mcp api --api-port <free_port>\`.`;
@@ -258,3 +352,17 @@ function withPortHint(error, port) {
   }
   return error;
 }
+
+function clampInt(value, fallback, min, max) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(Math.max(Math.floor(number), min), max);
+}
+
+class ApiError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}