VIDAL Helpdesk MCP

AI-powered helpdesk infrastructure for the VIDAL ecosystem. This repository provides a production-oriented MCP server and scheduled audit runtime for Swiss SME support operations, with explicit schema isolation, strict CI, runtime validation, structured logging, and defensive CORS controls.

Business Context

vidal-helpdesk-mcp acts as an AI-enabled control plane for helpdesk automation. It exposes operational ticket workflows through Model Context Protocol tools, connects to Supabase for the helpdesk data plane, and runs scheduled SLA audits through Vercel and GitHub Actions.

The system is designed for Swiss SME expectations around reliability, privacy, and operational evidence:

• Organization-scoped reads and writes.

• Explicit runtime schema boundaries through SUPABASE_SCHEMA.

• Service-role access isolated to backend runtimes.

• Runtime environment validation with Zod.

• Structured JSON logs suitable for Vercel Log Drains, Datadog, or SIEM ingestion.

• CORS deny-by-default using ALLOWED_ORIGINS.

Related MCP server: Servidor MCP Universal

Architecture Principles

Directory Architecture

Runtime Flow

flowchart LR
  GHA[GitHub Actions] -->|POST with Origin and Bearer token| API[Vercel /api/cron/audit]
  API --> CORS[CORS allowlist]
  API --> ENV[Zod env validation]
  API --> SVC[AuditService.run]
  SVC --> HD[(Supabase runtime schema)]
  SVC --> PUB[(Supabase public schema)]
  SVC --> RESEND[Resend email]
  SVC --> LOGS[JSON logs]

Operational Configuration

Create .env locally or configure the same variables in Vercel.

SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_SCHEMA=public
VIDAL_MCP_AUDIT_URL=https://your-vercel-domain.example/api/cron/audit

MCP_ORGANIZATION_ID=your-organization-uuid
MCP_AGENT_ID=your-agent-uuid

ANTHROPIC_API_KEY=sk-ant-your-key

AUDIT_CRON_SECRET=your-audit-cron-secret
AUDIT_EMAIL_ENABLED=true
AUDIT_EMAIL_DEDUPE_MINUTES=120
RESEND_API_KEY=re_your_key
RESEND_FROM_EMAIL=helpdesk@example.com

ALLOWED_ORIGINS=https://your-helpdesk-domain.example,https://your-mcp-domain.example

ALLOWED_ORIGINS Format

ALLOWED_ORIGINS is a comma-separated allowlist. Each entry must be a full origin including protocol and host.

Valid:

ALLOWED_ORIGINS=https://app.example.ch,https://vidal-helpdesk-mcp.vercel.app

Invalid:

ALLOWED_ORIGINS=app.example.ch,*

If ALLOWED_ORIGINS is absent during npm run build, the build still succeeds. If it is empty at runtime for protected endpoints, the service returns a controlled runtime error instead of silently allowing access.

GitHub Actions Secrets

VIDAL_MCP_AUDIT_URL=https://your-vercel-domain.example/api/cron/audit
VIDAL_MCP_AUDIT_SECRET=your-audit-cron-secret

The scheduled audit workflow derives the Origin header from VIDAL_MCP_AUDIT_URL. That origin must also be present in ALLOWED_ORIGINS.

Local Development

npm ci
npm run lint
npm test
npm run build
npm run dev

CI Gates

The CI workflow is strict:

npm ci
npm run lint
npm test
npm run build

There is no test bypass. Any failing test aborts the pipeline.

Audit Endpoint

Endpoint:

POST /api/cron/audit

Required headers:

Origin: https://your-allowlisted-origin.example
Authorization: Bearer <AUDIT_CRON_SECRET>
Content-Type: application/json

Runtime responsibilities:

• Validate Origin against ALLOWED_ORIGINS.

• Validate runtime environment variables.

• Query active tickets from SUPABASE_SCHEMA.

• Query shared organization metadata from the public schema.

• Calculate SLA compliance.

• Send audit email via Resend.

• Persist audit run evidence.

• Emit structured logs.

Audit Health Endpoint

Endpoint:

GET /api/health/audit

Required headers:

Origin: https://your-allowlisted-origin.example
Authorization: Bearer <AUDIT_CRON_SECRET>

This endpoint checks runtime configuration and Supabase connectivity without sending emails.

{
  "status": "ok",
  "supabase": "ok",
  "resend": "configured",
  "schema": "public",
  "organizationId": "set",
  "emailEnabled": true,
  "dedupeMinutes": 120
}

Structured Logging

Every audit event is written as a single JSON line to stdout.

{
  "timestamp": "2026-06-11T17:42:10.916Z",
  "level": "info",
  "requestId": "request-id",
  "organizationId": "organization-id",
  "workflow": "audit-cron",
  "httpStatus": 200,
  "supabaseErrorCode": null,
  "resendErrorCode": null,
  "message": "Audit cron completed"
}

This format is compatible with Vercel logs, Vercel Log Drains, Datadog pipelines, and SIEM ingestion.

MCP Tools

All MCP tool inputs are validated with Zod before execution.

Production Notes

• Configure ALLOWED_ORIGINS before enabling scheduled audits.

• Keep SUPABASE_SERVICE_ROLE_KEY backend-only.

• Rotate AUDIT_CRON_SECRET and GitHub Actions secrets periodically.

• Use Vercel production environment variables, not preview defaults, for scheduled workflows.

• Connect Vercel Log Drains or Datadog before relying on the audit workflow as operational evidence.