MCP-PDF-Server

KAP-AI/MCP-PDF-Server

3.1

If you are the rightful owner of MCP-PDF-Server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

KPDF2Edit MCP Server is a comprehensive server for processing PDF files, enabling data extraction, search, editing, and manipulation using PyMuPDF and related libraries.

KPDF2Edit MCP Server

📄 Комплексный MCP сервер для обработки PDF для извлечения данных, поиска, редактирования и манипуляции PDF файлами с использованием PyMuPDF и связанных библиотек.

STDIO транспортный протокол для MCP клиентов (VS Code, Claude Desktop, KiloCode).

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

1. Сборка проекта

# Клонировать репозиторий
git clone https://github.com/your-repo/kpdf2edit.git
cd kpdf2edit

# Установить Python зависимости
pip install -r requirements.txt

# Локальный запуск
python pdf_server.py

2. Запуск сервера

📡 Для MCP клиентов (VS Code, Claude Desktop, KiloCode) - STDIO режим
python pdf_server.py stdio
🐳 Использование Docker
# Собрать образ
docker build -t kpdf2edit:latest .

# Запустить в Docker (STDIO режим)
docker run --name kap-pdf-server --rm kpdf2edit:latest

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

# Тестировать STDIO режим
python test_mcp.py

🚀 Использование

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

Добавить в ~/Library/Application Support/Code/User/settings.json:

{
  "mcp": {
    "servers": {
      "kpdf2edit": {
        "type": "stdio",
        "command": "python",
        "args": ["/path/to/pdf_server.py", "stdio"]
      }
    }
  }
}

Интеграция с KiloCode

Добавить в настройки MCP KiloCode (обычно в ~/.config/kilocode/mcp_settings.json):

{
  "mcpServers": {
    "kpdf2edit": {
      "command": "python",
      "args": ["/path/to/pdf_server.py", "stdio"]
    }
  }
}

Или используя Docker:

{
  "mcpServers": {
    "kpdf2edit": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "kpdf2edit:latest", "stdio"]
    }
  }
}

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

Добавить в claude_desktop_config.json:

{
  "mcpServers": {
    "kpdf2edit": {
      "command": "python",
      "args": ["/path/to/pdf_server.py", "stdio"]
    }
  }
}

Docker развертывание

# Собрать образ
docker build -t kpdf2edit:latest .

# Запустить контейнер (STDIO режим)
docker run --name kap-pdf-server --rm kpdf2edit:latest

🔍 Тестирование и отладка

Тестирование MCP протокола

# Запустить тестовый скрипт
python test_mcp.py

# Или тестировать вручную с MCP клиентом
python pdf_server.py stdio

📄 Инструменты обработки PDF

🔍 Извлечение изображений (extract_images)

Извлечь все встроенные растровые изображения из PDF и вернуть в виде ZIP архива.

Параметры:

  • pdf_path (string): Путь к PDF файлу
  • quality (integer, опционально): Качество JPEG (по умолчанию: 90)

Возвращает: Путь к ZIP архиву с извлеченными изображениями

📝 Извлечение текста (extract_text)

Извлечь текст из PDF и вернуть в виде markdown содержимого.

Параметры:

  • pdf_path (string): Путь к PDF файлу
  • by_pages (boolean, опционально): Извлекать текст по страницам (по умолчанию: false)

Возвращает: Содержимое текста в формате Markdown

🔎 Поиск текста (search_text)

Найти текст в PDF и вернуть номера страниц и позиции.

Параметры:

  • pdf_path (string): Путь к PDF файлу
  • search_text (string): Текст для поиска

Возвращает: Список совпадений с номерами страниц и ограничивающими рамками

✏️ Редактирование текста (edit_text)

Редактировать текст в PDF на определенной странице (ограниченная функциональность).

⚠️ Ограничения:

  • Работает только с текстовыми блоками, не встроенными в изображения
  • Замена текста может не сохранить точное форматирование
  • Лучше всего для простых текстовых исправлений
  • Полное WYSIWYG редактирование PDF невозможно

