# PRD: SnelStart MCP Plugin
**Project:** snelstart-mcp
**Auteur:** Albert Barth
**Datum:** 24 januari 2026
**Versie:** 1.0
---
## 1. Overzicht
### 1.1 Probleem
- 1 jaar achterstand in administratie voor 2-5 BV's
- Handmatig werken in SnelStart is tijdrovend
- Creditcard statements (ICS, bankkaarten) moeten gematcht worden met boekingen
- Dollar betalingen moeten gekoppeld worden aan euro ontvangsten
- Facturen staan verspreid en moeten centraal beheerd worden
### 1.2 Oplossing
Een MCP (Model Context Protocol) server die directe toegang geeft tot SnelStart via Claude Code CLI. Hiermee kan je via natuurlijke taal of directe commands je administratie bijwerken.
### 1.3 Scope Fase 1 (Read-Only)
- Verbinding maken met meerdere SnelStart administraties
- Lezen van alle relevante data (facturen, boekingen, relaties, grootboeken)
- Lokale factuur sync (download naar mapje)
- Basis overzichten en rapportages
---
## 2. Doelgroep & Use Cases
### 2.1 Primaire Gebruiker
- Ondernemer met 2-5 BV's
- Gebruikt SnelStart Online (B2B API)
- Werkt via Claude Code CLI
- Wil achterstand wegwerken + structuur opzetten
### 2.2 Use Cases Fase 1 (Read-Only)
| Use Case | Beschrijving | MCP Tool |
|----------|--------------|----------|
| UC1 | Alle openstaande facturen bekijken per BV | `list_invoices` |
| UC2 | Relaties (klanten/leveranciers) doorzoeken | `search_relaties` |
| UC3 | Grootboekrekeningen bekijken | `list_grootboeken` |
| UC4 | Boekingen van periode opvragen | `list_boekingen` |
| UC5 | BTW overzicht genereren | `get_btw_summary` |
| UC6 | Facturen downloaden naar lokale map | `sync_invoices_to_folder` |
| UC7 | Wisselen tussen administraties | `switch_administration` |
| UC8 | Administratie status/health check | `get_admin_status` |
### 2.3 Toekomstige Use Cases (Fase 2+)
| Use Case | Beschrijving | Fase |
|----------|--------------|------|
| UC10 | Facturen aanmaken | 2 |
| UC11 | Boekingen invoeren | 2 |
| UC12 | Creditcard CSV importeren | 2 |
| UC13 | Dollar/Euro matching | 2 |
| UC14 | Bulk boekingen | 3 |
| UC15 | Automatische reconciliatie | 3 |
---
## 3. Technische Architectuur
### 3.1 Tech Stack
Gebaseerd op sparkbuddy-live patronen:
```
snelstart-mcp/
├── src/
│ ├── index.ts # MCP Server entry point
│ ├── config/
│ │ └── index.ts # Configuratie (multi-admin)
│ ├── integrations/
│ │ └── snelstart/
│ │ ├── client.ts # SnelStart API Client (van vibecodingacademy)
│ │ ├── auth.ts # Token management
│ │ └── types.ts # TypeScript types
│ ├── tools/ # MCP Tools
│ │ ├── invoices.ts # Factuur tools
│ │ ├── relaties.ts # Relatie tools
│ │ ├── boekingen.ts # Boeking tools
│ │ ├── grootboeken.ts # Grootboek tools
│ │ ├── admin.ts # Administratie switching
│ │ └── sync.ts # Lokale sync tools
│ ├── services/
│ │ ├── InvoiceSyncService.ts
│ │ └── CurrencyMatchService.ts # (Fase 2)
│ └── types/
│ └── snelstart.ts # Shared types
├── data/
│ └── invoices/ # Lokale factuur opslag
│ ├── bv1/
│ ├── bv2/
│ └── ...
├── package.json
├── tsconfig.json
└── .env.example
```
### 3.2 Dependencies
```json
{
"dependencies": {
"@modelcontextprotocol/sdk": "latest",
"zod": "^3.x"
},
"devDependencies": {
"typescript": "^5.x",
"ts-node": "^10.x",
"@types/node": "^20.x"
}
}
```
### 3.3 SnelStart API Integratie
Gebaseerd op werkende code uit vibecodingacademy:
**Authenticatie:**
```typescript
// OAuth 2.0 met client key
POST https://auth.snelstart.nl/b2b/token
Body: grant_type=clientkey&clientkey={connectionKey}
// Headers voor API calls
{
'Ocp-Apim-Subscription-Key': subscriptionKey,
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
}
```
**Base URL:** `https://b2bapi.snelstart.nl/v2`
**Endpoints Fase 1:**
| Endpoint | Methode | Beschrijving |
|----------|---------|--------------|
| `/companyInfo` | GET | Administratie info |
| `/relaties` | GET | Klanten/leveranciers |
| `/grootboeken` | GET | Rekeningschema |
| `/verkoopboekingen` | GET | Verkoopfacturen |
| `/inkoopboekingen` | GET | Inkoopfacturen |
| `/dagboekboekingen` | GET | Bankboekingen |
| `/btwtarieven` | GET | BTW tarieven |
| `/kostenplaatsen` | GET | Kostenplaatsen |
### 3.4 Multi-Administratie Support
```typescript
// .env configuratie per administratie
SNELSTART_ADMINS=bv1,bv2,bv3
# BV1
SNELSTART_BV1_NAME="Holding BV"
SNELSTART_BV1_SUBSCRIPTION_KEY="xxx"
SNELSTART_BV1_CONNECTION_KEY="xxx"
# BV2
SNELSTART_BV2_NAME="Werk BV"
SNELSTART_BV2_SUBSCRIPTION_KEY="xxx"
SNELSTART_BV2_CONNECTION_KEY="xxx"
```
---
## 4. MCP Tools Specificatie (Fase 1)
### 4.1 Administratie Tools
#### `list_administrations`
Toon alle geconfigureerde administraties.
```typescript
{
name: "list_administrations",
description: "Toon alle beschikbare SnelStart administraties",
inputSchema: {}
}
// Response
[
{ id: "bv1", name: "Holding BV", active: true },
{ id: "bv2", name: "Werk BV", active: false }
]
```
#### `switch_administration`
Wissel naar andere administratie.
```typescript
{
name: "switch_administration",
description: "Wissel naar een andere SnelStart administratie",
inputSchema: {
admin_id: { type: "string", description: "Administratie ID (bv1, bv2, etc.)" }
}
}
```
#### `get_admin_status`
Health check van huidige administratie.
```typescript
{
name: "get_admin_status",
description: "Toon status en basisinfo van huidige administratie",
inputSchema: {}
}
// Response
{
name: "Holding BV",
connected: true,
lastSync: "2026-01-24T10:30:00Z",
openInvoices: 12,
totalRelaties: 45
}
```
### 4.2 Factuur Tools
#### `list_invoices`
Lijst van facturen met filters.
```typescript
{
name: "list_invoices",
description: "Toon facturen (verkoop en/of inkoop)",
inputSchema: {
type: {
type: "string",
enum: ["verkoop", "inkoop", "beide"],
default: "beide"
},
status: {
type: "string",
enum: ["open", "betaald", "alle"],
default: "alle"
},
from_date: { type: "string", description: "Vanaf datum (YYYY-MM-DD)" },
to_date: { type: "string", description: "Tot datum (YYYY-MM-DD)" },
search: { type: "string", description: "Zoek in factuurnummer of omschrijving" },
limit: { type: "number", default: 50 }
}
}
```
#### `get_invoice`
Detail van specifieke factuur.
```typescript
{
name: "get_invoice",
description: "Toon details van een specifieke factuur",
inputSchema: {
invoice_id: { type: "string", required: true },
type: { type: "string", enum: ["verkoop", "inkoop"], required: true }
}
}
```
#### `sync_invoices_to_folder`
Download facturen naar lokale map.
```typescript
{
name: "sync_invoices_to_folder",
description: "Sync facturen naar lokale map (JSON + eventueel PDF)",
inputSchema: {
folder: {
type: "string",
description: "Lokale map pad (default: ./data/invoices/{admin_id})"
},
from_date: { type: "string" },
to_date: { type: "string" },
type: { type: "string", enum: ["verkoop", "inkoop", "beide"], default: "beide" }
}
}
// Response
{
synced: 45,
folder: "/Users/albert/projecten/snelstart-mcp/data/invoices/bv1",
files: ["2024-001.json", "2024-002.json", ...]
}
```
### 4.3 Relatie Tools
#### `list_relaties`
Toon klanten en leveranciers.
```typescript
{
name: "list_relaties",
description: "Toon relaties (klanten/leveranciers)",
inputSchema: {
type: {
type: "string",
enum: ["klant", "leverancier", "beide"],
default: "beide"
},
search: { type: "string", description: "Zoek op naam of email" },
limit: { type: "number", default: 100 }
}
}
```
#### `get_relatie`
Detail van specifieke relatie.
```typescript
{
name: "get_relatie",
description: "Toon details van een relatie",
inputSchema: {
relatie_id: { type: "string", required: true }
}
}
```
### 4.4 Boeking Tools
#### `list_boekingen`
Toon boekingen/transacties.
```typescript
{
name: "list_boekingen",
description: "Toon boekingen van een periode",
inputSchema: {
type: {
type: "string",
enum: ["bank", "kas", "memoriaal", "alle"],
default: "alle"
},
from_date: { type: "string", required: true },
to_date: { type: "string", required: true },
grootboek_id: { type: "string", description: "Filter op grootboekrekening" },
limit: { type: "number", default: 200 }
}
}
```
### 4.5 Grootboek Tools
#### `list_grootboeken`
Toon rekeningschema.
```typescript
{
name: "list_grootboeken",
description: "Toon grootboekrekeningen (rekeningschema)",
inputSchema: {
category: {
type: "string",
enum: ["balans", "resultaat", "alle"],
default: "alle"
},
search: { type: "string", description: "Zoek op nummer of naam" }
}
}
```
### 4.6 BTW Tools
#### `get_btw_summary`
BTW overzicht voor periode.
```typescript
{
name: "get_btw_summary",
description: "Genereer BTW overzicht voor aangifte",
inputSchema: {
from_date: { type: "string", required: true },
to_date: { type: "string", required: true }
}
}
// Response
{
period: "2025-Q4",
verkopen_hoog: { basis: 50000, btw: 10500 },
verkopen_laag: { basis: 5000, btw: 450 },
inkopen_binnenland: { basis: 20000, btw: 4200 },
te_betalen: 6750
}
```
---
## 5. Lokale Factuur Sync
### 5.1 Folder Structuur
```
data/
└── invoices/
├── bv1/
│ ├── verkoop/
│ │ ├── 2024/
│ │ │ ├── 2024-0001.json
│ │ │ └── 2024-0001.pdf (indien beschikbaar)
│ │ └── 2025/
│ └── inkoop/
│ ├── 2024/
│ └── 2025/
├── bv2/
└── ...
```
### 5.2 Factuur JSON Schema
```typescript
interface LocalInvoice {
id: string; // SnelStart ID
type: 'verkoop' | 'inkoop';
factuurnummer: string;
factuurdatum: string; // ISO date
vervaldatum: string;
relatie: {
id: string;
naam: string;
email?: string;
};
regels: Array<{
omschrijving: string;
aantal: number;
prijs: number;
btw_percentage: number;
totaal: number;
}>;
totalen: {
excl_btw: number;
btw: number;
incl_btw: number;
};
status: 'open' | 'betaald' | 'vervallen';
// Sync metadata
_synced_at: string;
_snelstart_modified: string;
}
```
### 5.3 Bi-Directionele Sync (Fase 2)
**Download (SnelStart → Lokaal):**
- `sync_invoices_to_folder` tool
- Detecteert wijzigingen via `modifiedOn` timestamp
- Slaat JSON + optioneel PDF op
**Upload (Lokaal → SnelStart) - Fase 2:**
- Nieuwe facturen in `./data/invoices/{admin}/drafts/`
- Tool `upload_draft_invoices` verwerkt drafts
- Na upload verplaatst naar juiste jaar-map
---
## 6. Configuratie
### 6.1 Environment Variables
```bash
# .env
# Administraties (comma-separated IDs)
SNELSTART_ADMINS=holding,werkbv,andere
# Per administratie
SNELSTART_HOLDING_NAME="Holding BV"
SNELSTART_HOLDING_SUBSCRIPTION_KEY="47bb5a11504e4b4585eee2c373eefff9"
SNELSTART_HOLDING_CONNECTION_KEY="base64-encoded-key"
SNELSTART_WERKBV_NAME="Werk BV"
SNELSTART_WERKBV_SUBSCRIPTION_KEY="..."
SNELSTART_WERKBV_CONNECTION_KEY="..."
# Lokale opslag
DATA_FOLDER="./data"
# API Settings
SNELSTART_BASE_URL="https://b2bapi.snelstart.nl/v2"
SNELSTART_AUTH_URL="https://auth.snelstart.nl/b2b/token"
TOKEN_BUFFER_SECONDS=60
```
### 6.2 Claude Code Integratie
Toevoegen aan `~/.claude/mcp.json`:
```json
{
"mcpServers": {
"snelstart": {
"command": "node",
"args": ["/Users/albertbarth/projecten/snelstart-mcp/dist/index.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}
```
---
## 7. Implementatie Roadmap
### Fase 1: Read-Only (MVP) - Week 1-2
| Stap | Taak | Status |
|------|------|--------|
| 1.1 | Project setup (TS, MCP SDK) | - |
| 1.2 | SnelStart client (auth, request) | - |
| 1.3 | Multi-admin configuratie | - |
| 1.4 | Tool: list_administrations | - |
| 1.5 | Tool: switch_administration | - |
| 1.6 | Tool: get_admin_status | - |
| 1.7 | Tool: list_invoices | - |
| 1.8 | Tool: get_invoice | - |
| 1.9 | Tool: list_relaties | - |
| 1.10 | Tool: list_grootboeken | - |
| 1.11 | Tool: list_boekingen | - |
| 1.12 | Tool: get_btw_summary | - |
| 1.13 | Tool: sync_invoices_to_folder | - |
| 1.14 | Testing & documentatie | - |
### Fase 2: Write Operations - Week 3-4
| Stap | Taak |
|------|------|
| 2.1 | Tool: create_invoice |
| 2.2 | Tool: create_relatie |
| 2.3 | Tool: create_boeking |
| 2.4 | Tool: upload_draft_invoices |
| 2.5 | ICS creditcard CSV parser |
| 2.6 | Bankafschrift CSV parser |
### Fase 3: Advanced Features - Week 5+
| Stap | Taak |
|------|------|
| 3.1 | Dollar/Euro matching service |
| 3.2 | Automatische reconciliatie |
| 3.3 | Bulk import tools |
| 3.4 | Rapportage tools |
| 3.5 | Web interface (optioneel) |
---
## 8. Security & Privacy
### 8.1 Credentials
- API keys NOOIT in code
- Alleen in `.env` (niet in git)
- Token caching in memory (niet op disk)
### 8.2 Data Opslag
- Lokale facturen in `./data/` (gitignored)
- Geen persoonlijke data logging
- Audit trail voor write operaties (fase 2)
### 8.3 Rate Limiting
- SnelStart API heeft quota's
- Client respecteert rate limits
- Retry met exponential backoff
---
## 9. Success Criteria
### Fase 1 Complete Wanneer:
- [ ] Alle 8 read tools werken
- [ ] Multi-admin switching werkt
- [ ] Facturen syncen naar lokale map
- [ ] BTW overzicht genereren werkt
- [ ] Gedocumenteerd en getest
### Gebruikerservaring:
```bash
# Voorbeeld sessie in Claude Code
> use snelstart tool list_administrations
# Toont: holding, werkbv
> use snelstart tool switch_administration admin_id=holding
# Switched to: Holding BV
> use snelstart tool list_invoices type=verkoop status=open
# Toont: 5 openstaande verkoopfacturen
> use snelstart tool sync_invoices_to_folder from_date=2024-01-01 to_date=2024-12-31
# Synced: 156 facturen naar ./data/invoices/holding/
```
---
## 10. Open Vragen
1. **PDF Download:** Ondersteunt SnelStart API directe PDF download van facturen?
2. **Webhook Support:** Kan SnelStart webhooks sturen voor realtime updates?
3. **Batch Limits:** Wat zijn de API limieten voor bulk requests?
---
## Appendix A: SnelStart API Referentie
Gebaseerd op werkende implementatie in `/vibecodingacademy/backend/src/integrations/snelstart/`:
- **Auth endpoint:** `https://auth.snelstart.nl/b2b/token`
- **API base:** `https://b2bapi.snelstart.nl/v2`
- **Token geldigheid:** 1 uur
- **Documentatie:** https://b2bapi-developer.snelstart.nl/
---
*Dit document wordt bijgewerkt naarmate het project vordert.*
