SmartPro MCP Server

A basic skeleton for building an MCP (Model Context Protocol) server.

Setup

1. Install dependencies:

npm install

2. Configure environment variables:

   • Copy .env.example to .env

   • Fill in the required environment variables:

     • SUPABASE_URL - Your Supabase project URL (required)

     • SUPABASE_SERVICE_ROLE_KEY - Your Supabase service role key (required)

     • MCP_PORT - Port number for MCP server (required)

     • HUB_BASE_URL - Base URL for Hub API (optional)

     • CONTRACTS_BASE_URL - Base URL for Contracts API (optional)

3. Build the project:

npm run build

4. Run in development mode:

npm run dev

5. Run the built server:

npm start

Related MCP server: SupaMCPBuilder

Environment Variables

The server uses strict environment variable validation with Zod. The server will fail fast at startup if required environment variables are missing or invalid.

Required Variables

• SUPABASE_URL - Supabase project URL

• SUPABASE_SERVICE_ROLE_KEY - Supabase service role key (server-side only)

• MCP_PORT - Port number for the MCP server

Optional Variables

• HUB_BASE_URL - Base URL for Hub platform API calls

• CONTRACTS_BASE_URL - Base URL for Contracts platform API calls

• LOG_LEVEL - Logging level (debug, info, warn, error) - default: info

• AUDIT_ENABLED - Enable audit logging (true/false) - default: true

• NODE_ENV - Node environment (development, production, test) - default: development

Structure

• src/index.ts - Main server file with handlers for tools, resources, and prompts

• src/config/env.ts - Environment variable validation with Zod

• src/auth/ - Authentication and context resolution (JWT verification, tenant/role extraction)

• src/rbac/ - Role-based access control (permissions, authorization)

• src/audit/ - Audit logging for tool calls

• src/tools/ - Tool implementations (hub, contracts)

• src/resources/ - Resource implementations (hub, contracts, identity)

• src/common/ - Common utilities (errors, schemas)

• migrations/ - Database migrations (audit table)

• package.json - Project dependencies and scripts

• tsconfig.json - TypeScript configuration

Authentication & Authorization (DB-First)

The server uses Supabase JWT tokens for authentication with database-first resolution for security:

1. Token Source: The platform (Next.js API) passes Supabase access tokens via Authorization: Bearer <token> header or in request metadata.

2. Context Resolution (DB-First):

   • Step 1: Verify JWT → extract user_id (sub claim)

   • Step 2: Query database → resolve tenant_id and role from database (source of truth)

   • Step 3: Build context with userId, tenantId (from DB), role (from DB), and permissions

   Security: tenant_id and role are never trusted from JWT claims in production. This prevents privilege escalation if JWT metadata is tampered with.

3. Database Configuration: Configure where tenant/role are stored via environment variables (see .env.example). Defaults work for common Supabase patterns (profiles table).

4. RBAC: Tools check permissions before execution using the requirePermission() function.

5. Development Fallback: In NODE_ENV=development, if DB lookup fails, falls back to JWT claims with a warning. In production, DB lookup failure is an authentication error.

Audit Logging

All tool calls are logged to the mcp_tool_audit_logs table in Supabase:

• Tenant isolation: Logs are scoped by tenant_id

• Sensitive data redaction: Passwords, tokens, etc. are automatically redacted

• Entity references: Automatically extracts entity IDs (booking_id, invoice_id, etc.)

• Performance tracking: Latency is recorded for each call

• Error tracking: Failed calls are logged with error messages

Database Migration

Run the migration to create the audit table:

-- See migrations/001_create_mcp_tool_audit_logs.sql

Implementation

To implement your MCP server:

1. Environment Setup: Configure required environment variables (see .env.example)

2. Database Migration: Run the audit table migration in Supabase

3. Tools: Implement tool handlers in src/tools/ with proper permission checks

4. Resources: Implement resource handlers in src/resources/ with tenant isolation

5. Prompts: Add prompt definitions in the ListPromptsRequestSchema handler

MCP Configuration

To use this server with Cursor or other MCP clients, add it to your MCP configuration file (e.g., ~/.cursor/mcp.json):

{
  "mcpServers": {
    "smartpro-mcp-server": {
      "command": "node",
      "args": ["path/to/smartpro-mcp-server/dist/index.js"]
    }
  }
}