Параметры:

  • pdf_path (string): Путь к PDF файлу
  • page_num (integer): Номер страницы для редактирования
  • old_text (string): Текст для замены
  • new_text (string): Новый текст для замены

Возвращает: Путь к измененному PDF файлу

🔗 Объединение PDF (merge_pdfs)

Объединить несколько PDF файлов в один.

Параметры:

  • pdf_paths (array): Список путей к PDF файлам для объединения

Возвращает: Путь к объединенному PDF файлу

✂️ Разделение PDF (split_pdf)

Разделить PDF на несколько файлов на основе диапазонов страниц.

Параметры:

  • pdf_path (string): Путь к PDF файлу для разделения
  • ranges (array): Диапазоны страниц для разделения (например: ['1-3', '5', '7-10'])
  • output_dir (string): Выходная директория для разделенных файлов

Возвращает: Путь к директории с разделенными PDF файлами

🔄 Поворот страниц (rotate_pages)

Повернуть страницы в PDF.

Параметры:

  • pdf_path (string): Путь к PDF файлу
  • rotation (integer): Угол поворота в градусах (90, 180, 270)
  • pages (array, опционально): Номера страниц для поворота (1-based, все страницы если не указано)
  • output_path (string, опционально): Путь к выходному файлу

Возвращает: Путь к повернутому PDF файлу

🗜️ Сжатие PDF (compress_pdf)

Сжать PDF путем снижения качества изображений.

Параметры:

  • pdf_path (string): Путь к PDF файлу
  • quality (integer, опционально): Качество сжатия (1-100, по умолчанию: 75)
  • output_path (string, опционально): Путь к выходному файлу

Возвращает: Путь к сжатому PDF файлу

🔧 Архитектура

📡 Stdio режим (MCP совместимость)

  • Назначение: Интеграция с MCP клиентами (VS Code, Claude Desktop, KiloCode)
  • Протокол: JSON-RPC через stdin/stdout
  • Запуск: python pdf_server.py stdio
  • Особенности: Полная совместимость со спецификацией MCP

🛠️ Технические детали

Системные требования

  • Python: версия 3.11 или новее
  • ОС: Linux, macOS, Windows
  • Зависимости: PyMuPDF, Pillow, pypdf

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

kpdf2edit/
├── pdf_server.py          # Основной код сервера
├── requirements.txt        # Python зависимости
├── Dockerfile              # Docker конфигурация
├── README.md               # Документация
└── ...

Сборка и развертывание

# Установить зависимости
pip install -r requirements.txt

# Запустить локально
python pdf_server.py

# Docker сборка
docker build -t kpdf2edit:latest .

# Кроссплатформенные сборки (используя PyInstaller)
pip install pyinstaller
pyinstaller --onefile pdf_server.py

Функции безопасности

  • Ограничение размера файла: Максимум 100MB на PDF
  • Валидация типа файла: Принимаются только PDF файлы
  • Валидация заголовка: Проверяет магические байты PDF (%PDF-)
  • Операция без состояния: Нет сохранения данных между сессиями
  • Очистка временных файлов: Автоматическая очистка в Docker контейнерах

Конфигурация

  • Режим работы: STDIO режим для MCP клиентов
  • Логирование: Все логи выводятся в stderr

📝 Лицензия: MIT License

📚 Дополнительные ресурсы

🤝 Поддержка

Если у вас есть вопросы или проблемы:

  1. Проверьте документацию в этом репозитории
  2. Просмотрите логи сервера в stderr
  3. Запустите тестовый скрипт: python test_mcp.py
  4. Создайте issue в репозитории проекта

⚠️ Важные ограничения

Ограничения редактирования текста:

  • PDF не является форматом текстового процессора
  • Редактирование текста ограничено простыми текстовыми блоками
  • Форматирование может быть не идеально сохранено
  • Сложные макеты нельзя полностью редактировать
  • Для продвинутого редактирования используйте специализированные редакторы PDF

Общие ограничения:

  • Максимальный размер файла: 100MB
  • Нет поддержки зашифрованных PDF
  • Качество извлечения изображений зависит от оригинального PDF
  • Сжатие является базовым (заглушка для продвинутой реализации)