@echofiles/echo-pdf 0.4.0 → 0.4.1

package/README.md

@@ -144,6 +144,7 @@ echo-pdf setup add cursor
 echo-pdf setup add cline
 echo-pdf setup add windsurf
 echo-pdf setup add json
+echo-pdf setup add claude-desktop --mode stdio
 ```
 
 `setup add` 输出的是配置片段，把它合并到对应客户端的 MCP 配置文件。
@@ -283,6 +284,10 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
 - `ECHO_PDF_MCP_KEY`（可选，启用 MCP 鉴权）
 - `ECHO_PDF_WORKER_NAME`（CLI 默认 URL 推导）
 
+鉴权注意：
+
+- 如果配置了 `authHeader/authEnv` 但未注入对应 secret，服务会返回配置错误（fail-closed），不会默认放行。
+
 ## 7. 本地开发与测试
 
 安装与开发：

package/bin/echo-pdf.js

@@ -4,6 +4,8 @@ import fs from "node:fs"
 import os from "node:os"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
+import { downloadFile, postJson, uploadFile, withUploadedLocalFile } from "./lib/http.js"
+import { runMcpStdio } from "./lib/mcp-stdio.js"
 
 const CONFIG_DIR = path.join(os.homedir(), ".config", "echo-pdf-cli")
 const CONFIG_FILE = path.join(CONFIG_DIR, "config.json")
@@ -163,25 +165,6 @@ const buildProviderApiKeys = (config, profileName) => {
   return providerApiKeys
 }
 
-const postJson = async (url, payload, extraHeaders = {}) => {
-  const response = await fetch(url, {
-    method: "POST",
-    headers: { "Content-Type": "application/json", ...extraHeaders },
-    body: JSON.stringify(payload),
-  })
-  const text = await response.text()
-  let data
-  try {
-    data = JSON.parse(text)
-  } catch {
-    data = { raw: text }
-  }
-  if (!response.ok) {
-    throw new Error(`${response.status} ${JSON.stringify(data)}`)
-  }
-  return data
-}
-
 const print = (data) => {
   process.stdout.write(`${JSON.stringify(data, null, 2)}\n`)
 }
@@ -209,57 +192,6 @@ const buildMcpRequest = (id, method, params = {}) => ({
   params,
 })
 
-const uploadFile = async (serviceUrl, filePath) => {
-  const absPath = path.resolve(process.cwd(), filePath)
-  const bytes = fs.readFileSync(absPath)
-  const filename = path.basename(absPath)
-  const form = new FormData()
-  form.append("file", new Blob([bytes]), filename)
-  const response = await fetch(`${serviceUrl}/api/files/upload`, { method: "POST", body: form })
-  const text = await response.text()
-  let data
-  try {
-    data = JSON.parse(text)
-  } catch {
-    data = { raw: text }
-  }
-  if (!response.ok) {
-    throw new Error(`${response.status} ${JSON.stringify(data)}`)
-  }
-  return data
-}
-
-const downloadFile = async (serviceUrl, fileId, outputPath) => {
-  const response = await fetch(`${serviceUrl}/api/files/get?fileId=${encodeURIComponent(fileId)}&download=1`)
-  if (!response.ok) {
-    const text = await response.text()
-    throw new Error(`${response.status} ${text}`)
-  }
-  const bytes = Buffer.from(await response.arrayBuffer())
-  const absOut = path.resolve(process.cwd(), outputPath)
-  fs.mkdirSync(path.dirname(absOut), { recursive: true })
-  fs.writeFileSync(absOut, bytes)
-  return absOut
-}
-
-const withUploadedLocalFile = async (serviceUrl, tool, args) => {
-  const nextArgs = { ...(args || {}) }
-  if (tool.startsWith("pdf_")) {
-    const localPath = typeof nextArgs.path === "string"
-      ? nextArgs.path
-      : (typeof nextArgs.filePath === "string" ? nextArgs.filePath : "")
-    if (localPath && !nextArgs.fileId && !nextArgs.url && !nextArgs.base64) {
-      const upload = await uploadFile(serviceUrl, localPath)
-      const fileId = upload?.file?.id
-      if (!fileId) throw new Error(`upload failed for local path: ${localPath}`)
-      nextArgs.fileId = fileId
-      delete nextArgs.path
-      delete nextArgs.filePath
-    }
-  }
-  return nextArgs
-}
-
 const runDevServer = (port, host) => {
   const wranglerBin = path.resolve(__dirname, "../node_modules/.bin/wrangler")
   const wranglerArgs = ["dev", "--port", String(port), "--ip", host]
@@ -276,100 +208,13 @@ const runDevServer = (port, host) => {
   })
 }
 
-const mcpReadLoop = (onMessage, onError) => {
-  let buffer = Buffer.alloc(0)
-  let expectedLength = null
-  process.stdin.on("data", (chunk) => {
-    buffer = Buffer.concat([buffer, chunk])
-    while (true) {
-      if (expectedLength === null) {
-        const headerEnd = buffer.indexOf("\r\n\r\n")
-        if (headerEnd === -1) break
-        const headerRaw = buffer.slice(0, headerEnd).toString("utf-8")
-        const lines = headerRaw.split("\r\n")
-        const cl = lines.find((line) => line.toLowerCase().startsWith("content-length:"))
-        if (!cl) {
-          onError(new Error("Missing Content-Length"))
-          buffer = buffer.slice(headerEnd + 4)
-          continue
-        }
-        expectedLength = Number(cl.split(":")[1]?.trim() || "0")
-        buffer = buffer.slice(headerEnd + 4)
-      }
-      if (!Number.isFinite(expectedLength) || expectedLength < 0) {
-        onError(new Error("Invalid Content-Length"))
-        expectedLength = null
-        continue
-      }
-      if (buffer.length < expectedLength) break
-      const body = buffer.slice(0, expectedLength).toString("utf-8")
-      buffer = buffer.slice(expectedLength)
-      expectedLength = null
-      try {
-        const maybePromise = onMessage(JSON.parse(body))
-        if (maybePromise && typeof maybePromise.then === "function") {
-          maybePromise.catch(onError)
-        }
-      } catch (error) {
-        onError(error)
-      }
-    }
-  })
-}
-
-const mcpWrite = (obj) => {
-  const body = Buffer.from(JSON.stringify(obj))
-  const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`)
-  process.stdout.write(header)
-  process.stdout.write(body)
-}
-
-const runMcpStdio = async () => {
+const runMcpStdioCommand = async () => {
   const config = loadConfig()
-  const serviceUrl = config.serviceUrl
-  const headers = buildMcpHeaders()
-  mcpReadLoop(async (msg) => {
-    const method = msg?.method
-    const id = Object.hasOwn(msg || {}, "id") ? msg.id : null
-    if (msg?.jsonrpc !== "2.0" || typeof method !== "string") {
-      mcpWrite({ jsonrpc: "2.0", id, error: { code: -32600, message: "Invalid Request" } })
-      return
-    }
-    if (method === "notifications/initialized") return
-    if (method === "initialize" || method === "tools/list") {
-      const data = await postJson(`${serviceUrl}/mcp`, msg, headers)
-      mcpWrite(data)
-      return
-    }
-    if (method === "tools/call") {
-      try {
-        const tool = String(msg?.params?.name || "")
-        const args = (msg?.params?.arguments && typeof msg.params.arguments === "object")
-          ? msg.params.arguments
-          : {}
-        const preparedArgs = await withUploadedLocalFile(serviceUrl, tool, args)
-        const payload = {
-          ...msg,
-          params: {
-            ...(msg.params || {}),
-            arguments: preparedArgs,
-          },
-        }
-        const data = await postJson(`${serviceUrl}/mcp`, payload, headers)
-        mcpWrite(data)
-      } catch (error) {
-        mcpWrite({
-          jsonrpc: "2.0",
-          id,
-          error: { code: -32603, message: error instanceof Error ? error.message : String(error) },
-        })
-      }
-      return
-    }
-    const data = await postJson(`${serviceUrl}/mcp`, msg, headers)
-    mcpWrite(data)
-  }, (error) => {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+  await runMcpStdio({
+    serviceUrl: config.serviceUrl,
+    headers: buildMcpHeaders(),
+    postJson,
+    withUploadedLocalFile,
   })
 }
 
@@ -793,7 +638,7 @@ const main = async () => {
   }
 
   if (command === "mcp" && subcommand === "stdio") {
-    await runMcpStdio()
+    await runMcpStdioCommand()
     return
   }
 

package/bin/lib/http.js

@@ -0,0 +1,72 @@
+import fs from "node:fs"
+import path from "node:path"
+
+export const postJson = async (url, payload, extraHeaders = {}) => {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...extraHeaders },
+    body: JSON.stringify(payload),
+  })
+  const text = await response.text()
+  let data
+  try {
+    data = JSON.parse(text)
+  } catch {
+    data = { raw: text }
+  }
+  if (!response.ok) {
+    throw new Error(`${response.status} ${JSON.stringify(data)}`)
+  }
+  return data
+}
+
+export const uploadFile = async (serviceUrl, filePath) => {
+  const absPath = path.resolve(process.cwd(), filePath)
+  const bytes = fs.readFileSync(absPath)
+  const filename = path.basename(absPath)
+  const form = new FormData()
+  form.append("file", new Blob([bytes]), filename)
+  const response = await fetch(`${serviceUrl}/api/files/upload`, { method: "POST", body: form })
+  const text = await response.text()
+  let data
+  try {
+    data = JSON.parse(text)
+  } catch {
+    data = { raw: text }
+  }
+  if (!response.ok) {
+    throw new Error(`${response.status} ${JSON.stringify(data)}`)
+  }
+  return data
+}
+
+export const downloadFile = async (serviceUrl, fileId, outputPath) => {
+  const response = await fetch(`${serviceUrl}/api/files/get?fileId=${encodeURIComponent(fileId)}&download=1`)
+  if (!response.ok) {
+    const text = await response.text()
+    throw new Error(`${response.status} ${text}`)
+  }
+  const bytes = Buffer.from(await response.arrayBuffer())
+  const absOut = path.resolve(process.cwd(), outputPath)
+  fs.mkdirSync(path.dirname(absOut), { recursive: true })
+  fs.writeFileSync(absOut, bytes)
+  return absOut
+}
+
+export const withUploadedLocalFile = async (serviceUrl, tool, args) => {
+  const nextArgs = { ...(args || {}) }
+  if (tool.startsWith("pdf_")) {
+    const localPath = typeof nextArgs.path === "string"
+      ? nextArgs.path
+      : (typeof nextArgs.filePath === "string" ? nextArgs.filePath : "")
+    if (localPath && !nextArgs.fileId && !nextArgs.url && !nextArgs.base64) {
+      const upload = await uploadFile(serviceUrl, localPath)
+      const fileId = upload?.file?.id
+      if (!fileId) throw new Error(`upload failed for local path: ${localPath}`)
+      nextArgs.fileId = fileId
+      delete nextArgs.path
+      delete nextArgs.filePath
+    }
+  }
+  return nextArgs
+}

