simple-dynamsoft-mcp 7.4.42 → 7.6.0

package/.env.example

@@ -43,5 +43,24 @@
 # MCP_DATA_DOWNLOAD_RETRY_MAX_DELAY_MS=5000
 
 # Optional: observability
+# Console logs go to stderr. Format: json (default, one JSON object per line) | text (readable lines)
+# MCP_LOG_FORMAT=json
 # MCP_VERBOSE_LOGS=false
 # MCP_LOG_LEVEL=info
+# Request logs (one per tools/call / resources/read). stderr gets a summary:
+# tool or uri, outcome, duration, response size, and requester info (user agent, opt-in client id).
+# MCP_LOG_REQUESTS=true
+# Detailed request log directory: daily requests-<YYYY-MM-DD>-<host>.jsonl files with
+# arguments and full response. Unset = no detailed log.
+# MCP_REQUEST_LOG_DIR=
+# Delete detailed log files older than N days (0 = keep forever)
+# MCP_REQUEST_LOG_RETENTION_DAYS=30
+# Max JSON chars per logged arguments/response field in the detailed log (0 = no limit)
+# MCP_LOG_MAX_FIELD_CHARS=0
+# HTTP requester identity (personal data, opt-in): off (default) | hash (salted client_id) | full (client_ip)
+# MCP_LOG_CLIENT_IP=off
+# Secret salt for client_id; set it (e.g. as an ACA secret) for ids that stay stable across restarts.
+# If unset, a per-process salt is used. Never store it next to the request logs.
+# MCP_LOG_IP_SALT=
+# Honor X-Forwarded-For (right-most entry) only when a trusted proxy sets it, e.g. Azure Container Apps ingress
+# MCP_LOG_TRUST_PROXY=false

package/README.md

@@ -296,12 +296,15 @@ mcpServers:
 The server exposes this minimal tool surface:
 
 - `get_index` -- compact product/version/sample index with selection guidance
-- `search` -- semantic search across docs and samples (also accepts exact sample IDs)
+- `search` -- semantic search across docs and samples (also accepts exact sample IDs); returns `doc://` and `sample://` links
+- `read_document` -- read the full text (title, public docs URL, body) of a `doc://` URI returned by `search`
 - `list_samples` -- browse available samples for a product/edition/platform
 - `resolve_version` -- resolve current version for a product/edition/platform
 - `get_quickstart` -- opinionated quickstart: picks a sample by scenario, returns code + install instructions
 - `get_sample_files` -- get full project files for a known sample (discovered via list_samples or search)
 
+Typical doc Q&A flow: `search` -> `read_document` with the exact `doc://` URI -> answer from the returned text and cite its public URL. Clients that support MCP resources can also fetch the same `doc://` / `sample://` URIs with `resources/read`.
+
 ## Advanced Configuration And Operator Docs
 
 Advanced settings, CI/runbook details, and maintenance workflows live in:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "7.4.42",
