@mgsoftwarebv/mcp-server-bridge 3.0.0 → 3.0.2

package/README.md

@@ -1,248 +1,209 @@
 # @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.
+An MCP server that connects **Cursor / Claude Desktop / Windsurf** directly to your **Refront** Postgres database, exposing tickets, customers, projects, AI dev sessions and time tracking as MCP tools and resources.
 
-## 📦 Installatie
+Since v3.0 the bridge talks straight to Postgres via Drizzle ORM — the previous PostgREST/JWT transport has been removed.
+
+## 📦 Installation
 
 ```bash
 npm install -g @mgsoftwarebv/mcp-server-bridge
 ```
 
-## 🔧 Cursor Configuratie
+## 🔧 Cursor Configuration
 
-### Voor Refront SaaS Klanten (Aanbevolen)
+Add the following to your `~/.cursor/mcp.json`. You always need two things:
 
-Voeg het volgende toe aan je `~/.cursor/mcp.json`:
+1. An **API key** from your Refront dashboard (`/settings/developer`, format `mid_...`).
+2. A **Postgres connection string** for your Refront database (`DATABASE_URL`).
 
 ```json
 {
   "mcpServers": {
-    "mg-tickets": {
+    "refront": {
       "command": "npx",
       "args": [
         "-y",
         "@mgsoftwarebv/mcp-server-bridge@latest",
-        "--api-key=mid_your_api_key_here"
+        "--api-key=mid_your_api_key_here",
+        "--database-url=postgresql://USER:PASSWORD@HOST:PORT/DBNAME"
       ]
     }
   }
 }
 ```
 
-**Dat is alles!** Geen database credentials, geen Supabase URL - alleen je API key.
-
-### Voor Eigen Database (Advanced)
+Both values can also be supplied via environment variables instead of CLI flags:
 
 ```json
 {
   "mcpServers": {
-    "mg-tickets-custom": {
+    "refront": {
       "command": "npx",
-      "args": [
-        "-y",
-        "@mgsoftwarebv/mcp-server-bridge@latest",
-        "--api-key=mid_your_api_key_here"
-      ],
+      "args": ["-y", "@mgsoftwarebv/mcp-server-bridge@latest"],
       "env": {
-        "SUPABASE_URL": "https://your-project.supabase.co",
-        "SUPABASE_SERVICE_ROLE_KEY": "your_service_role_key"
+        "MG_TICKETS_API_KEY": "mid_your_api_key_here",
+        "DATABASE_PRIMARY_POOLER_URL": "postgresql://USER:PASSWORD@HOST:PORT/DBNAME"
       }
     }
   }
 }
 ```
 
-### 🔑 API Key Krijgen
+### 🔑 Getting an API Key
 
-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
+1. Go to your Refront dashboard: `/settings/developer`
+2. Create a new API key
+3. Copy the key (format: `mid_...`)
+4. Use it in your MCP configuration
 
-## 📋 Command-Line Opties
+### 🗄️ Getting the Database URL
 
-```bash
-# Basis gebruik
-mg-tickets-mcp --api-key=mid_your_key_here
+- **Refront SaaS customers**: ask MG Software for a read-only Postgres user that points at your team's database (we do not hardcode a default connection string here for security reasons).
+- **Self-hosted**: use the same `DATABASE_PRIMARY_POOLER_URL` you configured for the API/dashboard.
+
+The bridge uses `@refront/db/job-client`, which is tuned for a single connection per process and gracefully closes idle connections.
 
-# Met custom base URL
-mg-tickets-mcp --api-key=mid_your_key_here --base-url=https://your-custom-domain.com/functions/v1/mcp-server
+## 📋 Command-Line Options
+
+```bash
+# Basic usage
+mg-tickets-mcp --api-key=mid_your_key --database-url=postgresql://...
 
 # 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
+export MG_TICKETS_API_KEY=mid_your_key
+export DATABASE_PRIMARY_POOLER_URL=postgresql://USER:PASSWORD@HOST:PORT/DBNAME
 mg-tickets-mcp
 ```
 
-## 🛠️ Beschikbare Tools
+`--database-url` falls back to `DATABASE_PRIMARY_POOLER_URL`, then to `DATABASE_URL`. The bridge exits at startup if no connection string is provided.
 
-De bridge geeft toegang tot alle tools van je MCP server:
+For attachment downloads you also need to expose Cloudflare R2 credentials (`R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, optional `R2_PUBLIC_DOMAIN`). Without them the attachment / image inlining tools will return an error, but everything else keeps working.
 
-### 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
+## 🏢 Multi-provider support
 
-### 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
+A single API key now works even if you belong to **multiple providers** (workspaces). The key is bound to one provider as its default, but every team-scoped tool accepts an optional `teamId` argument that is validated against your team memberships.
 
-### Time Tracking
-- **log-hours** 🆕 - Analyseer chat conversatie en log uren automatisch naar agenda (zie Cursor Command `/hours`)
+How it resolves which provider a tool acts on:
 
-## ⏱️ Quick Hour Logging met `/hours` Command
+- **`teamId` provided** → it is validated against your memberships and used.
+- **`teamId` omitted, you belong to one provider** → that provider is used automatically (no change for single-provider users).
+- **`teamId` omitted, you belong to several** → list/create tools return the list of your providers and ask the AI to re-call with a `teamId`. By-id and session tools resolve across all your providers (the record id disambiguates), and accept `teamId` to narrow.
 
-De nieuwe `/hours` Cursor command maakt het super eenvoudig om uren te loggen:
+Use **get-teams** to list the providers you can act on and copy a `teamId`.
 
