@echofiles/echo-pdf 0.3.1 → 0.4.1

package/README.md

@@ -48,6 +48,13 @@ npm i -g @echofiles/echo-pdf
 echo-pdf init --service-url https://echo-pdf.echofilesai.workers.dev
 ```
 
+本地一键启动服务（daemon）：
+
+```bash
+echo-pdf dev --port 8788
+echo-pdf init --service-url http://127.0.0.1:8788
+```
+
 配置 API Key（仅保存在本机 CLI 配置，不会上报到服务端存储）：
 
 ```bash
@@ -115,6 +122,20 @@ echo-pdf mcp call --tool pdf_extract_pages --args '{
 }'
 ```
 
+### 3.1.3 stdio MCP（支持本地文件路径）
+
+stdio 模式会把本地 `path/filePath` 自动上传为 `fileId` 后再调用远端工具。
+
+```bash
+echo-pdf mcp stdio
+```
+
+生成 Claude Desktop/Cursor 等可用的 stdio 配置片段：
+
+```bash
+echo-pdf setup add claude-desktop --mode stdio
+```
+
 ### 3.2 给客户端生成 MCP 配置片段
 
 ```bash
@@ -123,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 配置文件。
@@ -172,6 +194,12 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/api/files/upload \
 
 返回中会拿到 `file.id`。
 
+CLI 等价命令：
+
+```bash
+echo-pdf file upload ./sample.pdf
+```
+
 ### 5.2 提取页面图片
 
 ```bash
@@ -185,6 +213,18 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
   }'
 ```
 
+CLI（支持直接传本地路径）：
+
+```bash
+echo-pdf call --tool pdf_extract_pages --args '{"path":"./sample.pdf","pages":[1],"returnMode":"url"}'
+```
+
+下载产物：
+
+```bash
+echo-pdf file get --file-id <FILE_ID> --out ./output.bin
+```
+
 ### 5.3 OCR
 
 ```bash
@@ -244,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

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
+import { spawn } from "node:child_process"
 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")
@@ -162,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`)
 }
@@ -208,6 +192,32 @@ const buildMcpRequest = (id, method, params = {}) => ({
   params,
 })
 
