Официально включён в проект открытого ПО Model Context Protocol servers. 🎉

Обзор

Сервер протокола Context Model для преобразования форматов документов с использованием pandoc. Этот сервер предоставляет инструменты для преобразования содержимого между различными форматами документов с сохранением форматирования и структуры.

Обратите внимание, что mcp-pandoc находится на ранней стадии разработки. Поддержка PDF находится в процессе разработки, функциональность и доступные инструменты могут изменяться и расширяться по мере продолжения улучшения сервера.

Благодарности: Этот проект использует Pandoc Python package для преобразования документов, что составляет основу данного проекта.

📋 Краткая справка

Новичок в mcp-pandoc? Ознакомьтесь с 📖 ШПАРГАЛКОЙ.md для получения:

• ⚡ Примеров для копирования и вставки для всех форматов
• 🔄 Матрицы двустороннего преобразования
• 🎯 Типовых рабочих процессов и профессиональных советов
• 🌟 Руководства по стилизации с помощью эталонного документа

Идеально для быстрого поиска и скорого начала работы!

Демо

🎥 Смотреть на YouTube

Скриншоты

Скоро будет больше...

Инструменты

1. convert-contents
   • Преобразует содержимое между поддерживаемыми форматами
   • Входные параметры:
     • contents (string): Исходное содержимое для преобразования (обязательно, если не предоставлен input_file)
     • input_file (string): Полный путь к входному файлу (обязательно, если не предоставлен contents)
     • input_format (string): Исходный формат содержимого (по умолчанию markdown)
     • output_format (string): Целевой формат (по умолчанию markdown)
     • output_file (string): Полный путь для выходного файла (обязателен для форматов pdf, docx, rst, latex, epub)
     • reference_doc (string): Путь к эталонному документу для стилизации (поддерживается для выходного формата docx)
     • defaults_file (string): Путь к файлу defaults для Pandoc (YAML), содержащему параметры преобразования
     • filters (array): Список путей к фильтрам Pandoc для применения во время преобразования
   • Поддерживаемые входные/выходные форматы:
     • markdown
     • html
     • pdf
     • docx
     • rst
     • latex
     • epub
     • txt
     • ipynb
     • odt
   • Примечание: Для расширенных форматов (pdf, docx, rst, latex, epub) требуется путь к output_file

🔧 Расширенные возможности

Файлы Defaults (Конфигурация YAML)

Используйте файлы defaults для создания многоразовых шаблонов преобразования с единообразным форматированием:

# academic-paper.yaml
from: markdown
to: pdf
number-sections: true
toc: true
metadata:
  title: "Academic Paper"
  author: "Research Team"

Пример использования: "Преобразовать paper.md в PDF, используя defaults academic-paper.yaml, и сохранить как paper.pdf"

Фильтры Pandoc

Применяйте пользовательские фильтры для расширенной обработки:

Пример использования: "Преобразовать docs.md в HTML с фильтрами ['/path/to/mermaid-filter.py'] и сохранить как docs.html"

💡 Для получения всеобъемлющих примеров и рабочих процессов см. ШПАРГАЛКУ.md

📊 Поддерживаемые форматы и преобразования

Матрица двустороннего преобразования

Примечание о поддержке PDF

Этот инструмент использует pandoc для преобразований, что позволяет генерировать PDF-файлы из перечисленных выше форматов. Однако преобразование из PDF в другие форматы не поддерживается. Поэтому PDF следует рассматривать как формат только для вывода.

Категории форматов

Требования по форматам

• PDF (.pdf) - требует установки TeX Live
• DOCX (.docx) - поддерживает пользовательскую стилизацию через эталонные документы
• Все остальные - не требуют дополнительных условий

Примечание: Для расширенных форматов:

1. Требуются полные пути к файлам с именем файла и расширением
2. Преобразование в PDF требует установки TeX Live (см. раздел Критические требования -> Для macOS: brew install texlive)
3. Когда путь вывода не указан:
   • Базовые форматы: Отображает преобразованное содержимое в чате
   • Расширенные форматы: Может сохраняться во временной директории системы (/tmp/ в системах Unix)

Использование и конфигурация

ПРИМЕЧАНИЕ: Убедитесь, что вы выполнили установку необходимых пакетов, упомянутых ниже в разделе "Критические требования".

Для использования опубликованной версии

{
  "mcpServers": {
    "mcp-pandoc": {
      "command": "uvx",
      "args": ["mcp-pandoc"]
    }
  }
}

💡 Быстрый старт: См. ШПАРГАЛКУ.md для примеров копирования и вставки и типовых рабочих процессов.

⚠️ Важные замечания

Критические требования

1. Установка Pandoc

• Требуется: Установите pandoc — основной движок конвертации документов

• Установка:

  ```bash

  macOS

  brew install pandoc

  Ubuntu/Debian

  sudo apt-get install pandoc

  Windows

  Загрузите установщик с: https://pandoc.org/installing.html

  ```

• Проверка: pandoc --version

1. Установка пакета UV

• Требуется: Установите пакет uv (включает команду uvx)

• Установка:

  ```bash

  macOS

  brew install uv

  Windows/Linux

  pip install uv ```

• Проверка: uvx --version

1. Предпосылки для конвертации в PDF: Требуются только если вам нужно конвертировать и сохранять pdf

