@echofiles/echo-pdf 0.3.0 → 0.3.1

package/README.md

@@ -88,6 +88,33 @@ echo-pdf mcp tools
 echo-pdf mcp call --tool file_ops --args '{"op":"list"}'
 ```
 
+### 3.1.1 纯 MCP 场景推荐流程（本地 PDF）
+
+远端 MCP server 无法直接读取你本机文件路径。推荐两步：
+
+1. 先通过 HTTP 上传本地 PDF，拿到 `fileId`
+2. 再用 MCP 工具传 `fileId` 调用
+
+示例：
+
+```bash
+curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/api/files/upload \
+  -F 'file=@./input.pdf'
+
+echo-pdf mcp call --tool pdf_extract_pages --args '{"fileId":"<FILE_ID>","pages":[1]}'
+```
+
+### 3.1.2 不上传文件的 URL ingest 流程
+
+如果 PDF 已经在公网可访问，直接传 `url`：
+
+```bash
+echo-pdf mcp call --tool pdf_extract_pages --args '{
+  "url":"https://example.com/sample.pdf",
+  "pages":[1]
+}'
+```
+
 ### 3.2 给客户端生成 MCP 配置片段
 
 ```bash
@@ -107,6 +134,12 @@ echo-pdf setup add json
 - `pdf_tables_to_latex`
 - `file_ops`
 
+MCP 输出策略：
+
+- `pdf_extract_pages` 在 MCP 下默认 `returnMode=url`（不传 `returnMode` 时生效）
+- MCP `text` 会对大字段做去二进制/截断，避免把大段 base64 塞进上下文
+- 二进制结果请优先使用 `resource_link` 中的下载地址
+
 ## 4. Web UI 使用
 
 打开：
@@ -183,6 +216,7 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
 - `agent.defaultProvider`
 - `agent.defaultModel`
 - `service.publicBaseUrl`
+- `service.fileGet.cacheTtlSeconds`
 - `service.maxPdfBytes`
 - `service.storage.maxFileBytes`
 - `service.storage.maxTotalBytes`
@@ -205,6 +239,8 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
 - `ECHO_PDF_DEFAULT_PROVIDER`
 - `ECHO_PDF_DEFAULT_MODEL`
 - `ECHO_PDF_PUBLIC_BASE_URL`（可选，强制 artifacts 生成外部可访问绝对 URL）
+- `ECHO_PDF_FILE_GET_CACHE_TTL_SECONDS`（可选，`/api/files/get` 缓存秒数，`0` 表示 `no-store`）
+- `ECHO_PDF_FILE_GET_AUTH_HEADER` + `ECHO_PDF_FILE_GET_AUTH_ENV`（可选，启用下载端点 header 鉴权）
 - `ECHO_PDF_MCP_KEY`（可选，启用 MCP 鉴权）
 - `ECHO_PDF_WORKER_NAME`（CLI 默认 URL 推导）
 
