@mgsoftwarebv/mcp-server-bridge 3.0.1 → 3.3.0

package/README.md

@@ -1,210 +1,224 @@
-# @mgsoftwarebv/mcp-server-bridge
-
-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.
-
-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 Configuration
-
-Add the following to your `~/.cursor/mcp.json`. You always need two things:
-
-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": {
-    "refront": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@mgsoftwarebv/mcp-server-bridge@latest",
-        "--api-key=mid_your_api_key_here",
-        "--database-url=postgresql://USER:PASSWORD@HOST:PORT/DBNAME"
-      ]
-    }
-  }
-}
-```
-
-Both values can also be supplied via environment variables instead of CLI flags:
-
-```json
-{
-  "mcpServers": {
-    "refront": {
-      "command": "npx",
-      "args": ["-y", "@mgsoftwarebv/mcp-server-bridge@latest"],
-      "env": {
-        "MG_TICKETS_API_KEY": "mid_your_api_key_here",
-        "DATABASE_PRIMARY_POOLER_URL": "postgresql://USER:PASSWORD@HOST:PORT/DBNAME"
-      }
-    }
-  }
-}
-```
-
-### 🔑 Getting an API Key
-
-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
-
-### 🗄️ Getting the Database URL
-
-- **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.
-
-## 📋 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
-export DATABASE_PRIMARY_POOLER_URL=postgresql://USER:PASSWORD@HOST:PORT/DBNAME
-mg-tickets-mcp
-```
-
-`--database-url` falls back to `DATABASE_PRIMARY_POOLER_URL`, then to `DATABASE_URL`. The bridge exits at startup if no connection string is provided.
-
-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.
-
-## 🏢 Multi-provider support
-
-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.
-
-How it resolves which provider a tool acts on:
-
-- **`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.
-
-Use **get-teams** to list the providers you can act on and copy a `teamId`.
-
-## 🛠️ Available Tools
-
-### Teams
-- **get-teams** — list the provider teams (workspaces) you can act on; use a returned id as `teamId` on other tools
-
-### 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
-
-> **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.
-
-### 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
-
-## ⏱️ Quick Hour Logging with `/hours`
-
-The `/hours` Cursor command makes logging time effortless:
-
-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).
-
-### 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
-
-The bridge logs to stderr so you can capture debug output without breaking the MCP stdio protocol:
-
-```bash
-mg-tickets-mcp --api-key=mid_... --database-url=postgresql://... 2>debug.log
-```
-
-Debug output shows:
-- Database connection / startup status
-- API key validation hash
-- Tool dispatch and access decisions
-- Errors with stack traces
-
-## 🏗️ Development
-
-```bash
-git clone https://github.com/mgsoftwarebv/tickets-v2.git
-cd tickets-v2/packages/mcp-server-bridge
-
-bun install
-bun run build
-
-node dist/index.js --api-key=mid_... --database-url=postgresql://...
-```
-
-## 🔄 Updates
-
-```bash
-npm update -g @mgsoftwarebv/mcp-server-bridge
-# Or via npx (no install required)
-npx @mgsoftwarebv/mcp-server-bridge@latest --api-key=mid_...
-```
-
-## 🆘 Troubleshooting
-
-### ❌ "API key is required"
-- Pass `--api-key=` or set `MG_TICKETS_API_KEY`.
-- Make sure the key has the format `mid_...` (length 68).
-
-### ❌ "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).
-
-### ❌ "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.
-
-### ❌ "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
-
-MIT © MG Software B.V.
+# @mgsoftwarebv/mcp-server-bridge
+
+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.
+
+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 Configuration
+
+Add the following to your `~/.cursor/mcp.json`. You always need two things:
+
+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": {
+    "refront": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@mgsoftwarebv/mcp-server-bridge@latest",
+        "--api-key=mid_your_api_key_here",
+        "--database-url=postgresql://USER:PASSWORD@HOST:PORT/DBNAME"
+      ]
+    }
+  }
+}
+```
+
+Both values can also be supplied via environment variables instead of CLI flags:
+
+```json
+{
+  "mcpServers": {
+    "refront": {
+      "command": "npx",
+      "args": ["-y", "@mgsoftwarebv/mcp-server-bridge@latest"],
+      "env": {
+        "MG_TICKETS_API_KEY": "mid_your_api_key_here",
+        "DATABASE_PRIMARY_POOLER_URL": "postgresql://USER:PASSWORD@HOST:PORT/DBNAME"
+      }
+    }
+  }
+}
+```
+
+### 🔑 Getting an API Key
+
+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
+
+### 🗄️ Getting the Database URL
+
+- **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.
+
+## 📋 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
+export DATABASE_PRIMARY_POOLER_URL=postgresql://USER:PASSWORD@HOST:PORT/DBNAME
+mg-tickets-mcp
+```
+
+`--database-url` falls back to `DATABASE_PRIMARY_POOLER_URL`, then to `DATABASE_URL`. The bridge exits at startup if no connection string is provided.
+
+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.
+
+## 🏢 Multi-provider support
+
+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.
+
+How it resolves which provider a tool acts on:
+
+- **`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.
+
+Use **get-teams** to list the providers you can act on and copy a `teamId`.
+
+## 🛠️ Available Tools
+
+### Teams
+- **get-teams** — list the provider teams (workspaces) you can act on; use a returned id as `teamId` on other tools
+
+### 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
+
+> **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.
+
+### Quote / Proposal Documents
+- **list-documents** — list documents with filters (type, status, customer, title search)
+- **get-document** — fetch one document with metadata and the full blocks JSON
+- **create-document** — create a document from content blocks (cover, toc, heading, text, callout, table, chart incl. multi-series, pricing, timeline, two_column, divider, signature); supports a `teamId` provider override and links to a `customerId`
+- **update-document** — change title/status/customer, replace all blocks, or append blocks
+
+Document text runs through a built-in **humanizer** that strips AI-sounding patterns (em-dashes, NL/EN clichés like "naadloos"/"seamless", filler phrases). Control it per call with `humanize`:
+
+- `"rules"` (default) — deterministic cleanup, no API key needed; the tool result includes a change report
+- `"full"` — rules + an LLM rewrite pass (requires `OPENAI_API_KEY` in the bridge `env`)
+- `"off"` — store the blocks exactly as provided
+
+Optional PDF compilation: pass `compilePdf: true` to trigger the `compile-document-pdf` Trigger.dev job after create/update. This requires `TRIGGER_SECRET_KEY` (and optionally `TRIGGER_API_URL`) in the bridge `env`; without it the dashboard compiles the PDF when the document is opened or shared.
+
+### 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
+
+## ⏱️ Quick Hour Logging with `/hours`
+
+The `/hours` Cursor command makes logging time effortless:
+
+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).
+
+### 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
+
+The bridge logs to stderr so you can capture debug output without breaking the MCP stdio protocol:
+
+```bash
+mg-tickets-mcp --api-key=mid_... --database-url=postgresql://... 2>debug.log
+```
+
+Debug output shows:
+- Database connection / startup status
+- API key validation hash
+- Tool dispatch and access decisions
+- Errors with stack traces
+
+## 🏗️ Development
+
+```bash
+git clone https://github.com/mgsoftwarebv/tickets-v2.git
+cd tickets-v2/packages/mcp-server-bridge
+
+bun install
+bun run build
+
+node dist/index.js --api-key=mid_... --database-url=postgresql://...
+```
+
+## 🔄 Updates
+
+```bash
+npm update -g @mgsoftwarebv/mcp-server-bridge
+# Or via npx (no install required)
+npx @mgsoftwarebv/mcp-server-bridge@latest --api-key=mid_...
+```
+
+## 🆘 Troubleshooting
+
+### ❌ "API key is required"
+- Pass `--api-key=` or set `MG_TICKETS_API_KEY`.
+- Make sure the key has the format `mid_...` (length 68).
+
+### ❌ "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).
+
+### ❌ "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.
+
+### ❌ "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
+
+MIT © MG Software B.V.