# SmartPro MCP Server

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

## Setup

1. Install dependencies:
```bash
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:
```bash
npm run build
```

4. Run in development mode:
```bash
npm run dev
```

5. Run the built server:
```bash
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:

```sql
-- 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`):

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