Skip to main content
Glama

MES Document MCP

CI

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.server

  • A CLI: uv run mes-doc-mcp ...

  • A Python package: mes_doc_mcp

  • Parsers 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 artifact

Quickstart

git clone https://github.com/sjMun09/MES-mcp.git
cd MES-mcp
uv sync --extra dev
uv run pytest -q

Create sample files:

uv run python scripts/create_examples.py

Try 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.md

Run the MCP server:

uv run python -m mes_doc_mcp.server

More 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

.xlsx

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

.xlsm

same as xlsx

restricted

md/docx/pdf/xlsx

macros are detected and never executed

.csv

rows, encoding fallback

table cells

md/docx/pdf/xlsx

UTF-8, CP949, EUC-KR, Latin-1 fallback

.md

front matter, headings, paragraphs, lists, fenced code, tables, image links

blocks/table cells

md/docx/pdf/xlsx

best round-trip format

.docx

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

.pdf

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_ingest

  • document_outline

  • document_search

  • document_read_chunk

  • document_extract_tables

  • document_inspect_capabilities

  • document_propose_edit

  • document_dry_run_edit

  • document_apply_edit

  • document_diff

  • document_validate

  • document_export

Excel:

  • excel_inspect_workbook

  • excel_read_range

  • excel_write_range

  • excel_evaluate_formulas

  • excel_recalculate_workbook

MES:

  • mes_classify_document

  • mes_extract_entities

  • mes_validate_data

  • mes_generate_report

  • mes_export_json

Safety Model

Defaults are intentionally conservative:

  • Original files are copied into immutable-style storage before parsing.

  • Writes require revision_id and approval_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 build

Current local status:

14 passed
compileall ok
uv build ok
server import ok

Project 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 scripts

Honest 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.

  • .xls and .xlsb need 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 tools
document_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_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

    B3/5.0

    Scored across 23 tools

    Disambiguation5/5

    Tools are clearly grouped into document, Excel, and MES operations with distinct purposes. No overlapping functionality; each tool has a unique role.

    Naming Consistency5/5

    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.

    Tool Count4/5

    23 tools is slightly high but appropriate given three subdomains (document, Excel, MES). Each tool serves a specific need without redundancy.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to perform safe, semantic edits on Markdown and DOCX documents through a normalized model with staging, diff review, and stale-edit protection.
      13
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      7
      MIT