exactmcp/README.md

MCP server for Exact Online API integration

# Exact MCP Server

Een Model Context Protocol (MCP) server voor integratie met de Exact Online API. Deze server biedt LLM's toegang tot Exact Online data via gestandaardiseerde tools.

## Functionaliteiten

- **OAuth2 Authenticatie**: Veilige authenticatie met Exact Online
- **Sales Orders**: Ophalen van verkooporders
- **Items**: Ophalen van artikelen/producten
- **Accounts**: Ophalen van klanten en leveranciers
- **Facturen**: Ophalen van verkoopfacturen

## Installatie

```bash
# Installeer via npm
npm install -g exact-mcp-server

# Of gebruik direct via npx
npx exact-mcp-server
```

## Development Setup

```bash
# Clone en installeer dependencies
git clone <repository-url>
cd exact-mcp-server
npm install

# Build het project
npm run build

# Start in development mode
npm run dev
```

## Configuratie

### Voor Claude Desktop

Voeg toe aan je `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "exact-online": {
      "command": "npx",
      "args": ["exact-mcp-server"]
    }
  }
}
```

### Exact Online App Setup

1. Ga naar de [Exact App Center](https://apps.exactonline.com/)
2. Registreer een nieuwe app
3. Noteer je Client ID en Client Secret
4. Stel de redirect URI in op `http://localhost:8080/callback`

## Gebruik

### 1. Authenticatie

```
authenticate({
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "redirectUri": "http://localhost:8080/callback"
})
```

Dit geeft je een authorization URL. Ga naar deze URL en autoriseer de app.

### 2. Authenticatie voltooien

```
complete_auth({
  "authCode": "authorization-code-from-callback"
})
```

### 3. Data ophalen

```
get_sales_orders({
  "divisionCode": "12345",
  "filter": "OrderDate gt datetime'2024-01-01T00:00:00'",
  "select": "OrderNumber,OrderDate,AmountFC",
  "top": 10
})
```

## Beschikbare Tools

### authenticate
Initieert OAuth2 authenticatie met Exact Online.

**Parameters:**
- `clientId` (string, required): Exact Online App Client ID
- `clientSecret` (string, required): Exact Online App Client Secret  
- `redirectUri` (string, optional): OAuth redirect URI (default: http://localhost:8080/callback)

### complete_auth
Voltooit de OAuth authenticatie met een authorization code.

**Parameters:**
- `authCode` (string, required): Authorization code uit de OAuth callback

### get_sales_orders
Haalt verkooporders op uit Exact Online.

**Parameters:**
- `divisionCode` (string, required): Division code (bedrijfsdatabase)
- `filter` (string, optional): OData filter query
- `select` (string, optional): OData select velden
- `top` (number, optional): Aantal records (default: 50)

### get_items
Haalt artikelen op uit Exact Online.

**Parameters:**
- `divisionCode` (string, required): Division code
- `filter` (string, optional): OData filter query  
- `select` (string, optional): OData select velden
- `top` (number, optional): Aantal records (default: 50)

### get_accounts
Haalt accounts (klanten/leveranciers) op uit Exact Online.

**Parameters:**
- `divisionCode` (string, required): Division code
- `filter` (string, optional): OData filter query
- `select` (string, optional): OData select velden  
- `top` (number, optional): Aantal records (default: 50)

## OData Query Voorbeelden

### Filters
```
OrderDate gt datetime'2024-01-01T00:00:00'
AmountFC gt 1000
Status eq 12
```

### Select velden
```
OrderNumber,OrderDate,AmountFC,CustomerName
Code,Description,SalesPrice
```

## Rate Limits

Exact Online hanteert rate limits:
- Dagelijkse limiet per bedrijf
- Minutenlimiet om bursting te voorkomen

De server handelt token refresh automatisch af.

## Troubleshooting

### "Not authenticated" fout
Zorg ervoor dat je eerst `authenticate` en dan `complete_auth` hebt uitgevoerd.

### Token expired
De server refresht tokens automatisch. Als dit faalt, herhaal het authenticatieproces.

### Division code niet gevonden
Gebruik `complete_auth` om beschikbare divisions te zien.

## Licentie

MIT