Dokumenty biurowe

Co robi

Dokumenty biurowe to wbudowany worker, który czyta, zapisuje i konwertuje pliki Word, Excel, PowerPoint i PDF, a przy okazji rysuje wykresy. Nie wymaga konta ani klucza API i sięga tylko po pliki, które masz już w projekcie. Ta strona opisuje workera kryjącego się za funkcją Dokumenty biurowe: z czego się składa, jakie formaty obsługuje i którędy przechodzi przez niego plik.

Z czego się składa

Worker to jeden kontener, mcp-office, czyli cienka warstwa TypeScriptu narzucona na sprawdzone narzędzia:

markitdown i SheetJS do odczytu
pandoc do konwersji Markdown
WeasyPrint do konwersji HTML i Markdown na PDF
LibreOffice headless do konwersji Office na PDF oraz Office na Office
python-docx, openpyxl i python-pptx do tworzenia i edycji plików
pypdf do operacji na PDF
matplotlib do rysowania wykresów jako obrazów

Z hosta podłącza tylko jedno: przestrzeń roboczą twojego projektu, do odczytu i zapisu, pod /workspace. Nie ma tu punktu montowania /tokens, dokładnie jak w workerze do automatyzacji przeglądarki, który również obchodzi się bez danych logowania.

Jak to działa

Claude wywołuje narzędzie przez hub, worker działa na pliku w przestrzeni roboczej twojego projektu, a wynik wraca jako plik i krótki podgląd, nie zaś jako cały dokument wciśnięty do kontekstu.

Odczyt dokumentu. Silnik dobiera się do typu pliku: SheetJS do arkuszy kalkulacyjnych, markitdown do Worda, PowerPointa i PDF, a dla trudniejszych plików czekają rozwiązania zapasowe. Nic z tego nie uruchamia OCR, więc zeskanowany PDF albo taki złożony z samego obrazu nie ma warstwy tekstu, z której dałoby się coś wydobyć. Nie licz też na pełnowierną ścieżkę w stylu “edytowalny dokument Word prosto z PDF”.

Zapis albo konwersja. Przy PDF worker obiera najkrótszą drogę, zależnie od tego, z czym startujesz: Markdown, HTML albo gotowy plik .docx, .xlsx lub .pptx. Z edytowalnym plikiem Office jest tak samo, a wyjść masz trzy: Markdown, ustrukturyzowana specyfikacja albo istniejący plik, który edytujesz na miejscu (jako nową kopię).

convertOffice przeprowadza konwersję formatów według sztywnej macierzy, na przykład .docx na pdf, odt, txt, html albo rtf. Parę spoza tej macierzy, choćby .xlsx na .docx, po prostu odrzuca.

Z wykresami rzecz ma się podobnie: renderChart daje samodzielny plik PNG albo SVG, natomiast natywny, edytowalny wykres w arkuszu albo prezentacji powstaje jedynie w createXlsx lub createPptx, bo wykres wstawiony do .docx zawsze pozostaje obrazem.

Każda ścieżka, wejściowa i wyjściowa, zostaje przed użyciem sprowadzona do postaci kanonicznej i sprawdzona: tę spoza przestrzeni roboczej albo taką z elementem będącym dowiązaniem symbolicznym worker odrzuca. Wygenerowane pliki lądują w .speedwave/office/ w twoim projekcie, zapis odbywa się atomowo, a istniejącego pliku nic nie nadpisze, dopóki nie przekażesz overwrite: true.

Co potrafi

Żadne z tych narzędzi nie kasuje ani nie nadpisuje twojego pliku źródłowego: edycje i konwersje zawsze zapisują nowy plik, a istniejący wynik podmienia się tylko wtedy, gdy przekażesz overwrite: true.

