↓ Перейти к основному содержимому
Tatarinov
Tatarinov

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

·585 слов·3 минут·
OpenCode AI Оупенкод Markitdown Mcp Pdf Python
Оглавление
logo

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

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

Майкрософт выпустила утилиту 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 как эмсипи-сервер для оупенкод для меня это полезная комбинация. Юзайте для себя и вашего агента.

Related