# Een Payload-website koppelen

SiteHome koppelt met Payload via de officiële MCP-plugin en twee kleine SiteHome-tools voor veldinformatie en afbeeldingsuploads. Je developer installeert ze in de website; de eigenaar maakt een beperkte MCP-sleutel en koppelt in SiteHome. Deze uitleg is voor nieuwe koppelingen. Bestaande REST/plugin-koppelingen worden niet automatisch omgezet.

## 1. Installeer overeenkomende pakketten en de uitbreiding

Gebruik Payload en `@payloadcms/plugin-mcp` op dezelfde versie **3.92.0**. De uitbreiding heeft ook `zod` 3.25 nodig. Volg de [installatiehandleiding van de uitbreiding](https://github.com/bkeetman/sitehome/tree/main/integrations/payload/mcp-extension) en de [officiële MCP-uitleg](https://payloadcms.com/docs/plugins/mcp). Uitleg voor een bèta kan functies beschrijven die de stabiele versie 3.92.0 niet heeft.

Kopieer zowel `index.ts` als `schema.ts` uit de uitbreiding naar de website. Registreer `sitehomeMcpTools` bij `mcp.tools` van de officiële plugin. Dit is kleine integratiecode in de website die onderhoud vraagt, geen apart gepubliceerd SiteHome npm-pakket.

Geef de oorspronkelijke collectieconfiguraties door, voordat Payload standaardinstellingen toevoegt. Gebruik dezelfde expliciete collectierechten voor de officiële plugin en de helper. Neem alleen de bedoelde contentcollecties en hun mediacollecties met uploadondersteuning op. Zet **find, create en update** aan voor content en **find en create** voor media. Laat **delete** uit. De installatiehandleiding bevat het volledige configuratievoorbeeld.

Behoud bestaande toegangsregels, hooks en validatie. De uitbreiding werkt met de officiële standaardauthenticatie via bearer-sleutels op 3.92.0; eigen authenticatie of een andere versie vraagt aparte aanpassing en controle.

## Waarvoor zijn de twee tools?

De developer van de website installeert deze tools eenmalig. De agency of klant die daarna koppelt hoeft ze niet zelf te installeren of technisch te begrijpen; die heeft het websiteadres en een MCP-sleutel met de juiste rechten nodig.

- **`sitehomeSchema`** geeft veldtypen, labels, keuzes en relatiedoelen door, zodat SiteHome de juiste editor kan tonen.
- **`sitehomeUpload`** ontvangt nieuwe afbeeldingsbestanden via Payload, met de gewone rechten en validatie van de gekoppelde gebruiker.

Kopieer beide uitbreidingsbestanden naar een map `sitehome-mcp-extension` en registreer ze zoals hieronder. Vervang `Articles`, `Media` en hun slugs door de bestaande collecties van de website; behoud alle overige configuratie en plugins.

```ts
import { buildConfig } from 'payload'
import { mcpPlugin } from '@payloadcms/plugin-mcp'
import { sitehomeMcpTools } from './sitehome-mcp-extension'

const collections = [Articles, Media] // Je bestaande collectieconfiguraties
const mcpCollections = {
  articles: { enabled: { find: true, create: true, update: true, delete: false } },
  media: { enabled: { find: true, create: true, delete: false } },
}

// Behoud hier je overige instellingen en plugins.
export default buildConfig({
collections,
plugins: [mcpPlugin({
  collections: mcpCollections,
  mcp: { tools: sitehomeMcpTools(collections, mcpCollections) },
})],
})
```

## 2. Voer de migraties uit en zet de wijziging online

De officiële plugin voegt zijn collectie voor MCP API-sleutels toe. Controleer de configuratie en eventuele databasemigratie volgens het normale proces van het project en voer de vereiste migratie uit vóór het online zetten. Verander geen bestaande sleutels en verzwak geen toegangsregels. Laat de website-eigenaar het online zetten goedkeuren.

## 3. Maak een beperkte MCP-sleutel

1. Maak een aparte Payload-gebruiker met alleen toegang tot de bedoelde content- en mediacollecties.
2. Log in als die gebruiker en maak een sleutel bij **MCP → API Keys**. Gebruik een MCP-sleutel, niet **Enable API Key** bij een gewone gebruiker.
3. Zet dezelfde collectierechten aan als hierboven. Schakel in de groep **Tools** expliciet **sitehomeSchema** en **sitehomeUpload** in. Laat delete en tools voor configuratiewijzigingen uit.
4. Kopieer de sleutel en geef hem veilig aan de website-eigenaar. Zet hem niet in broncode, chatlogs of publieke omgevingsvariabelen.

De gebruiker achter de sleutel moet ook de bijbehorende Payload-rechten hebben. Toolrechten geven op zichzelf geen toegang tot content.

## 4. Koppel in SiteHome

Kies **Website koppelen → Payload**. Vul het adres in waar Payload draait, zonder `/admin`, en plak de MCP-sleutel. SiteHome controleert de koppeling en veldinformatie, toont de leesbare contentcollecties en koppelt de collecties die je kiest. Houd de mediacollecties beschikbaar voor afbeeldingsvelden.

De sleutel blijft versleuteld op de server. Een concept bewaren in SiteHome schrijft niets naar Payload. Publiceren staat eerst uit, tot een websitebeheerder het aanzet. Elke publicatie vraagt nog steeds een controle van de exacte wijzigingen en een bewuste actie.

## Velden, uploads en publiceren

De uitbreiding beschrijft veldsoorten, labels, keuzes en doelen van relaties en media. De ondersteunde basis bestaat uit eenvoudige velden, ondersteunde Lexical-tekst met behoud van onbekende onderdelen, losse afbeeldingen en relaties naar één of meerdere collecties. Dit betekent niet dat elk eigen Payload-bedieningselement te bewerken is. Onbekende bediening, willekeurige arrays, galerijen, geneste groepen en vertaalde velden vallen buiten deze scope; niet-ondersteunde velden blijven gesloten.

`sitehomeUpload` accepteert PNG, JPEG en WebP tot 10 MiB. De tool gebruikt Payloads bestands-API met de rechten, validatie en hooks van de gekoppelde gebruiker. Een upload publiceert op zichzelf geen contentitem.

Payload bepaalt validatie, hooks en toegang. Hun aanwezigheid sluit op deze route een verder ondersteund veld niet. SiteHome bootst de voorwaardelijke presentatie van het beheer niet na en voert geen websitecode uit. Na het schrijven controleert het de werkelijk opgeslagen waarden en publicatiestatus; een hook die invoer verandert mag niet als exact geslaagde publicatie worden gemeld.

Vlak vóór publiceren controleert SiteHome het schema, de bron en concepten van anderen opnieuw. Een gevonden wijziging vraagt een nieuwe controle. **MCP heeft geen atomaire revisiecontrole:** een gelijktijdige wijziging na die controle en vóór het schrijven kan nog worden overschreven. De website-eigenaar accepteert deze beperking; beschrijf dit niet als gegarandeerde bescherming tegen gelijktijdige bewerkingen.

## Voor een AI-codeassistent

Stel officiële `@payloadcms/plugin-mcp@3.92.0` met overeenkomende Payload-pakketten en de SiteHome-uitbreiding van twee bestanden in volgens de installatiehandleiding hierboven. Stel expliciete content- en mediarechten in, registreer `sitehomeSchema` en `sitehomeUpload` en leg uit hoe de eigenaar beide aangepaste tools op de MCP-sleutel inschakelt. Behoud toegangsregels, validatie en hooks. Laat de configuratie en migratie zien voordat de eigenaar dit online zet. Maak geen klantsleutels en zet geen bestaande koppeling automatisch om.