# Taklo MCP-server

De publieke [MCP](https://modelcontextprotocol.io)-server van **Taklo** — all-in-one bedrijfssoftware voor installatie- en onderhoudsbedrijven.

Een AI-agent kan hiermee feiten over Taklo opzoeken, de maandprijs laten uitrekenen, de boekhoudkoppelingen opvragen, en een proefperiode of terugbelverzoek voorbereiden.

## Het endpoint

```
https://taklo.nl/mcp
```

- **Transport:** Streamable HTTP
- **Authenticatie:** geen
- **Kosten:** geen

### Aansluiten

```json
{
  "mcpServers": {
    "taklo": {
      "type": "http",
      "url": "https://taklo.nl/mcp"
    }
  }
}
```

### Met de hand uitproberen

Stuur een `Accept`-kop die zowel `application/json` als `text/event-stream` accepteert. Zonder die kop antwoordt de server met `-32000 Not Acceptable` — dat is geen storing.

```bash
curl -s -X POST https://taklo.nl/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Een `GET` op `/mcp` geeft `405`. Dat is correct voor een stateless Streamable-HTTP-server: er is geen sessie om te heropenen. Gebruik `/health` als healthcheck, niet `/mcp`.

## De tools

| Tool | Wat het doet | Soort |
| --- | --- | --- |
| `taklo_info` | Feiten over Taklo: prijzen, fair-use, bijkopen, proefperiode, diensten | alleen-lezen |
| `taklo_prijs_berekenen` | Maandprijs voor een aantal gebruikers, met de opbouw erbij | alleen-lezen |
| `taklo_koppelingen` | Boekhoudpakketten, en per pakket of je het zelf kunt aanzetten | alleen-lezen |
| `start_gratis_proefperiode` | Geeft de registreer-link voor de 14-dagen-proef | legt verzoek vast |
| `plan_terugbelmoment` | Legt een terugbelverzoek vast | legt verzoek vast |

Alle bedragen zijn **exclusief btw** (b2b). De tools vermelden dat zelf; geef het mee als je een bedrag doorvertelt.

## Begrensde bevoegdheid

Geen enkele tool maakt zelf een account, afspraak of aanvraag definitief.

`start_gratis_proefperiode` maakt **geen** account aan. De tool geeft een registreer-link terug; de gebruiker rondt daar zelf af met zijn eigen e-mailadres. Dat is met opzet — een proef hoort bij een mens, niet bij een assistent. Geef de link ongewijzigd door, inclusief de queryparameters: daarmee ziet Taklo dat de aanmelding via een AI-assistent kwam.

`plan_terugbelmoment` legt het verzoek vast. Er wordt niemand automatisch gebeld; een mens bevestigt eerst.

Het proces doet nergens een outbound HTTP-call en raakt geen enkele database van Taklo aan.

## De data

De lees-tools serveren een snapshot uit `data/*.json`, niet een live query. Elk antwoord draagt een `snapshotDatum` zodat je ziet hoe oud de feiten zijn. De snapshots worden bij Taklo gegenereerd uit de productcode en periodiek ververst.

Pas `data/*.json` niet met de hand aan in een fork die je actueel wilt houden — dan ontstaat er een tweede waarheid naast taklo.nl.

## Verschil met de server die op taklo.nl draait

De door Taklo gehoste server schrijft de twee schrijvende tool-aanroepen ook naar een interne logtabel, zodat Taklo kan meelezen hoeveel agent-verkeer er is. Die logsink is interne infrastructuur en zit niet in deze repo; hier gaat dezelfde regel naar stdout.

Richting de aanroepende agent is het gedrag identiek: dezelfde vijf tools, dezelfde antwoorden, dezelfde referentiecodes.

## Zelf draaien

```bash
npm install
npm start           # luistert op :8790
```

Of met Docker:

```bash
docker build -t taklo-mcp .
docker run -p 8790:8790 taklo-mcp
```

Daarna:

```bash
curl -s http://localhost:8790/health
```

`ALLOWED_HOSTS` in `server.js` bepaalt welke `Host`-headers geaccepteerd worden (bescherming tegen DNS-rebinding). Draai je dit achter een eigen domein, zet dat domein er dan bij.

## Rate limiting

30 lees-acties en 5 schrijvende acties per minuut per IP-adres. De emmers staan in het geheugen van het proces.

Let op bij hergebruik: staat er een gateway of proxy voor die namens meerdere gebruikers aanroept, dan zien al die gebruikers samen één emmer.

## Licentie

MIT — zie [LICENSE](LICENSE).