+  "version": "7.6.0",
   "description": "MCP server for Dynamsoft SDKs - Capture Vision, Barcode Reader (Mobile/Python/Web), Dynamic Web TWAIN, and Document Viewer. Provides documentation, code snippets, and API guidance.",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,7 @@
   "scripts": {
     "start": "node src/index.js",
     "test": "npm run test:lite",
-    "test:unit": "node --test test/unit/gemini-retry.test.js test/unit/profile-config.test.js test/unit/lexical-provider.test.js test/unit/hydration-mode.test.js test/unit/hydration-policy.test.js test/unit/repo-map.test.js test/unit/download-utils.test.js test/unit/logging.test.js test/unit/rag-signature-manifest.test.js test/unit/startup-timing.test.js test/unit/http-startup-readiness.test.js test/unit/resource-index-startup.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/update-sdk-versions.test.js test/unit/version-policy.test.js test/unit/query-expansion.test.js test/unit/docs-loader-enrich.test.js",
+    "test:unit": "node --test test/unit/gemini-retry.test.js test/unit/profile-config.test.js test/unit/lexical-provider.test.js test/unit/hydration-mode.test.js test/unit/hydration-policy.test.js test/unit/repo-map.test.js test/unit/download-utils.test.js test/unit/logging.test.js test/unit/request-logging.test.js test/unit/request-log-file.test.js test/unit/rag-signature-manifest.test.js test/unit/startup-timing.test.js test/unit/http-startup-readiness.test.js test/unit/resource-index-startup.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/update-sdk-versions.test.js test/unit/version-policy.test.js test/unit/query-expansion.test.js test/unit/docs-loader-enrich.test.js",
     "test:lite": "npm run test:stdio && npm run test:http && npm run test:package",
     "test:lexical": "node --test test/integration/stdio.test.js test/integration/http.test.js",
     "test:gemini": "node scripts/run-gemini-tests.mjs",
@@ -34,7 +34,7 @@
     "test:contract": "node --test test/contract/contract.test.js",
     "check:version-drift": "node scripts/check-version-drift.mjs",
     "test:lazy": "node --test test/integration/lazy-hydration.test.js",
-    "test:regression:unit": "node --test test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/profile-config.test.js test/unit/hydration-mode.test.js test/unit/logging.test.js",
+    "test:regression:unit": "node --test test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/profile-config.test.js test/unit/hydration-mode.test.js test/unit/logging.test.js test/unit/request-logging.test.js test/unit/request-log-file.test.js",
     "test:regression:integration": "node --test test/integration/package-runtime.test.js test/integration/lazy-hydration.test.js",
     "test:regression": "npm run test:regression:unit && npm run test:regression:integration",
     "data:bootstrap": "git submodule sync --recursive && git submodule update --init --recursive --jobs 1",

package/src/data/submodule-sync.js

@@ -2,14 +2,11 @@ import { existsSync, readFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { logEvent } from "../observability/logging.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const projectRoot = join(__dirname, "..", "..");
 
-function logDataSync(message) {
-  console.error(`[data-sync] ${message}`);
-}
-
 function readBoolEnv(key, fallback = false) {
   const value = process.env[key];
   if (value === undefined || value === "") return fallback;
@@ -111,27 +108,30 @@ async function maybeSyncSubmodulesOnStart() {
   const timeoutMs = readIntEnv("DATA_SYNC_TIMEOUT_MS", 30000);
   const gitmodulesPath = join(projectRoot, ".gitmodules");
   const entries = parseGitmodules(gitmodulesPath);
-  logDataSync(`start entries=${entries.length} timeout_ms=${timeoutMs}`);
+  logEvent("data-sync", "start", { entries: entries.length, timeout_ms: timeoutMs });
   if (entries.length === 0) {
-    logDataSync("no submodules found; skipping");
+    logEvent("data-sync", "skipped", { reason: "no_submodules" });
     return;
   }
 
   let okCount = 0;
   let failCount = 0;
   for (const entry of entries) {
-    logDataSync(`sync path=${entry.path} branch=${entry.branch}`);
+    logEvent("data-sync", "sync", { path: entry.path, branch: entry.branch });
     const result = syncSubmodule(entry, timeoutMs);
     if (!result.ok) {
       failCount += 1;
-      const details = result.message ? `: ${result.message}` : "";
-      console.error(`[data-sync] ${entry.path} ${result.step} failed${details}`);
+      logEvent("data-sync", "sync_failed", {
+        path: entry.path,
+        step: result.step,
+        message: result.message
+      }, { level: "error" });
       continue;
     }
     okCount += 1;
-    logDataSync(`ok path=${entry.path}`);
+    logEvent("data-sync", "sync_ok", { path: entry.path });
   }
-  logDataSync(`done ok=${okCount} failed=${failCount}`);
+  logEvent("data-sync", "done", { ok: okCount, failed: failCount });
 }
 
 export {

package/src/observability/logging.js

@@ -1,3 +1,12 @@
+// Structured logging on stderr (stdout is reserved for the stdio MCP
+// transport). Every entry carries ts, level, component, and event; caller
+// fields are merged in. MCP_LOG_FORMAT selects the console rendering:
+// "json" (default, one JSON object per line) or "text" (one human-readable
+// line). Detailed request log files are always JSON (see request-log-file.js).
+
+const RESERVED_KEYS = new Set(["ts", "level", "component", "event"]);
+const REQUEST_EVENTS = new Set(["tool_call", "resource_read"]);
+
 function normalizeEnvValue(value) {
   if (value === undefined || value === null) return "";
   return String(value).trim().toLowerCase();
@@ -10,11 +19,8 @@ function isVerboseLoggingEnabled(env = process.env) {
   return ["1", "true", "yes", "on"].includes(toggle);
 }
 
-function quoteValue(value) {
-  const raw = String(value ?? "");
-  if (raw.length === 0) return "\"\"";
-  if (/\s|=/.test(raw)) return JSON.stringify(raw);
-  return raw;
+function resolveLogFormat(env = process.env) {
+  return normalizeEnvValue(env.MCP_LOG_FORMAT) === "text" ? "text" : "json";
 }
 
 function latencyBucket(latencyMs) {
@@ -27,25 +33,99 @@ function latencyBucket(latencyMs) {
   return "ge3s";
 }
 
-function logEvent(component, event, fields = {}, options = {}) {
-  const level = normalizeEnvValue(options.level || "info") || "info";
-  const verbose = isVerboseLoggingEnabled(options.env);
-  if (level === "debug" && !verbose) return;
+function jsonReplacer(_key, value) {
+  if (typeof value === "bigint") return value.toString();
+  if (value instanceof Error) return { name: value.name, message: value.message };
+  return value;
+}
 
-  const parts = [`[${component}]`, `event=${quoteValue(event || "detail")}`];
+function serializeLogEntry(entry) {
+  try {
+    return JSON.stringify(entry, jsonReplacer);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return JSON.stringify({
+      ts: entry.ts,
+      level: entry.level,
+      component: entry.component,
+      event: entry.event,
+      serialization_error: message
+    });
+  }
+}
+
+function createLogEntry(component, event, fields = {}, level = "info") {
+  const entry = {
+    ts: new Date().toISOString(),
+    level,
+    component: String(component || "app"),
+    event: String(event || "detail")
+  };
   for (const [key, value] of Object.entries(fields || {})) {
     if (value === undefined || value === null || value === "") continue;
-    parts.push(`${key}=${quoteValue(value)}`);
+    if (RESERVED_KEYS.has(key)) continue;
+    entry[key] = value;
+  }
+  return entry;
+}
+
+function formatTextValue(value) {
+  if (typeof value === "string") {
+    return value === "" || /[\s="\x00-\x1f]/.test(value) ? JSON.stringify(value) : value;
   }
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(value, jsonReplacer);
+}
+
+// "search ok 374ms 1804 chars" / "read doc://x error -32603 \"msg\" 1ms".
+function formatRequestHead(entry, consumed) {
+  const parts = [];
+  if (entry.event === "tool_call") {
+    parts.push(formatTextValue(entry.tool ?? "?"));
+    consumed.add("tool");
+  } else {
+    parts.push("read", formatTextValue(entry.uri ?? "?"));
+    consumed.add("uri");
+  }
+  parts.push(entry.send_failed ? "undelivered" : entry.is_error ? "error" : "ok");
+  if (entry.error) {
+    parts.push(String(entry.error.code), formatTextValue(String(entry.error.message ?? "")));
+  }
+  if (entry.duration_ms !== undefined) parts.push(`${entry.duration_ms}ms`);
+  if (entry.response_chars !== undefined) parts.push(`${entry.response_chars} chars`);
+  for (const key of ["is_error", "error", "duration_ms", "response_chars", "send_failed"]) consumed.add(key);
+  return parts;
+}
 
-  if (level !== "info") {
-    parts.push(`level=${level}`);
+function formatTextLine(entry) {
+  const parts = [entry.ts, entry.level.toUpperCase().padEnd(5), `[${entry.component}]`];
+  const consumed = new Set(RESERVED_KEYS);
+  if (entry.component === "mcp" && REQUEST_EVENTS.has(entry.event)) {
+    parts.push(...formatRequestHead(entry, consumed));
+  } else {
+    parts.push(entry.event);
+  }
+  for (const [key, value] of Object.entries(entry)) {
+    if (!consumed.has(key)) parts.push(`${key}=${formatTextValue(value)}`);
   }
-  console.error(parts.join(" "));
+  return parts.join(" ");
+}
+
+function logEvent(component, event, fields = {}, options = {}) {
+  const env = options.env || process.env;
+  const level = normalizeEnvValue(options.level || "info") || "info";
+  const verbose = isVerboseLoggingEnabled(env);
+  if (level === "debug" && !verbose) return;
+
+  const entry = createLogEntry(component, event, fields, level);
+  console.error(resolveLogFormat(env) === "text" ? formatTextLine(entry) : serializeLogEntry(entry));
 }
 
 export {
+  createLogEntry,
+  formatTextLine,
   isVerboseLoggingEnabled,
   latencyBucket,
-  logEvent
+  logEvent,
+  serializeLogEntry
 };

package/src/observability/request-log-file.js

@@ -0,0 +1,267 @@
+import { createWriteStream } from "node:fs";
+import { mkdir, readdir, unlink } from "node:fs/promises";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { logEvent, serializeLogEntry } from "./logging.js";
+
+const FILE_PATTERN = /^requests-(\d{4}-\d{2}-\d{2})-.+\.jsonl$/;
+const DEFAULT_RETENTION_DAYS = 30;
+const DAY_MS = 24 * 60 * 60 * 1000;
+// Cap on entries queued in memory while the log volume is slow or stalled.
+const DEFAULT_MAX_BUFFERED_BYTES = 8 * 1024 * 1024;
+
+function resolveRetentionDays(env = process.env) {
+  const raw = env.MCP_REQUEST_LOG_RETENTION_DAYS;
+  if (raw === undefined || raw === "") return DEFAULT_RETENTION_DAYS;
+  const parsed = Number.parseInt(String(raw), 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_RETENTION_DAYS;
+}
+
+function sanitizeFilePart(value) {
+  return String(value || "").replace(/[^A-Za-z0-9._-]/g, "_") || "host";
+}
+
+function utcDay(ms) {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+// Appends detailed request entries as JSON lines to
+// <dir>/requests-<YYYY-MM-DD>-<host>.jsonl (UTC day). One file per host keeps
+// replicas sharing a network volume from interleaving writes. Files older than
+// retentionDays are removed when a new day's file is opened (0 keeps all).
+//
+// Logging must never disrupt requests:
+// - Failures are reported on stderr once per day (for whichever day's stream
+//   failed, including streams already rotated out or closing) and never thrown.
+//   A failing old stream never disables its replacement.
+// - If the volume stalls, entries are dropped once maxBufferedBytes are queued
+//   across every day's file not yet closed (entries waiting for the file to
+//   open plus bytes queued in its stream, including a rotated-out file still
+//   flushing), so memory stays bounded. Dropping is reported once per stall,
+//   and resuming (with the dropped count) on the next write that fits. A
+//   single entry larger than the cap is dropped and reported with its size. A
+//   cap of 0 queues nothing.
+// - No blocking filesystem calls run on the request path: the directory is
+//   created asynchronously, and entries logged meanwhile are queued (within
+//   the cap) and written in order once the file opens.
+function createRequestLogFile({
+  dir,
+  retentionDays = DEFAULT_RETENTION_DAYS,
+  host = hostname(),
+  now = Date.now,
+  maxBufferedBytes = DEFAULT_MAX_BUFFERED_BYTES,
+  makeDir = (path) => mkdir(path, { recursive: true }),
+  openStream = (path) => createWriteStream(path, { flags: "a" })
+}) {
+  const hostPart = sanitizeFilePart(host);
+  const reportedDays = new Set();
+  // One sink per day's file. Entries logged before the directory exists and
+  // the stream is open wait in sink.pending; afterwards they queue in the
+  // stream. A sink stays in `sinks` (and counts against the cap) until its
+  // stream closes or its open fails, including after rotation.
+  const sinks = new Set();
+  let current = null;
+  let failedDay = "";
+  let droppedEntries = 0;
+  let cleanup = Promise.resolve();
+
+  function reportFailure(day, error) {
+    if (reportedDays.has(day)) return;
+    reportedDays.add(day);
+    const message = error instanceof Error ? error.message : String(error);
+    logEvent("request-log", "file_write_failed", { dir, day, message }, { level: "error" });
+  }
+
+  function sinkBytes(sink) {
+    const streamBytes = sink.stream && !sink.stream.destroyed ? sink.stream.writableLength || 0 : 0;
+    return sink.pendingBytes + streamBytes;
+  }
+
+  function queuedBytes() {
+    let total = 0;
+    for (const sink of sinks) total += sinkBytes(sink);
+    return total;
+  }
+
+  function discardPending(sink) {
+    sink.pending = [];
+    sink.pendingBytes = 0;
+  }
+
+  function disableDay(day) {
+    failedDay = day;
+    const failed = current;
+    current = null;
+    if (!failed) return;
+    discardPending(failed);
+    failed.stream?.destroy();
+  }
+
+  function resumeAfterBackpressure() {
+    if (!droppedEntries) return;
+    logEvent("request-log", "file_backpressure_resumed", { dir, dropped_entries: droppedEntries }, { level: "warn" });
+    droppedEntries = 0;
+  }
+
+  async function removeExpired(today) {
+    if (!retentionDays) return;
+    const cutoff = Date.parse(`${today}T00:00:00Z`) - retentionDays * DAY_MS;
+    let names;
+    try {
+      names = await readdir(dir);
+    } catch (error) {
+      logEvent("request-log", "retention_failed", { dir, message: error instanceof Error ? error.message : String(error) }, { level: "warn" });
+      return;
+    }
+    for (const name of names) {
+      const match = FILE_PATTERN.exec(name);
+      if (!match || Date.parse(`${match[1]}T00:00:00Z`) >= cutoff) continue;
+      try {
+        await unlink(join(dir, name));
+      } catch (error) {
+        logEvent("request-log", "retention_failed", { file: name, message: error instanceof Error ? error.message : String(error) }, { level: "warn" });
+      }
+    }
+  }
+
+  // Directory creation is async so a slow or stalled volume never blocks the
+  // event loop on the request path.
+  function createSink(day) {
+    const sink = { day, stream: null, pending: [], pendingBytes: 0, ended: false };
+    let markDone;
+    sink.done = new Promise((resolve) => {
+      markDone = resolve;
+    });
+    const finish = () => {
+      sinks.delete(sink);
+      markDone();
+    };
+    sinks.add(sink);
+
+    sink.ready = Promise.resolve()
+      .then(() => makeDir(dir))
+      .then(() => {
+        if (failedDay === day) {
+          finish();
+          return;
+        }
+        const stream = openStream(join(dir, `requests-${day}-${hostPart}.jsonl`));
+        stream.on("error", (error) => {
+          reportFailure(day, error);
+          if (current === sink) disableDay(day);
+        });
+        stream.once("close", finish);
+        sink.stream = stream;
+        for (const line of sink.pending) stream.write(line);
+        discardPending(sink);
+        if (sink.ended) stream.end();
+        cleanup = removeExpired(day);
+      })
+      .catch((error) => {
+        reportFailure(day, error);
+        if (current === sink) disableDay(day);
+        discardPending(sink);
+        if (!sink.stream) finish();
+      });
+    return sink;
+  }
+
+  function endSink(sink) {
+    sink.ended = true;
+    sink.stream?.end();
+  }
+
+  function write(entry) {
+    const day = utcDay(now());
+    if (day === failedDay) return;
+    try {
+      if (!current || current.day !== day) {
+        if (current) endSink(current);
+        current = createSink(day);
+      }
+      const line = `${serializeLogEntry(entry)}\n`;
+      const lineBytes = Buffer.byteLength(line);
+      if (lineBytes > maxBufferedBytes) {
+        logEvent("request-log", "file_entry_too_large", {
+          dir,
+          day,
+          entry_bytes: lineBytes,
+          limit_bytes: maxBufferedBytes
+        }, { level: "warn" });
+        return;
+      }
+      const queued = queuedBytes();
+      if (queued + lineBytes > maxBufferedBytes) {
+        if (!droppedEntries) {
+          logEvent("request-log", "file_backpressure_dropping", {
+            dir,
+            day,
+            buffered_bytes: queued,
+            limit_bytes: maxBufferedBytes
+          }, { level: "warn" });
+        }
+        droppedEntries += 1;
+        return;
+      }
+      resumeAfterBackpressure();
+      if (current.stream) {
+        current.stream.write(line);
+      } else {
+        current.pending.push(line);
+        current.pendingBytes += lineBytes;
+      }
+    } catch (error) {
+      reportFailure(day, error);
+      disableDay(day);
+    }
+  }
+
+  // Ends the current day's file and resolves once every sink has finished:
+  // pending opens complete and flush, and rotated-out streams still flushing
+  // close, so shutdown does not drop entries. Errors are reported by each
+  // stream's handler; "close" follows them, so this still resolves.
+  function close() {
+    const last = current;
+    current = null;
+    if (last) endSink(last);
+    return Promise.all([...sinks].map((sink) => sink.done)).then(() => undefined);
+  }
+
+  async function whenCleanupDone() {
+    await Promise.all([...sinks].map((sink) => sink.ready));
+    await cleanup;
+  }
+
+  return {
+    write,
+    close,
+    whenCleanupDone
+  };
+}
+
+let sharedFile = null;
+let sharedDir = "";
+
+// Process-wide writer for MCP_REQUEST_LOG_DIR; null when file logging is off.
+function getRequestLogFile(env = process.env) {
+  const dir = String(env.MCP_REQUEST_LOG_DIR || "").trim();
+  if (!dir) return null;
+  if (!sharedFile || sharedDir !== dir) {
+    sharedFile = createRequestLogFile({ dir, retentionDays: resolveRetentionDays(env) });
+    sharedDir = dir;
+  }
+  return sharedFile;
+}
+
+async function closeRequestLogFile() {
+  const file = sharedFile;
+  sharedFile = null;
+  sharedDir = "";
+  await file?.close();
+}
+
+export {
+  closeRequestLogFile,
+  createRequestLogFile,
+  getRequestLogFile
+};

package/src/observability/request-logging.js

@@ -0,0 +1,220 @@
+import { createHmac, randomBytes } from "node:crypto";
+import { createLogEntry, logEvent } from "./logging.js";
+import { getRequestLogFile } from "./request-log-file.js";
+
+// JSON-RPC methods whose parameters and responses are logged. These are the
+// user-driven operations worth reviewing (what was asked, what was returned).
+const LOGGED_METHODS = new Map([
+  ["tools/call", "tool_call"],
+  ["resources/read", "resource_read"]
+]);
+
+// Detailed entries go to disk, so arguments/responses are kept whole unless
+// MCP_LOG_MAX_FIELD_CHARS sets a cap.
+const DEFAULT_MAX_FIELD_CHARS = 0;
+const MAX_PENDING_REQUESTS = 1000;
+const MAX_USER_AGENT_CHARS = 256;
+// Cap for caller-controlled scalars (uri, tool name, JSON-RPC id).
+const MAX_SCALAR_CHARS = 1024;
+const CLIENT_IP_MODES = new Set(["hash", "full", "off"]);
+
+// Salt for hashed client ids, so they are not reversible by brute forcing the
+// IPv4 space without it. Use MCP_LOG_IP_SALT (a deployment secret) for ids that
+// are stable across restarts and replicas. Without it, a per-process salt is
+// used: ids only group requests within one process lifetime. The salt is never
+// written next to the logs it de-identifies.
+const processSalt = randomBytes(32).toString("hex");
+
+function resolveIpSalt(env = process.env) {
+  return env.MCP_LOG_IP_SALT || processSalt;
+}
+
+function readBoolEnv(env, key, fallback) {
+  const value = env[key];
+  if (value === undefined || value === "") return fallback;
+  return ["1", "true", "yes", "on"].includes(String(value).trim().toLowerCase());
+}
+
+function isRequestLoggingEnabled(env = process.env) {
+  return readBoolEnv(env, "MCP_LOG_REQUESTS", true);
+}
+
+function resolveMaxFieldChars(env = process.env) {
+  const raw = env.MCP_LOG_MAX_FIELD_CHARS;
+  if (raw === undefined || raw === "") return DEFAULT_MAX_FIELD_CHARS;
+  const parsed = Number.parseInt(String(raw), 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_MAX_FIELD_CHARS;
+}
+
+// IP-derived fields are personal data, so they are opt-in.
+function resolveClientIpMode(env = process.env) {
+  const mode = String(env.MCP_LOG_CLIENT_IP || "").trim().toLowerCase();
+  return CLIENT_IP_MODES.has(mode) ? mode : "off";
+}
+
+// Bounds a logged value when a cap is configured. 0 disables the limit.
+function limitForLog(value, maxChars) {
+  if (value === undefined || !maxChars) return value;
+  let text;
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    return "[unserializable]";
+  }
+  if (text === undefined || text.length <= maxChars) return value;
+  return { truncated: true, original_chars: text.length, preview: text.slice(0, maxChars) };
+}
+
+// Bounds caller-controlled fields that are expected to be short (uri, tool
+// name, JSON-RPC id, error message) even when the caller sends something else.
+function capScalar(value) {
+  if (typeof value !== "string") return limitForLog(value, MAX_SCALAR_CHARS);
+  if (value.length <= MAX_SCALAR_CHARS) return value;
+  return `${value.slice(0, MAX_SCALAR_CHARS)}...[truncated ${value.length - MAX_SCALAR_CHARS} chars]`;
+}
+
+function normalizeIp(value) {
+  let ip = String(value || "").trim();
+  if (!ip) return "";
+  const bracketed = /^\[([^\]]+)\](?::\d+)?$/.exec(ip);
+  if (bracketed) ip = bracketed[1];
+  const ipv4WithPort = /^(\d{1,3}(?:\.\d{1,3}){3}):\d+$/.exec(ip);
+  if (ipv4WithPort) ip = ipv4WithPort[1];
+  if (ip.toLowerCase().startsWith("::ffff:") && ip.includes(".")) ip = ip.slice(7);
+  return ip;
+}
+
+// X-Forwarded-For is client-controlled unless a proxy in front of the server
+// rewrites it, so it is only honored with MCP_LOG_TRUST_PROXY=true (e.g. Azure
+// Container Apps ingress). The trusted proxy appends the peer it saw, so the
+// right-most entry is the one a client cannot spoof. Otherwise the socket peer
+// is used.
+function resolveClientIp(req, env = process.env) {
+  if (readBoolEnv(env, "MCP_LOG_TRUST_PROXY", false)) {
+    const forwarded = req?.headers?.["x-forwarded-for"];
+    const header = Array.isArray(forwarded) ? forwarded.join(",") : forwarded;
+    if (header) {
+      const parts = String(header).split(",").map((part) => part.trim()).filter(Boolean);
+      if (parts.length > 0) return normalizeIp(parts[parts.length - 1]);
+    }
+  }
+  return normalizeIp(req?.socket?.remoteAddress);
+}
+
+function describeClientIp(ip, env = process.env) {
+  if (!ip) return {};
+  const mode = resolveClientIpMode(env);
+  if (mode === "off") return {};
+  if (mode === "full") return { client_ip: ip };
+  const salt = resolveIpSalt(env);
+  return { client_id: createHmac("sha256", salt).update(ip).digest("hex").slice(0, 16) };
+}
+
+function buildHttpRequestContext(req, env = process.env) {
+  const context = { transport: "http" };
+  if (resolveClientIpMode(env) !== "off") {
+    Object.assign(context, describeClientIp(resolveClientIp(req, env), env));
+  }
+  const userAgent = req?.headers?.["user-agent"];
+  if (userAgent) context.user_agent = String(userAgent).slice(0, MAX_USER_AGENT_CHARS);
+  return context;
+}
+
+function isResponse(message) {
+  return Boolean(message) && message.id !== undefined && message.id !== null
+    && ("result" in message || "error" in message);
+}
+
+function jsonLength(value) {
+  try {
+    return JSON.stringify(value)?.length ?? 0;
+  } catch {
+    return undefined;
+  }
+}
+
+// One entry per tools/call or resources/read. stderr gets a short summary
+// (what was called, outcome, duration, response size). The detailed entry
+// (arguments, full response, caller context) is appended to the request log
+// file when MCP_REQUEST_LOG_DIR is set. Hooks the transport so every tool and
+// resource handler is covered without per-handler code. Safe to call before or
+// after server.connect(transport).
+function attachRequestLogging(transport, context = {}, {
+  env = process.env,
+  now = Date.now,
+  file = getRequestLogFile(env)
+} = {}) {
+  if (!isRequestLoggingEnabled(env)) return transport;
+  const maxChars = resolveMaxFieldChars(env);
+  const pending = new Map();
+
+  const previousOnMessage = transport.onmessage;
+  transport.onmessage = (message, extra) => {
+    const event = message && message.id !== undefined ? LOGGED_METHODS.get(message.method) : undefined;
+    if (event) {
+      if (pending.size >= MAX_PENDING_REQUESTS) {
+        pending.delete(pending.keys().next().value);
+      }
+      pending.set(message.id, { event, params: message.params || {}, startedAt: now() });
+    }
+    previousOnMessage?.(message, extra);
+  };
+
+  function record(message, request, durationMs, sendError) {
+    const params = request.params;
+    const isToolCall = request.event === "tool_call";
+    const rpcError = message.error;
+    const level = rpcError || sendError ? "warn" : "info";
+    const summary = {
+      ...context,
+      request_id: capScalar(message.id),
+      tool: isToolCall ? capScalar(params.name) : undefined,
+      uri: isToolCall ? undefined : capScalar(params.uri),
+      duration_ms: durationMs,
+      is_error: Boolean(rpcError) || message.result?.isError === true,
+      error: rpcError ? { code: rpcError.code, message: capScalar(rpcError.message) } : undefined,
+      send_failed: sendError ? true : undefined,
+      send_error: sendError ? capScalar(sendError instanceof Error ? sendError.message : String(sendError)) : undefined
+    };
+
+    logEvent("mcp", request.event, {
+      ...summary,
+      response_chars: rpcError ? undefined : jsonLength(message.result)
+    }, { level, env });
+
+    file?.write(createLogEntry("mcp", request.event, {
+      ...summary,
+      arguments: isToolCall ? limitForLog(params.arguments || {}, maxChars) : undefined,
+      response: rpcError ? undefined : limitForLog(message.result, maxChars)
+    }, level));
+  }
+
+  // Logged after the transport accepts the response, so an entry reflects
+  // delivery; a rejected send is logged with send_failed and rethrown.
+  // duration_ms measures handler time (request received -> response ready).
+  const originalSend = transport.send.bind(transport);
+  transport.send = async (message, options) => {
+    const request = isResponse(message) ? pending.get(message.id) : undefined;
+    if (!request) return originalSend(message, options);
+    pending.delete(message.id);
+    const durationMs = now() - request.startedAt;
+    try {
+      const result = await originalSend(message, options);
+      record(message, request, durationMs, null);
+      return result;
+    } catch (error) {
+      record(message, request, durationMs, error);
+      throw error;
+    }
+  };
+
+  return transport;
+}
+
+export {
+  attachRequestLogging,
+  buildHttpRequestContext,
+  describeClientIp,
+  limitForLog,
+  resolveClientIp
+};

package/src/server/create-server.js

@@ -2,7 +2,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ensureDataScopesHydrated } from "../data/bootstrap.js";
 import { createScopeHydrator } from "./helpers/server-helpers.js";
 import { registerResourceHandlers } from "./resources/register-resources.js";
+import { createIndexedResourceReader } from "./resources/read-indexed-resource.js";
 import { registerIndexTools } from "./tools/register-index-tools.js";
+import { registerDocumentTools } from "./tools/register-document-tools.js";
 import { registerSampleTools } from "./tools/register-sample-tools.js";
 import { registerVersionTools } from "./tools/register-version-tools.js";
 import { registerQuickstartTools } from "./tools/register-quickstart-tools.js";
@@ -71,6 +73,8 @@ export function createMcpServerInstance({ pkgVersion, resourceIndexApi, ragApi }
       "",
       "How to use it:",
       "- Call get_index first to see valid product/edition/platform combinations before asking the user anything.",
+      "- To answer from documentation: call search, then call read_document with the exact doc:// uri it returned, and base the answer on that text, citing the public documentation URL it contains. Do not answer from search summaries alone or hand doc:// links to the user.",
+      "- For sample:// results, call get_sample_files with resource_uri to get the complete sample project.",
       "- Only ask the user to disambiguate dimensions that actually vary for the chosen product. Do NOT ask about dimensions that don't apply.",
       "",
       "Platform/edition rules (important):",
@@ -84,6 +88,12 @@ export function createMcpServerInstance({ pkgVersion, resourceIndexApi, ragApi }
     ].join("\n")
   });
 
+  const readIndexedResource = createIndexedResourceReader({
+    parseResourceUri,
+    ensureLatestMajor,
+    readResourceContent
+  });
+
   registerIndexTools({
     server,
     ensureScopeHydrated,
@@ -100,6 +110,11 @@ export function createMcpServerInstance({ pkgVersion, resourceIndexApi, ragApi }
     getSampleSuggestions
   });
 
+  registerDocumentTools({
+    server,
+    readIndexedResource
+  });
+
   registerSampleTools({
     server,
     registry,
@@ -183,9 +198,8 @@ export function createMcpServerInstance({ pkgVersion, resourceIndexApi, ragApi }
   registerResourceHandlers({
     server,
     getPinnedResources,
-    parseResourceUri,
-    ensureLatestMajor,
-    readResourceContent
+    readResourceContent,
+    readIndexedResource
   });
 
   return server;

package/src/server/resources/read-indexed-resource.js

@@ -0,0 +1,33 @@
+// Products whose versioned doc/sample URIs are subject to the latest-major policy.
+const VERSION_POLICY_PRODUCTS = ["dbr", "dwt", "ddv", "mrz", "mds"];
+
+// Shared read path for doc:// and sample:// URIs. Used by the MCP resource
+// templates (resources/read) and the read_document tool so both enforce the
+// same version policy and stale-URI guidance.
+export function createIndexedResourceReader({ parseResourceUri, ensureLatestMajor, readResourceContent }) {
+  return async function readIndexedResource(uri) {
+    const uriStr = String(uri);
+    const parsed = parseResourceUri(uriStr);
+    if (parsed && VERSION_POLICY_PRODUCTS.includes(parsed.product)) {
+      const policy = ensureLatestMajor({
+        product: parsed.product,
+        version: parsed.version,
+        edition: parsed.edition,
+        platform: parsed.platform
+      });
+      if (!policy.ok) {
+        throw new Error(policy.message);
+      }
+    }
+
+    const resource = await readResourceContent(uriStr);
+    if (!resource) {
+      // Doc URIs embed a positional index + exact version, so they can go stale
+      // across data refreshes. Point the agent back to search to re-discover the
+      // current URI instead of dead-ending (issue #153).
+      throw new Error(`Resource not found: ${uriStr}. The URI may be stale (doc URIs change across data refreshes). Call search with keywords from the title to get the current URI.`);
+    }
+
+    return resource;
+  };
+}

package/src/server/resources/register-resources.js

@@ -3,9 +3,8 @@ import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 export function registerResourceHandlers({
   server,
   getPinnedResources,
-  parseResourceUri,
-  ensureLatestMajor,
-  readResourceContent
+  readResourceContent,
+  readIndexedResource
 }) {
   for (const entry of getPinnedResources()) {
     server.registerResource(
@@ -26,29 +25,7 @@ export function registerResourceHandlers({
   }
 
   async function templateReadHandler(uri) {
-    const uriStr = uri.toString();
-    const parsed = parseResourceUri(uriStr);
-    if (parsed && ["dbr", "dwt", "ddv", "mrz", "mds"].includes(parsed.product)) {
-      const policy = ensureLatestMajor({
-        product: parsed.product,
-        version: parsed.version,
-        edition: parsed.edition,
-        platform: parsed.platform
-      });
-      if (!policy.ok) {
-        throw new Error(policy.message);
-      }
-    }
-
-    const resource = await readResourceContent(uriStr);
-    if (!resource) {
-      // Doc URIs embed a positional index + exact version, so they can go stale
-      // across data refreshes. Point the agent back to search to re-discover the
-      // current URI instead of dead-ending (issue #153).
-      throw new Error(`Resource not found: ${uriStr}. The URI may be stale (doc URIs change across data refreshes). Call search with keywords from the title to get the current URI.`);
-    }
-
-    return { contents: [resource] };
+    return { contents: [await readIndexedResource(uri.toString())] };
   }
 
   server.registerResource(

package/src/server/tools/register-document-tools.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+
+function errorResult(text) {
+  return { isError: true, content: [{ type: "text", text }] };
+}
+
+export function registerDocumentTools({ server, readIndexedResource }) {
+  server.registerTool(
+    "read_document",
+    {
+      title: "Read Document",
+      description: [
+        "Read the full text of a Dynamsoft documentation page by its doc:// URI.",
+        "",
+        "WHEN TO USE:",
+        "- After search returns doc:// results: call read_document with the exact uri from a resource_link or the plain URI list before answering.",
+        "- When you need the actual article body (API details, parameters, code snippets) instead of the search summary.",
+        "",
+        "WHEN NOT TO USE:",
+        "- For sample:// URIs, use get_sample_files with resource_uri instead (complete sample projects).",
+        "- Do not construct or edit doc:// URIs yourself; they are generated by search and may change across data refreshes.",
+        "",
+        "PARAMETERS:",
+        "- uri (required): The exact doc:// URI returned by search (e.g. a resource_link uri).",
+        "",
+        "RETURNS: The document as markdown text: title, public documentation URL (cite it in answers), and the full article body.",
+        "On failure (stale or missing URI, unsupported version, unsupported scheme) returns isError with guidance; call search again to get a current URI.",
+        "",
+        "RELATED TOOLS: search (find doc:// URIs), get_sample_files (read sample:// projects), get_quickstart (starter code)."
+      ].join("\n"),
+      inputSchema: {
+        uri: z.string().trim().min(1, "uri is required.").describe("Exact doc:// URI returned by search.")
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ uri }) => {
+      const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(uri)?.[1]?.toLowerCase();
+      if (scheme === "sample") {
+        return errorResult(`read_document only reads doc:// URIs. For sample:// URIs, call get_sample_files with resource_uri="${uri}".`);
+      }
+      if (scheme !== "doc") {
+        return errorResult(`Unsupported URI: "${uri}". read_document accepts only doc:// URIs returned by search.`);
+      }
+
+      let resource;
+      try {
+        resource = await readIndexedResource(uri);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return errorResult(`Failed to read document: ${message}`);
+      }
+
+      const text = typeof resource.text === "string" ? resource.text : "";
+      if (!text.trim()) {
+        return errorResult(`Document ${uri} has no readable text content. Call search again to find an alternative document.`);
+      }
+
+      return { content: [{ type: "text", text }] };
+    }
+  );
+}

package/src/server/tools/register-index-tools.js

@@ -9,7 +9,6 @@ import {
 } from "../public-offerings.js";
 import { buildUnsupportedPublicScopeResponse } from "./public-routing.js";
 import { validatePlatform, validateEdition } from "../normalizers.js";
-import { logEvent } from "../../observability/logging.js";
 
 export function registerIndexTools({
   server,
@@ -118,9 +117,9 @@ export function registerIndexTools({
         "- type: 'doc', 'sample', 'index', 'policy', or 'any' (default). Use 'sample' to restrict to sample results.",
         "- limit: 1-10 (default 5). Max number of results.",
         "",
-        "RETURNS: An MCP response whose content array includes a leading text summary item followed by zero or more resource_link items with URIs. Use resources/read to fetch full content of doc:// URIs. Use get_sample_files to fetch full project files for sample:// URIs.",
+        "RETURNS: An MCP response whose content array includes a leading text summary item followed by zero or more resource_link items with URIs. For doc:// URIs, call read_document with the exact returned uri to get the full document text before answering. For sample:// URIs, call get_sample_files with resource_uri to get the full project files.",
         "",
-        "RELATED TOOLS: get_index (discover products first), list_samples (browse all samples), get_sample_files (retrieve full sample project files), resources/read (read a doc resource)."
+        "RELATED TOOLS: get_index (discover products first), list_samples (browse all samples), read_document (read a doc:// result), get_sample_files (retrieve full sample project files)."
       ].join("\n"),
       inputSchema: {
         query: z.string().trim().min(1, "Query is required.").describe("Keywords to search across docs and samples."),
@@ -199,7 +198,7 @@ export function registerIndexTools({
           const content = [
             {
               type: "text",
-              text: `Found ${selected.length} exact match(es) for "${query}". Read the links you need with resources/read.`
+              text: `Found ${selected.length} exact match(es) for "${query}". Call get_sample_files with the exact resource_uri to get the full sample project.`
             }
           ];
 
@@ -305,15 +304,6 @@ export function registerIndexTools({
           }
         }
 
-        // Zero-result queries are the highest-value eval/synonym-gap signal — log
-        // them so they can be harvested from production logs (issue #156).
-        logEvent("search", "zero_result_query", {
-          query,
-          product: normalizedProduct || "",
-          edition: normalizedEdition || "",
-          platform: normalizedPlatform || "",
-          type: type || "any"
-        });
         return {
           content: [{
             type: "text",
@@ -325,9 +315,10 @@ export function registerIndexTools({
       // Capture Vision / DCV is the umbrella framework, not a selectable public
       // product — steer the agent to the right offering (issue #150).
       const dcvUmbrella = /\b(capture[\s-]?vision|dcv)\b/i.test(query) && !normalizedProduct;
+      const readGuidance = "For doc:// results, call read_document with the exact uri to get the document text; for sample:// results, call get_sample_files with resource_uri.";
       const leadText = dcvUmbrella
-        ? `"Capture Vision" (DCV) is Dynamsoft's umbrella framework — pick the public product for your task: DBR (barcodes), MRZ (passports/IDs), MDS (document capture), DWT (scanner hardware), DDV (document viewer). Results below span the closest matches.\nFound ${topResults.length} result(s) for "${query}".`
-        : `Found ${topResults.length} result(s) for "${query}". Read the links you need with resources/read.`;
+        ? `"Capture Vision" (DCV) is Dynamsoft's umbrella framework — pick the public product for your task: DBR (barcodes), MRZ (passports/IDs), MDS (document capture), DWT (scanner hardware), DDV (document viewer). Results below span the closest matches.\nFound ${topResults.length} result(s) for "${query}". ${readGuidance}`
+        : `Found ${topResults.length} result(s) for "${query}". ${readGuidance}`;
       const content = [
         {
           type: "text",
@@ -356,7 +347,7 @@ export function registerIndexTools({
 
       const plainLines = topResults.map((entry, index) => {
         const sampleId = entry.type === "sample" ? getSampleIdFromUri(entry.uri) : "";
-        const action = entry.type === "sample" ? "get_sample_files resource_uri" : "resources/read uri";
+        const action = entry.type === "sample" ? "get_sample_files resource_uri" : "read_document uri";
         const sampleNote = sampleId ? ` sample_id=${sampleId}` : "";
         const scoreNote = formatScoreNote(entry);
         return `- ${index + 1}. ${entry.uri}${sampleNote}${scoreNote} (${action})`;

package/src/server/tools/register-project-tools.js

@@ -83,7 +83,7 @@ export function registerProjectTools({
         "",
         "WHEN NOT TO USE:",
         "- If you do not have a sample_id or resource_uri yet, call list_samples or search first to discover one.",
-        "- For doc:// URIs, use resources/read instead (this tool only handles sample:// URIs).",
+        "- For doc:// URIs, use read_document instead (this tool only handles sample:// URIs).",
         "- If the user just wants a quick code snippet, use get_quickstart instead.",
         "",
         "PARAMETERS:",
@@ -137,7 +137,7 @@ export function registerProjectTools({
             isError: true,
             content: [{
               type: "text",
-              text: "resource_uri must use the sample:// scheme. For doc:// URIs, use resources/read instead."
+              text: "resource_uri must use the sample:// scheme. For doc:// URIs, call read_document with the exact uri instead."
             }]
           };
         }

package/src/server/transports/http.js

@@ -1,6 +1,8 @@
 import { createServer as createHttpServer } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { logEvent } from "../../observability/logging.js";
+import { attachRequestLogging, buildHttpRequestContext } from "../../observability/request-logging.js";
+import { closeRequestLogFile } from "../../observability/request-log-file.js";
 
 async function startHttpServer({
   host,
@@ -74,9 +76,10 @@ async function startHttpServer({
 
     try {
       server = createServer();
-      transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: undefined
-      });
+      transport = attachRequestLogging(
+        new StreamableHTTPServerTransport({ sessionIdGenerator: undefined }),
+        buildHttpRequestContext(req)
+      );
       await server.connect(transport);
       await transport.handleRequest(req, res);
     } catch (error) {
@@ -110,6 +113,7 @@ async function startHttpServer({
     await new Promise((resolve) => {
       httpServer.close(() => resolve());
     });
+    await closeRequestLogFile();
     process.exit(0);
   };
 

package/src/server/transports/stdio.js

@@ -1,10 +1,11 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { logEvent } from "../../observability/logging.js";
+import { attachRequestLogging } from "../../observability/request-logging.js";
 
 async function startStdioServer({ createServer }) {
   logEvent("transport", "server_start", { mode: "stdio" });
   const server = createServer();
-  const transport = new StdioServerTransport();
+  const transport = attachRequestLogging(new StdioServerTransport(), { transport: "stdio" });
   await server.connect(transport);
   return { server, transport };
 }