MES Document MCP
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., "@MES Document MCP Ingest production.xlsx and show outline"
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.
MES Document MCP
AI agents need a safe way to work with real manufacturing documents. This project provides a production-oriented MCP server and CLI for Excel, PDF, Word, and Markdown files used in MES workflows.
It does not try to make an LLM directly edit office files. It turns documents into a structured DocumentIR, keeps source provenance, requires approved PatchIR edits, validates output artifacts, and exports back to md, docx, pdf, or xlsx.
What This Is
This repository contains:
An MCP server:
uv run python -m mes_doc_mcp.serverA CLI:
uv run mes-doc-mcp ...A Python package:
mes_doc_mcpParsers for Excel, PDF, Word, Markdown, and CSV
MES extraction and validation helpers
Secure patch/edit/export workflow
Tests and CI gates for public GitHub use
Typical users:
MES engineers handling production Excel files
Manufacturing data teams cleaning mixed office documents
AI agent builders who need document tools with citations and guarded edits
Teams converting messy spreadsheets into reports and standard JSON
Related MCP server: SmartOffice-MCP
Why It Exists
MES teams often receive business-critical data in Excel, Word, PDF, and Markdown:
production daily reports
work orders
quality inspection sheets
defect reports
BOM and routing tables
LOT traceability documents
LLMs are useful here, but unsafe if they directly mutate files. This server gives the agent controlled tools instead.
source file
→ secure ingest
→ DocumentIR with source refs
→ search / inspect / MES extraction
→ PatchIR proposal
→ dry-run diff
→ human approval
→ apply
→ validate
→ export artifactQuickstart
git clone https://github.com/sjMun09/MES-mcp.git
cd MES-mcp
uv sync --extra dev
uv run pytest -qCreate sample files:
uv run python scripts/create_examples.pyTry the CLI:
uv run mes-doc-mcp ingest examples/sample_production.xlsx
uv run mes-doc-mcp list
uv run mes-doc-mcp validate DOC_ID
uv run mes-doc-mcp mes DOC_ID
uv run mes-doc-mcp export DOC_ID md examples/out/production_report.mdRun the MCP server:
uv run python -m mes_doc_mcp.serverMore detail:
MCP Client Config
Use this from the repository root:
{
"mcpServers": {
"mes-doc-mcp": {
"command": "uv",
"args": ["run", "python", "-m", "mes_doc_mcp.server"],
"cwd": "/absolute/path/to/MES-mcp"
}
}
}Then ask your AI client:
Ingest examples/sample_production.xlsx.
Inspect sheets, tables, formulas, merged cells, and source ranges.
Extract MES entities and validate quantity consistency.
Propose fixes as PatchIR only. Do not apply changes until I approve.Supported Formats
Format | Read | Patch | Export | Notes |
| sheets, ranges, tables, formulas, comments, hyperlinks, merged cells, hidden rows/cols, image/chart metadata | table cells, Excel cells | md/docx/pdf/xlsx | formula overwrite is blocked unless explicitly allowed |
| same as xlsx | restricted | md/docx/pdf/xlsx | macros are detected and never executed |
| rows, encoding fallback | table cells | md/docx/pdf/xlsx | UTF-8, CP949, EUC-KR, Latin-1 fallback |
| front matter, headings, paragraphs, lists, fenced code, tables, image links | blocks/table cells | md/docx/pdf/xlsx | best round-trip format |
| headings, paragraphs, tables, headers/footers, run style metadata, image metadata | blocks/table cells | md/docx/pdf/xlsx | complex Word XML is not fully round-tripped |
| pages, text layer, table candidates, image metadata | IR-level edits then regenerate | md/docx/pdf/xlsx | scanned PDFs require OCR outside this project |
Main Tools
Document:
document_ingestdocument_outlinedocument_searchdocument_read_chunkdocument_extract_tablesdocument_inspect_capabilitiesdocument_propose_editdocument_dry_run_editdocument_apply_editdocument_diffdocument_validatedocument_export
Excel:
excel_inspect_workbookexcel_read_rangeexcel_write_rangeexcel_evaluate_formulasexcel_recalculate_workbook
MES:
mes_classify_documentmes_extract_entitiesmes_validate_datames_generate_reportmes_export_json
Safety Model
Defaults are intentionally conservative:
Original files are copied into immutable-style storage before parsing.
Writes require
revision_idandapproval_id.Patches are schema-checked and dry-run capable.
Formula cell overwrite is blocked unless
allow_formula_overwrite=true.Export will not overwrite files unless explicitly requested.
Export artifacts are opened and hashed before publishing.
Macro/OLE/ActiveX/PDF JavaScript/zip traversal/zip bomb risks are detected.
Blocked ingest attempts are written to audit logs.
Document text is treated as untrusted data, not agent instructions.
Production Gates
Run before publishing changes:
uv sync --extra dev
uv run pytest -q
uv run python -m compileall -q src tests
uv buildCurrent local status:
14 passed
compileall ok
uv build ok
server import okProject Layout
src/mes_doc_mcp/
server.py MCP tool/resource/prompt server
cli.py local CLI
models.py DocumentIR, Block, SourceRef, PatchResult
parsers/ Excel, CSV, Markdown, Word, PDF parsers
patches.py PatchIR validation and application
renderers.py md/docx/pdf/xlsx exporters
validation.py structural validation gates
security.py file risk detection
artifacts.py export artifact validation
mes.py MES classification/extraction/validation
office.py optional LibreOffice recalculation helper
tests/ regression and production-gate tests
docs/ public usage docs
examples/ generated sample documents
scripts/ helper scriptsHonest Limits
This is not OCR. Image-only scanned PDFs need an OCR step before useful extraction.
PDF body editing is not true round-trip editing. Edit IR and regenerate PDF.
.xlsand.xlsbneed a conversion layer before full support.Complex pivot tables and charts are detected/preserved as metadata, not faithfully regenerated.
Real production confidence improves with site-specific golden fixtures.
License
MIT. See LICENSE.
Available Tools
23 toolsdocument_apply_editC
Apply PatchIR after approval and revision check.
Inputs: patch (required), doc_id (required), approval_id (required), revision_id (required). Returns: result
document_diffC
Diff two revisions. If after_revision_id is omitted, compare with latest.
Inputs: doc_id (required), before_revision_id (required), after_revision_id. Returns: result
document_dry_run_editC
Validate PatchIR and return a diff without saving.
Inputs: patch (required), doc_id (required), revision_id (required). Returns: result
document_exportC
Export current DocumentIR to md, docx, pdf, or xlsx.
Inputs: doc_id (required), output_format (required), overwrite, output_path. Returns: result
document_extract_tablesC
Return all detected table blocks.
Inputs: doc_id (required). Returns: result
document_ingestC
Ingest a document into immutable storage and create DocumentIR.
Inputs: file_path (required), allow_blocked. Returns: result
document_inspect_capabilitiesC
Report what this document can safely support.
Inputs: doc_id (required). Returns: result
document_listA
List ingested documents.
Inputs: no named parameters. Returns: result
document_outlineC
Return a compact outline with block ids and source references.
Inputs: doc_id (required). Returns: result
document_propose_editC
Return an edit envelope the AI/client can fill with PatchIR operations.
Inputs: doc_id (required), instruction (required). Returns: result
document_read_chunkC
Read one block or the first N blocks.
Inputs: doc_id (required), limit, block_id. Returns: result
document_searchC
Search text, headings, table cells, and metadata.
Inputs: query (required), doc_id (required), limit. Returns: result
document_validateC
Run structural and MES validation.
Inputs: doc_id (required). Returns: result
excel_evaluate_formulasB
Report formula cells. Full recalculation requires LibreOffice/Excel worker.
Inputs: doc_id (required). Returns: result
excel_inspect_workbookC
Return Excel-specific workbook metadata already extracted into IR.
Inputs: doc_id (required). Returns: result
excel_read_rangeB
Read an Excel range with formulas, comments, hyperlinks, and source refs.
Inputs: sheet (required), doc_id (required), range_ref (required). Returns: result
excel_recalculate_workbookC
Recalculate workbook with LibreOffice when available and write a new artifact.
Inputs: doc_id (required), output_path (required). Returns: result
excel_write_rangeC
Create excel_set_cell patches for a rectangular value matrix.
Inputs: sheet (required), doc_id (required), values (required), start_cell (required), +2 more. Returns: result
mes_classify_documentB
Classify an ingested document into MES document types.
Inputs: doc_id (required). Returns: result
mes_export_jsonC
Export normalized MES JSON buckets with validation issues.
Inputs: doc_id (required). Returns: result
mes_extract_entitiesC
Extract MES-like records from detected tables.
Inputs: doc_id (required). Returns: result
mes_generate_reportC
Generate a Markdown MES report and return text.
Inputs: doc_id (required). Returns: result
mes_validate_dataD
Run MES validation rules.
Inputs: doc_id (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 23 tools
Tools are clearly grouped into document, Excel, and MES operations with distinct purposes. No overlapping functionality; each tool has a unique role.
All tools follow a consistent snake_case pattern with domain prefix (document_, excel_, mes_) followed by verb_noun, e.g., document_apply_edit, excel_read_range.
23 tools is slightly high but appropriate given three subdomains (document, Excel, MES). Each tool serves a specific need without redundancy.
Covers core workflows: ingestion, editing, validation, export, search, and MES operations. Missing document deletion and revision listing, but these are minor gaps.
Related MCP Connectors
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
Create documents and reusable templates, request signatures, and track approvals — for AI agents.
Turns agent output into versioned web pages, PDFs, Word docs, spreadsheets and Markdown.
Read, edit and improve shared documents and knowledge with people and agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to extract and analyze text content from various document formats (PDF, DOCX, PPTX, XLSX) in local knowledge bases, and create new formatted Word and Excel documents with structured data and reports.5MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to create, edit, format, and analyze Microsoft Office documents (Excel, Word, PPT, PDF) using natural language, with features like table replication and automated styling.2MIT
- AlicenseAqualityCmaintenanceEnables AI agents to perform safe, semantic edits on Markdown and DOCX documents through a normalized model with staging, diff review, and stale-edit protection.13MIT
- AlicenseAqualityCmaintenanceEnables AI agents to read and edit Word (.docx) and PDF documents with byte-level fidelity, using minimal in-package rewrites for DOCX and text-layer detection with page rendering for PDF, including OCR-free handling of scanned files via image output.7MIT