asset-aware-mcp
This MCP server provides asset-aware document infrastructure for AI agents, enabling citation-ready document processing, native file editing, evidence management, and knowledge-graph-backed workflows.
PDF & document ingestion: Parse PDFs (PyMuPDF, Docling, etc.), preflight classification, OCR, ETL to markdown/assets, batch ingest.
Native document editing: Create/read/update DOCX (DFM bridge, headers/footers, footnotes, tables, tracked changes), XLSX/XLSM (cells, tables, worksheets, layout), PPTX (slides, shapes, pictures, tables), PDF (page composition, rotation, crop), CSV/TSV (cell/row/column CRUD).
Evidence & citations: Search/verify/export citation-ready spans with AssetRef locators, CRAAP scaffolds, CSL/custom citations, Foam wiki packs.
A2T (Anything to Table): Plan, create, manage, cite, and draft tables from any source (PDF, KG, URLs, user input), with token-efficient resume and audit trails.
Document assets: Fetch tables/figures/sections, export portable agent-asset bundles (manifest, assets.jsonl, Foam notes).
Knowledge graph: LightRAG integration for cross-document reasoning, search, and evidence-linking.
Section navigation: Browse/search document hierarchy, extract blocks.
Jobs & profiles: Async ingestion, job status tracking, ETL profile configuration.
Conversion: Convert documents between formats (docx, odt, ods, pdf, etc.) with safe output paths.
Allows conversion of legacy .doc, .odt, and .ods files to .docx format using LibreOffice, enabling ingestion and editing within the MCP server.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@asset-aware-mcp retrieve table 2 from the cancer trial document"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
asset-aware-mcp
Citation-ready document infrastructure for AI agents: editable native documents, reusable evidence, and portable Foam/LightRAG wikis.
🌐 繁體中文 · Docs Site · GitHub Wiki
v1.4.1 Consolidated native-document release
This release brings together the document and evidence work below. We keep the 1.4.x line and consolidate verified changes instead of releasing each feature. Check GitHub Releases for publication status and the changelog for details.
Format | Supported workflows |
Pages/regions, page assembly, annotations, AcroForm fields, actual previews, historical evidence | |
DOCX | Creation, scoped body/table edits, table grids/layout, headers/footers, footnotes/endnotes |
XLSX/XLSM | Cells, worksheet/grid/layout operations, native Tables, A2T application and independent XLSX creation |
ODS | Creation, exact logical-cell edits/clearing, dependency-checked worksheet rename and optional Calc previews |
CSV/TSV | Literal fields and row/column CRUD with explicit dialects and byte-preservation checks |
PPTX | Slides, text, notes, pictures, editable tables and optional whole-slide previews |
Raster images | Frames/regions, PNG/TIFF derivatives, composition and checked candidate revisions |
Evidence/Wiki | Immutable selections/derivations, complete receipts, CSL/custom citations and exact source attachments |
Discover the installed runtime's complete contract and enabled flags before acting.
Since v1.4.0, native-contract-v2 can page schemas: inspect schema_delivery, select
for_op, or follow the hash-pinned schema_request. Follow contract_request for
paged policies too; abbreviated previews are not complete operation instructions.
Related MCP server: PageIndex Light MCP
🎯 Why Asset-Aware MCP?
Model document analysis may be enough for summaries and questions. This project's purpose is ongoing work on native documents with reusable, checkable results: which source revision was used, which component changed, what stayed intact, and which evidence still supports a claim after later edits or a change of model.
An asset carries identity, revision, native locators, representations, relationships, available operations and validation state. Wiki notes link these assets; citation formatting preserves the underlying evidence. Complete operation receipts and historical sources remain available after component edits or deletion.
MCP checks source/version integrity, native constraints and operation results. The Agent performs complete semantic and visual review and coordinates corrections. Static previews do not establish interactive viewer parity or universal fidelity. Arbitrary PDF body editing and ODS worksheet/grid lifecycle remain open work. See native usage and limits, capability gaps and upstream references, actual Agent evaluations and contracts.
✨ Features
Version 1.3.0 adds a native DOCX bridge with revision-bound read_docx and
update_docx, reusing the existing DFM checks before committing a managed version.
It preserves unrelated package parts and supports explicit tracked text changes;
source writeback and agent layout review remain separate. DOCX block references now
support bounded reads and native verification; wiki snapshots include full block
records, the original DOCX and exact package-part attachments. Existing 1.2.0 wiki
outputs retain their identities and bytes. See the DOCX bridge guide.
📄 Asset-Aware ETL - PDF → Markdown with a pluggable multi-engine parser (
ETL_ENGINE):PyMuPDF (default) - Fast extraction (~50MB), no models required
PyMuPDF4LLM (
[pdf-plus]) - Drop-in layout-aware upgrade, no GPUDocling (
[docling]) - MIT-licensed layout+table+formula+chart engine; bridges through an isolated.venv-doclinginterpreter when the main environment can't install it directly (see docs/docling-setup.md)MinerU - Adapter retained, but the packaged extra is on security hold while MinerU pins a vulnerable
transformers<5chainMarker - Adapter retained for evaluation, but production selection fails closed while upstream
marker-pdfconflicts with the patched Pillow floor. The legacyuse_markerparameter now means “prefer the configured structured extractor”; it does not bypass this hold.
🧩 Unified Segmentation Export - Normalized
segmentation.jsonmerges manifest, blocks, reading order, and persisted markdown line spans for downstream tools and extensions.🩺 Safe PDF Preflight Router -
document(op="preflight")classifies each page as native, sparse, image, scanned, or hybrid; returns 1-based top-left locators, source SHA-256, OCR reasons, and a bounded extraction-engine recommendation from a process-isolated inspector.📦 Reusable Agent Asset Bundles -
document(op="export_assets")writes deterministicmanifest.json,assets.jsonl, copied media, and a portable Foamindex.md/notes/**subtree while preserving stable IDs, hashes, locators, and citation refs.🛡️ PDF Safety/Structure/Coverage/Accessibility Audits - OpenDataloader-inspired artifact-only reports flag suspicious hidden/off-page/prompt-injection text, native structure signals, segmentation coverage gaps, and accessibility/readability readiness via the existing
documentfacade.document(op="prepare_ai")anddocument(op="auto")expose agent-ready status and next actions without adding public tools.🧭 Structural Pointer Retrieval - Proxy-Pointer-inspired
document(op="pointer_index"),document(op="structural_retrieve"), anddocument(op="compare")preserve section breadcrumbs, line/char/byte locators, source hashes, asset IDs, and evidence-span provenance without adding MCP tools.🖼️ Layout Overlay Debugging - Render page overlays from
original.pdfto inspect bbox, segment type, and reading order visually.🔤 On-Demand OCR Preprocessing - Optional
ocrmypdfpreprocessing path for scanned PDFs before ETL.🧭 Section Navigation - Dynamic hierarchy section tree through the
sectionfacade: browse, search, detail, content reading, and block extraction for any depth of headings.🔄 Async Job Pipeline - Supports asynchronous ingest, configured structured parse, OCR, and conversion jobs with progress tracking.
🔀 Mixed-Format Batch Ingestion -
document(op="auto", file_paths=[...])auto-detects a batch mixing PDF with DOCX/DOC/ODT/ODS, ingests each file through its correct existing engine in one background job, isolates per-file failures so one bad file cannot abort the rest, and reports per-file progress — no new public tool required.🗺️ Document Manifest - Provides a structured "map" of the document for precise data access by Agents.
🧠 LightRAG Integration - Knowledge Graph + Vector Index, supporting cross-document comparison and reasoning.
🧾 Verified Citation Bundles -
citation_bundle, Foam evidence packs, citation health checks, table/figure evidence notes, and claim promotion export citation-ready spans with locator, quote/hash, context, CRAAP scaffold, and verification status.📝 Docx Editing (DFM) - Edit .docx files in Markdown via Docx-Flavored Markdown format. Supports legacy
.doc,.odt, and.odsingest via LibreOffice auto-conversion. The balanced surface keeps 6 DOCX/DFM public entrypoints for ingest, read, save, validation, conversion, table edit planning, and Docx ↔ A2T bridges.🛡️ DFM Integrity Checker - Automatic validation and auto-repair at every pipeline stage (post-ingest, pre-save, post-save). Catches orphan markers, column mismatches, and format inconsistencies.
📊 A2T (Anything to Table) - 7 operation-based tools for building professional tables from any source (PDF assets, Knowledge Graph, URLs, user input). Features: stable row IDs, row search/filter/paging, citation coverage, artifact-only large-table render, skipped-large-table UX, Citations (AssetRef), Audit Trail, Schema Evolution, Templates, Drafting, and Token-efficient resumption.
🖥️ VS Code Management Extension - Graphical interface for monitoring server status, ingested documents, document artifacts, citation spans, and A2T tables/drafts with one-click Excel export.
🔌 MCP SDK 2 Server - Uses the official Python SDK
MCPServerAPI, runtime-injected context, and v2 clients. MCP SDK v1 is intentionally unsupported.🔬 Research-ready, domain-neutral assets - Works with scholarly, technical, policy, and operational documents; bounded image bytes let compatible multimodal clients analyze figures instead of relying on server-local paths.
🏗️ Architecture
┌─────────────────────────────────────────────────────────┐
│ AI Agent (Copilot) │
└─────────────────────┬───────────────────────────────────┘
│ MCP Protocol (Tools & Resources)
┌─────────────────────▼───────────────────────────────────┐
│ MCP Server (Modular Presentation) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ tools/: 30 public tools (balanced surface) │ │
│ │ 17 facade tools + 13 high-frequency shortcuts │ │
│ │ compact=17 │ legacy/direct compatibility=63 │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ resources/: 13 resources in 2 modules │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────┐
│ ETL Pipeline (DDD) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ PyMuPDF │ │ Asset │ │ LightRAG │ │
│ │ Adapter │→ │ Parser │→ │ Index │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────┬───────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────┐
│ Local Storage │
│ ./data/ │
│ ├── {doc_id}/ # PDF document artifacts │
│ ├── docx_{id}/ # Docx IR + DFM + Assets │
│ ├── tables/ # A2T Tables (JSON/MD/XLSX) │
│ │ └── drafts/ # Table Drafts (Persistence) │
│ └── lightrag_db/ # Knowledge Graph │
└─────────────────────────────────────────────────────────┘📁 Project Structure (DDD)
asset-aware-mcp/
├── src/
│ ├── domain/ # 🔵 Domain: Entities, Value Objects, Interfaces
│ ├── application/ # 🟢 Application: Doc Service, Table Service (A2T), Asset Service
│ ├── infrastructure/ # 🟠 Infrastructure: PyMuPDF, LightRAG, Excel Renderer
│ └── presentation/ # 🔴 Presentation: MCP SDK 2 MCPServer
├── data/ # Document and Asset Storage
├── docs/
│ └── spec.md # Technical Specification
├── tests/ # Unit and Integration Tests
├── vscode-extension/ # VS Code Management Extension
└── pyproject.toml # uv Project Config📐 Architecture and workflows
The maintained, versioned references are the documentation site, architecture guide, PDF workflow, MCP tool catalog, and release checklist. They are generated and checked with the implementation so tool counts, engine holds, and release behavior do not drift inside obsolete screenshots.
🚀 Quick Start
# Install dependencies (using uv) — default install stays on the fast PyMuPDF backend
uv sync
# Optional high-fidelity PDF->asset engines:
# uv sync --extra pdf-plus # PyMuPDF4LLM: drop-in layout-aware upgrade
# uv sync --extra docling # Docling: MIT layout+table+formula+chart engine
# MinerU and Marker packaged extras are temporarily empty security holds.
# Then set ETL_ENGINE=pymupdf4llm|docling.
# Run MCP Server
uv run python -m src.presentation.server
# Or use the VS Code extension for graphical managementRuntime note:
The VS Code extension prefers a managed Python 3.11 runtime when launching the MCP server via version-pinned uv tool run, with Python 3.10 fallback for older machines. This avoids native package builds on end-user machines, especially macOS systems without Xcode Command Line Tools, while keeping the project itself compatible with newer Python versions.
Installation scope note:
The VS Code extension installs once per user. In a trusted workspace, the native VS Code MCP provider may use workspace-scoped
DATA_DIR, cache, settings, and.env; local source is accepted only in Extension Development/Test mode (or a future explicit opt-in).Global Codex and Cline entries always launch
asset-aware-mcp==<extension-version>from extension global storage. They do not inherit workspace-local source, workspace-scoped settings, or repository.envvalues. Restricted Mode skips external config writes and assistant-asset sync entirely.
Engine selection note:
ETL_ENGINE picks the extraction backend (default pymupdf). The active packaged structured engines (pymupdf4llm, docling) lazy-load and gracefully fall back to PyMuPDF when their extra is not installed. Marker remains on hold because marker-pdf requires Pillow<11; MinerU is also on hold because MinerU 3.4.4 pins transformers<5 while current security fixes require transformers>=5.5. Both adapters remain in-tree, but this package will not install a known-vulnerable dependency chain. Use document(op="preflight", pdf_path="...") to choose between fast native extraction, OCR, and Docling before ingest.
Agent asset / Foam handoff:
document(op="preflight", pdf_path="/papers/source.pdf")
document(op="auto", file_paths=["/papers/source.pdf"])
document(op="export_assets", doc_id="doc_...", output_dir="agent-assets")The exported directory is deterministic and portable: manifest.json is the
bundle contract, assets.jsonl is the agent-readable inventory, and
index.md plus notes/** can be mounted or copied into a Foam workspace.
🔌 MCP Tools
The default runtime surface is balanced: 30 public tools that keep the full document workflow available without overwhelming agents. It is made of 17 operation-based facade tools plus 13 high-frequency shortcuts. Set ASSET_AWARE_MCP_TOOL_SURFACE=compact for the 17 facade-only surface, or ASSET_AWARE_MCP_TOOL_SURFACE=legacy / ASSET_AWARE_MCP_ENABLE_LEGACY_TOOLS=true for the full 63-tool compatibility inventory.
Area | Balanced public tools |
Documents, assets, evidence, conversion |
|
DOCX / DFM |
|
Sections, jobs, KG, ETL profiles |
|
A2T tables |
|
See MCP Tools and Tool Consolidation for operation details, shortcut rationale, and legacy direct-tool mapping.
Agent handoff note:
Use document(op="auto", file_paths=[...]) for new PDFs and document(op="auto", doc_id="...") or document(op="prepare_ai", doc_id="...") for existing documents. document(op="prepare_ai", output_format="json") returns the v2 readiness contract with status, blockers, warnings, capabilities, artifacts, missing_audits, invalid_audits, audit_artifacts, and next_actions. document(op="audit", doc_id="...") reuses current audit artifacts only when they are present and valid; pass refresh=true to rebuild safety, native-structure, coverage, and accessibility reports. Use document(op="pointer_index"), document(op="structural_retrieve", query="..."), and document(op="compare", doc_b_id="...", criteria="...") when an agent needs section-level structural retrieval or comparison without new public tools. Readiness and job-status artifact discovery are read-only, so status checks do not create document directories.
PDF audit caveat: The audit reports are inspired by OpenDataloader-style artifact workflows, but they are not a sanitizer, a PDF/UA certification, or an OpenDataloader compatibility layer. They preserve source artifacts and report conservative diagnostics for review.
🔧 Tech Stack
Category | Technology |
Language | Python 3.10+ |
Package Manager | uv (all pip/setup-python removed) |
ETL | PyMuPDF (default) + secure optional PyMuPDF4LLM / Docling engines; MinerU and Marker adapters are on dependency security hold |
RAG | LightRAG (lightrag-hku) |
MCP | Official Python MCP SDK 2 ( |
Storage | Local filesystem (JSON/Markdown/PNG) |
📋 Documentation
Installation guidance:
Default install:
uv sync(slim ~227 MB; no LightRAG/KG dependencies).LightRAG / Knowledge Graph backend (optional, since v0.6.34):
uv tool install --upgrade --python 3.11 'asset-aware-mcp[lightrag]'for uvx/published users, oruv sync --extra lightragfor local source checkouts. Required before settingENABLE_LIGHTRAG=true.VS Code extension: run the command
Asset-Aware MCP: Install LightRAG Backendfrom the Command Palette; it auto-detects source vs published mode and emits the matching install command.OpenRouter optional preset (since v0.6.35): set
LLM_BACKEND=openrouter,OPENROUTER_API_KEY=..., and optionallyOPENROUTER_MODEL=liquid/lfm-2.5-1.2b-instruct:freefor fast low-cost summaries and draft RAG answers. LightRAG retrieval still uses the configured embedding backend.High-fidelity PDF engines:
uv sync --extra pdf-plus(PyMuPDF4LLM) oruv sync --extra docling(Docling), then setETL_ENGINEaccordingly. Docling ships a cross-platform isolated installer; see docs/docling-setup.md.MinerU and Marker backends: their adapters remain available for upstream testing, but the packaged extras are empty security holds until their dependency caps permit patched
transformersand Pillow releases.VS Code extension:
assetAwareMcp.enableMarkerBackendis retained as a setting, but the launcher will not installmarker-pdfwhile the security hold is active.Technical Spec - Detailed technical specification
Architecture - System architecture
Constitution - Project principles
Competitive Analysis - MCP + DOCX ecosystem landscape
📄 License
Available Tools
30 toolscitation_bundleC
Export citation-ready evidence spans as a verified bundle.
Each entry carries AssetRef, exact quote/hash, locator metadata, context, conservative CRAAP scaffold, optional verification status, and Foam anchor metadata. Use output_format="foam" for a Foam-compatible evidence pack. Pass wiki_root to write the pack and optionally update an index note.
Inputs: doc_id (required), limit, query, span_id, +11 more.
convert_documentC
Consolidated document conversion entrypoint.
Dispatches to the existing conversion tools so each source family keeps its established output-path containment policy.
Inputs: source (required), target_format (required), mode, md_text, +3 more.
discover_sourcesB
🔍 資料來源探索:跨文件搜尋可用於表格的資料來源。
整合 Section、Figure、Table、Knowledge Graph 多個資料庫,
返回統一的 AssetRef 格式結果。短 evidence span 會保持
canonical;過長 span 僅回傳 discovery-only span_preview,完整可驗證
AssetRef 必須從 persisted citation / agent-asset bundle 取得。
Args: query: 搜尋關鍵字 doc_ids: 限定搜尋的文件(不指定則搜尋所有文件) include_kg: 是否包含知識圖譜搜尋 limit: 每類來源的最大結果數
Returns: 發現的資料來源(AssetRef 格式)
Example: discover_sources("remimazolam dosing") discover_sources("drug comparison", doc_ids=["doc_abc"])
Inputs: query (required), limit, doc_ids, include_kg. Returns: result
documentA
Document operations including versioned native file assets.
Operation -> required parameters:
auto: exactly one offile_paths(ingest) ordoc_id(readiness).ingest/import:file_paths.preflight:pdf_pathonly;file_pathsis rejected.inspect/prepare_ai/ audit and retrieval operations:doc_id.export_assets/agent_assets:doc_id;output_diris optional.native:native_requestwith its own op (contract/schema/register/create/ list/inspect/read_cell/read_docx/read_docx_block/update_docx/create_pptx/ read_pptx/read_pptx_shape/update_pptx/verify/export_wiki/update/history/publish/writeback/refresh/archive). XLSX/XLSM expose cells; DOCX has a checked DFM bridge; PPTX has native shapes and scoped run edits. Query the contract for PDF create/read/read-page/render/ add/update/delete/reorder operations with revision-pinned page references. PDF edits compose pages and change rotation/crop; native text reading is not OCR. Native wiki includes XLSX/XLSM cells, DOCX blocks/parts, PPTX shapes/parts and PDF pages/previews/exact source bytes; other formats retain opaque source attachments. Verification checks integrity, while agents review semantics, rendered layout and extraction coverage. Native wiki citation_contract/citation_metadata belong inside native_request. contract accepts for_op for one operation. Check schema_delivery; follow schema_request for complete paged JSON and pin schema_sha256 on continuation.
Existing direct document tools stay registered and keep their original
contracts. The facade descriptions make op-specific requirements visible
even though the shared JSON schema can require only op globally.
Inputs: op (required), page, limit, query, +24 more.
document_assetD
Consolidated document asset and section entrypoint.
Inputs: op (required), path, fuzzy, limit, +16 more.
docxD
Consolidated DOCX/DFM entrypoint.
The legacy DOCX tools remain registered and keep their original parameters and output formats. This wrapper only adds an operation-based facade.
Inputs: op (required), force, doc_id, strict, +8 more.
docx_tableD
Consolidated DOCX table bridge entrypoint.
Existing docx_table_* tools remain available for clients that rely on their names or generated allow-lists.
Inputs: op (required), doc_id, block_id, register, +4 more.
docx_table_edit_planA
Plan a DOCX table write-back before applying structural changes.
The current DFM bridge is safest for same-shape cell text updates. This
plan separates safe cell updates from row/column/header structural changes
so the caller can review risk before docx_table_from_context.
Inputs: doc_id (required), block_id (required), table_id, target_rows, +1 more. Returns: result
etl_profileD
Consolidated ETL profile entrypoint.
Existing profile tools stay registered for backwards compatibility.
Inputs: op (required), name, doc_id, activate, +4 more.
evidenceB
Evidence operations; contract describes citation formats, bundle applies them.
citation_contract accepts a preset selector or named-field inline/reference templates; citation_metadata supplies bibliographic fields, never locators. csl_contract returns the complete hash-paged CSL document schema. render_citations accepts citation_document for document-context APA/Chicago/ Vancouver processing; read every text page at one text_sha256. Optional wiki_root exports an immutable citation snapshot with exact native sources. CSL text_limit is 1..8000 characters; stop paging when next_text_offset is null. inspect_etl_source takes ref={doc_id,source_type,source_id} and returns a full current AssetRef via hash paging. capture_etl_source verifies/captures it in ref. read_etl_source reads the resulting immutable ref; view_etl_source returns its actual original PDF page image. Use the captured ref in CSL sources; source extraction accuracy and semantic support still require Agent review.
Inputs: op (required), ref, limit, query, +18 more.
fetch_document_assetA
Fetch specific content from a document with precision.
Asset Types:
"table": Returns table as markdown (with page number)
"figure": Returns image as base64 with page number for verification
"section": Returns section text content
"full_text": Returns entire document as markdown
Args: doc_id: Document identifier asset_type: One of "table", "figure", "section", "full_text" asset_id: Asset ID from manifest (e.g., "tab_1", "fig_1_1", "sec_methods") Use "full" for full_text type max_size: Maximum image dimension (longest edge) for figures. - None (default): Use default 1024px - 0: Return original size (no resize) - N: Resize to Npx longest edge (e.g., 512, 768, 2048)
Returns: For figures: ImageContent that vision AI can directly analyze For others: TextContent in markdown format
Example: # Get Table 1 from document fetch_document_asset("abc123", "table", "tab_1")
# Get figure with default resize (1024px)
fetch_document_asset("abc123", "figure", "fig_2_1")
# Get figure at specific size (512px for smaller context)
fetch_document_asset("abc123", "figure", "fig_2_1", max_size=512)
# Get original image (no resize)
fetch_document_asset("abc123", "figure", "fig_2_1", max_size=0)
Inputs: doc_id (required), asset_type (required), asset_id, max_size, +1 more.
find_evidence_spansC
Search citation-ready evidence spans with exact locator metadata.
Returns span-level AssetRef JSON that can be passed to table_cite.
Inputs: doc_id (required), limit, query, span_id, +1 more. Returns: result
get_docx_contentA
取得 docx 文件的可編輯 DFM 內容。
若指定 block_id,只回傳該區塊的內容;否則回傳完整 DFM。
Args: doc_id: 文件 ID(由 ingest_docx 產生) block_id: 可選,特定區塊 ID(如 p001, t001, h001)
Returns: DFM 內容或特定區塊資訊
Inputs: doc_id (required), block_id, max_chars. Returns: result
get_job_statusA
Get the status of an ETL job.
Use this to check progress of document ingestion started with ingest_documents.
Args:
job_id: Job ID returned from ingest_documents
Returns: Job status including progress, phase, and result (if completed)
Example: get_job_status("job_20251226_143000_abc12345")
Inputs: job_id (required). Returns: result
ingest_documentsA
Process PDF files and create Document Manifests.
ETL Pipeline:
Extract text (to markdown) and images
Generate structured Document Manifest
Index in LightRAG (if enabled)
Args: file_paths: List of absolute paths to PDF files async_mode: Kept for backwards compatibility. PDF ingestion is routed to a background job from the MCP tool layer to keep stdio clients responsive. use_marker: Backwards-compatible flag that requests the configured structured extractor. The active packaged structured route is Docling; MinerU and Marker are dependency security holds. Default False uses PyMuPDF (faster and always available). marker_max_pages_per_chunk: When using a configured structured extractor, split PDFs into fixed-size page chunks. Set 0 to use the safe automatic strategy. extract_figures: When using a configured structured extractor, control whether image crops are extracted and saved. Disable this first for image-heavy textbooks to reduce memory pressure. page_ranges: 1-indexed inclusive page ranges applied to every input file, e.g. ["1-50", "120-160"].
Returns:
Job ID for tracking progress with get_job_status.
Example: # Async (recommended for large files): ingest_documents(["/papers/study1.pdf"]) # Then check status: get_job_status("job_xxx")
# With the configured structured extractor for precise source tracking:
ingest_documents(["/papers/textbook.pdf"], use_marker=True)
Inputs: file_paths (required), deskew, async_mode, use_marker, +7 more. Returns: result
ingest_docxA
攝入 .docx / .doc 文件,轉換為 DFM (Docx-Flavored Markdown) 格式。
將 docx 解析為中間表示 (IR),再轉換為可在 VS Code 中編輯的 DFM 格式。 支援複雜元素:合併表格、圖表、頁首頁尾、巨集、目錄等。 支援舊版 .doc 格式(自動透過 LibreOffice 轉換為 .docx)。
輸出目錄結構:
data/{doc_id}/
├── content.dfm # 可編輯的 Markdown + YAML 標注
├── ir.json # IR 快照(用於回寫)
├── original.docx # 原始檔案備份
├── parts/ # 保留的 XML 零件
└── assets/ # 圖片和二進位資產Args: file_path: .docx 或 .doc 檔案的絕對路徑
Returns: 攝入結果摘要(doc_id、區塊數量等)
Inputs: file_path (required). Returns: result
jobD
Consolidated job entrypoint over get/list/cancel.
Existing job tools stay registered for backwards compatibility.
Inputs: op (required), job_id, active_only.
knowledgeC
Consolidated knowledge-graph entrypoint.
Existing consult/export tools remain registered and keep their separate contracts for clients that prefer explicit tool names.
Inputs: op (required), mode, limit, query, +7 more.
list_documentsA
List all processed documents with summaries.
Returns: List of documents with doc_id, title, and asset counts
Inputs: no named parameters. Returns: result
list_jobsA
List ETL jobs.
Args: active_only: If True, only show pending/processing jobs
Returns: List of jobs with status and progress
Inputs: active_only. Returns: result
parse_pdf_structureC
Create a background job using the configured structured PDF extractor.
Inputs: pdf_path (required), deskew, async_mode, output_dir, +6 more. Returns: result
plan_tableB
📋 表格規劃工具:Schema 設計、模板查詢、模板建表。
Operations:
schema: 根據問題自動規劃表格結構
templates: 列出內建表格模板
from_template: 從模板快速建立表格
Args: operation: 操作類型 question: [schema] 使用者問題 doc_ids: [schema] 相關文件 ID hints: [schema] 結構提示 template_name: [from_template] 模板名稱 title_override: [from_template] 自訂標題
Examples: plan_table("schema", question="比較三種藥物副作用") plan_table("templates") plan_table("from_template", template_name="drug_comparison")
Inputs: operation (required), hints, doc_ids, question, +2 more. Returns: result
save_docxA
將編輯後的內容存回 .docx 檔案。
支援兩種模式:
DFM 模式(預設):傳入 dfm_content(.dfm 格式全文)
MD 模式(from_md=True):從磁碟讀取 content.md + format.yaml
回寫流程:
解析 DFM/MD → 提取修改
載入原始 IR
合併修改(格式合併策略)
重建 .docx
安全機制:若內容萎縮 > 50%,預設拒絕輸出(疑似資料遺失)。 使用 force=True 強制輸出。
若 track_changes=True,會將 DFM 中的文字修改以真正 Word Track
Changes (w:del/w:ins) 寫回,供使用者在 Word 中逐項審查。
Args: doc_id: 文件 ID dfm_content: 編輯後的 DFM 全文(from_md=True 時可省略) output_path: 輸出路徑(預設為 data/{doc_id}/output.docx) from_md: 若為 True,從磁碟讀取 content.md + format.yaml 而非使用 dfm_content force: 若為 True,即使偵測到嚴重內容萎縮仍強制輸出 track_changes: 若為 True,以 Word Track Changes 寫入文字 diff revision_author: 產生追蹤修訂時使用的作者名稱
Returns: 儲存結果
Inputs: doc_id (required), force, from_md, dfm_content, +3 more. Returns: result
sectionD
Consolidated section navigation entrypoint.
Inputs: op (required), doc_id (required), path, fuzzy, +8 more.
table_citeA
📎 表格引用管理:為儲存格附加、查詢、移除來源引用。
引用是「平行附加層」,不改變表格資料結構。 每個引用用 AssetRef 指向具體來源(PDF section、URL、使用者輸入等)。
Operations:
add: 新增引用到儲存格
get: 查詢引用摘要(cell / row / table);完整引用用 read
read: 完整 cell/value/citation JSON 分頁,不截斷 canonical quote/locator
remove: 移除引用
cell_history: 查看儲存格變更歷史
Args: operation: 操作類型 table_id: 表格 ID row_index: 列索引 (0-based),get 時可省略取得全表引用 column_name: 欄位名,get 時可省略取得整列引用 refs: [add] 引用列表,每項為 AssetRef dict [{"source_type":"section","doc_id":"doc_xxx","asset_id":"sec_01","excerpt":"..."}] [{"source_type":"external","url":"https://doi.org/...","label":"Smith 2024"}] [{"source_type":"user_input","excerpt":"Patient reported"}] confidence: [add] Agent 信心度 0.0~1.0 notes: [add] 備註 ref_index: [remove] 移除特定引用索引(不指定則移除整個 cell 引用) text_offset: [read] 字元起點;後續頁必須保留 citation_sha256 text_limit: [read] 每頁 1..4000 字元,可能因回應上限縮短 citation_sha256: [read] 首頁回傳的 hash,拒絕混接不同 cell/value/citation
read requires a row_id (preferred) or row_index and column_name. Concatenate text_excerpt pages at one hash, verify UTF-8 SHA-256, then parse the full JSON. Follow next_text_offset until null. Readback does not verify source or meaning.
Examples: table_cite("add", "tbl_xxx", row_index=0, column_name="Drug", refs=[{"source_type":"section","doc_id":"doc_a","asset_id":"sec_01", "excerpt":"dose was 5mg"}], confidence=0.9) table_cite("get", "tbl_xxx") # 全表引用 table_cite("get", "tbl_xxx", row_index=0) # 全列引用 table_cite("cell_history", "tbl_xxx", row_index=0, column_name="Drug")
Inputs: table_id (required), operation (required), refs, limit, +10 more. Returns: result
table_dataC
📝 表格資料操作:新增/取得/更新/刪除 列 & 儲存格。
Operations:
add_rows: 批次新增資料列
get_row: 取得單列(含引用)
update_row: 整列更新
delete_row: 刪除列
get_cell: 取得單格(含引用)
update_cell: 更新單格
clear_cell: 清除單格
Args: operation: 操作類型 table_id: 表格 ID rows: [add_rows] 資料列列表 row: [update_row] 新的列資料 row_index: [get/update/delete_row, cell ops] 列索引 (0-based) column_name: [cell ops] 欄位名 value: [update_cell] JSON 值;native 欄位使用 {kind, value} 保留型別
Examples: table_data("add_rows", "tbl_xxx", rows=[{"Drug":"A","Dose":1}]) table_data("get_row", "tbl_xxx", row_index=0) table_data("update_cell", "tbl_xxx", row_index=0, column_name="Drug", value="B")
Inputs: table_id (required), operation (required), row, rows, +10 more. Returns: result
table_draftA
📝 草稿工作流:建立、更新、新增資料、恢復、提交。
草稿會自動保存,即使對話中斷也能恢復。 適合長時間的表格建立流程。
Operations:
create: 建立草稿
update: 更新草稿
add_rows: 批次新增資料到草稿
resume: 恢復草稿(Token-efficient)
commit: 草稿轉正式表格
list: 列出草稿
delete: 刪除草稿
Args: operation: 操作類型 draft_id: [大部分操作] 草稿 ID title: [create/update] 標題 intent: [create/update] comparison / citation / summary proposed_columns: [create/update] 欄位定義 extraction_plan: [create/update] 抽取計畫 source_doc_ids: [create/update] 來源文件 ID source_sections: [create/update] 來源章節 ID notes: [create/update] 工作筆記 rows: [add_rows] 資料列
Examples: table_draft("create", title="Drug Comparison", intent="comparison", proposed_columns=[{"name":"Drug","type":"text"}]) table_draft("add_rows", draft_id="draft_xxx", rows=[{"Drug":"A"}]) table_draft("commit", draft_id="draft_xxx")
Inputs: operation (required), rows, notes, title, +6 more. Returns: result
table_historyA
📜 表格歷史與統計:變更紀錄、Token 估算。
Operations:
changes: 查看表格變更歷史
tokens: 估算 Token 消耗
Args: operation: 操作類型 table_id: 表格 ID [changes, tokens] limit: [changes] 最近 N 筆 draft_id: [tokens] 草稿 ID(可選) text: [tokens] 任意文字(可選)
Examples: table_history("changes", "tbl_xxx") table_history("tokens", "tbl_xxx")
Inputs: operation (required), text, limit, draft_id, +1 more. Returns: result
table_manageB
📊 表格管理工具:建立、刪除、列表、預覽、渲染、Schema 演進。
Operations:
create: 建立新表格
delete: 刪除表格
list: 列出所有表格
preview: Markdown 預覽
resume: 恢復工作(Token-efficient)
render: 渲染為 Excel/Markdown
add_column: 新增欄位
remove_column: 移除欄位
rename_column: 重新命名欄位
Args: operation: 操作類型 intent: [create] comparison / citation / summary title: [create] 表格標題 columns: [create] 欄位列表 [{"name":"Drug","type":"text"}] source_description: [create] 資料來源 table_id: [大部分操作] 表格 ID limit: [preview] 預覽行數 format: [render] 輸出格式 filename: [render] 檔案名稱 column_name: [add/remove/rename_column] 欄位名 column_type: [add_column] 欄位類型 required: [add_column] 是否必填 default_value: [add_column] 預設值 enum_values: [add_column] enum 可選值 new_name: [rename_column] 新欄位名
Examples: table_manage("create", intent="comparison", title="Drug Compare", columns=[{"name":"Drug","type":"text"}]) table_manage("list") table_manage("preview", table_id="tbl_xxx") table_manage("add_column", table_id="tbl_xxx", column_name="Route", column_type="enum", enum_values=["IV","IM"])
Inputs: operation (required), limit, title, format, +13 more. Returns: result
verify_citation_refC
Verify a span-level AssetRef against the persisted citation index.
Inputs: ref (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
The tool set contains multiple consolidated facades and direct tools that heavily overlap: document, document_asset, fetch_document_asset, section, docx, docx_table, and evidence all cover document/asset territory, while job duplicates get_job_status/list_jobs. Even with detailed descriptions, an agent must read long contracts to pick the right entrypoint. Several tools have unclear boundaries despite some well-written individual descriptions.
Names are consistently lowercase and snake_case, but they follow no single pattern: action-first names like ingest_documents and get_docx_content coexist with noun-only entrypoints like document, job, section, and evidence, plus the mixed table_manage/table_data versus plan_table style. Most names are readable and descriptive, but the generic single-word facades are vague and the overall convention is uneven.
30 tools exceeds the 25-tool threshold and is inflated by redundant consolidated/direct pairs, e.g., document vs document_asset vs docx, and job vs get_job_status/list_jobs. The underlying domain is broad, but many tools could be merged or removed without losing capability, making the surface feel heavy for agents to navigate.
The server covers the document lifecycle well: PDF/DOCX ingestion, document listing and asset retrieval, table CRUD/drafts/citations, evidence spans/bundles, DOCX write-back, and job tracking. Minor gaps remain, such as the lack of a clearly exposed direct PDF create/update/delete tool outside the monolithic document facade and no OCR path, but core workflows have no dead ends.
Maintenance
Related MCP Connectors
Stateless agentic tools over MCP: concept extraction, long-context, knowledge graph, planning.
Shared, peer-validated knowledge archive for AI agents — search, contribute, and validate via MCP
Knowledge commons for AI agents: cited, licensed, queryable claims over MCP.
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to download, index, and semantically search PDF research papers using 8 MCP tools.48 PyPI5GPL 3.0
- FlicenseAqualityDmaintenanceAgentic PDF search via MCP, enabling intelligent document retrieval through LLM reasoning instead of vector similarity.24-
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to extract structured data from PDFs with confidence scores and provenance, and to search, review, and correct documents via MCP tools, resources, and prompts.-
- AlicenseNot gradedqualityCmaintenanceExtracts text and tables from PDFs for AI agents via MCP, enabling structured data retrieval from invoices, reports, and statements.49 PyPI1MIT