@@ -263,3 +299,12 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
     "arguments":{"fileId":"<FILE_ID>","pages":[1],"returnMode":"url"}
   }'
 ```
+
+### 8.4 错误码语义
+
+- 客户端输入错误返回稳定 `4xx + code`，例如：
+  - `PAGES_REQUIRED`（400）
+  - `PAGE_OUT_OF_RANGE`（400）
+  - `MISSING_FILE_INPUT`（400）
+  - `FILE_NOT_FOUND`（404）
+- 服务端故障返回 `5xx`。

package/echo-pdf.config.json

@@ -2,6 +2,9 @@
   "service": {
     "name": "echo-pdf",
     "publicBaseUrl": "https://echo-pdf.echofilesai.workers.dev",
+    "fileGet": {
+      "cacheTtlSeconds": 300
+    },
     "maxPdfBytes": 10000000,
     "maxPagesPerRequest": 20,
     "defaultRenderScale": 2,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@echofiles/echo-pdf",
   "description": "MCP-first PDF agent on Cloudflare Workers with CLI and web demo.",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "publishConfig": {
     "access": "public"

package/src/http-error.ts

@@ -0,0 +1,21 @@
+export class HttpError extends Error {
+  readonly status: number
+  readonly code: string
+  readonly details?: unknown
+
+  constructor(status: number, code: string, message: string, details?: unknown) {
+    super(message)
+    this.status = status
+    this.code = code
+    this.details = details
+  }
+}
+
+export const badRequest = (code: string, message: string, details?: unknown): HttpError =>
+  new HttpError(400, code, message, details)
+
+export const notFound = (code: string, message: string, details?: unknown): HttpError =>
+  new HttpError(404, code, message, details)
+
+export const unprocessable = (code: string, message: string, details?: unknown): HttpError =>
+  new HttpError(422, code, message, details)

package/src/index.ts

@@ -61,6 +61,21 @@ const asObj = (value: unknown): JsonObject =>
 const resolvePublicBaseUrl = (request: Request, configured?: string): string =>
   typeof configured === "string" && configured.length > 0 ? configured : request.url
 
+const sanitizeDownloadFilename = (filename: string): string => {
+  const cleaned = filename
+    .replace(/[\r\n"]/g, "")
+    .replace(/[^\x20-\x7E]+/g, "")
+    .trim()
+  return cleaned.length > 0 ? cleaned : "download.bin"
+}
+
+const isFileGetAuthorized = (request: Request, env: Env, config: { authHeader?: string; authEnv?: string }): boolean => {
+  if (!config.authHeader || !config.authEnv) return true
+  const required = env[config.authEnv]
+  if (typeof required !== "string" || required.length === 0) return true
+  return request.headers.get(config.authHeader) === required
+}
+
 const sseResponse = (stream: ReadableStream<Uint8Array>): Response =>
   new Response(stream, {
     headers: {
@@ -147,6 +162,10 @@ export default {
           version: config.mcp.version,
           authHeader: config.mcp.authHeader ?? null,
         },
+        fileGet: {
+          authHeader: config.service.fileGet?.authHeader ?? null,
+          cacheTtlSeconds: config.service.fileGet?.cacheTtlSeconds ?? 300,
+        },
       })
     }
 
@@ -304,6 +323,10 @@ export default {
     }
 
     if (request.method === "GET" && url.pathname === "/api/files/get") {
+      const fileGetConfig = config.service.fileGet ?? {}
+      if (!isFileGetAuthorized(request, env, fileGetConfig)) {
+        return json({ error: "Unauthorized", code: "UNAUTHORIZED" }, 401)
+      }
       const fileId = url.searchParams.get("fileId") || ""
       if (!fileId) return json({ error: "Missing fileId" }, 400)
       const file = await fileStore.get(fileId)
@@ -311,9 +334,13 @@ export default {
       const download = url.searchParams.get("download") === "1"
       const headers = new Headers()
       headers.set("Content-Type", file.mimeType)
-      headers.set("Cache-Control", "no-store")
+      const cacheTtl = Number(fileGetConfig.cacheTtlSeconds ?? 300)
+      const cacheControl = cacheTtl > 0
+        ? `public, max-age=${Math.floor(cacheTtl)}, s-maxage=${Math.floor(cacheTtl)}`
+        : "no-store"
+      headers.set("Cache-Control", cacheControl)
       if (download) {
-        headers.set("Content-Disposition", `attachment; filename=\"${file.filename.replace(/\"/g, "")}\"`)
+        headers.set("Content-Disposition", `attachment; filename=\"${sanitizeDownloadFilename(file.filename)}\"`)
       }
       return new Response(file.bytes, { status: 200, headers })
     }

package/src/mcp-server.ts

@@ -48,6 +48,16 @@ const maybeAuthorized = (request: Request, env: Env, config: EchoPdfConfig): boo
 const resolvePublicBaseUrl = (request: Request, configured?: string): string =>
   typeof configured === "string" && configured.length > 0 ? configured : request.url
 