+const runDevServer = (port, host) => {
+  const wranglerBin = path.resolve(__dirname, "../node_modules/.bin/wrangler")
+  const wranglerArgs = ["dev", "--port", String(port), "--ip", host]
+  const cmd = fs.existsSync(wranglerBin) ? wranglerBin : "npx"
+  const args = fs.existsSync(wranglerBin) ? wranglerArgs : ["-y", "wrangler", ...wranglerArgs]
+  const child = spawn(cmd, args, {
+    stdio: "inherit",
+    env: process.env,
+    cwd: process.cwd(),
+  })
+  child.on("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal)
+    process.exit(code ?? 0)
+  })
+}
+
+const runMcpStdioCommand = async () => {
+  const config = loadConfig()
+  await runMcpStdio({
+    serviceUrl: config.serviceUrl,
+    headers: buildMcpHeaders(),
+    postJson,
+    withUploadedLocalFile,
+  })
+}
+
 const parseConfigValue = (raw, type = "auto") => {
   if (type === "string") return String(raw)
   if (type === "number") {
@@ -302,6 +312,7 @@ const usage = () => {
   process.stdout.write(`echo-pdf CLI\n\n`)
   process.stdout.write(`Commands:\n`)
   process.stdout.write(`  init [--service-url URL]\n`)
+  process.stdout.write(`  dev [--port 8788] [--host 127.0.0.1]\n`)
   process.stdout.write(`  provider set --provider <${PROVIDER_SET_NAMES.join("|")}> --api-key <KEY> [--profile name]\n`)
   process.stdout.write(`  provider use --provider <${PROVIDER_ALIASES.join("|")}> [--profile name]\n`)
   process.stdout.write(`  provider list [--profile name]\n`)
@@ -312,13 +323,29 @@ const usage = () => {
   process.stdout.write(`  model list [--profile name]\n`)
   process.stdout.write(`  tools\n`)
   process.stdout.write(`  call --tool <name> --args '<json>' [--provider alias] [--model model] [--profile name]\n`)
+  process.stdout.write(`  file upload <local.pdf>\n`)
+  process.stdout.write(`  file get --file-id <id> --out <path>\n`)
   process.stdout.write(`  mcp initialize\n`)
   process.stdout.write(`  mcp tools\n`)
   process.stdout.write(`  mcp call --tool <name> --args '<json>'\n`)
+  process.stdout.write(`  mcp stdio\n`)
   process.stdout.write(`  setup add <claude-desktop|claude-code|cursor|cline|windsurf|gemini|json>\n`)
 }
 
-const setupSnippet = (tool, serviceUrl) => {
+const setupSnippet = (tool, serviceUrl, mode = "http") => {
+  if (mode === "stdio") {
+    return {
+      mcpServers: {
+        "echo-pdf": {
+          command: "echo-pdf",
+          args: ["mcp", "stdio"],
+          env: {
+            ECHO_PDF_SERVICE_URL: serviceUrl,
+          },
+        },
+      },
+    }
+  }
   const transport = {
     type: "streamable-http",
     url: `${serviceUrl}/mcp`,
@@ -405,6 +432,14 @@ const main = async () => {
     return
   }
 
+  if (command === "dev") {
+    const port = typeof flags.port === "string" ? Number(flags.port) : 8788
+    const host = typeof flags.host === "string" ? flags.host : "127.0.0.1"
+    if (!Number.isFinite(port) || port <= 0) throw new Error("dev --port must be positive number")
+    runDevServer(Math.floor(port), host)
+    return
+  }
+
   if (command === "provider" && subcommand === "set") {
     const providerAlias = resolveProviderAliasInput(flags.provider)
     const apiKey = flags["api-key"]
@@ -538,15 +573,42 @@ const main = async () => {
     const tool = flags.tool
     if (typeof tool !== "string") throw new Error("call requires --tool")
     const args = typeof flags.args === "string" ? JSON.parse(flags.args) : {}
+    const preparedArgs = await withUploadedLocalFile(config.serviceUrl, tool, args)
     const provider = resolveProviderAlias(profile, flags.provider)
     const model = typeof flags.model === "string" ? flags.model : resolveDefaultModel(profile, provider)
     const providerApiKeys = buildProviderApiKeys(config, profileName)
-    const payload = buildToolCallRequest({ tool, args, provider, model, providerApiKeys })
+    const payload = buildToolCallRequest({ tool, args: preparedArgs, provider, model, providerApiKeys })
     const data = await postJson(`${config.serviceUrl}/tools/call`, payload)
     print(data)
     return
   }
 
+  if (command === "file") {
+    const action = rest[0] || ""
+    const config = loadConfig()
+    if (action === "upload") {
+      const filePath = rest[1]
+      if (!filePath) throw new Error("file upload requires a path")
+      const data = await uploadFile(config.serviceUrl, filePath)
+      print({
+        fileId: data?.file?.id || "",
+        filename: data?.file?.filename || path.basename(filePath),
+        sizeBytes: data?.file?.sizeBytes || 0,
+        file: data?.file || null,
+      })
+      return
+    }
+    if (action === "get") {
+      const fileId = typeof flags["file-id"] === "string" ? flags["file-id"] : ""
+      const out = typeof flags.out === "string" ? flags.out : ""
+      if (!fileId || !out) throw new Error("file get requires --file-id and --out")
+      const savedTo = await downloadFile(config.serviceUrl, fileId, out)
+      print({ ok: true, fileId, savedTo })
+      return
+    }
+    throw new Error("file command supports: upload|get")
+  }
+
   if (command === "mcp" && subcommand === "initialize") {
     const config = loadConfig()
     const data = await postJson(`${config.serviceUrl}/mcp`, buildMcpRequest(1, "initialize"), buildMcpHeaders())
@@ -575,11 +637,18 @@ const main = async () => {
     return
   }
 
+  if (command === "mcp" && subcommand === "stdio") {
+    await runMcpStdioCommand()
+    return
+  }
+
   if (command === "setup" && subcommand === "add") {
     const tool = rest[0]
     if (!tool) throw new Error("setup add requires tool name")
     const config = loadConfig()
-    print(setupSnippet(tool, config.serviceUrl))
+    const mode = typeof flags.mode === "string" ? flags.mode : "http"
+    if (!["http", "stdio"].includes(mode)) throw new Error("setup add --mode must be http|stdio")
+    print(setupSnippet(tool, config.serviceUrl, mode))
     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.3.1",
+  "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") {