# file-conversion

A small library + CLI + MCP server for converting between everyday file formats. Built primarily for Claude Desktop to call during other workflows, but usable directly from the command line.

Currently supports:

- **CSV → Excel** (`.csv` → `.xlsx`, one sheet)
- **Excel → CSV per sheet** (`.xlsx` → one `.csv` per sheet in an output directory)
- **Markdown → Word** (`.md` → `.docx`, via pandoc)
- **Markdown → Word, GxP template** — same as above, plus a version-history table, a definitions table, and a footer with title and version on every page

See [`requirements/requirements.md`](requirements/requirements.md) for the CLI spec and [`requirements/mcp.md`](requirements/mcp.md) for the MCP server spec.

## Quick start

### 1. System dependency

The markdown → Word converters use [pandoc](https://pandoc.org/). Install once:

```bash
brew install pandoc
```

### 2. Virtual environment

```bash
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
```

### 3. Smoke test

```bash
.venv/bin/file-conversion --help
```

## CLI usage

```
file-conversion COMMAND [ARGS]...

Commands:
  csv-to-xlsx   CSV_PATH XLSX_PATH [--sheet-name NAME]
  xlsx-to-csvs  XLSX_PATH OUTPUT_DIR
  md-to-docx    MD_PATH DOCX_PATH [--landscape]
  md-to-docx-gxp MD_PATH DOCX_PATH [--title TEXT] [--version TEXT] [--landscape]
```

`md-to-docx-gxp` reads optional YAML frontmatter from the markdown to populate
the version table and definitions table. CLI flags `--title` and `--version`
override frontmatter when provided. See `requirements/requirements.md` for the
frontmatter schema.

`--landscape` sets Letter landscape page orientation (11" × 8.5") on both
markdown → Word commands — useful for documents with wide tables. Without it,
pandoc's page setup is left untouched and Word applies its default portrait
page.

```bash
.venv/bin/file-conversion md-to-docx wide-tables.md wide-tables.docx --landscape
.venv/bin/file-conversion md-to-docx-gxp sop.md sop.docx --landscape
```

## MCP server

`python -m file_conversion.mcp_server` exposes the same four conversions as MCP
tools over stdio. Add it to your Claude Desktop config as a regular MCP server.
Both markdown → Word tools take a `landscape: bool = False` argument matching
the CLI flag.

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for how to set up a dev environment,
run the tests, and submit a pull request.

## License

Apache License 2.0 — see [`LICENSE`](LICENSE).