mcp-pandoc: Bir Belge Dönüştürme MCP Sunucusu

Resmi olarak Model Context Protocol sunucuları açık kaynak projesine dahil edilmiştir. 🎉

Genel Bakış

pandoc kullanarak belge formatı dönüştürme için bir Model Context Protocol sunucusu. Bu sunucu, biçimlendirme ve yapıyı koruyarak içeriği farklı belge formatları arasında dönüştürmek için araçlar sağlar.

mcp-pandoc'un şu anda erken geliştirme aşamasında olduğunu lütfen unutmayınız. PDF desteği geliştirme aşamasındadır ve sunucuyu geliştirmeye devam ettikçe işlevsellik ve kullanılabilir araçlar değişebilir ve genişleyebilir.

Kredi: Bu proje, belge dönüştürme için Pandoc Python paketini kullanmakta ve bu projenin temelini oluşturmaktadır.

📋 Hızlı Referans

mcp-pandoc'ta yeni misiniz? 📖 CHEATSHEET.md dosyasını kontrol edin

⚡ Tüm formatlar için kopyala-yapıştır örnekleri
🔄 Çift yönlü dönüştürme matrisi
🎯 Yaygın iş akışları ve ipuçları
🌟 Referans belge stil rehberi

Hızlı aramalar ve hızlı başlama için mükemmel!

Demo

🎥 YouTube'da İzleyin

Ekran Görüntüleri

Daha fazlası yakında gelecek...

Araçlar

convert-contents
- İçeriği desteklenen formatlar arasında dönüştürür
- Girdiler:
  - contents (string): Dönüştürülecek kaynak içerik (input_file sağlanmadıysa gerekli)
  - input_file (string): Giriş dosyasının tam yolu (contents sağlanmadıysa gerekli)
  - input_format (string): İçeriğin kaynak formatı (varsayılan olarak markdown)
  - output_format (string): Hedef format (varsayılan olarak markdown)
  - output_file (string): Çıktı dosyası için tam yol (pdf, docx, rst, latex, epub formatları için gerekli)
  - reference_doc (string): Stil için kullanılacak referans belgenin yolu (docx çıktı formatı için desteklenmiştir)
  - defaults_file (string): Dönüştürme seçeneklerini içeren Pandoc varsayılanları dosyasının (YAML) yolu
  - filters (array): Dönüştürme sırasında uygulanacak Pandoc filtre yollarının listesi
- Desteklenen giriş/çıktı formatları:
  - markdown
  - html
  - pdf
  - docx
  - rst
  - latex
  - epub
  - txt
  - ipynb
  - odt
- Not: Gelişmiş formatlar (pdf, docx, rst, latex, epub) için bir output_file yolu gereklidir

🔧 Gelişmiş Özellikler

Varsayılanlar Dosyaları (YAML Yapılandırması)

Tutarlı biçimlendirme ile yeniden kullanılabilir dönüştürme şablonları oluşturmak için varsayılanlar dosyalarını kullanın:

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

Örnek kullanım: "Convert paper.md to PDF using defaults academic-paper.yaml and save as paper.pdf"

Pandoc Filtreleri

Geliştirilmiş işleme için özel filtreler uygulayın:

Örnek kullanım: "Convert docs.md to HTML with filters ['/path/to/mermaid-filter.py'] and save as docs.html"

💡 Kapsamlı örnekler ve iş akışları için, bkz. CHEATSHEET.md

📊 Desteklenen Formatlar ve Dönüştürmeler

Çift Yönlü Dönüştürme Matrisi

Kaynaktan\Hedef	MD	HTML	TXT	DOCX	PDF	RST	LaTeX	EPUB	IPYNB	ODT
Markdown	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
HTML	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
TXT	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
DOCX	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
RST	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
LaTeX	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
EPUB	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
IPYNB	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
ODT	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅

PDF Desteği Hakkında Not

