# office-mcp

[![test](https://github.com/xxxsonaaaaaa-maker/office-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/xxxsonaaaaaa-maker/office-mcp/actions/workflows/test.yml)
[![license: MIT](https://img.shields.io/badge/license-MIT-black.svg)](LICENSE)
[![python](https://img.shields.io/badge/python-3.10%2B-1F4E5A.svg)](pyproject.toml)

**MCP server that turns JSON into real files.** Excel, Word, CSV — no code
generation, no broken binaries, no `openpyxl` in your context window.

LLMs cannot reliably emit a valid `.xlsx`. They can write Python that *sometimes*
does, without formatting, formulas, column widths or multiple sheets — and they
burn 200 lines of context doing it. This server replaces that with one tool call:
15 lines of JSON in, a proper file out.

```
agent → make_xlsx({path, sheets}) → report.xlsx with styled headers, number
        formats, frozen panes, autofilter and a =SUM total row
```

## Install

```bash
uvx --from git+https://github.com/xxxsonaaaaaa-maker/office-mcp office-mcp
```

No npm account, no PyPI, no build step. Python 3.10+.

## Configure

Any MCP client (Claude Desktop, Cursor, Windsurf, Continue, custom):

```json
{
  "mcpServers": {
    "office": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xxxsonaaaaaa-maker/office-mcp", "office-mcp"]
    }
  }
}
```

## Tools

| Tool | Output | Highlights |
|---|---|---|
| `make_xlsx` | `.xlsx` | multiple sheets, column types (`text/number/money/percent/float`), widths, frozen header, autofilter, `=SUM` totals |
| `make_docx` | `.docx` | headings, paragraphs, bullets, tables with a real Word style |
| `make_csv` | `.csv` | custom delimiter, UTF-8 BOM so Excel opens Cyrillic correctly |

## Example

```json
{
  "path": "out/report.xlsx",
  "title": "October sales",
  "sheets": [{
    "name": "October",
    "columns": [
      {"header": "Item", "width": 28},
      {"header": "Qty", "type": "number"},
      {"header": "Price", "type": "money"},
      {"header": "Total", "type": "money"}
    ],
    "rows": [["Nails 90mm", 120, 12, 1440], ["Screws 4x50", 500, 3, 1500]],
    "totals": true
  }]
}
```

Result: `out/report.xlsx`, styled header row, `1440` formatted as money,
`=SUM(D4:D5)` in the total row.

## Safety

- Relative paths only; `..` is rejected — the server cannot write outside
  its working directory.
- Extension must match the tool (`.xlsx`, `.docx`, `.csv`), otherwise the
  call fails with a readable message instead of writing a corrupt file.
- Errors are returned as `isError` content with a human-readable reason, so
  the agent can fix the arguments and retry instead of guessing.

## Design notes

- **Zero transport coupling.** `office_core.py` is pure `dict → bytes`.
  The MCP layer, a CLI or an HTTP API are thin wrappers over the same core.
- **No storage.** Files are written locally; nothing is uploaded anywhere.
- **No magic.** The server compiles a spec. It does not invent content,
  call an LLM, or require a key.

## Status

v0.1 — XLSX, DOCX, CSV. PPTX and PDF are next; see `PLAN.md`.

## License

MIT