Narzędzie	Co robi
`readDocument`	Wydobywa treść pliku Word, Excel, PowerPoint, PDF albo HTML do Markdown.
`readPdfText`	Zwraca surową warstwę tekstu z PDF, bez struktury.
`pdfMetadata`	Podaje liczbę stron PDF, tytuł, autora i to, czy plik jest zaszyfrowany.
`markdownToPdf`	Renderuje Markdown do PDF przez pandoc i WeasyPrint.
`htmlToPdf`	Renderuje lokalny HTML do PDF przez WeasyPrint.
`markdownToDocx`	Zamienia Markdown na plik Word przez pandoc.
`markdownToPptx`	Zamienia Markdown na prezentację, po jednym slajdzie na nagłówek.
`renderChart`	Rysuje wykres słupkowy, liniowy, kołowy, punktowy albo warstwowy do PNG albo SVG.
`createDocx`	Składa plik Word ze specyfikacji nagłówków, akapitów, tabel i obrazów.
`editDocx`	Dopisuje treść, podmienia tekst albo usuwa akapit w pliku Word, zapisując nową kopię.
`createXlsx`	Składa skoroszyt z danych arkusza, opcjonalnie z natywnymi wykresami Excela.
`editXlsx`	Ustawia komórki albo formuły, dodaje arkusz albo wykres, zapisując nową kopię.
`createPptx`	Składa prezentację ze slajdów z tytułami, punktami, obrazami albo natywnymi wykresami.
`editPptx`	Dodaje slajd, zmienia jego tytuł albo go usuwa, zapisując nową kopię.
`officeToPdf`	Renderuje istniejący plik Office albo ODF do PDF przez LibreOffice.
`convertOffice`	Konwertuje między formatami Office i ODF według sztywnej macierzy, na przykład `.xlsx` na `.csv`.
`mergePdf`	Scala dwa lub więcej plików PDF w jeden.
`splitPdf`	Rozbija PDF na osobne pliki według zakresu stron.
`rotatePdf`	Obraca wybrane strony o 90, 180 albo 270 stopni.
`watermarkPdf`	Nakłada jednostronicowy znak wodny PDF na każdą stronę dokumentu.
`fillPdfForm`	Wypełnia pola formularza AcroForm PDF na podstawie mapy nazwa-wartość i domyślnie je spłaszcza.

Folderyour-project/
- Folder.speedwave/
  - Folderoffice/
    report.pdf
    slides.pptx

flowchart LR
  Claude -->|"tool call"| Hub["Hub"]
  Hub -->|"HTTP"| Worker["worker mcp-office<br/>bez tokenów, bez ruchu wychodzącego"]
  Worker -->|"czyta"| WS["przestrzeń robocza projektu<br/>/workspace:rw"]
  Worker -->|"zapisuje"| Out[".speedwave/office/"]

LibreOffice headless bierze jedno zadanie naraz, więc równoległe wywołania officeToPdf i convertOffice czekają w kolejce. Treść Markdown, HTML albo specyfikacji wklejoną wprost worker przyjmuje do 200 KB, a narzędzia do PDF domyślnie czytają do 2000 stron.

Skonfiguruj

Włącz Beta features w menu Speedwave na pasku zadań, a potem włącz Dokumenty biurowe dla swojego projektu na liście integracji. Za pierwszym razem worker buduje swój obraz na żądanie, ściągając LibreOffice i środowisko Pythona, przez co restart trwa dłużej niż zwykle. Kolejne przełączenia idą niemal od ręki, bo obraz siedzi już w pamięci podręcznej. Ogólne kroki opisuje Połącz integrację.

Granice bezpieczeństwa

Worker sięga wyłącznie po pliki z przestrzeni roboczej twojego projektu. Na zewnątrz nie wychodzi wcale: pracuje w odciętej sieci wewnętrznej, z której nie prowadzi żadna droga na świat, więc nie pobierze adresu URL ani nie zawoła żadnej usługi z zewnątrz, a htmlToPdf i markdownToPdf ładują tylko lokalne zasoby z przestrzeni roboczej, nigdy zdalne. Nawet przejęty parser zostaje zamknięty w plikach twojego projektu, bo poza nimi kontener nie ma do czego sięgnąć. Makra i inna aktywna zawartość nie ruszają nigdy: LibreOffice działa bez dostawcy skryptów, a parsery Pythona czytają XML, ale go nie wykonują. Tak samo wygląda model izolacji opisany w Model izolacji, gdzie worker trzyma zawsze tylko te dane logowania, których wymaga jego zadanie, a tutaj nie trzyma żadnych.