# MES Document MCP

[![CI](https://github.com/sjMun09/MES-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sjMun09/MES-mcp/actions/workflows/ci.yml)

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

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

```text
source file
→ secure ingest
→ DocumentIR with source refs
→ search / inspect / MES extraction
→ PatchIR proposal
→ dry-run diff
→ human approval
→ apply
→ validate
→ export artifact
```

## Quickstart

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

Create sample files:

```bash
uv run python scripts/create_examples.py
```

Try the CLI:

```bash
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:

```bash
uv run python -m mes_doc_mcp.server
```

More detail:

- [Quickstart](docs/quickstart.md)
- [MCP Client Setup](docs/mcp-client-setup.md)
- [Tool Reference](docs/tool-reference.md)
- [Examples](docs/examples.md)
- [Production Criteria](PRODUCTION.md)
- [Usage Guide](USAGE.md)
- [Publication Checklist](docs/publication-checklist.md)

## MCP Client Config

Use this from the repository root:

```json
{
  "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:

```text
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:

```bash
uv sync --extra dev
uv run pytest -q
uv run python -m compileall -q src tests
uv build
```

Current local status:

```text
14 passed
compileall ok
uv build ok
server import ok
```

## Project Layout

```text
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](LICENSE).