把文件變成
Agent 可重用的資產

從 PDF、DOCX 到 citation-ready spans、表格、圖像與 Foam wiki。MCP SDK 2 讓來源、locator 與 hash 一路可驗證。

開始使用 檢視 GitHub
MCP SDK 2
30
tools
PyMuPDF default

示意流程 · PDF preflight / DOCX DFM ingest

  1. PDF / DOCX
  2. RoutePDF preflight
    DOCX DFM
  3. Extract
  4. Verify
  5. Agent Assets
  6. Foam Wiki

Sample Paper

1 Introduction
✓ 格式檢查 ✓ 可讀性 ✓ 頁面結構 ✓ 資源完整
文字 spans128 表格24 圖像16 sections6

locator

page=12 bbox=[72,144,540,188] block=3 · line=2 · span=1 SHA-256 ✓
span_0001.json table_0003.json image_0007.png manifest.json
Sample Paper 方法 Table 1 結論
source
sample_paper.pdf
locator
page=12&bbox=72,144,540,188&block=3&line=2&span=1
sha256
8f3c2b6e7a3d2c1b9e7f6d4c2a9b8e3f1a2d3c4b5e6f70f8192a3b4c5d6e7f809

一條可驗證的文件工作流

先檢查來源，再拆解、驗證與匯出；每一步都有清楚的責任邊界。

  1. 01預檢分類頁面與 OCR 需求
  2. 02攝入背景 job 保持 stdio 回應
  3. 03拆解文字、表格、圖像與 sections
  4. 04驗證locator、quote 與 SHA-256
  5. 05匯出deterministic agent asset bundle
  6. 06建庫Foam notes 與可選 LightRAG
最小工作流（MCP 呼叫示例）mcp
1 document(op="preflight", pdf_path="/path/paper.pdf")
2 document(op="ingest", file_paths=["/path/paper.pdf"])
3 document(op="export_assets", doc_id="doc_...", output_dir="agent-assets")

功能不是清單，是可組合的證據層

同一份來源被拆成 agent 能讀、能查、能驗證、能重新組合的資產。

閱讀完整流程

文件入口

PDF · DOCX · DOC · ODT · ODS

結構拆解

text · table · figure · section

Citation

exact quote · line/char/byte · hash

文件 → 證據層
A文字loc:p.12:L3–5 ▦表格loc:p.12:T1 ▧圖像loc:p.12:F1 §章節loc:p.12:S2

Agent Assets

manifest · JSONL · media · Foam

DOCX / DFM

可逆編輯與 stale-write 防護

Knowledge

Foam-first · LightRAG opt-in

30 個 MCP tools，按任務分組

先選任務，再看 operation；不用背 30 個名字。

完整 MCP reference 工具選擇器

文件核心

document

balanced

PDF 文件生命週期的主要 facade：預檢、攝入、稽核、檢索與資產匯出。

Module
document_tools.py
主要輸入
op, pdf_path, doc_id, file_paths, output_dir
Outcome
read-only preflight、background ingest、citation-ready agent asset bundle
呼叫範例
document(op="export_assets", doc_id="doc_...", output_dir="agent-assets")
閱讀完整工具 contract

從安裝到第一份 asset export

選擇一條啟動路徑；完整 client 設定與驗證步驟保留在安裝指南。

完整安裝指南
  1. 1Codex codex mcp add asset-aware-mcp -- uv tool run --python 3.11 --from asset-aware-mcp==VERSION asset-aware-mcp
  2. 2VS Code 從 Marketplace 安裝 VSIX，使用原生 MCP provider 開啟 Marketplace
  3. 3Local source uv sync && uv run asset-aware-mcp

開發與發布，先守住證據契約

功能、依賴與網站更新都進同一套 focused regression 與 release gates。

1

MCP SDK 2 only

Context 只處理 progress；operational logs 走 stderr。

2

來源不可變

保留 source SHA、mtime、locator 與 citation hash。

3

回歸先行

每個行為修正都附 focused regression。

4

可稽核發布鏈

CI → 3 OS smoke → artifacts → PyPI → Marketplace → GitHub Release

發布序列（證據導向）required
  1. 01focused regression + full pytestGATE
  2. 02ruff · mypy · bandit · auditsGATE
  3. 03docs builder --checkGATE
  4. 04CI smoke: Linux / Windows / macOSGATE
  5. 05build wheel · sdist · VSIXGATE
  6. 06artifact + install smokeGATE
  7. 07tag → PyPI → Marketplace → ReleaseSHIP
目前安全策略 △ Marker / MinerU security hold △ LightRAG opt-in △ PDF worker bounded MessagePack IPC △ MCP text hard cap

Large-span transport contract 大型 span 的 MCP 回應只提供明確標示的 asset-ref-preview-v1，且 canonical_asset_ref=false；完整 exact quote 與可自我驗證 AssetRef 留在持久化 citation / agent-asset bundle，不把截斷內容偽裝成 canonical reference。

程式碼、issue 與 release 都在 GitHub