@mgsoftwarebv/mcp-server-bridge/README.md

MCP Server bridge for MG Tickets - connects Cursor to HTTP MCP server with image support and GitHub code exploration

# @mgsoftwarebv/mcp-server-bridge

Een MCP Server bridge die **Cursor** verbindt met de **MG Tickets HTTP MCP Server**. Deze bridge implementeert het stdio MCP protocol en communiceert met jouw Supabase Edge Function MCP server.

## 📦 Installatie

```bash
npm install -g @mgsoftwarebv/mcp-server-bridge
```

## 🔧 Cursor Configuratie

### Voor MG Software SaaS Klanten (Aanbevolen)

Voeg het volgende toe aan je `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "mg-tickets": {
      "command": "npx",
      "args": [
        "-y",
        "@mgsoftwarebv/mcp-server-bridge@latest",
        "--api-key=mid_your_api_key_here"
      ]
    }
  }
}
```

**Dat is alles!** Geen database credentials, geen Supabase URL - alleen je API key.

### Voor Eigen Database (Advanced)

```json
{
  "mcpServers": {
    "mg-tickets-custom": {
      "command": "npx",
      "args": [
        "-y",
        "@mgsoftwarebv/mcp-server-bridge@latest",
        "--api-key=mid_your_api_key_here"
      ],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your_service_role_key"
      }
    }
  }
}
```

### 🔑 API Key Krijgen

1. Ga naar je MG Tickets dashboard: `http://localhost:3001/settings/developer`
2. Maak een nieuwe API key aan
3. Kopieer de key (formaat: `mid_...`)
4. Gebruik deze in je configuratie

## 📋 Command-Line Opties

```bash
# Basis gebruik
mg-tickets-mcp --api-key=mid_your_key_here

# Met custom base URL
mg-tickets-mcp --api-key=mid_your_key_here --base-url=https://your-custom-domain.com/functions/v1/mcp-server

# Via environment variables
export MG_TICKETS_API_KEY=mid_your_key_here
export MG_TICKETS_BASE_URL=https://cvjdbczxyczjnatuolsk.supabase.co/functions/v1/mcp-server
mg-tickets-mcp
```

## 🛠️ Beschikbare Tools

De bridge geeft toegang tot alle tools van je MCP server:

### Tickets & Projects
- **get-tickets** - Haal tickets op met filters
- **get-ticket-by-id** - Haal een specifieke ticket op
- **create-ticket** - Maak een nieuwe ticket aan
- **get-customers** - Haal customers op
- **get-customer-by-id** - Haal een specifieke customer op
- **create-customer** - Maak een nieuwe customer aan
- **get-projects** - Haal projects op
- **get-project-by-id** - Haal een specifiek project op
- **create-project** - Maak een nieuw project aan

### AI Development Tracking
- **start-ai-session-smart** - Start AI development sessie met time tracking
- **track-manual-follow-up** - Track manual follow-ups
- **sync-session-todos** - Synchroniseer todos met sessie
- **complete-ai-session** - Voltooi AI sessie met samenvatting
- **get-completion-context** - Haal completion context op
- **save-customer-response** - Sla customer response op

### Time Tracking
- **log-hours** 🆕 - Analyseer chat conversatie en log uren automatisch naar agenda (zie Cursor Command `/hours`)

## ⏱️ Quick Hour Logging met `/hours` Command

De nieuwe `/hours` Cursor command maakt het super eenvoudig om uren te loggen:

1. **Voer je werk uit in Cursor** - gewoon normaal chatten en coderen
2. **Type `/hours`** - wanneer je klaar bent
3. **AI analyseert de chat** en schat in hoeveel tijd een senior developer (zonder AI) zou besteden
4. **Automatische projectkoppeling** - gebruikt je workspace folder naam
5. **Draft entry** - wordt aangemaakt in de tracker (niet direct gefactureerd)

### Hoe werkt het?

