--- title: "把文件變成 AI 能用的資料：PreciseMD 文檔解析、NAS 串接與 MCP／CLI 整合" description: "四種使用情境：於 Playground 上傳檔案解析、串接 NAS 批次處理、以 MCP 讓 AI Agent 呼叫工具，以及以 CLI 整合至腳本與排程" canonical_url: "https://docs.ardge.com/zh-tw/knowledge/precisemd/mcp-cli-integration" --- # 把文件變成 AI 能用的資料：PreciseMD 文檔解析、NAS 串接與 MCP／CLI 整合 > 四種使用情境：於 Playground 上傳檔案解析、串接 NAS 批次處理、以 MCP 讓 AI Agent 呼叫工具，以及以 CLI 整合至腳本與排程 ## Overview PreciseMD 是 ARX 平台上的文件解析應用，能將圖片、PDF、Excel、PowerPoint 裡的文字與圖表精準抽取出來，轉換成 AI 知識庫可以直接使用的資料。 知識庫的品質取決於來源資料的精準度：解析越完整，AI 於搜尋與生成答案時越不容易出錯，員工與客戶也越能查到正確的資訊。 本文涵蓋四種使用情境，各情境彼此獨立，可依需求選讀： - **情境 1 · 上傳檔案解析**：將文件送入 PreciseMD，取得結構化的圖文內容 - **情境 2 · 串接 NAS**：連接既有檔案系統，批次處理既有文件 - **情境 3 · MCP 整合**：讓 AI Agent 自動探索並呼叫 PreciseMD 的工具 - **情境 4 · CLI 整合**：將解析能力整合至腳本、排程或 CI 流程 ## 適用產品 - ARX OS 1.0 及以上版本 - PreciseMD 1.0 及以上版本 ## 前置準備 開始之前，請先確認以下兩項： - 已從 App Market 安裝 PreciseMD - 您的帳號具備 PreciseMD 的存取權限，能於桌面看到此應用程式 --- ## 情境 1. 上傳檔案進行解析，取得結構化的圖文內容 此情境適用於手邊有零散檔案、需先確認解析效果的狀況。整段流程於 Playground 頁面完成，無須任何設定。 ### 1. 上傳檔案 1. 開啟 PreciseMD，前往 Playground 頁面 2. 點擊「Source Documents」區塊的 Upload 按鈕 3. 選取要解析的檔案，或將檔案拖曳到方塊中 4. 點擊上傳 > **支援格式**：PDF、JPG、PNG、WEBP、BMP、TIFF、DOCX、XLSX、PPTX > **單次上限**：100 份檔案 ### 2. 執行檔案解析 1. 在「Source Documents」區塊，勾選要解析的檔案 2. 點擊下方的「RUN」按鈕，開始解析 #### 複雜結構文件：啟用進階視覺解析模式 版面複雜的文件（例如財務報表、進口報關資料）可啟用**進階視覺解析模式**。系統將透過視覺模型重新校正解析結果，藉此提升準確度。 啟用後可另以文字補充解析提示，說明文件的版面結構，或指定需特別留意的重點欄位。提示越具體，校正後的結果越貼近實際用途。 > ⚠️ **會增加解析時間** > 啟用後每頁約增加 5 秒，檔案量大時請預留時間。 ### 3. 檢視解析結果 1. 在「Run History」區塊，點擊要查看的檔案 2. 畫面跳出彈窗，提供以下四種檢視方式： - **Original**：原始檔案格式 - **Bounding Box**：在原檔案上圈選出被解析的範圍 - **Preview**：渲染顯示解析出的 Markdown 文件 - **Markdown**：以 Markdown 語法呈現解析結果 --- ## 情境 2. 串接 NAS 設定批次解析任務，處理企業既有的檔案 企業文件若已集中存放於 NAS，無須逐一手動上傳。PreciseMD 可透過 SMB 協定直接連接 NAS 讀取檔案，並將解析結果寫入指定的另一個資料夾；原始資料維持不動，知識庫的來源資料同時建立完成。 ### 1. 設定 NAS 連線 1. 開啟 PreciseMD，前往 Data Source 2. 點擊「Add Connection」按鈕 3. 輸入連線名稱、NAS IP、帳號密碼，並選擇 Shared folder ### 2. 建立解析任務 1. 開啟 PreciseMD，前往 Task 2. 點擊「Add Task」按鈕 3. 設定 Task Name、Source Folder、Target Folder 各欄位的意義如下： - **Source Folder（來源資料夾）**：此任務要處理的原始資料位置 - **Target Folder（目的資料夾）**：解析後的結構化資料存放位置 - **Scan Path**：往下掃描的資料夾層數 - **Model Connection**：指定本次任務使用的模型，留空則採用系統預設模型 - **VLM & Prompt**：設定方式參考[複雜結構文件：啟用進階視覺解析模式](#%E8%A4%87%E9%9B%9C%E7%B5%90%E6%A7%8B%E6%96%87%E4%BB%B6%E5%95%9F%E7%94%A8%E9%80%B2%E9%9A%8E%E8%A6%96%E8%A6%BA%E8%A7%A3%E6%9E%90%E6%A8%A1%E5%BC%8F) ### 3. 執行解析 1. 開啟 PreciseMD，前往 Task 2. 在要執行的任務列，點擊「Run」按鈕開始解析 3. 等待該任務列的 Last Result 顯示 Completed --- ## 情境 3. AI Agent 透過 MCP 使用 PreciseMD 解析文件 前兩個情境皆由人於網頁介面操作。若需讓 AI Agent（Claude Code、Cursor，或企業自建的 Agent）自行解析文件、管理資料來源、追蹤批次任務，可透過 PreciseMD 的 **HTTP MCP** 介面整合這些能力。 整合後，Agent 可使用下列 11 個工具：
工具 用途 權限等級 資料來源限制
arcor_system_version 查詢系統版本 唯讀 —
arcor_list_capabilities 查詢目前 PAT 可用的工具 唯讀 —
arcor_run_ocr 解析單一檔案 一般 —
arcor_run_batch_ocr 對資料來源執行批次解析 一般 受限
arcor_get_job 查詢批次任務狀態與進度 唯讀 受限
arcor_cancel_job 取消執行中的批次任務 破壞性 受限
arcor_create_datasource 建立 SMB 資料來源 一般 —
arcor_list_datasources 列出資料來源 唯讀 受限
arcor_browse_datasource 瀏覽資料來源內的檔案 唯讀 受限
arcor_delete_datasource 刪除資料來源 破壞性 受限
arcor_list_prompts 列出可用的解析提示 唯讀 —
權限等級對應 PAT 的操作範圍：唯讀 PAT 只能使用「唯讀」工具，「破壞性」工具需要可刪除的 PAT。「受限」的工具只能操作 PAT 允許存取的資料來源，列表結果也只會出現這些資料來源。 > ⚠️ **開始之前，請先確認執行環境** > 上傳檔案走的是 REST 端點，**不是** MCP 工具呼叫。驅動 Agent 的環境必須能發出 HTTP 請求（`curl`、Python `requests`、或工作流引擎的 HTTP 節點皆可）。 > 純聊天介面若無法執行程式或發送 HTTP 請求，即無法使用單檔解析，因為沒有任何 MCP 工具能直接接收檔案內容。 ### 1. 建立 PAT 取得存取權限 MCP 連線透過 **PAT（Personal Access Token）** 驗證身分。PAT 由系統管理員建立，可替任一使用者帳號建立；一般使用者無法自行建立。 1. 以管理員帳號開啟 PreciseMD，前往 User Management 頁面 2. 在要授權的使用者的 Action 欄，點擊「Manage personal access tokens」 3. 在「Personal Access Tokens」彈窗中，點擊「Create」按鈕 4. 在「Create Personal Access Token」彈窗中，設定 Name、Action Scope、Resource Scope 與 Expires At（留空代表永不過期） 5. 取得產生的 Token > ⚠️ **請立即保存 Token** > Token 建立後請立刻存放到 Agent 啟動時能讀取的地方。若遺失，只能重新建立一組。 建立 PAT 時需要決定兩種權限範圍： - **操作範圍（Action Scope）**：決定這個 PAT 能執行哪一類操作，分為 Read only、Read and write、Read, write and delete - **資料存取範圍（Resource Scope）**：決定這個 PAT 能存取哪些資料來源。勾選「Grant all datasources」代表涵蓋現有與未來所有資料來源，也可以只指定個別資料來源；至少要選一個，否則無法建立 ### 2. 在 AI Agent 設定 MCP Server 請將下列連線資訊填入 Agent 的 MCP 設定：
項目 值
連線位址 /mcp
傳輸方式 Streamable HTTP
認證 Authorization: Bearer
單次請求上限 256 KB（僅計工具呼叫的參數，檔案內容不會經過這個端點）
> 💡 **如何取得 ** > 前往 ARX 桌面，於 PreciseMD 圖示上按右鍵，選擇以新分頁開啟，再從網址列複製協定、主機與連接埠，例如 `http://192.168.1.20:30002`。本文所有 `` 皆以此取代。 以 Claude Code 為例，將下列內容存成專案根目錄的 `.mcp.json`。第一次在該專案啟動 Claude Code 時，會詢問是否啟用此 MCP Server，選擇啟用即可。 ```json { "mcpServers": { "precisemd": { "type": "http", "url": "/mcp", "headers": { "Authorization": "Bearer " } } } } ``` #### 讓 Agent 載入 PreciseMD MCP skill `precisemd-mcp` skill 教 Agent 怎麼串接這些工具：檔案怎麼上傳、批次工作怎麼輪詢，以及每種錯誤代表什麼。每個 PreciseMD 安裝都會提供與自身版本相符的 skill，下載不需認證。 請將 `SKILLS` 設為 Agent 載入 skill 的目錄：Claude Code 是 `~/.claude/skills`，Codex、Cursor 與 GitHub Copilot 是 `~/.agents/skills`。 ```bash SKILLS=~/.claude/skills curl -fSL -o /tmp/mcp.zip "/api/v1/skills/mcp.zip" rm -rf "$SKILLS/precisemd-mcp" mkdir -p "$SKILLS" && unzip /tmp/mcp.zip -d "$SKILLS" ``` Windows 請改在 PowerShell 執行： ```powershell $skills = "$HOME\.claude\skills" Invoke-WebRequest -UseBasicParsing -Uri "/api/v1/skills/mcp.zip" -OutFile "$env:TEMP\mcp.zip" Remove-Item -Recurse -Force "$skills\precisemd-mcp" -ErrorAction SilentlyContinue Expand-Archive -Path "$env:TEMP\mcp.zip" -DestinationPath $skills ``` - **Claude Desktop 與 claude.ai**：在 **Customize > Skills** 直接上傳 `mcp.zip`，不要先解壓縮 - **自建的 Agent**：解壓縮後讓 Agent 讀取 `precisemd-mcp/SKILL.md`，它引用的檔案都在 `precisemd-mcp/` 資料夾裡 > ⚠️ **不要用檔案總管的「解壓縮全部」** > zip 裡只有一個 `precisemd-mcp/` 資料夾，Agent 會直接在 skill 目錄底下找這個資料夾。「解壓縮全部」會在外面多包一層以 zip 檔名命名的資料夾，Agent 就載入不了。 > 💡 **PreciseMD 升級後請重新下載 skill** > 上面的指令會先刪除舊資料夾再解壓縮，新版已移除的檔案才不會殘留。如果解壓縮失敗，錯誤訊息說下載的檔案不是 zip 檔，代表你的 PreciseMD 安裝還沒有提供這個下載方式。 ### 3. 上傳檔案並執行解析 單次 MCP 請求上限為 256 KB，因此**檔案內容不經過 MCP 通道**，改由獨立的 REST 端點上傳，再將取得的憑證交予工具使用。
項目 值
上傳端點 POST /api/v1/mcp/uploads
認證 與 MCP 連線相同的 PAT（Read only 的 PAT 無法上傳，將回傳 403）
檔案大小上限 100 MB
支援格式 PDF、JPG、PNG、WEBP、BMP、TIFF
傳送格式 application/octet-stream （直接送出檔案內容），或 multipart/form-data （欄位名稱為 file ）
上傳範例： ```bash curl -X POST /api/v1/mcp/uploads \ -H "Authorization: Bearer " \ -H "Content-Type: application/octet-stream" \ --data-binary @invoice.pdf ``` 回應的 `data.uploadToken` 交予 `arcor_run_ocr` 後，Agent 即可取得解析後的 Markdown。`uploadToken` 只能使用一次，未使用時約 15 分鐘後失效。兩種流程如下： **單檔解析**：上傳檔案（REST）→ `arcor_run_ocr`（MCP）→ 取得 Markdown **批次解析**（不需上傳）：`arcor_list_datasources` → `arcor_browse_datasource` → `arcor_run_batch_ocr` → 輪詢 `arcor_get_job` 批次解析的來源與目的路徑都是相對於共用資料夾根目錄的路徑，開頭不加 `/`，例如 `invoices/2026`。目的資料夾必須事先存在，MCP 工具不會自動建立。 --- ## 情境 4. AI Agent 透過 CLI 使用 PreciseMD 解析文件 CLI 為單一可執行檔，適合整合至腳本、排程任務、CI 流程，或供具備 shell 權限的 Agent 直接下達指令。其設計以自動化為前提：所有指令皆支援 `--json` 輸出，並以結束代碼分類錯誤，便於程式判斷後續處理。 指令總覽：
群組 指令
認證 auth login｜status｜logout 、 health 、 version
單檔解析 ocr 、 ocr result
資料來源 ds create｜list｜get｜update｜delete 、 ds browse｜upload｜download 、 ds create-dir｜test-connection
任務 task create｜list｜get｜update｜delete
工作 job trigger｜list｜status｜logs｜cancel
提示範本 prompt-template create｜list｜get｜update｜delete （可簡寫為 pt ）
Playground playground quick-upload｜quick-run 、 playground workspace …
通用參數：`--server `、`--json`、`--token `、`--config `、`--fields <欄位清單>` ### 1. 安裝 CLI 執行檔由 PreciseMD 伺服器直接提供，無須外部套件庫。下列指令將安裝至 `~/.local/bin`，無須 sudo 權限： ```bash export ARCOR_SERVER="" OS=$(uname -s | tr '[:upper:]' '[:lower:]') ARCH=$(uname -m); [ "$ARCH" = "x86_64" ] && ARCH="amd64"; [ "$ARCH" = "aarch64" ] && ARCH="arm64" mkdir -p "$HOME/.local/bin" curl -fSL -o "$HOME/.local/bin/arcor" \ "${ARCOR_SERVER}/api/v1/cli/download?os=${OS}&arch=${ARCH}" chmod +x "$HOME/.local/bin/arcor" export PATH="$HOME/.local/bin:$PATH" arcor version ``` 伺服器提供的執行檔涵蓋 Linux（amd64、arm64）、macOS（Apple Silicon，arm64）與 Windows（amd64）。Intel 晶片的 Mac 沒有對應版本。Windows 請改在瀏覽器開啟 `/api/v1/cli/download?os=windows&arch=amd64` 下載 `arcor.exe`。 #### 讓 Agent 載入 PreciseMD CLI skill Agent 操作 CLI 時，`precisemd-cli` skill 會教它常用的指令與參數，以及每個結束碼代表什麼。skill 名稱是 `precisemd-cli`，但指令仍是 `arcor`，設定檔仍在 `~/.arcor/`，環境變數仍是 `ARCOR_SERVER` 與 `ARCOR_TOKEN`。每個 PreciseMD 安裝都會提供與自身版本相符的 skill，下載不需認證。 請將 `SKILLS` 設為 Agent 載入 skill 的目錄：Claude Code 是 `~/.claude/skills`，Codex、Cursor 與 GitHub Copilot 是 `~/.agents/skills`。指令沿用上面設定的 `ARCOR_SERVER`。 ```bash SKILLS=~/.claude/skills curl -fSL -o /tmp/cli.zip "${ARCOR_SERVER}/api/v1/skills/cli.zip" rm -rf "$SKILLS/precisemd-cli" mkdir -p "$SKILLS" && unzip /tmp/cli.zip -d "$SKILLS" ``` Windows 請先在 PowerShell 設定 `ARCOR_SERVER`（`$env:ARCOR_SERVER = ""`），再執行： ```powershell $skills = "$HOME\.claude\skills" Invoke-WebRequest -UseBasicParsing -Uri "${env:ARCOR_SERVER}/api/v1/skills/cli.zip" -OutFile "$env:TEMP\cli.zip" Remove-Item -Recurse -Force "$skills\precisemd-cli" -ErrorAction SilentlyContinue Expand-Archive -Path "$env:TEMP\cli.zip" -DestinationPath $skills ``` - **Claude Desktop 與 claude.ai**：在 **Customize > Skills** 直接上傳 `cli.zip`，不要先解壓縮 - **自建的 Agent**：解壓縮後讓 Agent 讀取 `precisemd-cli/SKILL.md`，它引用的檔案都在 `precisemd-cli/` 資料夾裡 > ⚠️ **不要用檔案總管的「解壓縮全部」** > zip 裡只有一個 `precisemd-cli/` 資料夾，Agent 會直接在 skill 目錄底下找這個資料夾。「解壓縮全部」會在外面多包一層以 zip 檔名命名的資料夾，Agent 就載入不了。 > 💡 **PreciseMD 升級後請重新下載 skill** > 上面的指令會先刪除舊資料夾再解壓縮，新版已移除的檔案才不會殘留。如果解壓縮失敗，錯誤訊息說下載的檔案不是 zip 檔，代表你的 PreciseMD 安裝還沒有提供這個下載方式。 ### 2. 登入取得存取權限 CLI 使用 PAT 驗證身分。建立方式與情境 3 相同，請參考[建立 PAT 取得存取權限](#1-%E5%BB%BA%E7%AB%8B-pat-%E5%8F%96%E5%BE%97%E5%AD%98%E5%8F%96%E6%AC%8A%E9%99%90)。 ```bash # 儲存 PAT（自動化情境建議使用這種非互動方式） arcor auth login --server --token # 或改用管線傳入，避免 Token 留在指令歷史中 echo | arcor auth login --server # 或只設環境變數，不寫入本機檔案 export ARCOR_TOKEN= ``` 接著驗證： ```bash arcor auth status # 確認 PAT 仍然有效 arcor health # 確認伺服器連線正常 ``` - 設定檔存放於 `~/.arcor/config.yaml`（權限 0600），可以 `--config` 指定其他路徑 - 登入成功後，後續指令無須再帶 `--server` - `arcor auth logout` 只清除本機儲存的 PAT，**不會**在伺服器端撤銷 ### 3. 解析單一檔案 ```bash arcor ocr invoice.pdf # 直接輸出 Markdown arcor ocr invoice.pdf --output result.md # 寫入檔案 arcor ocr invoice.pdf --json # 輸出完整結構化 JSON arcor ocr invoice.pdf --timeout 15m # 自訂等待上限（預設 10 分鐘） arcor ocr invoice.pdf --async # 立即回傳 runId，不等待完成 arcor ocr result # 之後再取回結果 arcor ocr invoice.pdf --vlm --prompt "..." # 啟用進階視覺解析並附上解析提示 ``` `arcor ocr` 將自動完成上傳、執行、輪詢與輸出，為單檔解析最直接的方式。加上 `--quiet` 可關閉進度訊息，使輸出更適合程式解析。 > `arcor ocr` 支援 PDF、JPG、PNG、WebP、BMP、TIFF。Office 格式（DOCX、XLSX、PPTX）請改用網頁介面處理。 ### 4. 批次解析 批次解析由三個物件組成：**資料來源**（檔案位置）、**任務**（處理方式）、**工作**（單次實際執行）。 #### 建立來源與目的資料來源 ```bash arcor ds create --name "invoices-in" --scheme smb \ --ip 192.168.1.10 --user svc --password '***' --share invoices-in arcor ds create --name "invoices-out" --scheme smb \ --ip 192.168.1.10 --user svc --password '***' --share invoices-out ``` 回傳的 ID 將用於下一步，可透過 `--json | jq -r '.id'` 取出。 > ⚠️ **只能建立遠端類型的資料來源** > 例如 SMB。本機檔案系統的資料來源由系統管理，自行建立將回傳 403。 #### 建立任務 ```bash arcor task create \ --name "invoice-ocr" \ --prompt "Convert to Markdown faithfully" \ --source-datasource-id <來源 ID> --source-path "." \ --target-datasource-id <目的 ID> --target-path "." \ --enable-vlm \ --scan-depth 2 ``` - `--source-path`／`--target-path`：相對於共用資料夾根目錄的路徑，開頭不加 `/`；`.` 代表根目錄本身。目的資料夾必須事先存在，可用 `arcor ds create-dir <目的 ID> --path <路徑>` 建立 - `--prompt`：必須搭配 `--enable-vlm`，否則會被拒絕 - `--enable-vlm`：啟用進階視覺解析。解析時間較長，品質較佳 - `--scan-depth`：掃描的資料夾層數。`1` 只處理來源資料夾本身，`2` 再往下一層，依此類推；不指定或填 `0` 以下時為 10 層 #### 執行並監控 ```bash arcor job trigger # 觸發任務，回傳 jobId（JSON 欄位為 id） arcor job status # 查詢一次整體進度 arcor job logs # 每個檔案的處理結果 arcor job logs --status running # 目前正在處理哪個檔案 arcor job logs --status failed # 只看失敗的檔案 ``` #### 輸出檔案的命名規則 PDF 與圖片的每一頁會產生一個 `.md` 與一個 `.jpg`；DOCX、PPTX 只產生 `.md`： ```text report.pdf → report_pdf_page_001.md、report_pdf_page_001.jpg sub/dir/invoice.pdf → sub/dir/invoice_pdf_page_001.md、… ``` 格式為 `{檔名}_{副檔名}_page_{頁碼}.md`，目的資料夾會保留來源的子目錄結構。若頁面中含有圖片（產品照、圖表等），會另存到同層的 `imgs/` 資料夾，Markdown 以 `` 引用。 每個 `.md` 檔開頭皆有 YAML frontmatter，記錄來源路徑、頁碼、處理時間、是否啟用 VLM、檔案雜湊等資訊，便於下游 RAG 系統索引。 驗證輸出： ```bash arcor ds browse <目的 ID> --path "." --json | jq '.items[].name' ``` ### 5. 自動化時的注意事項 錯誤以結束代碼分類，方便腳本判斷後續處理：
結束代碼 意義 建議處理
0 成功 —
1 參數或輸入錯誤 以 <指令> --help 檢查參數
2 認證失敗（401／403） 不可自動重試 。PAT 已失效或權限不足，需重新取得 PAT 後執行 arcor auth login
3 伺服器錯誤（5xx） 延遲後重試
4 網路錯誤（連不上伺服器、請求逾時） 檢查伺服器位址，以退避策略重試
`arcor ocr` 等待超過 `--timeout` 時回傳 `1`，錯誤訊息會附上 `arcor ocr result `，照著執行即可接續取回結果，不必重新上傳。 供 Agent 使用 CLI 時，建議遵守下列事項： - **一律加上 --json**：表格輸出供人閱讀，程式無法穩定解析 - **以 --fields 縮小輸出**：例如 `--fields id,name,status`，僅取所需欄位可節省 context - **沒有 --dry-run**：`create`／`update`／`delete` 將立即生效。刪改之前請先以 `get ` 確認目標正確 - **不要混用 --from-json 與個別參數**：CLI 將直接拒絕此組合 ## Sitemap See the full [sitemap](https://docs.ardge.com/sitemap.md) for all pages.