SmartPro 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

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"]
    }
  }
}