Bu araç dönüştürmeler için pandoc kullanır ve yukarıdaki formatlardan PDF dosyaları oluşturmaya izin verir. Ancak bir PDF'den diğer formatlara dönüştürme desteklenmiyor. Bu nedenle PDF, yalnızca çıktı formatı olarak düşünülmelidir.

Format Kategorileri

Kategori	Formatlar	Gereksinimler
Temel	MD, HTML, TXT, IPYNB, ODT	Hiçbiri
Gelişmiş	DOCX, PDF, RST, LaTeX, EPUB	`output_file` yolu belirtilmeli
Stillenmiş	DOCX referans belgesi	Özel şablon desteği ⭐

Format'a Göre Gereksinimler

PDF (.pdf) - TeX Live kurulumu gerekir
DOCX (.docx) - referans belgeler aracılığıyla özel stil desteği
Diğerleri - ek gereksinim yoktur

Not: Gelişmiş formatlar için:

Dosya adı ve uzantısı içeren tam dosya yolları gereklidir
PDF dönüştürme TeX Live kurulumunu gerektirir (bkz. Kritik Gereksinimler bölümü -> macOS için: brew install texlive)
Çıktı yolu belirtilmediğinde:
- Temel formatlar: Sohbette dönüştürülmüş içeriği görüntüler
- Gelişmiş formatlar: Sistem geçici dizinine kaydedebilir (Unix sistemlerde /tmp/)

Kullanım ve Yapılandırma

NOT: Aşağıdaki "Kritik Gereksinimler" altında belirtilen gerekli paketleri kurduğunuzdan emin olun.

Yayınlanmış olanı kullanmak için

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

💡 Hızlı Başlama: Kopyala-yapıştır örnekleri ve yaygın iş akışları için CHEATSHEET.md dosyasını görün.

⚠️ Önemli Notlar

Kritik Gereksinimler

Pandoc Kurulumu

Gerekli: pandoc yükleyin - çekirdek belge dönüştürme motorunun

Kurulum:

# macOS
brew install pandoc

# Ubuntu/Debian
sudo apt-get install pandoc

# Windows
# İndirme bağlantısı: https://pandoc.org/installing.html

Doğrula: pandoc --version

UV paket kurulumu

Gerekli: uv paketini yükleyin (uvx komutu dahil)

Kurulum:

# macOS
brew install uv

# Windows/Linux
pip install uv

Doğrula: uvx --version

PDF Dönüştürme Ön Koşulları: Yalnızca pdf dönüştürme ve kaydetme gerekiyorsa gerekli

PDF dönüştürmesini denemeden önce TeX Live yüklü olmalıdır

Kurulum komutları:

# Ubuntu/Debian
sudo apt-get install texlive-xetex

# macOS
brew install texlive

# Windows
# MiKTeX veya TeX Live yükleyin:
# https://miktex.org/ veya https://tug.org/texlive/

Dosya Yolu Gereksinimleri

Dosyaları kaydederken veya dönüştürürken, dosya adı ve uzantısı dahil tam dosya yolları belirtmelisiniz
Araç otomatik olarak dosya adları veya uzantıları oluşturmaz

Örnekler

✅ Doğru Kullanım:

# İçeriği PDF'ye dönüştürme
"Convert this text to PDF and save as /path/to/document.pdf"

# Dosya formatları arasında dönüştürme
"Convert /path/to/input.md to PDF and save as /path/to/output.pdf"

# Referans belge şablonu kullanarak DOCX'e dönüştürme
"Convert input.md to DOCX using template.docx as reference and save as output.docx"

# Adım adım referans belge iş akışı
"First create a reference document: pandoc -o custom-reference.docx --print-default-data-file reference.docx" veya zaten bir belgeniz varsa onu kullanın
"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"

❌ Yanlış Kullanım:

# Dosya adı ve uzantısı eksik
"Save this as PDF in /documents/"

# Tam yol eksik
"Convert this to PDF"

# Uzantı eksik
"Save as /documents/story"

Yaygın Sorunlar ve Çözümler

