Whilst MCP Server

MCP (Model Context Protocol) server for Whilst document management. Enables AI assistants like Cursor, Claude Desktop, and VS Code Copilot to query, create, update, and manage Whilst documents and folders.

Features

• Document Management: List, get, create, update, delete documents
• Folder Management: Hierarchical folder structure with move/organize operations
• Search: Semantic search (AI-powered) and hybrid keyword+semantic search
• Resources: Read-only access via whilst:// URI scheme
• Prompts: Pre-built templates for common operations

Quick Start (Hosted)

The easiest way to use the Whilst MCP server is via our hosted endpoint. You just need an API key from your workspace settings.

Cursor IDE

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "whilst": {
      "url": "https://mcp.whilst.io/mcp",
      "headers": {
        "Authorization": "Bearer whl_live_your_key_here"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "whilst": {
      "url": "https://mcp.whilst.io/mcp",
      "headers": {
        "Authorization": "Bearer whl_live_your_key_here"
      }
    }
  }
}

Getting an API Key

1. Go to your Whilst workspace settings
2. Navigate to API Keys
3. Click Create API Key
4. Copy the generated key (starts with whl_live_)

Self-Hosted Mode (Advanced)

For self-hosted or local development, you can run the MCP server directly with database access.

Installation

npm install @whilst/mcp-server
# or
pnpm add @whilst/mcp-server

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | WHILST_API_KEY | Yes | API key for workspace authentication | | DATABASE_URL | Yes | PostgreSQL connection string | | OPENAI_API_KEY | No | Enables semantic search capabilities | | LOG_LEVEL | No | Logging level: debug, info, warn, error (default: info) |

Cursor IDE (Self-Hosted)

{
  "mcpServers": {
    "whilst": {
      "command": "npx",
      "args": ["@whilst/mcp-server"],
      "env": {
        "WHILST_API_KEY": "whl_live_your_key_here",
        "DATABASE_URL": "postgresql://...",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Claude Desktop (Self-Hosted)

{
  "mcpServers": {
    "whilst": {
      "command": "npx",
      "args": ["@whilst/mcp-server"],
      "env": {
        "WHILST_API_KEY": "whl_live_your_key_here",
        "DATABASE_URL": "postgresql://...",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Available Tools

Document Tools

| Tool | Description | |------|-------------| | list_documents | List documents with filters (folder, search, tags) | | get_document | Get full document content by ID | | create_document | Create a new document | | update_document | Update document content/metadata | | delete_document | Permanently delete a document |

Folder Tools

| Tool | Description | |------|-------------| | list_folders | List folders (flat or hierarchical) | | get_folder | Get folder with contents | | create_folder | Create a new folder | | update_folder | Update folder properties | | move_folder | Move folder to new parent | | delete_folder | Delete folder (optional cascade) |

Search Tools

| Tool | Description | |------|-------------| | semantic_search | AI-powered semantic search | | hybrid_search | Combined keyword + semantic search | | find_similar | Find documents similar to a given document |

Available Resources

| URI | Description | |-----|-------------| | whilst://documents | List all accessible documents | | whilst://documents/{id} | Full document content | | whilst://folders | Folder tree structure | | whilst://folders/{id} | Folder with contents | | whilst://folders/{id}/documents | Documents in a folder | | whilst://recent | Recently accessed documents | | whilst://pinned | Pinned documents |

Available Prompts

| Prompt | Description | |--------|-------------| | search_and_summarize | Search and summarize findings | | create_from_template | Create document from template (meeting_notes, project_brief, etc.) | | document_review | Review document and suggest improvements |

API Key Generation

API keys are generated from the Whilst web application:

1. Navigate to Workspace Settings > API Keys
2. Click "Create API Key"
3. Give it a name (e.g., "Cursor IDE")
4. Copy the generated key (it won't be shown again)

API key format: whl_live_<random> (production) or whl_test_<random> (development)

Development

# Watch mode
pnpm dev

# Build
pnpm build

# Type check
pnpm typecheck

# Lint
pnpm lint

# Test
pnpm test

Architecture

src/
├── index.ts           # Entry point (CLI)
├── server.ts          # MCP server setup
├── auth/              # Authentication & authorization
│   ├── api-key.ts     # API key validation
│   ├── context.ts     # Workspace context (AsyncLocalStorage)
│   └── permissions.ts # Permission enforcement
├── db/                # Database
│   └── pool.ts        # Connection pool management
├── tools/             # MCP tools (actions)
│   ├── documents.ts   # Document CRUD
│   ├── folders.ts     # Folder CRUD
│   └── search.ts      # Search operations
├── resources/         # MCP resources (read-only)
│   ├── documents.ts   # Document resources
│   └── folders.ts     # Folder resources
└── utils/             # Utilities
    ├── logging.ts     # Stderr logging (STDIO safe)
    ├── errors.ts      # Custom error classes
    └── embeddings.ts  # OpenAI embeddings

Security

• API keys are hashed with SHA-256 before storage
• All operations are scoped to the authenticated workspace
• Permission-based access control for tools and resources
• Document visibility rules enforced server-side