De AI:
1. **Haalt alle beschikbare projecten op** via `get-projects`
2. **Matched workspace intelligent** (bijv. "tickets-v2" → "Internal Tickets V2")
   - Geen match? → Logt zonder project
   - Meerdere matches? → Vraagt gebruiker
3. **Analyseert de chat** - wat is er gebouwd/opgelost
4. **Schat realistische tijd** (investigation + implementation + testing)
5. **Maakt tracker entry** als draft (met of zonder project)

### Voorbeeld:

```
Workspace: "tickets-v2"
Type: /hours

AI doet:
1. Haalt projecten op: ["Internal Tickets V2", "Client Portal", ...]
2. Match: "tickets-v2" → "Internal Tickets V2" ✓
3. Analyseert chat: Auth improvements
4. Schatting: 2 uur senior dev tijd
5. Creëert entry:
   - Project: Internal Tickets V2
   - Description: "Authentication improvements: Fixed login bug and added password validation"
   - Hours: 2h
   - Status: DRAFT

Of zonder project match:
Workspace: "random-scripts"
Type: /hours

AI doet:
1. Haalt projecten op: ["Internal Tickets V2", "Client Portal", ...]
2. Geen match gevonden voor "random-scripts"
3. Logt zonder project:
   - Project: (No project assigned)
   - Description: "Script improvements: Added data migration script"
   - Hours: 0.5h
   - Status: DRAFT
```

### Voordelen:

- ✅ Geen handmatig uren bijhouden tijdens het werk
- ✅ Realistische schatting (senior dev zonder AI)
- ✅ **Slimme projectkoppeling** - AI matched workspace naam semantisch
- ✅ Vraagt bevestiging bij twijfel over project
- ✅ Chat context als documentatie
- ✅ Draft entries voor review

## 📚 Beschikbare Resources

- **tickets://recent** - Recente tickets across alle teams
- **customers://all** - Alle customers
- **projects://active** - Actieve projects

## 🔍 Debugging

De bridge server logt naar stderr, zodat je debug informatie kunt zien:

```bash
# Run met debug output
mg-tickets-mcp --api-key=mid_your_key_here 2>debug.log
```

Debug output toont:
- Verbindingsstatus met HTTP server
- Tool uitvoering details
- Authenticatie informatie
- Error details

## 🏗️ Development

```bash
# Clone het project
git clone https://github.com/mgsoftwarebv/tickets-v2.git
cd tickets-v2/packages/mcp-server-bridge

# Installeer dependencies
bun install

# Build
bun run build

# Test lokaal
node dist/index.js --api-key=mid_your_key_here
```

## 🔄 Updates

```bash
# Update naar nieuwste versie
npm update -g @mgsoftwarebv/mcp-server-bridge

# Of via npx (geen installatie vereist)
npx @mgsoftwarebv/mcp-server-bridge@latest --api-key=mid_your_key_here
```

## 🆘 Troubleshooting

### ❌ "API key is required"
- Zorg dat je `--api-key=` meegeeft of `MG_TICKETS_API_KEY` environment variable hebt ingesteld
- Controleer dat je API key het juiste formaat heeft: `mid_...`

### ❌ "Failed to connect to HTTP server"
- Controleer dat je MCP server draait op de juiste URL
- Test je API key via browser of curl
- Controleer firewall/netwerk instellingen

### ❌ "Invalid API key"
- Maak een nieuwe API key aan in je developer settings
- Zorg dat de key toegang heeft tot de juiste scopes

### 🔧 Debug Mode
```bash
# Voeg debug output toe aan je mcp.json
{
  "mcpServers": {
    "mg-tickets-v2": {
      "command": "npx",
      "args": [
        "-y", 
        "@mgsoftwarebv/mcp-server-bridge@latest",
        "--api-key=mid_your_key_here"
      ],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}
```

## 📄 License

MIT © MG Software B.V.