package/bin/lib/mcp-stdio.js

@@ -0,0 +1,99 @@
+const mcpReadLoop = (onMessage, onError) => {
+  let buffer = Buffer.alloc(0)
+  let expectedLength = null
+  process.stdin.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk])
+    while (true) {
+      if (expectedLength === null) {
+        const headerEnd = buffer.indexOf("\r\n\r\n")
+        if (headerEnd === -1) break
+        const headerRaw = buffer.slice(0, headerEnd).toString("utf-8")
+        const lines = headerRaw.split("\r\n")
+        const cl = lines.find((line) => line.toLowerCase().startsWith("content-length:"))
+        if (!cl) {
+          onError(new Error("Missing Content-Length"))
+          buffer = buffer.slice(headerEnd + 4)
+          continue
+        }
+        expectedLength = Number(cl.split(":")[1]?.trim() || "0")
+        buffer = buffer.slice(headerEnd + 4)
+      }
+      if (!Number.isFinite(expectedLength) || expectedLength < 0) {
+        onError(new Error("Invalid Content-Length"))
+        expectedLength = null
+        continue
+      }
+      if (buffer.length < expectedLength) break
+      const body = buffer.slice(0, expectedLength).toString("utf-8")
+      buffer = buffer.slice(expectedLength)
+      expectedLength = null
+      try {
+        const maybePromise = onMessage(JSON.parse(body))
+        if (maybePromise && typeof maybePromise.then === "function") {
+          maybePromise.catch(onError)
+        }
+      } catch (error) {
+        onError(error)
+      }
+    }
+  })
+}
+
+const mcpWrite = (obj) => {
+  const body = Buffer.from(JSON.stringify(obj))
+  const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`)
+  process.stdout.write(header)
+  process.stdout.write(body)
+}
+
+export const runMcpStdio = async (deps) => {
+  const {
+    serviceUrl,
+    headers,
+    postJson,
+    withUploadedLocalFile,
+  } = deps
+  mcpReadLoop(async (msg) => {
+    const method = msg?.method
+    const id = Object.hasOwn(msg || {}, "id") ? msg.id : null
+    if (msg?.jsonrpc !== "2.0" || typeof method !== "string") {
+      mcpWrite({ jsonrpc: "2.0", id, error: { code: -32600, message: "Invalid Request" } })
+      return
+    }
+    if (method === "notifications/initialized") return
+    if (method === "initialize" || method === "tools/list") {
+      const data = await postJson(`${serviceUrl}/mcp`, msg, headers)
+      mcpWrite(data)
+      return
+    }
+    if (method === "tools/call") {
+      try {
+        const tool = String(msg?.params?.name || "")
+        const args = (msg?.params?.arguments && typeof msg.params.arguments === "object")
+          ? msg.params.arguments
+          : {}
+        const preparedArgs = await withUploadedLocalFile(serviceUrl, tool, args)
+        const payload = {
+          ...msg,
+          params: {
+            ...(msg.params || {}),
+            arguments: preparedArgs,
+          },
+        }
+        const data = await postJson(`${serviceUrl}/mcp`, payload, headers)
+        mcpWrite(data)
+      } catch (error) {
+        mcpWrite({
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32603, message: error instanceof Error ? error.message : String(error) },
+        })
+      }
+      return
+    }
+    const data = await postJson(`${serviceUrl}/mcp`, msg, headers)
+    mcpWrite(data)
+  }, (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+  })
+}

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.4.0",
+  "version": "0.4.1",
   "type": "module",
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -69,11 +69,25 @@ const sanitizeDownloadFilename = (filename: string): string => {
   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 fileGetAuthState = (
+  request: Request,
+  env: Env,
+  config: { authHeader?: string; authEnv?: string }
+): { ok: true } | { ok: false; status: number; code: string; message: string } => {
+  if (!config.authHeader || !config.authEnv) return { ok: true }
   const required = env[config.authEnv]
-  if (typeof required !== "string" || required.length === 0) return true
-  return request.headers.get(config.authHeader) === required
+  if (typeof required !== "string" || required.length === 0) {
+    return {
+      ok: false,
+      status: 500,
+      code: "AUTH_MISCONFIGURED",
+      message: `file get auth is configured but env "${config.authEnv}" is missing`,
+    }
+  }
+  if (request.headers.get(config.authHeader) !== required) {
+    return { ok: false, status: 401, code: "UNAUTHORIZED", message: "Unauthorized" }
+  }
+  return { ok: true }
 }
 
 const sseResponse = (stream: ReadableStream<Uint8Array>): Response =>
@@ -188,7 +202,7 @@ export default {
           preferredProvider,
           typeof body.model === "string" ? body.model : undefined
         )
-        if (name.startsWith("pdf_")) {
+        if (name === "pdf_ocr_pages" || name === "pdf_tables_to_latex") {
           if (typeof args.provider !== "string" || args.provider.length === 0) {
             args.provider = preferredProvider
           }
@@ -221,7 +235,7 @@ export default {
         const models = await listProviderModels(config, env, provider, runtimeKeys)
         return json({ provider, models })
       } catch (error) {
-        return json({ error: toError(error) }, 500)
+        return jsonError(error, 500)
       }
     }
 
@@ -324,8 +338,9 @@ 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 auth = fileGetAuthState(request, env, fileGetConfig)
+      if (!auth.ok) {
+        return json({ error: auth.message, code: auth.code }, auth.status)
       }
       const fileId = url.searchParams.get("fileId") || ""
       if (!fileId) return json({ error: "Missing fileId" }, 400)

package/src/mcp-server.ts

@@ -38,11 +38,20 @@ const err = (
 const asObj = (v: unknown): Record<string, unknown> =>
   typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : {}
 
-const maybeAuthorized = (request: Request, env: Env, config: EchoPdfConfig): boolean => {
-  if (!config.mcp.authHeader || !config.mcp.authEnv) return true
+const authState = (
+  request: Request,
+  env: Env,
+  config: EchoPdfConfig
+): { ok: true } | { ok: false; status: number; message: string } => {
+  if (!config.mcp.authHeader || !config.mcp.authEnv) return { ok: true }
   const required = env[config.mcp.authEnv]
-  if (typeof required !== "string" || required.length === 0) return true
-  return request.headers.get(config.mcp.authHeader) === required
+  if (typeof required !== "string" || required.length === 0) {
+    return { ok: false, status: 500, message: `MCP auth is configured but env "${config.mcp.authEnv}" is missing` }
+  }
+  if (request.headers.get(config.mcp.authHeader) !== required) {
+    return { ok: false, status: 401, message: "Unauthorized" }
+  }
+  return { ok: true }
 }
 
 const resolvePublicBaseUrl = (request: Request, configured?: string): string =>
@@ -64,8 +73,9 @@ export const handleMcpRequest = async (
   config: EchoPdfConfig,
   fileStore: FileStore
 ): Promise<Response> => {
-  if (!maybeAuthorized(request, env, config)) {
-    return new Response("Unauthorized", { status: 401 })
+  const auth = authState(request, env, config)
+  if (!auth.ok) {
+    return new Response(auth.message, { status: auth.status })
   }
 
   let body: JsonRpcRequest
@@ -85,6 +95,9 @@ export const handleMcpRequest = async (
   if (typeof method !== "string" || method.length === 0) {
     return err(id, -32600, "Invalid Request: method is required")
   }
+  if (method.startsWith("notifications/")) {
+    return new Response(null, { status: 204 })
+  }
   const params = asObj(body.params)
 
   if (method === "initialize") {