MarkItDown: конвертируем в макрдаун из оупенкод

Зачем это нужно

В работе с оупенкодом да и с агентами в целом, постоянно нужно читать документы, пдф файлы, эксель таблицы, презентации и прочие, не очень текстовые форматы. ЭЛЛ’мки хорошо понимают макрдаун, поэтому задача конвертации в маркдаун возникает постоянно. Также таким образом я — набиваю свое хранилище в обсидиан всякими гайдами.

Майкрософт выпустила утилиту MarkItDown пайтон библиотеку, которая умеет конвертировать, практически, всё во что угодно в маркдаун:

• *.PDF
• *.DOCX
• *.XLSX
• *.PPTX
• HTML
• *.EPUB
• *.XML
• ну и так далее

Что такое MCP и как это работает

MCP (Model Context Protocol) — это стандарт, который позволяет подключать внешние инструменты к эай-ассистентам (в нашем случае — к оупенкод). Через эмсипи мы даём оупенкод возможность выполнять произвольные действия: читать файлы, запускать команды, ходить в эпиай.

Мы создадим эмсипи сервер, который оборачивает MarkItDown в один простой инструмент convert_to_markdown. После этого оупенкод сможет сам сконвертировать файл в маркдаун, когда это понадобится.

Установка

1. Виртуальное окружение и зависимости

Макось больше не разрешает ставить пакеты через pip глобально, поэтому создадим venv и установим всё туда:

python3 -m venv ~/.config/opencode/mcp/venv
~/.config/opencode/mcp/venv/bin/pip3 install 'markitdown[all]' 'mcp[cli]'

Разбиваем на составляющие: markitdown[all] сама библиотека конвертации со всеми опциональными зависимостями, mcp[cli] Python SDK для создания эмсипи-серверов.

2. Скрипт эмсипи-сервера

Создаём файл ~/.config/opencode/mcp/markitdown_server.py:

Скачать готовый файл

from mcp.server.fastmcp import FastMCP
from markitdown import MarkItDown
import os

mcp = FastMCP("MarkItDown")

@mcp.tool()
def convert_to_markdown(file_path: str) -> str:
    """Convert any supported file (PDF, DOCX, PPTX, XLSX, HTML, EPUB, XML) to Markdown."""
    file_path = os.path.expanduser(os.path.abspath(file_path))
    if not os.path.exists(file_path):
        return f"Error: File not found: {file_path}"
    md = MarkItDown()
    result = md.convert(file_path)
    return result.text_content

if __name__ == "__main__":
    mcp.run(transport="stdio")

Здесь мы используем FastMCP - фреймворк, который берёт на себя всю работу: парсинг JSON-RPC, логирование и т.д. Кароче способ для ленивых.

3. Регистрация в оупенкод

Добавляем сервер в ~/.config/opencode/оупенкод.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bb-browser": { ... },
    "markitdown": {
      "type": "local",
      "command": [
        "/Users/beaverbloger/.config/opencode/mcp/venv/bin/python3",
        "/Users/beaverbloger/.config/opencode/mcp/markitdown_server.py"
      ]
    }
  }
}

Готово! оупенкод теперь знает про сервер и будет вызывать его автоматически.

4. Скилл для оупенкод

Чтобы агент сам знал когда вызывать convert_to_markdown, создаём скилл. Он подскажет агенту какие форматы поддерживаются и как сохранять результат.

Создайте файл ~/.opencode/skills/markitdown-converter/SKILL.md:

Скачать готовый файл

---
name: markitdown-converter
description: Convert files to Markdown using MCP tool
---

When the user provides a file in a non-text format that needs to be read or converted to Markdown:

1. **Supported formats:** `.pdf`, `.docx`, `.xlsx`, `.pptx`, `.html`, `.epub`, `.xml`

2. **Use the `convert_to_markdown` MCP tool** with the file path. The path can be:
   - Absolute: `/Users/name/file.pdf`
   - With `~`: `~/Downloads/file.docx`
   - Relative: `./file.xlsx`

3. **Save the result** as `.md` file next to the original:
   - `~/Documents/doc.pdf` → `~/Documents/doc.md`
   - `~/Downloads/report.xlsx` → `~/Downloads/report.md`

4. **Return the path** to the saved `.md` file to the user.

Теперь оупенкод сам понимает — файл не текстовый, надо конвертнуть.

Как это работает

Когда оупенкоду нужно обработать документ, он:

1. Видит, что есть инструмент convert_to_markdown
2. Отправляет к эмсипи-запрос с путём к файлу
3. Наш сервер запускает MarkItDown, конвертирует файл
4. Возвращает готовый маркдаун

Всё это происходит прозрачно. Оупенкод может вызвать этот инструмент самостоятельно, когда понимает, что файл нужно прочитать.

Проверка

Перезапустим оупенкод чтобы эмсипи у нас подхватился и просим конвертировать файл пдф в маркдаун. Или просто скажи «прочитай этот файл» — скилл подскажет агенту что делать и тот сам вызовет convert_to_markdown:

• Результат

Особенности

Из коробки библиотека использует встроенные инструменты: pdfplumber для пдф, mammoth для DOCX, openpyxl для XLSX, python-pptx для PPTX, beautifulsoup4 для HTML и т.д.

Итого

MarkItDown как эмсипи-сервер для оупенкод для меня это полезная комбинация. Юзайте для себя и вашего агента.