machine-bridge-mcp 0.2.0 → 0.2.4

package/README.md

@@ -28,15 +28,18 @@ 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.
-7. Starts the local daemon and prints:
+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
 MCP Server URL: https://<worker>.<account>.workers.dev/mcp
 MCP connection password: mcp_password_...
+API Base URL: http://127.0.0.1:8765/v1
+API key: local_api_key_...
 ```
 
-Keep the foreground process running for the current session. The installed autostart entry keeps the daemon available after future logins.
+Keep the foreground process running for the current session. The installed autostart entry keeps the daemon and local API available after future logins.
 
 The command is safe to run repeatedly:
 
@@ -44,43 +47,54 @@ 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 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.
+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
+
+The project exposes two connected integration surfaces:
 
-## Local OpenAI-compatible 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.
 
-`machine-bridge-mcp` can also expose a local OpenAI-compatible API provider for desktop AI clients such as Cherry Studio, Chatbox, Continue, or other apps that accept an OpenAI-style base URL and API key.
+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 only the local API service:
+Start the normal daemon and local API:
+
+```zsh
+machine-mcp
+```
+
+Start only the local API from remembered state:
 
 ```zsh
 machine-mcp api
 ```
 
-Or run it together with the Remote MCP daemon:
+Disable the default local API for a daemon run:
 
 ```zsh
-machine-mcp start --api
+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:
 
 ```zsh
+machine-mcp --api-port 8766
 machine-mcp api --api-port 8766
-machine-mcp start --api --api-port 8766
 ```
 
 `--port` is also accepted on the `api` command:
@@ -89,34 +103,23 @@ machine-mcp start --api --api-port 8766
 machine-mcp api --port 8766
 ```
 
-By default, the local API binds to `127.0.0.1` and does not start unless you run `machine-mcp api` or pass `--api`. It stores a per-workspace local API key in the same owner-only state profile used by the MCP credentials. Rotate it with:
-
-```zsh
-machine-mcp api --rotate-api-key
-```
+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.
 
-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
 
@@ -237,7 +240,7 @@ Default state roots:
 - Linux with `XDG_STATE_HOME`: `$XDG_STATE_HOME/machine-bridge-mcp`
 - Windows: `%APPDATA%\machine-bridge-mcp`
 
-State contains the MCP password, daemon secret, and local API key when the API provider has been started. Status/doctor output redacts secrets. The normal foreground `start` command prints the MCP password because users need to paste it into their MCP client; `api` prints the local API key for the same reason. Use `--no-print-credentials` to redact console credentials. State files, temporary Worker secret files, lock files, and log directories are created under the user state root with owner-only permissions where the platform supports POSIX modes.
+State contains the MCP password, daemon secret, and local API key. Status/doctor output redacts secrets. The normal foreground `start` command prints the MCP password only when a ChatGPT app is likely to need reconnection: first run, secret rotation, MCP URL changes, or `--print-mcp-credentials`. The local API base URL and API key print on normal foreground starts because desktop AI clients need them. Use `--no-print-credentials` to redact console credentials. State files, temporary Worker secret files, lock files, and log directories are created under the user state root with owner-only permissions where the platform supports POSIX modes.
 
 The Worker rejects browser requests with an `Origin` header unless the origin is the Worker itself or a loopback HTTP origin. To allow additional browser-based MCP clients, set `MBM_ALLOWED_ORIGINS` to a comma-separated list of exact origins in `wrangler.jsonc` or Cloudflare Worker settings.
 
@@ -251,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["Optional 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"]
 ```
@@ -269,8 +274,8 @@ Why this architecture:
 - The public MCP URL is stable after deployment.
 - The Worker stores OAuth client/code/token metadata and relays tool calls.
 - The local daemon is the only process touching files or executing commands.
-- The optional local `/v1` API binds to loopback by default and starts only when requested.
-- Autostart keeps the daemon alive across logins without requiring MCP clients to change URLs.
+- The local `/v1` API binds to loopback by default, starts automatically with the daemon, and can be disabled with `--no-api`.
+- Autostart keeps the daemon and local API alive across logins without requiring MCP clients to change URLs.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.2.0",
+  "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 { randomUUID } from "node:crypto";
-import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
+import { createHash, randomUUID } from "node:crypto";
 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: ${raw}`);
-  }
-  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" });
+    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;
   }
-  if (!res.hasHeader("content-type")) res.setHeader("content-type", "application/json");
-  if (response.body) await pipeline(Readable.fromWeb(response.body), res);
-  else res.end();
+  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}`));
+  }
+  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) {
@@ -203,6 +303,10 @@ function readBody(req, maxBytes) {
   });
 }
 
+function sha256String(value) {
+  return createHash("sha256").update(String(value)).digest("hex");
+}
+
 function isAuthorized(req, expectedKey) {
   const auth = String(req.headers.authorization || "");
   if (auth.startsWith("Bearer ") && auth.slice(7) === expectedKey) return true;
@@ -210,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 } });
 }
@@ -245,12 +337,32 @@ 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 --api-port <free_port>\` or \`machine-mcp start --api --api-port <free_port>\`.`;
+    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>\`.`;
   }
   if (error?.code === "EACCES") {
-    error.message = `Local API port ${port} is not permitted. Re-run with \`machine-mcp api --api-port <free_port>\`.`;
+    error.message = `Local API port ${port} is not permitted. Re-run with \`machine-mcp --api-port <free_port>\` or \`machine-mcp api --api-port <free_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;
+  }
+}