# Office & PDF Document Reader MCP Server for Google Antigravity

Dedykowany serwer Model Context Protocol (MCP) zoptymalizowany pod kątem szybkiego, oszczędnego w tokeny czytania i inspekcji dokumentów biurowych w Google Antigravity.

## Obsługiwane formaty
- **PDF** (`.pdf`): cyfrowy tekst, tabele, spis treści/zakładki, ekstrakcja wybranych stron (`page_range`).
- **Microsoft Word** (`.docx`): nagłówki, akapity, tabele, konwersja do czytelnego Markdown.
- **Microsoft Excel** (`.xlsx`, `.xls`, `.xlsm`): inspekcja arkuszy, kolumn i wierszy, dedykowane stronicowane tabele Markdown.
- **Microsoft PowerPoint** (`.pptx`): tytuły slajdów, treść slajdów, struktura prezentacji.
- **Pliki tekstowe** (`.csv`, `.tsv`, `.txt`, `.md`, `.html`).

---

## Wymagania wstępne
- **Python 3.10+** (zalecany 3.11, 3.12, 3.13 lub 3.14).
- Zainstalowane narzędzie **Google Antigravity** (`agy`).

---

## Szybka instalacja

Cały instalator jest **w pełni wieloplatformowy (Cross-Platform)** i automatycznie tworzy izolowane środowisko wirtualne (`.venv`), pobiera pakiety, rejestruje serwer w `~/.gemini/config/mcp_config.json` oraz konfiguruje globalne wytyczne w `GEMINI.md`.

### 🪟 Windows

Opcja 1 (PowerShell):
```powershell
.\install.ps1
```

Opcja 2 (Python bezpośrednio):
```powershell
python install.py
```

Opcja 3 (CMD / Podwójne kliknięcie):
Uruchom plik `install.bat`.

---

### 🐧 Ubuntu / Debian / Linux

1. Upewnij się, że posiadasz pakiety Pythona i venv:
```bash
sudo apt update
sudo apt install -y python3 python3-pip python3-venv
```

2. Nadaj uprawnienia i uruchom instalator:
```bash
chmod +x install.sh
./install.sh
```
*(lub bezpośrednio: `python3 install.py`)*

---

### 🍏 macOS

```bash
chmod +x install.sh
./install.sh
```

---

## Dostępne narzędzia MCP

Po instalacji agent Antigravity ma automatycznie dostęp do 3 narzędzi:

### 1. `inspect_document`
- **Przeznaczenie:** Błyskawiczny podgląd struktury i metadanych pliku (zajmuje < 50ms i minimalną liczbę tokenów).
- **Zwraca:** Liczbę stron i spis treści (PDF), spis arkuszy z nagłówkami kolumn (Excel), strukturę nagłówków H1-H3 (Word), spis slajdów (PowerPoint).
- **Argumenty:**
  - `file_path`: Ścieżka do pliku.

### 2. `read_document`
- **Przeznaczenie:** Uniwersalny odczyt i konwersja do Markdown z ochroną przed przepełnieniem kontekstu (`max_chars`).
- **Argumenty:**
  - `file_path`: Ścieżka do pliku.
  - `page_range`: (Opcjonalnie dla PDF) np. `"1-5"`, `"10-25"`, `"2,4,8"`.
  - `max_chars`: Maksymalny limit znaków (domyślnie 50 000).

### 3. `read_excel_sheet`
- **Przeznaczenie:** Dedykowany czytnik arkuszy kalkulacyjnych zoptymalizowany pod kątem tokenów.
- **Argumenty:**
  - `file_path`: Ścieżka do pliku Excel.
  - `sheet_name`: Nazwa arkusza (domyślnie pierwszy).
  - `start_row`: Numer wiersza początkowego (domyślnie 1).
  - `max_rows`: Liczba wierszy do wyświetlenia (domyślnie 100).
  - `columns`: Wybrane kolumny po nazwie lub literze (np. `"A,B,E"` lub `"Nazwa,Cena"`).

---

## Weryfikacja instalacji

W terminalu możesz sprawdzić status zarejestrowanego serwera:
```bash
agy mcp list
```
Powinien pojawić się wpis:
```text
NAME               TYPE   STATUS   COMMAND/URL
office-doc-reader  stdio  enabled  .../.gemini/mcp-servers/office-doc-reader/.venv/...
```

Wewnątrz czatu CLI TUI wpisz:
```text
/mcp
```
aby otworzyć interaktywny panel zarządzania serwerami MCP.