> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaspert.be/llms.txt
> Use this file to discover all available pages before exploring further.

# Gebruik de Kaspert AI-assistent voor financiele vragen en taken

> Bevraag transacties, krijg financiele samenvattingen, volg betalingsverplichtingen en maak kasboekboekingen met de Kaspert MCP-gebaseerde AI-tools in natuurlijke taal.

Kaspert biedt een set AI-aanroepbare tools aan via het **Model Context Protocol (MCP)** waarmee AI-assistenten, zoals Claude, de financiele data van je organisatie kunnen bevragen en bewerken in natuurlijke taal. In plaats van handmatig je kasboek te filteren om vragen te beantwoorden zoals "Hoeveel hebben we dit jaar aan kamp uitgegeven?" of "Wie moet nog hun lidgeld betalen?", kun je je AI-assistent rechtstreeks vragen stellen en binnen enkele seconden een gestructureerd antwoord krijgen. Alle tools werken binnen de context van je ingelogde organisatie, zodat data van andere groepen nooit toegankelijk is.

<Note>
  De AI-assistentfunctie vereist MCP-toegangsgegevens. Neem contact op met [**support@kaspert.be**](mailto:support@kaspert.be) voor instructies om je favoriete AI-client (Claude Desktop, Cursor, enz.) in te stellen.
</Note>

***

## Beschikbare tools

De MCP-server van Kaspert biedt vijf tools. Elke tool vereist authenticatie: ze gebruiken de OAuth-sessie van de ingelogde gebruiker en beperken alle queries automatisch tot de actieve organisatie van die gebruiker.

<CardGroup cols={2}>
  <Card title="financial_summary" icon="chart-pie">
    Krijg totalen voor inkomsten, onkosten, saldo en een opsplitsing per categorie voor elke datumbereik.
  </Card>

  <Card title="list_transactions" icon="list">
    Haal een gefilterde lijst van transacties op basis van type, categorie en datumbereik.
  </Card>

  <Card title="list_categories" icon="tags">
    Haal alle actieve categorieen op die voor je organisatie zijn gedefinieerd, optioneel gefilterd op werkjaar.
  </Card>

  <Card title="list_payment_obligations" icon="circle-check">
    Toon betalingsverplichtingen (lidgeld, kampkosten, enz.) met betaald/onbetaald-status en zoeken op persoon.
  </Card>

  <Card title="create_transaction" icon="plus">
    Voeg een nieuwe inkomsten- of onkostenboeking rechtstreeks toe aan het kasboek.
  </Card>
</CardGroup>

***

### `financial_summary`

Geeft totale inkomsten, totale onkosten, lopend saldo, aantal transacties en een opsplitsing van bedragen per categorie voor de opgegeven periode. Zowel `from` als `to` zijn optioneel. Als je ze weglaat, krijg je cijfers over de volledige periode.

<Tabs>
  <Tab title="Request">
    ```json title="financial_summary request" theme={null}
    {
      "tool": "financial_summary",
      "input": {
        "from": "2024-09-01",
        "to": "2025-08-31"
      }
    }
    ```

    <ParamField body="from" type="string">
      Startdatum in `YYYY-MM-DD`-formaat (optioneel). Als weggelaten, wordt geen ondergrens toegepast.
    </ParamField>

    <ParamField body="to" type="string">
      Einddatum in `YYYY-MM-DD`-formaat (optioneel). Als weggelaten, wordt geen bovengrens toegepast.
    </ParamField>
  </Tab>

  <Tab title="Response">
    ```json title="financial_summary response" theme={null}
    {
      "period": { "from": "2024-09-01", "to": "2025-08-31" },
      "income": 3450.00,
      "expense": 2180.50,
      "balance": 1269.50,
      "transaction_count": 47,
      "by_category": {
        "Kamp": { "income": 2100.00, "expense": 1850.00 },
        "Lidgeld": { "income": 1200.00, "expense": 0 },
        "Materiaal": { "income": 150.00, "expense": 330.50 }
      }
    }
    ```

    <ResponseField name="income" type="number">
      Totale inkomsten voor de periode in euro, afgerond op 2 decimalen.
    </ResponseField>

    <ResponseField name="expense" type="number">
      Totale onkosten voor de periode in euro, afgerond op 2 decimalen.
    </ResponseField>

    <ResponseField name="balance" type="number">
      `income - expense`. Positief betekent dat je organisatie in het zwart staat; negatief betekent dat je meer hebt uitgegeven dan ontvangen.
    </ResponseField>

    <ResponseField name="transaction_count" type="integer">
      Totaal aantal transacties in de periode.
    </ResponseField>

    <ResponseField name="by_category" type="object">
      Elke sleutel is een categorienaam. Elke waarde bevat `income`- en `expense`-subtotalen voor die categorie.
    </ResponseField>
  </Tab>
