npm package: @lindblad/complai-mcp
Description: MCP server providing COMPLAI compliance overview tools for AI assistants
Author: COMPLAI
Latest version: 0.3.1

# COMPLAI MCP Server

An MCP (Model Context Protocol) server that provides COMPLAI compliance data to AI assistants.

**Package:** `@lindblad/complai-mcp`

## Supported AI Tools

- **Claude Desktop** - Anthropic's desktop app
- **Cursor** - AI-powered code editor
- **VS Code** - With built-in MCP support
- **Windsurf** - AI coding assistant
- Any tool supporting the [Model Context Protocol](https://modelcontextprotocol.io/)

## Quick Start

### Claude Desktop

Add to `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac):

```json
{
  "mcpServers": {
    "complai": {
      "command": "npx",
      "args": ["-y", "@lindblad/complai-mcp"]
    }
  }
}
```

### Cursor / VS Code

Add to `.cursor/mcp.json` or `.vscode/mcp.json`:

```json
{
  "mcpServers": {
    "complai": {
      "command": "npx",
      "args": ["@lindblad/complai-mcp"],
      "env": {
        "COMPLAI_API_URL": "https://api.complai.com",
        "COMPLAI_AUTH0_DOMAIN": "lindcon.eu.auth0.com",
        "COMPLAI_AUTH0_CLIENT_ID": "your-client-id",
        "COMPLAI_AUTH0_AUDIENCE": "https://api.complai.com"
      }
    }
  }
}
```

2. When you first use a COMPLAI tool, use `complai_login`:
   - Your browser will open for login
   - If you belong to multiple organizations, Auth0 will show an org picker
   - Select your organization and complete login
   - Done! Your session is saved to `~/.complai/`

#### Organization Selection

`COMPLAI_ORGANIZATION_ID` is **optional**:

- **Not set**: Auth0 prompts user to select organization at login (recommended for multi-org users)
- **Set to org ID**: User is logged directly into that specific organization

```json
{
  "env": {
    "COMPLAI_ORGANIZATION_ID": "org_xxxxx"  // Optional: pre-select org
  }
}
```

### M2M Authentication (For Automation)

For scripts, CI/CD, or shared environments. Requires a client secret.

```json
{
  "mcpServers": {
    "complai": {
      "command": "npx",
      "args": ["@lindblad/complai-mcp"],
      "env": {
        "COMPLAI_API_URL": "https://api.complai.com",
        "COMPLAI_AUTH0_DOMAIN": "lindcon.eu.auth0.com",
        "COMPLAI_AUTH0_CLIENT_ID": "your-m2m-client-id",
        "COMPLAI_AUTH0_CLIENT_SECRET": "your-m2m-client-secret",
        "COMPLAI_AUTH0_AUDIENCE": "https://api.complai.com"
      }
    }
  }
}
```

Note: M2M tokens derive organization context from the client configuration in Auth0, not from environment variables.

### Mock Mode

For testing without any API connection:

```json
{
  "mcpServers": {
    "complai": {
      "command": "npx",
      "args": ["@lindblad/complai-mcp"],
      "env": {
        "COMPLAI_MOCK_MODE": "true"
      }
    }
  }
}
```

## Authentication Flow

### First Time Setup (User Auth Mode)

When you start the server for the first time, it will prompt for authentication:

```
COMPLAI MCP Server v0.1.0
─────────────────────────
API:  https://api.test.complai.com
Auth: User (Device Flow)

Authentication required. Starting device authorization flow...

┌─────────────────────────────────────────────────────────────┐
│  Please complete authentication in your browser:            │
│                                                             │
│  1. Open:  https://complai-test.eu.auth0.com/activate       │
│  2. Enter: ABCD-EFGH                                        │
│                                                             │
│  Waiting for authentication...                              │
└─────────────────────────────────────────────────────────────┘

✓ Authentication successful!

Starting server...
✓ Server ready
```

After logging in once, your session is saved to `~/.complai/` and you won't need to log in again.

### Logging Out

To log out, delete the stored credentials:
```bash
rm -rf ~/.complai/.credentials.enc
```

## Available Tools

### Auth

| Tool | Description |
|------|-------------|
| `complai_login` | Authenticate with COMPLAI (opens browser) |
| `complai_auth_status` | Check authentication status |
| `complai_list_organizations` | List organizations you have access to |

### Data

| Tool | Description |
|------|-------------|
| `complai_compliance_brief` | Aggregated compliance overview (risk distribution, task status, alerts) |
| `complai_data_rooms` | List or get data rooms with risk rating, engagement status, tags, manufacturer |
| `complai_tasks` | List or get tasks with completion status, deadline, form template |
| `complai_forms` | List or get forms/assessments with self-assessment and independent assessment status |
| `complai_corrective_actions` | List or get corrective actions with status, priority, deadline, findings |

All data tools accept an optional `id` parameter: omit it to get a paginated list, provide it to get a single item's details. List endpoints support filtering (e.g. `riskRatingName`, `completionStatus`, `status`, `priority`) and pagination (`page`, `pageSize`).

## Usage

Just ask your AI assistant:

- *"What's my compliance status?"*
- *"Show me all data rooms with high risk"*
- *"Which tasks are overdue?"*
- *"List open corrective actions"*
- *"What forms are incomplete for data room X?"*
- *"Give me a compliance summary for my board meeting"*

### First Time Authentication

On first use, you'll need to authenticate:

1. The AI will call `complai_login`
2. A browser window opens for you to log in with your COMPLAI credentials
3. Done! Your session is saved locally

### Multi-Organization Support

If you have access to multiple organizations:

1. Call `complai_list_organizations` to see available orgs
2. Call `complai_login` with the `organizationId` to switch orgs
3. Then use any data tool

## Example Output

### Compliance Brief

```json
{
  "summary": {
    "description": "Compliance overview as of 2026-02-04",
    "dataRooms": 24,
    "assets": 156,
    "manufacturers": 42,
    "totalTasks": 89,
    "overdueActions": 7
  },
  "riskDistribution": [
    { "level": "High", "count": 3, "percentage": 12.5 },
    { "level": "Medium", "count": 8, "percentage": 33.3 },
    { "level": "Low", "count": 13, "percentage": 54.2 }
  ],
  "taskStatus": {
    "overdue": 12,
    "dueThisWeek": 8,
    "onTrack": 45,
    "noDeadline": 24
  },
  "alerts": [
    "7 corrective actions are past their deadline",
    "12 tasks are overdue"
  ]
}
```

### Data Rooms (list)

```json
{
  "pagination": { "page": 0, "pageSize": 20, "totalCount": 24, "totalPages": 2 },
  "data": [
    {
      "dataRoomId": "abc-123",
      "dataRoomName": "Supplier ABC Audit",
      "riskRatingName": "Medium",
      "engagementStatusName": "In Progress",
      "assetsAmount": 5,
      "taskAmount": 12,
      "manufacturerName": "ABC Corp",
      "tags": ["ISO 27001", "GDPR"]
    }
  ]
}
```

### Corrective Actions (filtered)

```json
{
  "pagination": { "page": 0, "pageSize": 20, "totalCount": 3, "totalPages": 1 },
  "data": [
    {
      "actionId": "ca-456",
      "title": "Missing documentation for supplier X",
      "status": "open",
      "priority": "high",
      "deadlineDate": "2026-02-15T00:00:00.000Z",
      "findings": "Required ISO certificates not uploaded",
      "dataRoomName": "Supplier X Audit",
      "connectedTo": [
        { "taskName": "ISO 27001 Review", "assetName": "Widget A", "requirementName": "Certificate upload" }
      ]
    }
  ]
}
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `COMPLAI_ORGANIZATION_ID` | Skip org selection by setting a default organization ID |

## Security

- Credentials are stored encrypted in `~/.complai/` (AES-256-GCM)
- Access tokens are cached in memory only
- All API calls use HTTPS
- Permissions match the COMPLAI web UI

## Troubleshooting

**"Not authenticated"** - Run `complai_login` first

**"No organizations found"** - Your COMPLAI account may not have any org memberships

**"Access denied"** - You don't have permission for that organization

## Distribution Channels

| Channel | Transport | Setup |
|---------|-----------|-------|
| npm / npx (Cursor, Claude, VS Code) | stdio | See config above |
| Docker | HTTP | `docker run` — see [Installation Guide](../../docs/mcp-compliance-tool/installation.md#docker) |
| Azure Container Apps | HTTP | See [Deployment Guide](../../docs/mcp-compliance-tool/deployment.md) |
| ChatGPT | HTTP (remote) | See [Installation Guide](../../docs/mcp-compliance-tool/installation.md#chatgpt) |
| M365 Copilot | HTTP (remote) | See [Deployment Guide](../../docs/mcp-compliance-tool/deployment.md#m365-copilot-agent-deployment) |

## Documentation

Full documentation is available at [`docs/mcp-compliance-tool/`](../../docs/mcp-compliance-tool/):

- [Installation Guide](../../docs/mcp-compliance-tool/installation.md) — all distribution channels
- [Architecture](../../docs/mcp-compliance-tool/architecture.md) — system design, data model, security
- [Authentication](../../docs/mcp-compliance-tool/authentication.md) — Auth0 setup, token exchange
- [Deployment](../../docs/mcp-compliance-tool/deployment.md) — Azure + Copilot deployment
- [Troubleshooting](../../docs/mcp-compliance-tool/troubleshooting.md) — common issues

## License

MIT