• TeX Live должен быть установлен до попытки конвертации в PDF

• Команды установки:

  ```bash

  Ubuntu/Debian

  sudo apt-get install texlive-xetex

  macOS

  brew install texlive

  Windows

  Установите MiKTeX или TeX Live с:

  https://miktex.org/ или https://tug.org/texlive/

  ```

1. Требования к путям файлов

• При сохранении или конвертации файлов вы ОБЯЗАНЫ указывать полные пути файлов, включая имя файла и расширение
• Инструмент не генерирует автоматически имена файлов или расширения

Примеры

✅ Правильное использование:

# Конвертация содержимого в PDF
"Convert this text to PDF and save as /path/to/document.pdf"

# Конвертация между форматами файлов
"Convert /path/to/input.md to PDF and save as /path/to/output.pdf"

# Конвертация в DOCX с использованием шаблона эталонного документа
"Convert input.md to DOCX using template.docx as reference and save as output.docx"

# Пошаговый процесс работы с эталонным документом
"First create a reference document: pandoc -o custom-reference.docx --print-default-data-file reference.docx" or if you already have one, use that
"Then convert with custom styling: Convert this text to DOCX using /path/to/custom-reference.docx as reference and save as /path/to/styled-output.docx"

❌ Неправильное использование:

# Отсутствует имя файла и расширение
"Save this as PDF in /documents/"

# Отсутствует полный путь
"Convert this to PDF"

# Отсутствует расширение
"Save as /documents/story"

Типичные проблемы и решения

1. Конвертация в PDF не удается

   • Ошибка: "xelatex not found"
   • Решение: Сначала установите TeX Live (см. команды установки выше)

2. Конвертация файла не удается

   • Ошибка: "Invalid file path"
   • Решение: Укажите полный путь, включая имя файла и расширение
   • Пример: /path/to/document.pdf вместо просто /path/to/

3. Конвертация формата не удается

   • Ошибка: "Unsupported format"
   • Решение: Используйте только поддерживаемые форматы:
     • Базовые: txt, html, markdown
     • Продвинутые: pdf, docx, rst, latex, epub

4. Проблемы с эталонным документом

   • Ошибка: "Reference document not found"
   • Решение: Убедитесь, что путь к эталонному документу существует и доступен
   • Примечание: Эталонные документы работают только с форматом вывода DOCX
   • Как создать: pandoc -o reference.docx --print-default-data-file reference.docx

Быстрый старт

Ручная установка через файл конфигурации claude_desktop_config.json

• На MacOS: open ~/Library/Application\ Support/Claude/claude_desktop_config.json
• На Windows: %APPDATA%/Claude/claude_desktop_config.json

а) Только для локальной разработки и вклада в этот репозиторий

Конфигуляция для разработки/неопубликованных серверов

ℹ️ Замените на путь к вашему локально склонированному проекту

"mcpServers": {
"mcp-pandoc": {
  "command": "uv",
  "args": [
    "--directory",
    "<DIRECTORY>/mcp-pandoc",
    "run",
    "mcp-pandoc"
  ]
}
}

b) Конфигуляция опубликованных серверов - Пользователям следует использовать эту конфигурацию

"mcpServers": {
  "mcp-pandoc": {
    "command": "uvx",
    "args": [
      "mcp-pandoc"
    ]
  }
}

• Если вы столкнулись с какой-либо проблемой, используйте приведенную выше «Конфигурацию опубликованных серверов» напрямую вместо этой cli.

Примечание: Для использования локально настроенного mcp-pandoc следуйте шагу «Конфигурация для разработки/неопубликованных серверов» выше.

Разработка

Тестирование

Для запуска комплексного набора тестов и проверки всех поддерживаемых двусторонних конвертаций используйте следующую команду:

uv run pytest tests/test_conversions.py

Это обеспечивает обратную совместимость и проверяет основную функциональность инструмента.

Сборка и публикация

Для подготовки пакета к распространению:

1. Синхронизация зависимостей и обновление файла блокировки:

uv sync

1. Сборка дистрибутивов пакета:

uv build

Это создаст исходные и wheel дистрибутивы в каталоге dist/.

1. Публикация в PyPI:

uv publish

Примечание: Вам нужно будет установить учетные данные PyPI через переменные окружения или флаги команды:

• Токен: --token или UV_PUBLISH_TOKEN
• Или имя пользователя/пароль: --username/UV_PUBLISH_USERNAME и --password/UV_PUBLISH_PASSWORD

Отладка

Поскольку серверы MCP работают через stdiо, отладка может быть затруднительной. Для наилучшего опыта отладки мы настоятельно рекомендуем использовать MCP Inspector.

Вы можете запустить MCP Inspector через npm с помощью этой команды:

npx @modelcontextprotocol/inspector uv --directory /Users/vivekvells/Desktop/code/ai/mcp-pandoc run mcp-pandoc

При запуске Inspector отобразит URL-адрес, который вы можете открыть в браузере для начала отладки.

Вклад

Мы приветствуем вклад в развитие mcp-pandoc! Вот как вы можете присоединиться:

1. Сообщайте о проблемах: нашли ошибку или есть запрос функции? Откройте проблему на странице GitHub Issues.
2. Отправляйте Pull Requests: улучшайте кодовую базу или добавляйте функции, создавая pull request.