npm package: @jordanmgsoftware/mcp-tickets
Description: MCP Server voor MG Software Tickets - Hybrid Edge Function + Lokale Server
Author: MG Software B.V.
Latest version: 2.2.0

# MG Software MCP Tickets Server (Hybrid v2.0)

Een hybride Model Context Protocol (MCP) server voor het MG Software tickets systeem. Deze versie combineert het beste van beide werelden:

- **Basic operaties** → Supabase Edge Function (snel, schaalbaar)
- **Geavanceerde operaties** → Lokale handlers (flexibel, krachtig)

## 🏗️ Architectuur

### Edge Function Operaties (Fast Path)
- `query_tickets` - Tickets zoeken met filters
- `get_ticket` - Ticket details ophalen
- `get_ticket_stats` - Ticket statistieken
- `create_ticket` - Nieuwe tickets aanmaken
- `start_ai_task` - AI taken starten
- `update_ai_task` - AI taken bijwerken
- `complete_ai_task` - AI taken voltooien
- `get_ai_task` - AI taken ophalen

### Lokale Operaties (Advanced Path)
- **Comment management** - Geavanceerd comment beheer
- **Organization management** - Organisatie en project beheer
- **User management** - Gebruikersbeheer
- **Health checks** - Systeem status monitoring

## 🚀 Installatie & Setup

### 1. Dependencies installeren
```bash
cd mcp-server
npm install
```

### 2. Environment configuratie
Maak een `.env` bestand aan:
```env
SUPABASE_URL=https://jouw-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=jouw-service-role-key
```

### 3. Build & start
```bash
npm run build
npm start
```

## 🔧 Configuratie in Cursor

Voeg toe aan je `mcp-cursor-config.json`:
```json
{
  "mcpServers": {
    "mg-tickets": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/server.js"],
      "env": {
        "SUPABASE_URL": "https://jouw-project.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "jouw-service-role-key"
      }
    }
  }
}
```

## 📊 Beschikbare Tools

### Basic Operations (via Edge Function)
- **query_tickets** - Zoek tickets met filters en paginering
- **get_ticket** - Haal ticket details op met volledige informatie
- **get_ticket_stats** - Krijg statistieken voor een organisatie
- **create_ticket** - Maak een nieuw ticket aan
- **start_ai_task** - Start een AI taak met time tracking
- **update_ai_task** - Update AI taak met todos/activiteit
- **complete_ai_task** - Voltooi AI taak (goedkeuren/afwijzen)
- **get_ai_task** - Haal huidige AI taak op voor ticket

### Advanced Operations (lokaal)
- **add_comment** - Voeg comment toe aan ticket
- **get_comments** - Haal comments op voor ticket
- **update_comment** - Wijzig bestaande comment
- **get_organizations** - Haal organisaties op voor gebruiker
- **get_organization** - Krijg organisatie details
- **get_projects** - Haal projecten op voor organisatie
- **get_project** - Krijg project details
- **get_users** - Haal gebruikers op in organisatie
- **get_user_context** - Krijg gebruiker context info
- **health_check** - Controleer systeem status

## 🔍 Voorbeeld Gebruik

```javascript
// Basic operatie (snel via edge function)
await mcp.call("query_tickets", {
  userId: "user-123",
  organizationId: "org-456",
  status: ["open", "in-progress"],
  limit: 20
});

// Geavanceerde operatie (lokaal)
await mcp.call("add_comment", {
  userId: "user-123", 
  ticketId: "ticket-789",
  content: "Dit is een belangrijke update",
  mentions: ["user-456"]
});
```

## 🏥 Health Check

De server monitort zowel de lokale database als de edge function:

```javascript
await mcp.call("health_check", {});
// Toont status van beide systemen
```

## 🚨 Error Handling

De hybrid setup heeft automatische fallback:
- Edge function niet bereikbaar → Lokale error melding
- Database problemen → Duidelijke error berichten
- Alle responses in Nederlands voor consistentie

## 📈 Performance Voordelen

- **Edge Function**: Milliseconden response tijd
- **Lokale Handler**: Complexe operaties zonder latency
- **Hybrid**: Beste van beide werelden
- **Schaalbaar**: Edge functions schalen automatisch

## 🛠️ Development

### Build
```bash
npm run build
```

### Development modus
```bash
npm run dev
```

### Clean build
```bash
npm run clean && npm run build
```

## 📝 Versie Historie

### v2.0.0 (Hybrid)
- ✅ Edge Function integratie voor basic operaties
- ✅ Lokale handlers voor geavanceerde functies
- ✅ AI Task Tracking via edge function
- ✅ Hybride architectuur
- ✅ Nederlandse berichten
- ✅ Verbeterde error handling

### v1.0.0 (Legacy)
- ❌ Volledig lokale operaties (vervangen)

## 🤝 Support

Voor vragen of problemen, neem contact op met het MG Software ontwikkelteam.