mcp-pandoc: MCP-сервер преобразования документов

Официально включен в проект с открытым исходным кодом серверов Model Context Protocol . 🎉

Обзор

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

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

Кредит: В этом проекте для преобразования документов используется пакет Pandoc Python , который является основой этого проекта.

Related MCP server: md2pdf-mcp

Демо

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

Продолжение следует...

Инструменты

1. convert-contents

   • Преобразует контент между поддерживаемыми форматами

   • Входные данные:

     • contents (строка): Исходное содержимое для преобразования (обязательно, если не указан input_file)

     • input_file (строка): Полный путь к входному файлу (обязательно, если содержимое не указано)

     • input_format (string): Исходный формат содержимого (по умолчанию markdown)

     • output_format (string): Целевой формат (по умолчанию markdown)

     • output_file (строка): Полный путь к выходному файлу (обязательно для форматов pdf, docx, rst, latex, epub)

   • Поддерживаемые форматы ввода/вывода:

     • уценка

     • html

     • pdf

     • docx

     • первый

     • латекс

     • epub

     • текст

   • Примечание: для расширенных форматов (pdf, docx, rst, latex, epub) требуется путь к выходному файлу.

Поддерживаемые форматы

Поддерживаемые в настоящее время форматы:

Основные форматы (прямое преобразование):

• Обычный текст (.txt)

• Уценка (.md)

• HTML-код (.html)

Расширенные форматы (требуются полные пути к файлам):

• PDF (.pdf) — требуется установка TeX Live

• DOCX (.docx)

• РСТ (.rst)

• LaTeX (.tex)

• EPUB-файл (.epub)

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

1. Требуются полные пути к файлам с именем файла и расширением.

2. Для преобразования PDF требуется установка TeX Live (см. раздел Критические требования -> Для macOS: brew install texlive )

3. Если выходной путь не указан:

   • Базовые форматы: отображает преобразованный контент в чате.

   • Расширенные форматы: можно сохранять во временном каталоге системы (/tmp/ в системах Unix)

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

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

Использовать опубликованный

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

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

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

1. Установка Пандока

• Требуется : установить pandoc — основной механизм конвертации документов.

• Установка:

  # macOS
  brew install pandoc
  
  # Ubuntu/Debian
  sudo apt-get install pandoc
  
  # Windows
  # Download installer from: https://pandoc.org/installing.html

• Проверьте : pandoc --version

2. Установка УФ-пакета

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

• Установка:

  # macOS
  brew install uv
  
  # Windows/Linux
  pip install uv

• Проверьте : uvx --version

3. Предварительные условия для конвертации PDF: необходимы только в том случае, если вам нужно конвертировать и сохранять PDF.

• Перед попыткой конвертации PDF необходимо установить TeX Live.

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

  # Ubuntu/Debian
  sudo apt-get install texlive-xetex
  
  # macOS
  brew install texlive
  
  # Windows
  # Install MiKTeX or TeX Live from:
  # https://miktex.org/ or https://tug.org/texlive/

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

• При сохранении или конвертации файлов ОБЯЗАТЕЛЬНО указывайте полные пути к файлам, включая имя файла и расширение.

• Инструмент не генерирует автоматически имена файлов и расширения.

Примеры

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

# Converting content to PDF
"Convert this text to PDF and save as /path/to/document.pdf"

# Converting between file formats
"Convert /path/to/input.md to PDF and save as /path/to/output.pdf"

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

# Missing filename and extension
"Save this as PDF in /documents/"

# Missing complete path
"Convert this to PDF"

# Missing extension
"Save as /documents/story"

Распространенные проблемы и решения

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

   • Ошибка: «xelatex не найден»

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

2. Ошибка преобразования файла

   • Ошибка: «Неверный путь к файлу»

   • Решение: Укажите полный путь, включая имя файла и расширение.

   • Пример: /path/to/document.pdf вместо просто /path/to/

3. Не удалось преобразовать формат

   • Ошибка: «Неподдерживаемый формат»

   • Решение: Используйте только поддерживаемые форматы:

     • Базовые: txt, html, markdown

     • Расширенный: pdf, docx, rst, latex, epub

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

Установить

Вариант 1: Установка вручную с помощью файла конфигурации 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"
    ]
  }
}

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

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

Вариант 2: Автоматическая установка конфигурации опубликованных серверов через Smithery

Выполните следующую команду bash, чтобы автоматически установить опубликованный mcp-pandoc pypi для Claude Desktop через Smithery :

npx -y @smithery/cli install mcp-pandoc --client claude

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

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

Разработка

Строительство и издательское дело

Чтобы подготовить пакет к распространению:

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

uv sync

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

uv build

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

3. Опубликовать в PyPI:

uv publish

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

• Токен: --token или UV_PUBLISH_TOKEN

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

Отладка

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

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

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

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

Внося вклад

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

1. Сообщить о проблемах : Нашли ошибку или хотите запросить функцию? Откройте проблему на нашей странице GitHub Issues .

2. Отправьте запросы на извлечение : улучшите кодовую базу или добавьте функции, создав запрос на извлечение.