Skip to main content
Glama
Handwritten PDF Vision

Handwritten PDF Vision

Handwritten PDF Vision — AI Agent Skill + MCP

License: MIT Version: 2.0.0 Python: 3.10+ PyMuPDF: 1.28.2 MCP: 1.30.0

繁體中文 | English

作者:海鮮稽查長 SeaFoodInspector

手寫 PDF 的兩種讀取路徑:抽取文字,以及透過 MCP 渲染頁面圖片交給 AI 視覺分析

省流:這個 skill 解決什麼?

特別適用客群 :

覺得每次都要把手寫筆記截圖一次並傳給 AI 分析很麻煩且佔用相簿空間,因此想讓 agent 不需要截圖就直接讀取使用手寫電子筆記 PDF 檔案的人。


改善 agent 直接讀取檔案中的手寫 PDF 會錯誤解讀的問題 :

由於大部分 Drive/PDF 工具只預設回傳文字字串,導致過程遺失手寫筆跡、公式排版、箭頭、顏色與圖像。因此,此專案結合 Agent Skills 指令與本機 MCP 渲染工具,將指定頁面的完整畫面交給目前 agent 的視覺模型分析手寫筆記、公式與圖形,就像平常把截圖交給 agent 看一樣,讓 agent 真正看到手寫 PDF 的畫面,有助於大幅改善分析準確度。


支援從 Google Drive、NAS、本機等來源取得 PDF (NAS 需先掛載為本機可讀取的檔案路徑)

原始 PDF 的授權下載網址/本機 PDF
    → MCP 在記憶體中讀取與渲染指定頁面
    → 直接回傳 MCP 圖片內容
    → agent 實際看圖後分析

Related MCP server: okraPDF PDF MCP server

安裝:技能與 MCP 都要設定

需要 Python 3.10+、可執行本機 stdio MCP 的 agent,以及會把 MCP 圖片內容交給視覺模型的客戶端。Drive 來源另外需要已授權的 Drive 連接器;本專案不包含 Drive 登入憑證。

  1. 安裝技能。有 Node.js/npx 時可執行:

    npx skills add SeaFoodInspector056/handwritten-pdf-vision --skill handwritten-pdf-vision

    也可以請 Codex 使用 skill-installer 安裝本 Repo 根目錄的技能,保留已有私人來源設定。

  2. 在安裝後的技能資料夾開啟 Windows PowerShell/VS Code 終端機,建立一次環境:

    py -m venv .venv
    .\.venv\Scripts\python.exe -m pip install -r requirements.txt
    .\.venv\Scripts\python.exe scripts/setup_mcp.py --register-codex

    需要 Codex CLI 可在終端機中呼叫。設定只新增本專案的 MCP;若已有不同路徑的同名設定,會停止要求先檢查。已有 .venv 時不必重建。

  3. 重新載入 MCP 連線或重開應用程式,確認可呼叫 pdf_info 與 render_pdf_page。安裝 SKILL.md 不代表 MCP 已接上。

macOS/Linux 使用 python3 -m venv .venv 與 .venv/bin/python。其他 MCP 客戶端可執行 python scripts/setup_mcp.py,取得含實際絕對路徑的 stdio JSON 設定,再依該客戶端方式加入。虛擬環境與跨電腦的絕對路徑設定不能直接複製,需在目的電腦重新設定。

Codex 設定參考:官方 MCP 文件。Skills CLI 只安裝技能,不會自動登入 Drive 或註冊 MCP,也不代表所有 agent 都已相容。

使用方式

在對話中說:

使用 $handwritten-pdf-vision,從我的 Drive 找到計網概筆記,分析 PDF 第 10 頁。

技能保留自動選用設定,但實際是否選中由 agent 決定,明確提及可提高確定性。agent 應在使用時告知,並實際查看 MCP 圖片才回答。

MCP 工具

功能

pdf_info

查看頁數與頁面大小,不抽取筆記文字

render_pdf_page

渲染單一指定頁面,回傳說明文字與真正的 image/png MCP 圖片區塊

傳入 file_path 或 pdf_url 其中一個;後者是 Drive 連接器提供的授權 HTTPS 原始檔下載網址,不是 /view 分享網址。網址過期就重新取檔,不公開簽名網址。頁碼從 1 開始,按 PDF 實體頁序,不按手寫頁碼。

預設 200 DPI,可用 36–300 DPI。小字可提高 DPI,或傳入 clip=[x0,y0,x1,y1] 裁切區域,座標依 page.rect,單位為 PDF 點(72 點/英吋)。每次一頁,多頁分次呼叫。

每次限制:PDF 100 MiB、2,000 萬像素、Base64 圖片資料 8 MiB。超過會明確報錯,請降低 DPI 或裁切;不會默默省略。大型 PDF 可能需要另行分割。遠端 PDF 每次呼叫重新讀取,換取無跨請求快取,處理很多頁時使用本機原檔可減少下載。

驗證

在技能資料夾執行:

.\.venv\Scripts\python.exe -B -m unittest discover -s tests -v

測試包含真正的 stdio MCP 握手、工具探索、圖片回傳與錯誤回傳,以及頁碼、裁切、加密 PDF、下載限制、不產生圖片檔和原檔保護。另以筆記第 10 頁完成 Drive → 記憶體 → MCP 圖片回傳 → 圖片顯示與實際查看;本次透過 MCP 測試客戶端轉交圖片,與應用程式重新載入後的原生工具呼叫分開驗證。其他客戶端未逐一實測。

授權

原創程式、技能與文件採用 MIT,作者為海鮮稽查長 SeaFoodInspector。MCP Python SDK 為 MIT;PyMuPDF/MuPDF 另有 AGPL/商業授權,依賴條款不會被本專案 MIT 取代。詳見 第三方依賴說明。公開 Repo 不包含私人筆記、Drive IDs、憑證或暫時下載網址。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      An MCP server for reading, rendering, and searching PDF files, specifically optimized for LLMs to extract text, tables, and technical diagrams. It enables metadata retrieval, multi-format text extraction, and page-to-image rendering using PyMuPDF.
      5
      83
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      This MCP server enables AI agents to view PDFs as accessible HTML with bounding-box citations, and provides tools for layout-aware parsing, schema extraction, cross-document Q&A, and PDF rendering.
      27
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server that extracts text-layer content from PDF files, enabling AI agents to inspect, extract text, outlines, and page content.
      -