</Tabs>

***

### `list_transactions`

Geeft een lijst van individuele transacties die overeenkomen met de opgegeven filters, gesorteerd op nieuwste eerst. Resultaten zijn beperkt tot 200 per aanvraag; gebruik smallere datumbereiken voor grote datasets.

<Tabs>
  <Tab title="Request">
    ```json title="list_transactions request" theme={null}
    {
      "tool": "list_transactions",
      "input": {
        "from": "2024-09-01",
        "to": "2024-12-31",
        "type": "expense",
        "category": "Kamp",
        "limit": 50
      }
    }
    ```

    <ParamField body="type" type="string">
      Filter op `"income"` of `"expense"`. Laat weg om beide types te tonen.
    </ParamField>

    <ParamField body="category" type="string">
      Filter op exacte categorienaam (hoofdlettergevoelig). Gebruik `list_categories` om geldige namen op te halen.
    </ParamField>

    <ParamField body="from" type="string">
      Startdatum `YYYY-MM-DD` (optioneel).
    </ParamField>

    <ParamField body="to" type="string">
      Einddatum `YYYY-MM-DD` (optioneel).
    </ParamField>

    <ParamField body="limit" type="integer" default="50">
      Maximum aantal resultaten. Moet tussen 1 en 200 liggen.
    </ParamField>
  </Tab>

  <Tab title="Response">
    ```json title="list_transactions response" theme={null}
    {
      "transactions": [
        {
          "id": "a1b2c3d4-...",
          "date": "2024-11-12",
          "type": "expense",
          "amount": 312.50,
          "description": "Kampmateriaal tenten",
          "category": "Kamp",
          "source": "manual"
        },
        {
          "id": "e5f6g7h8-...",
          "date": "2024-10-03",
          "type": "expense",
          "amount": 45.00,
          "description": "Brico - verf lokaal",
          "category": "Kamp",
          "source": "bank_import"
        }
      ]
    }
    ```

    <ResponseField name="transactions" type="array">
      Array van transactie-objecten. Elk object bevat `id`, `date`, `type`, `amount`, `description`, `category` en `source` (`"manual"` of `"bank_import"`).
    </ResponseField>
  </Tab>
</Tabs>

***

### `list_categories`

Geeft alle categorieen die voor je organisatie zijn gedefinieerd. Gebruik deze tool voordat je `create_transaction` aanroept om zeker te zijn dat je een geldige categorienaam doorgeeft.

<Tabs>
  <Tab title="Request">
    ```json title="list_categories request" theme={null}
    {
      "tool": "list_categories",
      "input": {
        "werkjaar": "2024-2025",
        "only_active": true
      }
    }
    ```

    <ParamField body="werkjaar" type="string">
      Filter op werkjaar-label (bijvoorbeeld `"2024-2025"`). Laat weg om categorieen voor alle werkjaren op te halen.
    </ParamField>

    <ParamField body="only_active" type="boolean" default="true">
      Wanneer `true` (standaard), worden alleen actieve categorieen geretourneerd. Stel in op `false` om gearchiveerde categorieen op te nemen.
    </ParamField>
  </Tab>

  <Tab title="Response">
    ```json title="list_categories response" theme={null}
    {
      "categories": [
        { "id": "cat-001", "name": "Kamp", "werkjaar": "2024-2025", "is_active": true },
        { "id": "cat-002", "name": "Lidgeld", "werkjaar": "2024-2025", "is_active": true },
        { "id": "cat-003", "name": "Materiaal", "werkjaar": "2024-2025", "is_active": true },
        { "id": "cat-004", "name": "Vergaderingen", "werkjaar": "2024-2025", "is_active": true }
      ]
    }
    ```

    <ResponseField name="categories" type="array">
      Array van categorie-objecten, elk met `id`, `name`, `werkjaar` en `is_active`.
    </ResponseField>
  </Tab>
</Tabs>

***

### `list_payment_obligations`

Toont betalingsverplichtingen, lidgeld, kampkosten of elke andere gevolgde betaling, met hun betaald/onbetaald-status. Handig voor vragen zoals "Wie moet nog hun kampgeld betalen?".

