# Narzędzia MCP
> Każde narzędzie serwera MCP, według uprawnienia: co robi, jego argumenty i przykładowe wywołanie.
>
> Najpierw: [Podłączyć asystenta](https://ocost.io/docs/pl/mcp.md)

Każde narzędzie serwera MCP, wypisane z jego własnych definicji. [Podłączyć asystenta](https://ocost.io/docs/pl/mcp.md) konfiguruje serwer. Asystent czyta pełny opis każdego narzędzia w `tools/list`. Opisy argumentów są tam, tak jak tutaj, po angielsku.

## `documents:read`

### `get_document`

Odczytuje jeden dokument jako `ocost.document.v1`, jak `GET /public/v1/documents/{document_id}`.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `document_id` | uuid, wymagane | An id Ocost gave (a UUID) |

```json
{
  "name": "get_document",
  "arguments": {
    "document_id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11"
  }
}
```

### `get_file`

Zwraca status pliku, powód i dokumenty, jak `GET /public/v1/files/{file_id}`.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `file_id` | uuid, wymagane | An id Ocost gave (a UUID) |

```json
{
  "name": "get_file",
  "arguments": {
    "file_id": "01a1b08c-6e3a-7562-8f4a-7924722667b1"
  }
}
```

### `list_files`

Wymienia pliki według ostatniej zmiany, od najstarszej, jak `GET /public/v1/files`.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `status` | lista `received`, `reading`, `read`, `not_read`, `failed`, `needs_company` | Only files in these statuses |
| `updated_since` | date-time | Files changed at or after this time (ISO 8601) |
| `external_ref` | string | Only the files carrying this id of yours among their external_refs |
| `cursor` | string | `next_cursor` of the page before |
| `limit` | integer 1–100, domyślnie `50` | Pliki na stronę. |

```json
{
  "name": "list_files",
  "arguments": {
    "status": ["read", "not_read", "failed"],
    "updated_since": "2026-11-09T08:00:00Z"
  }
}
```

### `read_document`

Odczytuje strony dokumentu jako tekst, do 4 stron i 12 000 znaków.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `document_id` | uuid, wymagane | Identyfikator dokumentu. |
| `pages` | lista integer | Numery stron pliku do odczytania. |

```json
{
  "name": "read_document",
  "arguments": {
    "document_id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11",
    "pages": [1, 2]
  }
}
```

### `find_documents`

Wymienia dokumenty od najnowszych, według rodzaju, grupy lub firmy.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `kind` | `acceptance_protocol`, `agreement`, `bonus_payment_notification`, … (82 wartości) | Jeden typ dokumentu, tak jak wymienia je `kind_detail` w [Wartości](https://ocost.io/docs/pl/document.md#wartosci). |
| `company_id` | uuid | Identyfikator firmy, z `find_company`. |
| `family` | `invoices`, `payments`, `buying`, `contracts`, `reports`, `people`, `other` | Grupa rodzajów, na przykład `invoices` lub `contracts`. |

```json
{
  "name": "find_documents",
  "arguments": {
    "kind": "credit_note",
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `find_contracts`

Wymienia umowy z okresem obowiązywania, wypowiedzeniem i kwotami cyklicznymi.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `company_id` | uuid | Identyfikator firmy, z `find_company`. |

```json
{
  "name": "find_contracts",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `find_company`

Znajduje dostawców i klientów po nazwie, z ich identyfikatorami.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `name` | string, domyślnie `""` | Część nazwy. Bez niej wymienione są wszystkie. |
| `country` | string | Tylko firmy, których główny adres jest w tym kraju (ISO 3166-1 alpha-2, `DE`). |
| `relation` | `supplier`, `customer` | Tylko dostawcy albo tylko klienci. |

```json
{
  "name": "find_company",
  "arguments": {
    "name": "Musterbüro"
  }
}
```

### `find_project`

Znajduje projekty po nazwie, z ich identyfikatorami.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `name` | string, domyślnie `""` | Część nazwy. Bez niej wymienione są wszystkie. |

```json
{
  "name": "find_project",
  "arguments": {
    "name": "Neubau"
  }
}
```

### `company_documents`

Wymienia dokumenty firmy w obu kierunkach, do 30.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `company_id` | uuid, wymagane | Identyfikator firmy, z `find_company`. |

```json
{
  "name": "company_documents",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `invoice_detail`

Pokazuje jedną fakturę tak jak jej strona w Ocost: kwoty, termin płatności, rabat, zamówienie i historię.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `invoice_id` | uuid, wymagane | Identyfikator faktury. |

```json
{
  "name": "invoice_detail",
  "arguments": {
    "invoice_id": "01a1b08c-8c3d-7f41-a2b5-3e4f5a6b7c8d"
  }
}
```

### `open_decisions`

Wymienia otwarte decyzje połączonej osoby, najpilniejsze najpierw.

Tylko przez połączenie OAuth, jako osoba, która na nie zezwoliła.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `company_id` | uuid | Identyfikator firmy, z `find_company`. |
| `project_id` | uuid | Identyfikator projektu, z `find_project`. |

```json
{
  "name": "open_decisions",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `check_invoice`

Sprawdza faktury dostawców według § 14 UStG i to, czy każda jest e-fakturą.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `document_ids` | lista uuid | Faktury do sprawdzenia, według ich identyfikatorów. |
| `company_id` | uuid | Identyfikator firmy, z `find_company`. |
| `issued_since` | date | Data wystawienia, od. |
| `issued_until` | date | Data wystawienia, do. |
| `only_missing` | boolean, domyślnie `false` | Tylko faktury, którym czegoś brakuje. |
| `title` | string | Tytuł tabeli. |

```json
{
  "name": "check_invoice",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c",
    "issued_since": "2026-01-01",
    "only_missing": true
  }
}
```

## `documents:write`

### `send_file`

Wysyła plik jako base64, jak `POST /public/v1/files`.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `filename` | string, wymagane | Its name, e.g. bill.pdf |
| `content_base64` | string, wymagane | The file's bytes in base64: a PDF, an image (JPEG, PNG, TIFF, WebP), a Word file (.docx, .doc) or an e-invoice's XML (XRechnung, UBL, CII), at most 25 MB |
| `external_ref` | string | Your own id for it, e.g. an Odoo bill's 'account.move,42'; kept and given back, beside the ones sent with the same bytes before |

```json
{
  "name": "send_file",
  "arguments": {
    "filename": "invoice.pdf",
    "content_base64": "JVBERi0xLjcK…",
    "external_ref": "account.move,42"
  }
}
```

## `search:read`

### `search_documents`

Przeszukuje treść dokumentów: po dokładnym tekście, słowach kluczowych, znaczeniu lub obu.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `query` | string, wymagane | Co znaleźć. |
| `match` | `exact`, `keywords`, `meaning`, `hybrid`, domyślnie `"hybrid"` | `exact` tak, jak zapisano, `keywords` po słowach, `meaning` po znaczeniu, `hybrid` oba. |
| `document_id` | uuid | Szukaj tylko w tym dokumencie. |
| `kinds` | lista `acceptance_protocol`, `agreement`, `bonus_payment_notification`, … (82 wartości) | Tylko te typy dokumentów, tak jak wymienia je `kind_detail` w [Wartości](https://ocost.io/docs/pl/document.md#wartosci). |
| `family` | `invoices`, `payments`, `buying`, `contracts`, `reports`, `people`, `other` | Grupa rodzajów, na przykład `invoices` lub `contracts`. |
| `company_id` | uuid | Identyfikator firmy, z `find_company`. |
| `project_id` | uuid | Identyfikator projektu, z `find_project`. |
| `site_id` | uuid | Identyfikator lokalizacji. |
| `issued_since` | date | Data wystawienia, od. |
| `issued_until` | date | Data wystawienia, do. |
| `due_since` | date | Termin płatności faktury, od. |
| `due_until` | date | Termin płatności faktury, do. |
| `gross_min` | liczba dziesiętna | Kwota brutto od, w walucie firmy. |
| `gross_max` | liczba dziesiętna | Kwota brutto do, w walucie firmy. |
| `direction` | `incoming`, `outgoing` | `incoming` od dostawców, `outgoing` do klientów. |
| `status` | `open`, `paid` | Status faktury: `open` lub `paid`. |
| `category` | string | Kod ECLASS dowolnego poziomu, z `find_category`. |
| `limit` | integer | Najwyżej tyle wierszy. |
| `title` | string | Tytuł tabeli. |

```json
{
  "name": "search_documents",
  "arguments": {
    "query": "Bürostuhl",
    "match": "hybrid",
    "kinds": ["invoice"],
    "issued_since": "2026-01-01"
  }
}
```

### `search`

Przeszukuje dokumenty na potrzeby deep research i wiedzy firmowej w ChatGPT.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `query` | string, wymagane | What to find |

```json
{
  "name": "search",
  "arguments": {
    "query": "Wartungsvertrag Aufzug"
  }
}
```

### `fetch`

Pobiera cały wynik `search`: jego pierwsze cztery strony, do 12 000 znaków.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `id` | string, wymagane | A result's id |

```json
{
  "name": "fetch",
  "arguments": {
    "id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11"
  }
}
```

## `figures:read`

### `find_category`

Zamienia słowa w dowolnym z języków Ocost na kody ECLASS.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `words` | string, wymagane | Słowa dla kategorii, w dowolnym z języków Ocost. |

```json
{
  "name": "find_category",
  "arguments": {
    "words": "Büromaterial"
  }
}
```

### `company_profile`

Podsumowuje ostatnie 12 miesięcy firmy: zakupy, sprzedaż, warunki, otwarte pozycje i czasy płatności.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `company_id` | uuid, wymagane | Identyfikator firmy, z `find_company`. |

```json
{
  "name": "company_profile",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `project_overview`

Porównuje plan projektu z tym, co wydano i zaangażowano, według dostawcy i miesiąca.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `project_id` | uuid, wymagane | Identyfikator projektu, z `find_project`. |

```json
{
  "name": "project_overview",
  "arguments": {
    "project_id": "01a1b08c-4b1c-7d20-9a4b-2c3d4e5f6a7b"
  }
}
```

### `query_figures`

Sumuje rekordy do wykresu, porównania lub zliczenia.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `source` | `documents`, `lines`, `invoices`, … (11 wartości), wymagane | Co sumować, na przykład `invoices` lub `lines`. |
| `group_by` | lista obiekt (`field`, `bucket`, `level`), wymagane | Jedno lub dwa pola: wiersze, potem kolumny. |
| `measure` | obiekt (`agg`, `field`, `signed`) | Co sumować: liczbę albo sumę, średnią, minimum lub maksimum pola. |
| `filters` | lista obiekt (`field`, `values`, `since`, `until`, `min`, `max`) | Warunki na polach źródła. |
| `year` | integer | Rok do zsumowania. `period` go zastępuje. |
| `compare` | `previous_period`, `previous_year` | Porównanie z poprzednim okresem lub z tym samym okresem rok wcześniej. |
| `top_n` | integer | Tylko największe grupy. |
| `matching` | obiekt (`query`, `match`) | Tylko dokumenty, które znajduje wyszukiwanie. |
| `title` | string | Tytuł tabeli. |
| `period` | string | Zwykłe słowa, na przykład `2025`, `Q3 2025` lub `last year`. |

```json
{
  "name": "query_figures",
  "arguments": {
    "source": "invoices",
    "measure": {"agg": "sum", "field": "net"},
    "group_by": [{"field": "company"}],
    "filters": [{"field": "direction", "values": ["incoming"]}],
    "period": "2025",
    "top_n": 10
  }
}
```

### `top_companies`

Szereguje największych dostawców lub klientów według kwoty netto w okresie.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `side` | `suppliers`, `customers`, domyślnie `"suppliers"` | Dostawcy (domyślnie) lub klienci. |
| `period` | string | Zwykłe słowa, na przykład `2025`, `Q3 2025` lub `last year`. |
| `since` | date | Od tej daty. |
| `until` | date | Do tej daty. |
| `category` | string | Kod ECLASS lub słowa. |
| `n` | integer, domyślnie `10` | Ile wymienić. |
| `title` | string | Tytuł tabeli. |

```json
{
  "name": "top_companies",
  "arguments": {
    "side": "suppliers",
    "period": "2025",
    "n": 10
  }
}
```

### `spend_over_time`

Podaje kwotę netto według miesiąca, kwartału lub roku, na życzenie według firmy lub kategorii.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `period` | string | Zwykłe słowa, na przykład `2025`, `Q3 2025` lub `last year`. |
| `bucket` | `month`, `quarter`, `year`, domyślnie `"month"` | Miesiąc (domyślnie), kwartał lub rok. |
| `by` | `company`, `category` | Kolumna dla każdej firmy lub każdego segmentu ECLASS. |
| `side` | `suppliers`, `customers`, domyślnie `"suppliers"` | Dostawcy (domyślnie) lub klienci. |
| `since` | date | Od tej daty. |
| `until` | date | Do tej daty. |
| `title` | string | Tytuł tabeli. |

```json
{
  "name": "spend_over_time",
  "arguments": {
    "period": "last 12 months",
    "bucket": "month",
    "by": "company"
  }
}
```

### `largest_documents`

Wymienia największe dokumenty według kwoty brutto w okresie.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `kind` | string | Rodzaj inny niż faktury do zapłaty, na przykład `credit_note`. |
| `side` | `suppliers`, `customers`, domyślnie `"suppliers"` | Dostawcy (domyślnie) lub klienci. |
| `period` | string | Zwykłe słowa, na przykład `2025`, `Q3 2025` lub `last year`. |
| `since` | date | Od tej daty. |
| `until` | date | Do tej daty. |
| `n` | integer, domyślnie `10` | Ile wymienić. |
| `title` | string | Tytuł tabeli. |

```json
{
  "name": "largest_documents",
  "arguments": {
    "period": "Q3 2025",
    "n": 10
  }
}
```

### `payables_due`

Wymienia nieopłacone faktury dostawców wymagalne w danym oknie, najpierw terminy Skonto.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `window` | `this_week`, `next_7_days`, `next_14_days`, `next_30_days`, `this_month` | Kiedy faktury są wymagalne. |
| `since` | date | Od tej daty. |
| `until` | date | Do tej daty. |
| `company_id` | uuid | Identyfikator firmy, z `find_company`. |
| `title` | string | Tytuł tabeli. |

```json
{
  "name": "payables_due",
  "arguments": {
    "window": "next_14_days"
  }
}
```

### `vat_preview`

Pokazuje podgląd USt-Voranmeldung według Kennzahl, do sprawdzenia przez doradcę podatkowego.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `period` | string | Miesiąc (`2026-10`) lub kwartał (`2026-Q4`). |
| `kz` | string | Kennzahl, aby wymienić jej faktury. |
| `title` | string | Tytuł tabeli. |

```json
{
  "name": "vat_preview",
  "arguments": {
    "period": "2026-10"
  }
}
```

### `find_anomalies`

Oznacza zduplikowane faktury, zmienione konta bankowe i ceny wyższe niż w zamówieniu.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `since` | date | Od tej daty. |
| `until` | date | Do tej daty. |
| `kinds` | lista `duplicate`, `bank_changed`, `price_above_order` | Tylko te oznaczenia. |
| `title` | string | Tytuł tabeli. |

```json
{
  "name": "find_anomalies",
  "arguments": {
    "since": "2026-08-01",
    "until": "2026-10-31",
    "kinds": ["bank_changed"]
  }
}
```

### `supplier_profile`

Podsumowuje dostawcę jednym wywołaniem: wydatki, warunki, szybkość płatności, otwarte pozycje i ceny.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `company_id` | uuid, wymagane | Identyfikator firmy, z `find_company`. |

```json
{
  "name": "supplier_profile",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

## `exports:write`

### `export_table`

Eksportuje tabelę zwróconą przez inne narzędzie do Excela lub CSV, pod linkiem ważnym 30 minut.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `query` | obiekt (`tool`, `args`), wymagane | `query` tabeli, bez zmian, tak jak zwróciło je narzędzie. |
| `title` | string, domyślnie `"Ocost"` | Tytuł tabeli. |
| `format` | `xlsx`, `csv`, domyślnie `"xlsx"` | Excel (`xlsx`, domyślnie) lub CSV. |

```json
{
  "name": "export_table",
  "arguments": {
    "query": {"tool": "top_companies", "args": {"period": "2025"}},
    "title": "Top suppliers 2025",
    "format": "xlsx"
  }
}
```

### `make_datev_export`

Tworzy eksport DATEV za okres jako jeden plik ZIP, pod podpisanym linkiem.

Tylko przez połączenie OAuth, jako osoba, która na nie zezwoliła.

| Argument | Typ | Znaczenie |
| --- | --- | --- |
| `starts_on` | date, wymagane | Pierwszy dzień okresu. |
| `ends_on` | date, wymagane | Ostatni dzień okresu, w tym samym roku obrotowym. |

```json
{
  "name": "make_datev_export",
  "arguments": {
    "starts_on": "2026-10-01",
    "ends_on": "2026-10-31"
  }
}
```

## Zobacz też

- [Podłączyć asystenta](https://ocost.io/docs/pl/mcp.md): Podłączyć asystenta do serwera MCP (https://api.ocost.io/public/mcp, te same klucze): Claude Code, Claude Desktop, Cursor, claude.ai i ChatGPT przez OAuth oraz każdy klient.
- [Klucze i uprawnienia](https://ocost.io/docs/pl/authentication.md): Klucze API: jak niesie je żądanie, ich wymiana, ich uprawnienia i odmowy.
- [Dokument](https://ocost.io/docs/pl/document.md): Schemat ocost.document.v1 w pojęciach EN 16931 (odwzorowywalny na UBL i CII): przykład, rodzaj i kierunek, źródła, kontrole, wersje oraz każde pole i każda wartość.
- Na ocost.io: [API and MCP](https://ocost.io/en/product/api-and-mcp)
