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.

$3

Add to ~/.cursor/mcp.json:

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

$3

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

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

$3

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.

$3

`bash
npm install @whilst/mcp-server


or


pnpm add @whilst/mcp-server
`

$3

| 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) |

$3

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

$3

`json
{
"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

$3

| 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 |

$3

| 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) |

$3

| 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_ (production) or whl_test_ (development)

Development

`bash


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