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 for the CLI spec and requirements/mcp.md for the MCP server spec.

Quick start

1. System dependency

The markdown → Word converters use pandoc. Install once:

brew install pandoc

2. Virtual environment

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

3. Smoke test

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

.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 for how to set up a dev environment, run the tests, and submit a pull request.

License

Apache License 2.0 — see LICENSE.