-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)
+## 🛠️ Available Tools
 
-### Hoe werkt het?
+### Teams
+- **get-teams** — list the provider teams (workspaces) you can act on; use a returned id as `teamId` on other tools
 
-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)
+### Tickets, Customers & Projects
+- **get-tickets** — list tickets with filters (status, priority, project, customer, text query)
+- **get-ticket-by-id** — fetch one ticket with comment text, a full attachment listing (ids), and inline images (base64)
+- **create-ticket** — create a new ticket
+- **update-ticket** — update fields (title, description, status, priority, type, project, customer, assignee, estimated hours); `assigneeId: null` unassigns
+- **add-ticket-comment** — add a comment (plain text or TipTap JSON); `isInternal` for internal-only notes
+- **get-ticket-comments** — read all comments as plain text (author, internal flag, timestamp)
+- **get-ticket-attachment** — get a 1-hour signed download URL for any ticket/comment attachment (any file type)
+- **get-customers** — list/search customers
+- **create-customer** — create a customer
+- **get-projects** — list/search projects
+- **create-project** — create a project
 
-### Voorbeeld:
+> **Note:** Ticket writes (`update-ticket`, `add-ticket-comment`) are recorded in the dashboard's ticket activity feed but do **not** send notifications (email/Slack/in-app) or trigger `@mention` routing. Notification delivery is a planned follow-up.
 
-```
-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
-```
+### AI Development Tracking
+- **start-ai-session-smart** — start an AI dev session with time tracking
+- **track-manual-follow-up** — record a manual follow-up prompt and adjust the time estimate
+- **sync-session-todos** — replace/extend the todo list for a session
+- **add-follow-up-todos** — append todos that came up during follow-up
+- **update-session-status** — change the session status (`started`, `in_progress`, `paused`, `completed`, `failed`)
+- **get-session-context** — read back current session state (ticket, todos, follow-ups)
+- **get-completion-context** — full context bundle for generating a customer response
+- **save-customer-response** — store the AI-generated customer response for provider approval
+- **complete-ai-session** — finalize the session, create/update a draft agenda event
+
+### Time Tracking
+- **log-hours** — log work hours as a draft agenda event (see the `/hours` Cursor command)
+
+### GitHub Code Exploration
+- **get-github-file** — read one file from the GitHub repo linked to a project
+- **list-github-directory** — list a directory in the GitHub repo linked to a project
 
-### Voordelen:
+## ⏱️ Quick Hour Logging with `/hours`
 
-- ✅ 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
+The `/hours` Cursor command makes logging time effortless:
 
-## 📚 Beschikbare Resources
+1. **Do your work in Cursor** — chat and code normally.
+2. **Type `/hours`** when you're done.
+3. **The AI analyzes the chat** and estimates how long a senior developer (without AI) would have spent.
+4. **Workspace ↔ project matching** is automatic where possible.
+5. **A draft entry** is created in the tracker (not billed yet).
 
-- **tickets://recent** - Recente tickets across alle teams
-- **customers://all** - Alle customers
-- **projects://active** - Actieve projects
+### How it works
+
+1. Lists all projects via `get-projects`.
+2. Matches the workspace folder name to the closest project (or skips matching when ambiguous).
+3. Analyzes the chat — what was built/fixed.
+4. Estimates a realistic time budget (investigation + implementation + testing).
+5. Creates a tracker entry as draft.
+
+## 📚 Available Resources
+
+- **tickets://recent** — most recent tickets across all accessible teams
+- **customers://all** — all accessible customers
+- **projects://active** — all accessible projects
 
 ## 🔍 Debugging
 
-De bridge server logt naar stderr, zodat je debug informatie kunt zien:
+The bridge logs to stderr so you can capture debug output without breaking the MCP stdio protocol:
 
 ```bash
-# Run met debug output
-mg-tickets-mcp --api-key=mid_your_key_here 2>debug.log
+mg-tickets-mcp --api-key=mid_... --database-url=postgresql://... 2>debug.log
 ```
 
-Debug output toont:
-- Verbindingsstatus met HTTP server
-- Tool uitvoering details
-- Authenticatie informatie
-- Error details
+Debug output shows:
+- Database connection / startup status
+- API key validation hash
+- Tool dispatch and access decisions
+- Errors with stack traces
 
 ## 🏗️ 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
+node dist/index.js --api-key=mid_... --database-url=postgresql://...
 ```
 
 ## 🔄 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
+# Or via npx (no install required)
+npx @mgsoftwarebv/mcp-server-bridge@latest --api-key=mid_...
 ```
 
 ## 🆘 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_...`
+- Pass `--api-key=` or set `MG_TICKETS_API_KEY`.
+- Make sure the key has the format `mid_...` (length 68).
 
-### ❌ "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
+### ❌ "Database URL is required"
+- Pass `--database-url=postgresql://...` or set `DATABASE_PRIMARY_POOLER_URL` / `DATABASE_URL`.
+- Confirm the user can reach the database from your machine (firewall, VPN, etc).
 
-### ❌ "Invalid API key"
-- Maak een nieuwe API key aan in je developer settings
-- Zorg dat de key toegang heeft tot de juiste scopes
+### ❌ "API key not found or invalid"
+- Generate a new API key in `/settings/developer` and check it is enabled.
+- Confirm the key belongs to a team that exists in the database you're connecting to.
 
-### 🔧 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"
-      }
-    }
-  }
-}
-```
+### ❌ "R2 storage is not configured"
+- Image / attachment tools need `R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`. Set them in the `env` block of your `mcp.json` if you need attachment support.
 
 ## 📄 License