<Tabs>
  <Tab title="Request">
    ```json title="list_payment_obligations request" theme={null}
    {
      "tool": "list_payment_obligations",
      "input": {
        "is_paid": false,
        "search": "Janssen",
        "limit": 50
      }
    }
    ```

    <ParamField body="is_paid" type="boolean">
      Filter op betaalde (`true`) of onbetaalde (`false`) verplichtingen. Laat weg om beide te tonen.
    </ParamField>

    <ParamField body="search" type="string">
      Zoeken zonder onderscheid tussen hoofd- en kleine letters op gedeelten van de persoonsnaam (bijvoorbeeld `"Janssen"` matcht `"Jan Janssen"` en `"Lies Janssens"`).
    </ParamField>

    <ParamField body="limit" type="integer" default="50">
      Maximum aantal resultaten. Moet tussen 1 en 200 liggen.
    </ParamField>
  </Tab>

  <Tab title="Response">
    ```json title="list_payment_obligations response" theme={null}
    {
      "obligations": [
        {
          "id": "obl-001",
          "person_name": "Jan Janssen",
          "amount": 85.00,
          "description": "Kamp 2025",
          "is_paid": false,
          "created_at": "2025-01-15T10:30:00Z"
        },
        {
          "id": "obl-002",
          "person_name": "Lies Janssens",
          "amount": 85.00,
          "description": "Kamp 2025",
          "is_paid": false,
          "created_at": "2025-01-15T10:31:00Z"
        }
      ]
    }
    ```

    <ResponseField name="obligations" type="array">
      Array van betalingsverplichting-objecten met `id`, `person_name`, `amount`, `description`, `is_paid` en `created_at`.
    </ResponseField>
  </Tab>
</Tabs>

***

### `create_transaction`

Voegt een nieuwe inkomsten- of onkostenboeking toe aan je kasboek. Gebruik eerst `list_categories` om zeker te zijn dat je een geldige categorienaam doorgeeft. Dit is de enige tool die **data schrijft**: alle andere tools zijn alleen-lezen.

<Tabs>
  <Tab title="Request">
    ```json title="create_transaction request" theme={null}
    {
      "tool": "create_transaction",
      "input": {
        "type": "expense",
        "amount": 45.50,
        "description": "Materiaal kamp - verfborstels",
        "category": "Kamp",
        "date": "2025-07-15"
      }
    }
    ```

    <ParamField body="type" type="string" required>
      `"income"` voor ontvangen geld, `"expense"` voor uitgegeven geld.
    </ParamField>

    <ParamField body="amount" type="number" required>
      Bedrag in euro. Moet een positief getal zijn (bijvoorbeeld `45.50`). Geef nooit een negatieve waarde door.
    </ParamField>

    <ParamField body="description" type="string" required>
      Een korte beschrijving van de transactie. Maximum 300 tekens.
    </ParamField>

    <ParamField body="category" type="string" required>
      Categorienaam. Moet exact overeenkomen met een bestaande actieve categorie voor je organisatie. Roep eerst `list_categories` aan als je twijfelt.
    </ParamField>

    <ParamField body="date" type="string">
      Datum in `YYYY-MM-DD`-formaat. Standaard vandaag als weggelaten.
    </ParamField>
  </Tab>

  <Tab title="Response">
    ```json title="create_transaction response" theme={null}
    {
      "transaction": {
        "id": "txn-9f3a2b...",
        "date": "2025-07-15",
        "type": "expense",
        "amount": 45.50,
        "description": "Materiaal kamp - verfborstels",
        "category": "Kamp"
      }
    }
    ```

    <ResponseField name="transaction" type="object">
      De nieuw aangemaakte transactie met zijn `id`, `date`, `type`, `amount`, `description` en `category`.
    </ResponseField>
  </Tab>
</Tabs>

***

## Authenticatie

Alle vijf MCP-tools vereisen een geauthenticeerde gebruikerssessie. Wanneer je je AI-client verbindt met het Kaspert MCP-endpoint, word je gevraagd om in te loggen met je Kaspert-credentials. De tools werken dan automatisch op de data van je actieve organisatie.

<Warning>
  Omdat `create_transaction` data schrijft naar je live kasboek, wees specifiek wanneer je je AI-assistent vraagt om boekingen aan te maken. Controleer het antwoord om te bevestigen dat het bedrag, de categorie en de beschrijving correct zijn voordat je verdergaat.
</Warning>