+const prepareMcpToolArgs = (toolName: string, args: Record<string, unknown>): Record<string, unknown> => {
+  if (toolName === "pdf_extract_pages") {
+    const mode = typeof args.returnMode === "string" ? args.returnMode : ""
+    if (!mode) {
+      return { ...args, returnMode: "url" }
+    }
+  }
+  return args
+}
+
 export const handleMcpRequest = async (
   request: Request,
   env: Env,
@@ -103,7 +113,7 @@ export const handleMcpRequest = async (
   }
 
   const toolName = typeof params.name === "string" ? params.name : ""
-  const args = asObj(params.arguments)
+  const args = prepareMcpToolArgs(toolName, asObj(params.arguments))
   if (!toolName) {
     return err(id, -32602, "Invalid params: name is required", {
       code: "INVALID_PARAMS",

package/src/pdf-agent.ts

@@ -2,6 +2,7 @@ import type { Env, FileStore, ReturnMode } from "./types"
 import type { AgentTraceEvent, EchoPdfConfig, PdfOperationRequest } from "./pdf-types"
 import { resolveModelForProvider, resolveProviderAlias } from "./agent-defaults"
 import { fromBase64, normalizeReturnMode, toDataUrl } from "./file-utils"
+import { badRequest, notFound, unprocessable } from "./http-error"
 import { extractPdfPageText, getPdfPageCount, renderPdfPageToPng, toBytes } from "./pdfium-engine"
 import { visionRecognize } from "./provider-client"
 
@@ -22,11 +23,20 @@ const traceStep = (
 }
 
 const ensurePages = (pages: ReadonlyArray<number>, pageCount: number, maxPages: number): number[] => {
-  if (pages.length === 0) throw new Error("At least one page is required")
-  if (pages.length > maxPages) throw new Error(`Page count exceeds maxPagesPerRequest (${maxPages})`)
+  if (pages.length === 0) throw badRequest("PAGES_REQUIRED", "At least one page is required")
+  if (pages.length > maxPages) {
+    throw badRequest("TOO_MANY_PAGES", `Page count exceeds maxPagesPerRequest (${maxPages})`, {
+      maxPagesPerRequest: maxPages,
+      providedPages: pages.length,
+    })
+  }
   for (const page of pages) {
     if (!Number.isInteger(page) || page < 1 || page > pageCount) {
-      throw new Error(`Page ${page} out of range 1..${pageCount}`)
+      throw badRequest("PAGE_OUT_OF_RANGE", `Page ${page} out of range 1..${pageCount}`, {
+        page,
+        min: 1,
+        max: pageCount,
+      })
     }
   }
   return [...new Set(pages)].sort((a, b) => a - b)
@@ -45,7 +55,7 @@ export const ingestPdfFromPayload = async (
   if (input.fileId) {
     const existing = await opts.fileStore.get(input.fileId)
     if (!existing) {
-      throw new Error(`File not found: ${input.fileId}`)
+      throw notFound("FILE_NOT_FOUND", `File not found: ${input.fileId}`, { fileId: input.fileId })
     }
     return {
       id: existing.id,
@@ -59,7 +69,11 @@ export const ingestPdfFromPayload = async (
 
   if (input.url) {
     traceStep(opts, "start", "file.fetch.url", { url: input.url })
-    bytes = await toBytes(input.url)
+    try {
+      bytes = await toBytes(input.url)
+    } catch (error) {
+      throw badRequest("URL_FETCH_FAILED", `Unable to fetch PDF from url: ${error instanceof Error ? error.message : String(error)}`)
+    }
     try {
       const u = new URL(input.url)
       filename = decodeURIComponent(u.pathname.split("/").pop() || filename)
@@ -74,10 +88,13 @@ export const ingestPdfFromPayload = async (
   }
 
   if (!bytes) {
-    throw new Error("Missing file input. Provide fileId, url or base64")
+    throw badRequest("MISSING_FILE_INPUT", "Missing file input. Provide fileId, url or base64")
   }
   if (bytes.byteLength > config.service.maxPdfBytes) {
-    throw new Error(`PDF exceeds max size (${config.service.maxPdfBytes} bytes)`)
+    throw badRequest("PDF_TOO_LARGE", `PDF exceeds max size (${config.service.maxPdfBytes} bytes)`, {
+      maxPdfBytes: config.service.maxPdfBytes,
+      sizeBytes: bytes.byteLength,
+    })
   }
 
   const meta = await opts.fileStore.put({
@@ -164,7 +181,7 @@ export const runPdfAgent = async (
   const providerAlias = resolveProviderAlias(config, request.provider)
   const model = resolveModelForProvider(config, providerAlias, request.model)
   if (!model) {
-    throw new Error("model is required for OCR or table extraction; set agent.defaultModel")
+    throw badRequest("MODEL_REQUIRED", "model is required for OCR or table extraction; set agent.defaultModel")
   }
 
   if (request.operation === "ocr_pages") {
@@ -216,7 +233,9 @@ export const runPdfAgent = async (
     })
     const latex = extractTabularLatex(rawLatex)
     if (!latex) {
-      throw new Error(`table extraction did not return valid LaTeX tabular for page ${page}`)
+      throw unprocessable("TABLE_LATEX_MISSING", `table extraction did not return valid LaTeX tabular for page ${page}`, {
+        page,
+      })
     }
     tables.push({ page, latex })
     traceStep(opts, "end", "table.page", { page, chars: latex.length })

package/src/pdf-config.ts

@@ -37,6 +37,9 @@ const validateConfig = (config: EchoPdfConfig): EchoPdfConfig => {
   ) {
     throw new Error("service.publicBaseUrl must start with http:// or https://")
   }
+  if (typeof config.service.fileGet?.cacheTtlSeconds === "number" && config.service.fileGet.cacheTtlSeconds < 0) {
+    throw new Error("service.fileGet.cacheTtlSeconds must be >= 0")
+  }
   if (!Number.isFinite(config.service.storage.maxFileBytes) || config.service.storage.maxFileBytes <= 0) {
     throw new Error("service.storage.maxFileBytes must be positive")
   }
@@ -73,6 +76,9 @@ export const loadEchoPdfConfig = (env: Env): EchoPdfConfig => {
   const providerOverride = env.ECHO_PDF_DEFAULT_PROVIDER
   const modelOverride = env.ECHO_PDF_DEFAULT_MODEL
   const publicBaseUrlOverride = env.ECHO_PDF_PUBLIC_BASE_URL
+  const fileGetAuthHeaderOverride = env.ECHO_PDF_FILE_GET_AUTH_HEADER
+  const fileGetAuthEnvOverride = env.ECHO_PDF_FILE_GET_AUTH_ENV
+  const fileGetCacheTtlOverride = env.ECHO_PDF_FILE_GET_CACHE_TTL_SECONDS
   const withOverrides: EchoPdfConfig = {
     ...resolved,
     service: {
@@ -81,6 +87,23 @@ export const loadEchoPdfConfig = (env: Env): EchoPdfConfig => {
         typeof publicBaseUrlOverride === "string" && publicBaseUrlOverride.trim().length > 0
           ? publicBaseUrlOverride.trim()
           : resolved.service.publicBaseUrl,
+      fileGet: {
+        authHeader:
+          typeof fileGetAuthHeaderOverride === "string" && fileGetAuthHeaderOverride.trim().length > 0
+            ? fileGetAuthHeaderOverride.trim()
+            : resolved.service.fileGet?.authHeader,
+        authEnv:
+          typeof fileGetAuthEnvOverride === "string" && fileGetAuthEnvOverride.trim().length > 0
+            ? fileGetAuthEnvOverride.trim()
+            : resolved.service.fileGet?.authEnv,
+        cacheTtlSeconds: (() => {
+          if (typeof fileGetCacheTtlOverride === "string" && fileGetCacheTtlOverride.trim().length > 0) {
+            const value = Number(fileGetCacheTtlOverride)
+            return Number.isFinite(value) && value >= 0 ? Math.floor(value) : resolved.service.fileGet?.cacheTtlSeconds
+          }
+          return resolved.service.fileGet?.cacheTtlSeconds
+        })(),
+      },
     },
     agent: {
       ...resolved.agent,

package/src/pdf-types.ts

@@ -23,6 +23,11 @@ export interface EchoPdfConfig {
   readonly service: {
     readonly name: string
     readonly publicBaseUrl?: string
+    readonly fileGet?: {
+      readonly authHeader?: string
+      readonly authEnv?: string
+      readonly cacheTtlSeconds?: number
+    }
     readonly maxPdfBytes: number
     readonly maxPagesPerRequest: number
     readonly defaultRenderScale: number

package/src/r2-file-store.ts

@@ -79,20 +79,7 @@ export class R2FileStore implements FileStore {
   }
 
   async list(): Promise<ReadonlyArray<StoredFileMeta>> {
-    const listed = await this.bucket.list({ prefix: PREFIX, limit: 1000 })
-    return listed.objects.map((obj) => {
-      const meta = (obj.customMetadata ?? {}) as MetaFields
-      const createdAt = parseCreatedAt(meta.createdAt, obj.uploaded)
-      const filename = meta.filename ?? toId(obj.key)
-      const mimeType = meta.mimeType ?? obj.httpMetadata?.contentType ?? "application/octet-stream"
-      return {
-        id: toId(obj.key),
-        filename,
-        mimeType,
-        sizeBytes: obj.size,
-        createdAt,
-      }
-    })
+    return await this.listAllFiles()
   }
 
   async delete(fileId: string): Promise<boolean> {
@@ -101,7 +88,7 @@ export class R2FileStore implements FileStore {
   }
 
   async stats(): Promise<unknown> {
-    const files = await this.list()
+    const files = await this.listAllFiles()
     const totalBytes = files.reduce((sum, file) => sum + file.sizeBytes, 0)
     return {
       backend: "r2",
@@ -114,17 +101,24 @@ export class R2FileStore implements FileStore {
   }
 
   async cleanup(): Promise<unknown> {
-    const before = await this.list()
-    const deletedExpired = await this.deleteExpired(before)
-    const afterExpired = await this.list()
-    const deletedEvicted = await this.evictIfNeeded(afterExpired, 0)
-    const after = await this.list()
+    const files = await this.listAllFiles()
+    const expired = files.filter((f) => isExpired(f.createdAt, this.policy.ttlHours))
+    const active = files.filter((f) => !isExpired(f.createdAt, this.policy.ttlHours))
+    if (expired.length > 0) {
+      await this.bucket.delete(expired.map((f) => toKey(f.id)))
+    }
+    const evict = this.pickEvictions(active, 0)
+    if (evict.length > 0) {
+      await this.bucket.delete(evict.map((f) => toKey(f.id)))
+    }
+    const evictIds = new Set(evict.map((f) => f.id))
+    const after = active.filter((f) => !evictIds.has(f.id))
     const totalBytes = after.reduce((sum, file) => sum + file.sizeBytes, 0)
     return {
       backend: "r2",
       policy: this.policy,
-      deletedExpired,
-      deletedEvicted,
+      deletedExpired: expired.length,
+      deletedEvicted: evict.length,
       stats: {
         fileCount: after.length,
         totalBytes,
@@ -133,12 +127,19 @@ export class R2FileStore implements FileStore {
   }
 
   private async cleanupInternal(incomingBytes: number): Promise<void> {
-    const files = await this.list()
-    await this.deleteExpired(files)
-    const afterExpired = await this.list()
-    await this.evictIfNeeded(afterExpired, incomingBytes)
-    const finalFiles = await this.list()
-    const finalTotal = finalFiles.reduce((sum, file) => sum + file.sizeBytes, 0)
+    const files = await this.listAllFiles()
+    const expired = files.filter((f) => isExpired(f.createdAt, this.policy.ttlHours))
+    const active = files.filter((f) => !isExpired(f.createdAt, this.policy.ttlHours))
+    if (expired.length > 0) {
+      await this.bucket.delete(expired.map((f) => toKey(f.id)))
+    }
+    const evict = this.pickEvictions(active, incomingBytes)
+    if (evict.length > 0) {
+      await this.bucket.delete(evict.map((f) => toKey(f.id)))
+    }
+    const evictIds = new Set(evict.map((f) => f.id))
+    const remaining = active.filter((f) => !evictIds.has(f.id))
+    const finalTotal = remaining.reduce((sum, file) => sum + file.sizeBytes, 0)
     if (finalTotal + incomingBytes > this.policy.maxTotalBytes) {
       const err = new Error(
         `storage quota exceeded: total ${finalTotal} + incoming ${incomingBytes} > maxTotalBytes ${this.policy.maxTotalBytes}`
@@ -150,17 +151,10 @@ export class R2FileStore implements FileStore {
     }
   }
 
-  private async deleteExpired(files: ReadonlyArray<StoredFileMeta>): Promise<number> {
-    const expired = files.filter((f) => isExpired(f.createdAt, this.policy.ttlHours))
-    if (expired.length === 0) return 0
-    await this.bucket.delete(expired.map((f) => toKey(f.id)))
-    return expired.length
-  }
-
-  private async evictIfNeeded(files: ReadonlyArray<StoredFileMeta>, incomingBytes: number): Promise<number> {
+  private pickEvictions(files: ReadonlyArray<StoredFileMeta>, incomingBytes: number): StoredFileMeta[] {
     const totalBytes = files.reduce((sum, f) => sum + f.sizeBytes, 0)
     const projected = totalBytes + incomingBytes
-    if (projected <= this.policy.maxTotalBytes) return 0
+    if (projected <= this.policy.maxTotalBytes) return []
 
     const needFree = projected - this.policy.maxTotalBytes
     const candidates = [...files].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
@@ -172,9 +166,30 @@ export class R2FileStore implements FileStore {
       if (freed >= needFree) break
       if (evict.length >= this.policy.cleanupBatchSize) break
     }
-    if (evict.length === 0) return 0
-    await this.bucket.delete(evict.map((f) => toKey(f.id)))
-    return evict.length
+    return evict
   }
-}
 
+  private async listAllFiles(): Promise<StoredFileMeta[]> {
+    const files: StoredFileMeta[] = []
+    let cursor: string | undefined
+    while (true) {
+      const listed = await this.bucket.list({ prefix: PREFIX, limit: 1000, cursor })
+      for (const obj of listed.objects) {
+        const meta = (obj.customMetadata ?? {}) as MetaFields
+        const createdAt = parseCreatedAt(meta.createdAt, obj.uploaded)
+        const filename = meta.filename ?? toId(obj.key)
+        const mimeType = meta.mimeType ?? obj.httpMetadata?.contentType ?? "application/octet-stream"
+        files.push({
+          id: toId(obj.key),
+          filename,
+          mimeType,
+          sizeBytes: obj.size,
+          createdAt,
+        })
+      }
+      if (listed.truncated !== true || !listed.cursor) break
+      cursor = listed.cursor
+    }
+    return files
+  }
+}

package/src/response-schema.ts

@@ -15,6 +15,10 @@ export interface ToolOutputEnvelope {
   readonly artifacts: ToolArtifact[]
 }
 
+const MAX_TEXT_STRING = 1200
+const MAX_TEXT_ARRAY = 40
+const MAX_TEXT_DEPTH = 8
+
 const asObj = (value: unknown): JsonObject =>
   typeof value === "object" && value !== null && !Array.isArray(value)
     ? (value as JsonObject)
@@ -113,6 +117,38 @@ const summarizeData = (data: unknown): string => {
   return "Tool executed successfully."
 }
 
+const sanitizeString = (value: string): string => {
+  if (value.startsWith("data:")) {
+    const [head] = value.split(",", 1)
+    return `${head},<omitted>`
+  }
+  if (/^[A-Za-z0-9+/=]{300,}$/.test(value)) {
+    return `<base64 omitted len=${value.length}>`
+  }
+  if (value.length > MAX_TEXT_STRING) {
+    return `${value.slice(0, MAX_TEXT_STRING)}...(truncated ${value.length - MAX_TEXT_STRING} chars)`
+  }
+  return value
+}
+
+const sanitizeForText = (value: unknown, depth = 0): unknown => {
+  if (depth >= MAX_TEXT_DEPTH) return "<max-depth>"
+  if (typeof value === "string") return sanitizeString(value)
+  if (typeof value !== "object" || value === null) return value
+  if (Array.isArray(value)) {
+    const items = value.slice(0, MAX_TEXT_ARRAY).map((item) => sanitizeForText(item, depth + 1))
+    if (value.length > MAX_TEXT_ARRAY) {
+      items.push(`<truncated ${value.length - MAX_TEXT_ARRAY} items>`)
+    }
+    return items
+  }
+  const out: Record<string, unknown> = {}
+  for (const [key, nested] of Object.entries(value)) {
+    out[key] = sanitizeForText(nested, depth + 1)
+  }
+  return out
+}
+
 export const buildMcpContent = (envelope: ToolOutputEnvelope): Array<Record<string, unknown>> => {
   const lines: string[] = [summarizeData(envelope.data)]
   if (envelope.artifacts.length > 0) {
@@ -130,7 +166,7 @@ export const buildMcpContent = (envelope: ToolOutputEnvelope): Array<Record<stri
     }
   }
   lines.push("")
-  lines.push(JSON.stringify(envelope, null, 2))
+  lines.push(JSON.stringify(sanitizeForText(envelope), null, 2))
 
   const content: Array<Record<string, unknown>> = [{ type: "text", text: lines.join("\n") }]
   for (const artifact of envelope.artifacts) {