MD-DOCX Конвертер

Инструмент на Python для двустороннего преобразования между Markdown (.md) и Microsoft Word (.docx). Разработан для упрощения переноса контента между документами Word и ИИ-инструментами, такими как Claude, ChatGPT и GitHub Copilot.

Что он делает

• Преобразует .md → .docx с правильной иерархией заголовков (Название, Заголовок 1–9)

• Преобразует .docx → .md в чистый GitHub Flavored Markdown (GFM)

• Запускается с простого ярлыка на рабочем столе — не требуется знание командной строки

• Обрабатывает заголовки, жирный/курсив/зачеркнутый текст, списки, списки задач, таблицы, цитаты, блоки кода, изображения и гиперссылки

См. MarkdownSyntax.md для получения полной информации о сопоставлении элементов и примечаний о том, что сохраняется, аппроксимируется или отбрасывается.

Требования

• Windows 10/11

• Python 3.11+

• Следующие пакеты Python (устанавливаются через pip):

pip install markdown-it-py python-docx

Настройка

1. Клонируйте репозиторий

git clone https://github.com/cjwpenner/md-docx-converter.git
cd md-docx-converter

2. Установите зависимости

pip install markdown-it-py python-docx

3. Создайте ярлык на рабочем столе

pip install pywin32
python create_shortcut.py

Это создаст ярлык MD-DOCX Converter на вашем рабочем столе Windows. pywin32 нужен только для создания ярлыка — он не требуется для запуска самого конвертера.

4. Запустите конвертер

Дважды щелкните MD-DOCX Converter на рабочем столе. Откроется окно консоли с запросом:

MD ↔ DOCX Converter
--------------------
Enter file path:

Вставьте или введите полный путь к вашему файлу .md или .docx и нажмите Enter. Преобразованный файл будет сохранен в той же директории с измененным расширением.

Вы также можете запускать его прямо из командной строки:

python md_docx_converter/converter.py

Примечания по конвертации

Иерархия заголовков

Сопоставление уровней заголовков зависит от контекста:

• MD → DOCX: Если в документе ровно один #, он становится Названием (Title) в Word. Все остальные заголовки сдвигаются на один уровень вниз. Если заголовков # несколько, все они становятся Заголовком 1 без Названия.

• DOCX → MD: Если в документе есть стиль Название (Title), он становится #. Все заголовки сдвигаются вверх соответствующим образом. Если Названия нет, Заголовок 1 становится #.

Элементы с потерей данных

Форматирование Word, не имеющее эквивалента в Markdown, аппроксимируется как жирный шрифт:

Изображения

• DOCX → MD: Внедренные изображения извлекаются в папку {filename}_images/ рядом с выходным файлом .md.

• MD → DOCX: Изображения, на которые ссылаются по относительному пути, внедряются повторно. Отсутствующие изображения заменяются на [image not found: path].

Интеграция с Claude Code

Этот инструмент интегрируется с Claude Code либо как плагин (рекомендуется — все настраивается двумя командами), либо как автономный MCP-сервер (для ручной настройки или Claude Desktop).

Вариант А: Плагин Claude Code (рекомендуется)

Плагин объединяет конфигурацию MCP-сервера и навык /convert. Выполните эти две команды внутри Claude Code:

/plugin marketplace add cjwpenner/md-docx-converter
/plugin install md-docx-converter@md-docx-converter

Это все — дальнейшая настройка не требуется. После выполнения /reload-plugins Claude получит инструменты конвертации, и вы сможете вызывать навык напрямую:

/md-docx-converter:convert path/to/file.md
/md-docx-converter:convert path/to/report.docx

Или просто попросите естественным языком: "Convert this to a Word document", и Claude автоматически использует инструменты.

Вариант Б: Только MCP-сервер (ручная настройка)

Используйте этот вариант, если вам нужны только инструменты MCP без плагина или если вы настраиваете Claude Desktop, а не Claude Code.

Установите пакет:

pip install mcp-md-docx

Claude Code — зарегистрируйте MCP-сервер:

claude mcp add md-docx-converter --transport stdio -- uvx mcp-md-docx

Claude Desktop — добавьте в %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "md-docx-converter": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-md-docx"]
    }
  }
}

Доступные инструменты

После настройки вы можете говорить, например:

• "Read report.docx and summarise it"

• "Turn this into a Word document and save it to my Desktop"

• "Convert all the bullet points in notes.docx into a table"

Структура проекта

md_docx_converter/
├── converter.py       # CLI entry point
├── md_to_docx.py      # Markdown → Word conversion
├── docx_to_md.py      # Word → Markdown conversion
├── heading_mapper.py  # Heading hierarchy pre-scan logic
├── image_handler.py   # Image extraction and embedding
└── launch.pyw         # Desktop shortcut launcher
mcp_md_docx/
├── server.py          # MCP server (four tools)
└── __main__.py        # Entry point for python -m mcp_md_docx
create_shortcut.py     # One-time shortcut setup script
pyproject.toml         # PyPI packaging config

Лицензия

Этот проект лицензирован под GNU General Public License v3.0 (GPLv3). Вы можете свободно использовать, изменять и распространять это программное обеспечение при условии, что любые производные работы также распространяются на тех же условиях лицензии.

См. LICENSE для получения полного текста лицензии.

Сторонние библиотеки

Этот проект зависит от следующих библиотек с открытым исходным кодом, все они лицензированы по MIT:

Полные тексты лицензий воспроизведены в THIRD_PARTY_NOTICES.md.