# SnelStart MCP Server

MCP (Model Context Protocol) server for SnelStart B2B API integration. Enables Claude Code CLI to interact directly with SnelStart accounting data.

## Features

- **Multi-administration support**: Switch between multiple SnelStart administrations
- **Full read/write operations**: 59 tools covering invoices, bookings, articles, documents, and more
- **Local sync**: Download invoices to local JSON files
- **VAT summaries**: Generate BTW summaries for reporting periods
- **Document import**: Upload bank statements (MT940, CAMT.053, CSV), UBL invoices, and OCR processing

## Requirements

- Node.js 20+
- SnelStart B2B API credentials (subscription key + connection key)
- Claude Code CLI

## Installation

```bash
npm install
npm run build
```

## Configuration

Create a `.env` file with your SnelStart credentials:

```env
# Comma-separated list of administration IDs
SNELSTART_ADMINS=vca,holding

# Per-administration credentials
SNELSTART_VCA_NAME="Vibe Coding Academy"
SNELSTART_VCA_SUBSCRIPTION_KEY=your_subscription_key
SNELSTART_VCA_CONNECTION_KEY=your_connection_key

SNELSTART_HOLDING_NAME="Holding BV"
SNELSTART_HOLDING_SUBSCRIPTION_KEY=your_subscription_key
SNELSTART_HOLDING_CONNECTION_KEY=your_connection_key

# API Settings (optional, defaults shown)
SNELSTART_BASE_URL=https://b2bapi.snelstart.nl/v2
SNELSTART_AUTH_URL=https://auth.snelstart.nl/b2b/token
TOKEN_BUFFER_SECONDS=60
```

### Getting Credentials

1. Create an account at https://b2bapi-developer.snelstart.nl/
2. Subscribe to 'Verkenning' to get your subscription key
3. In SnelStart web interface, go to 'Koppelingen' > 'Maatwerk SnelStart Software B.V.'
4. Generate a connection key (koppelsleutel)

## Usage with Claude Code

Add to your Claude Code MCP config (`~/.claude/mcp.json`):

```json
{
  "mcpServers": {
    "snelstart": {
      "command": "node",
      "args": ["/path/to/snelstart-mcp/dist/index.js"],
      "env": {
        "SNELSTART_ADMINS": "vca",
        "SNELSTART_VCA_NAME": "Vibe Coding Academy",
        "SNELSTART_VCA_SUBSCRIPTION_KEY": "your_key",
        "SNELSTART_VCA_CONNECTION_KEY": "your_key"
      }
    }
  }
}
```

## Available Tools (59 total)

### Administration (6 tools)
- `list_administrations` - List all configured administrations
- `switch_administration` - Switch to a different administration
- `get_admin_status` - Get status and company info
- `test_connection` - Test API connection
- `echo_test` - Diagnostic echo endpoint to test connectivity
- `check_access` - Check if user has access to the administration

### Invoices (4 tools)
- `list_invoices` - List sales/purchase invoices with filters
- `get_invoice` - Get invoice details by ID
- `sync_invoices_to_folder` - Download invoices to local JSON files
- `get_btw_summary` - Generate VAT summary for a period

### Relations (2 tools)
- `list_relaties` - List customers and suppliers
- `get_relatie` - Get relation details by ID

### Ledger Accounts (4 tools)
- `list_grootboeken` - List chart of accounts
- `list_grootboekmutaties` - List ledger mutations
- `get_grootboekmutatie` - Get ledger mutation details
- `create_grootboek` - Create a new ledger account

### Bookings - Read (2 tools)
- `list_boekingen` - List bank/cash/memorial bookings
- `get_inkoopboeking` - Get purchase booking details

### Bookings - Write (10 tools)
- `create_bankboeking` - Create a new bank booking
- `update_bankboeking` - Update an existing bank booking
- `delete_bankboeking` - Delete a bank booking
- `create_kasboeking` - Create a new cash booking
- `update_kasboeking` - Update an existing cash booking
- `delete_kasboeking` - Delete a cash booking
- `create_inkoopboeking` - Create a new purchase booking
- `update_inkoopboeking` - Update an existing purchase booking
- `delete_inkoopboeking` - Delete a purchase booking
- `set_inkoopboeking_kostenplaats` - Set cost center for a purchase booking

### Articles - Read (8 tools)
- `list_artikelen` - List products/articles
- `get_artikel` - Get article details
- `get_artikel_customfields` - Get custom fields for an article
- `list_artikel_prijsafspraken` - List price agreements for articles
- `list_artikelomzetgroepen` - List article revenue groups
- `get_artikelomzetgroep` - Get article revenue group details
- `list_actieprijzen` - List promotional prices
- `list_prijsafspraken` - List price agreements with customers

### Articles - Write (3 tools)
- `create_artikel` - Create a new article
- `update_artikel` - Update an existing article
- `delete_artikel` - Delete an article

### Orders & Quotes (6 tools)
- `list_verkooporders` - List sales orders
- `get_verkooporder` - Get sales order details
- `list_verkoopordersjablonen` - List sales order templates
- `get_verkoopordersjabloon` - Get sales order template details
- `list_offertes` - List quotes/quotations
- `get_offerte` - Get quote details

### VAT (2 tools)
- `list_btwaangiftes` - List VAT returns
- `get_btwaangifte` - Get VAT return details

### Documents - Read (2 tools)
- `get_document` - Get document details by ID
- `download_inkoopfactuur_documents` - Download purchase invoice documents

### Documents - Write (3 tools)
- `create_document` - Upload a new document
- `update_document` - Update document metadata
- `delete_document` - Delete a document

### Import Tools (4 tools)
- `upload_bankafschrift` - Upload bank statement (MT940, CAMT.053, CSV)
- `import_ubl_factuur` - Import UBL XML invoice
- `create_inkoopboeking_from_document` - Create purchase booking from document (OCR)
- `get_document_processing_status` - Get OCR processing status

### Other (3 tools)
- `list_dagboeken` - List journals (bank, cash, purchase, sales, memorial)
- `list_kostenplaatsen` - List cost centers
- `list_landen` - List all countries with ISO codes

## Example Queries

```
# List all open invoices
"Show me all open invoices"

# Get VAT summary for Q4
"Generate a BTW summary for Q4 2025"

# Find a customer
"Find customer with email info@example.com"

# Switch administration
"Switch to the holding administration"
```

## Development

```bash
npm run build       # Compile TypeScript
npm run typecheck   # Check types without compiling
npm run dev         # Run in development mode
```

## License

MIT