PDF Dönüştürme Başarısız
- Hata: "xelatex not found"
- Çözüm: İlk olarak TeX Live yükleyin (yukarıdaki kurulum komutlarını görün)
Dosya Dönüştürme Başarısız
- Hata: "Invalid file path"
- Çözüm: Dosya adı ve uzantısı dahil tam yol sağlayın
- Örnek: /path/to/document.pdf yerine sadece /path/to/
Format Dönüştürme Başarısız
- Hata: "Unsupported format"
- Çözüm: Yalnızca desteklenen formatları kullanın:
  - Temel: txt, html, markdown
  - Gelişmiş: pdf, docx, rst, latex, epub
Referans Belge Sorunları
- Hata: "Reference document not found"
- Çözüm: Referans belge yolunun var olduğundan ve erişilebilir olduğundan emin olun
- Not: Referans belgeler yalnızca DOCX çıktı formatı ile çalışır
- Nasıl oluşturulur: pandoc -o reference.docx --print-default-data-file reference.docx

Hızlı Başlama

claude_desktop_config.json config dosyası aracılığıyla manuel olarak yükleme

MacOS'ta: open ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows'ta: %APPDATA%/Claude/claude_desktop_config.json

a) Yalnızca yerel geliştirme ve bu depoya katkı için

Geliştirme/Yayınlanmamış Sunucular Yapılandırması

ℹ️ yerine yerel olarak klonlanmış proje yolunuzu yazın

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

b) Yayınlanmış Sunucular Yapılandırması - Tüketiciler bu yapılandırmayı kullanmalıdır

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

Herhangi bir sorunla karşılaşırsanız, yerine doğrudan yukarıdaki "Yayınlanmış Sunucular Yapılandırması"'nı kullanın.

Not: Yerel olarak yapılandırılan mcp-pandoc'u kullanmak için yukarıdaki "Geliştirme/Yayınlanmamış Sunucular Yapılandırması" adımını izleyin.

Geliştirme

Test Etme

Kapsamlı test paketini çalıştırmak ve tüm desteklenen çift yönlü dönüştürmeleri doğrulamak için aşağıdaki komutu kullanın:

uv run pytest tests/test_conversions.py

Bu, geriye dönük uyumluluğu sağlar ve aracın temel işlevselliğini doğrular.

Oluşturma ve Yayımlama

Paketi dağıtım için hazırlamak için:

Bağımlılıkları senkronize edin ve kilit dosyasını güncelleyin:

uv sync

Paket dağıtımları oluşturun:

uv build

Bu, dist/ dizininde kaynak ve wheel dağıtımları oluşturacak.

PyPI'de yayınlayın:

uv publish

Not: PyPI kimlik bilgilerini ortam değişkenleri veya komut bayrakları aracılığıyla ayarlamanız gerekir:

Token: --token veya UV_PUBLISH_TOKEN
Veya kullanıcı adı/şifre: --username/UV_PUBLISH_USERNAME ve --password/UV_PUBLISH_PASSWORD

Hata Ayıklama

MCP sunucuları stdio üzerinden çalıştığından hata ayıklama zor olabilir. En iyi hata ayıklama deneyimi için MCP Inspector kullanmanızı şiddetle tavsiye ederiz.

MCP Inspector'ı npm ile şu komutla başlatabilirsiniz:

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

Başlattığında, Inspector hata ayıklamaya başlamak için tarayıcıda erişebileceğiniz bir URL görüntüleyecek.

Katkıda Bulunma

mcp-pandoc'u geliştirmek için katkılarınızı bekliyoruz! İşte katılabileceğiniz yollar:

Sorunları Bildirin: Bir hata buldunuz mu veya bir özellik isteğiniz mi var? GitHub Issues sayfamızda bir sorun açın.
Pull Request'leri Gönderin: Kod tabanını iyileştirin veya pull request oluşturarak yeni özellikler ekleyin.

vivekVells/mcp-pandoc

Bu MCP sunucusu hakkında