### Environment Setup Example

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/CONFIGURATION.md

Instructions for setting up the environment by copying the example .env file and configuring Vikunja connection details and the Node.js environment.

```env
VIKUNJA_URL=https://your-vikunja-instance.com
VIKUNJA_API_TOKEN=your-api-token-here
```

```env
NODE_ENV=development  # or test, production
```

--------------------------------

### Docker Configuration Example (Dockerfile)

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/MIGRATION_GUIDE.md

Example Dockerfile demonstrating how to install and configure Vikunja MCP, including existing and new optional environment variables.

```dockerfile
# Existing configuration continues to work
FROM node:20-alpine
RUN npm install -g @democratize-technology/vikunja-mcp@latest

ENV VIKUNJA_URL=https://your-vikunja-instance.com/api/v1
ENV VIKUNJA_API_TOKEN=your-token

# Optional new settings
ENV CIRCUIT_BREAKER_ENABLED=true
ENV FILTER_MAX_LENGTH=1000

CMD ["vikunja-mcp"]
```

--------------------------------

### List Vikunja Projects Example

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/TECHNICAL_SPEC.md

Example of listing all projects in Vikunja using the assistant. This demonstrates a simple API call with no parameters.

```json
User: "Show me all my Vikunja projects"

Assistant uses: vikunja_projects.list
Parameters: {}

Response: [
  { id: 1, title: "Personal Tasks", ... },
  { id: 2, title: "Work Projects", ... }
]
```

--------------------------------

### Local Development Setup for Vikunja MCP

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Clone the repository, install dependencies, and build the project for local development. Configure your MCP client to use the local build.

```bash
git clone https://github.com/democratize-technology/vikunja-mcp.git
cd vikunja-mcp
npm install
npm run build
```

```json
{
  "vikunja": {
    "command": "node",
    "args": ["/path/to/vikunja-mcp/dist/index.js"],
    "env": {
      "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
      "VIKUNJA_API_TOKEN": "your-api-token"
    }
  }
}
```

--------------------------------

### Create Vikunja Task Example

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/TECHNICAL_SPEC.md

Example of creating a task in Vikunja using the assistant. Ensure parameters like projectId, dueDate, and priority are correctly formatted.

```json
User: "Create a task to review the MCP implementation"

Assistant uses: vikunja_tasks.create
Parameters: {
  title: "Review MCP implementation",
  projectId: 1,
  dueDate: "2024-02-01T17:00:00Z",
  priority: 3
}

Response: {
  id: 42,
  title: "Review MCP implementation",
  ...
}
```

--------------------------------

### Example Test Template

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/tests/README.md

A template for writing new tests, including setup, describe blocks for subcommands, and example test cases for success and validation errors. Remember to mock dependencies and include assertions.

```typescript
describe('New Tool', () => {
  let mockClient: any;
  let toolHandler: any;

  beforeEach(() => {
    jest.clearAllMocks();
    // Setup mocks
  });

  describe('subcommand', () => {
    it('should handle success case', async () => {
      // Arrange
      mockClient.method.mockResolvedValue(expectedResult);
      
      // Act
      const result = await callTool('subcommand', { /* args */ });
      
      // Assert
      expect(result).toBeDefined();
      // ... more assertions
    });

    it('should handle validation error', async () => {
      await expect(callTool('subcommand', { /* invalid args */ }))
        .rejects.toThrow('Expected error message');
    });
  });
});
```

--------------------------------

### MCP Server Tool Registration Example

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/CLAUDE.md

Example of registering a Vikunja tool with the MCP server, defining its subcommand options and validation schema using Zod.

```typescript
server.tool('vikunja_tasks', {
  subcommand: z.enum(['create', 'get', 'update', 'delete', 'list']),
  // ... Zod validation schema
}, async (args) => {
  // Route to specific operation handlers
})
```

--------------------------------

### Example Vikunja MCP Log Output

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Structured log output includes timestamps and log levels, written to stderr. This example shows server start and a debug log for task execution.

```text
[2025-05-25T17:00:00.000Z] [INFO] Vikunja MCP server started
[2025-05-25T17:00:00.100Z] [DEBUG] Executing tasks tool { subcommand: 'list', args: {...} }
```

--------------------------------

### Incorrect Import Path Example

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/SIMPLERESPONSE_MIGRATION_TEST_REPORT.md

Shows an example of an incorrect relative import path that needs to be fixed during the migration. This issue affects multiple tool modules.

```typescript
import from '../../../utils/response-factory'
```

--------------------------------

### API Usage Examples (TypeScript)

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/MIGRATION_GUIDE.md

Examples of using Vikunja APIs for creating tasks and filters. The filter parsing is now secured with Zod.

```typescript
// All these APIs work exactly the same
await vikunja_tasks.create({
  projectId: 1,
  title: "My task",
  filter: "priority >= 3"  // Now uses secure Zod parsing
});

await vikunja_filters.create({
  name: "High Priority",
  filter: "done = false && priority >= 4"  // Enhanced security, same syntax
});
```

--------------------------------

### Install Latest Vikunja MCP (Bash)

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/MIGRATION_GUIDE.md

Command to install the latest version of the Vikunja MCP package using npm.

```bash
npm install @democratize-technology/vikunja-mcp@latest
```

--------------------------------

### Vikunja MCP Standard Response Examples

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Provides examples of successful and error responses from the Vikunja MCP server, illustrating the standardized format. Success responses include data and metadata, while errors detail the issue.

```json
{
  "success": true,
  "operation": "create",
  "message": "Task created successfully",
  "data": { "id": 123, "title": "Complete documentation" },
  "metadata": { "timestamp": "2025-05-25T12:00:00Z" }
}
```

```json
{
  "success": false,
  "operation": "update",
  "message": "Task not found",
  "error": { "code": "TASK_NOT_FOUND", "details": "No task exists with ID 999" }
}
```

--------------------------------

### Get Configuration and Specific Sections

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/CONFIGURATION.md

Import and use functions to retrieve the complete configuration or specific parts like authentication and rate limiting. Also shows how to check feature flags.

```typescript
import { getConfiguration, getAuthConfig, getRateLimitConfig } from './config';

// Get complete configuration
const config = await getConfiguration();

// Get specific sections
const authConfig = await getAuthConfig();
const rateLimiting = await getRateLimitConfig();

// Check feature flags
const isEnabled = await isFeatureEnabled('enableServerSideFiltering');
```

--------------------------------

### Initialize and use storage with debug logging

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/STORAGE.md

Import and use the createFilterStorage function to initialize a storage adapter with a session identifier. This example also demonstrates retrieving statistics and performing a health check, with debug logging enabled implicitly by the import.

```typescript
import { createFilterStorage } from '@democratize-technology/vikunja-mcp/storage';

const storage = await createFilterStorage('debug-session');
const stats = await storage.getStats();
const health = await storage.healthCheck();

console.log('Storage Stats:', stats);
console.log('Health Check:', health);
```

--------------------------------

### Example Configuration Error Messages

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/CONFIGURATION.md

Illustrates common configuration validation error messages for invalid URL formats, negative numeric values, and incorrect enum selections.

```text
Configuration error in validation: Configuration validation failed:
  - auth.vikunjaUrl: Invalid url

Configuration error in validation: Configuration validation failed:
  - rateLimiting.default.requestsPerMinute: Number must be greater than 0

Configuration error in validation: Configuration validation failed:
  - logging.level: Invalid enum value. Expected 'error' | 'warn' | 'info' | 'debug', received 'verbose'
```

--------------------------------

### Update Main Application Entry Point Configuration

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/CONFIGURATION_MIGRATION.md

Initializes configuration early in the application's main entry point, replacing scattered environment checks with centralized configuration retrieval for authentication setup.

```typescript
// Before: Scattered environment checks
if (process.env.VIKUNJA_URL && process.env.VIKUNJA_API_TOKEN) {
  authManager.connect(process.env.VIKUNJA_URL, process.env.VIKUNJA_API_TOKEN);
}

// After: Centralized configuration
async function main() {
  // Initialize configuration early
  const config = await getConfiguration();
  
  if (config.auth.vikunjaUrl && config.auth.vikunjaToken) {
    authManager.connect(config.auth.vikunjaUrl, config.auth.vikunjaToken);
  }
  
  // Rest of startup logic
}
```

--------------------------------

### List All Tasks Across Projects

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Use this to retrieve all tasks from all projects. No specific setup is required beyond having the `vikunja_tasks` object available.

```typescript
// List all tasks across all projects
vikunja_tasks.list({ allProjects: true })
```

--------------------------------

### Run Filter Parsing Test

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/REFACTORING_SUMMARY.md

Example command to run a specific filter parsing test. This helps verify core filter functionality after refactoring.

```bash
# Core filter parsing works
npm test -- --testNamePattern="should parse simple equality condition"
# ✅ PASS tests/utils/filters.test.ts
```

--------------------------------

### Start Development Server with Watch Mode

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/CLAUDE.md

Launch a development server that automatically rebuilds and restarts on code changes, using tsx for direct TypeScript execution.

```bash
npm run dev
```

--------------------------------

### Corrected Import Path Example

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/SIMPLERESPONSE_MIGRATION_TEST_REPORT.md

Provides the corrected version of the import path, demonstrating the required change from '../../../' to '../../'.

```typescript
'../../utils/response-factory'
```

--------------------------------

### Session Isolation Example

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/STORAGE.md

Illustrates how storage instances created with different session identifiers are isolated, preventing data leakage between them.

```typescript
const storage1 = await createFilterStorage('session-1');
const storage2 = await createFilterStorage('session-2');

// Filters created in storage1 are not visible in storage2
await storage1.create({ name: 'Filter 1', filter: 'done = false', isGlobal: false });
await storage2.create({ name: 'Filter 1', filter: 'priority = 1', isGlobal: false });

// Both operations succeed - names can be duplicated across sessions
```

--------------------------------

### Test Coverage Report

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/BULK_OPERATIONS_PERFORMANCE_OPTIMIZATION.md

Example output of a test coverage report after running `npm run test:coverage`. Shows percentages for branches, functions, lines, and statements.

```bash
npm run test:coverage
# Branches: 92.3% (threshold: 90%)
# Functions: 98.9% (threshold: 98%)
# Lines: 96.1% (threshold: 95%)
# Statements: 96.1% (threshold: 95%)
```

--------------------------------

### Unit Test for Task Creation

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/TECHNICAL_SPEC.md

Example unit test for the Tasks Tool, mocking the Vikunja SDK to verify task creation functionality.

```typescript
// Mock Vikunja API responses
jest.mock('node-vikunja');

describe('Tasks Tool', () => {
  it('should create a task with valid data', async () => {
    // Mock the SDK response
    mockVikunjaClient.tasks.create.mockResolvedValue({
      id: 1,
      title: 'Test Task',
      // ... mocked response matching Vikunja API
    });

    // Test through MCP tool
    const result = await tasksTool.execute({
      subcommand: 'create',
      title: 'Test Task',
      projectId: 1
    });

    // Verify SDK was called correctly
    expect(mockVikunjaClient.tasks.create).toHaveBeenCalledWith({
      title: 'Test Task',
      projectId: 1
    });
  });
});
```

--------------------------------

### API Compatibility: Before and After Refactoring

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/ARCHITECTURE_SIMPLIFICATION.md

This example shows identical API calls for creating filters before and after refactoring, demonstrating that the external API remains 100% compatible.

```typescript
// Before refactoring
vikunja_filters.create({
  name: "High Priority Tasks",
  filter: "done = false && priority >= 4"
});

// After refactoring - identical API
vikunja_filters.create({
  name: "High Priority Tasks",
  filter: "done = false && priority >= 4"
});
```

--------------------------------

### Mock Setup for Vikunja Client

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/tests/README.md

Sets up Jest mocks for external modules and configures a mock client with required methods. Use this to isolate tests from actual API calls.

```typescript
// Mock the modules
jest.mock('../../src/index', () => ({
  getVikunjaClient: jest.fn()
}));

// Setup mock client with all required methods
const mockClient = {
  getToken: jest.fn().mockReturnValue('test-token'),
  tasks: {
    getAllTasks: jest.fn(),
    getProjectTasks: jest.fn(),
    createTask: jest.fn()
    // ... other methods
  }
};
```

--------------------------------

### Enhanced Bulk Operation Execution

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/BULK_OPERATIONS_PERFORMANCE_OPTIMIZATION.md

This example demonstrates the execution of an enhanced bulk operation that employs progressive enhancement strategies. It first attempts the bulk API with circuit breaker protection, falling back to adaptive batching, and finally to individual operations.

```typescript
const result = await bulkUpdateEnhancer.execute(
  taskIds,
  bulkApiOperation,  // Try bulk API first
  individualOperation // Fallback with adaptive batching
);
```

--------------------------------

### Example Security Enhancement (TypeScript)

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/MIGRATION_GUIDE.md

Illustrates how a potentially malicious filter input is handled differently in v0.1.x versus v0.2.0, where it's now safely rejected.

```typescript
// This input is now properly validated and secured
const maliciousFilter = 'priority >= "'.repeat(1000) + '"';

// v0.1.x: Could cause performance issues or crashes
// v0.2.0: Safely rejected with clear error message
```

--------------------------------

### vikunja_templates

Source: https://context7.com/democratize-technology/vikunja-mcp/llms.txt

Manage project templates. Create, list, get, update, delete, and instantiate projects from templates. Supports variable substitution for project instantiation.

```APIDOC
## Create Template

### Description
Creates a project template from an existing project, capturing its tasks and labels.

### Method
`vikunja_templates`

### Parameters
- `subcommand`: "create" (string, required)
- `projectId`: (number, required) - The ID of the project to create the template from.
- `name`: (string, required) - The name of the template.
- `description`: (string, optional) - A description for the template.
- `tags`: (string array, optional) - Tags to associate with the template.

### Response Example
```json
{
  "template": {
    "id": "template_1234567890",
    "name": "Sprint Template",
    "tasks": [...]
  }
}
```

## List Templates

### Description
Lists all available project templates.

### Method
`vikunja_templates`

### Parameters
- `subcommand`: "list" (string, required)

## Get Template

### Description
Retrieves a specific project template by its ID.

### Method
`vikunja_templates`

### Parameters
- `subcommand`: "get" (string, required)
- `id`: (string, required) - The ID of the template to retrieve.

## Update Template

### Description
Updates the metadata of an existing project template.

### Method
`vikunja_templates`

### Parameters
- `subcommand`: "update" (string, required)
- `id`: (string, required) - The ID of the template to update.
- `name`: (string, optional) - The new name for the template.
- `description`: (string, optional) - The new description for the template.
- `tags`: (string array, optional) - The new tags for the template.

## Delete Template

### Description
Deletes a project template.

### Method
`vikunja_templates`

### Parameters
- `subcommand`: "delete" (string, required)
- `id`: (string, required) - The ID of the template to delete.

## Instantiate Project from Template

### Description
Instantiates a new project from a template, applying variable substitution.

### Method
`vikunja_templates`

### Parameters
- `subcommand`: "instantiate" (string, required)
- `id`: (string, required) - The ID of the template to instantiate from.
- `projectName`: (string, required) - The name for the new project. Supports built-in variables like `{{PROJECT_NAME}}` and `{{TODAY}}`.
- `parentProjectId`: (number, optional) - The ID of the parent project for the new project.
- `variables`: (object, optional) - Custom variables for substitution in `projectName` and other template fields.
  - `PROJECT_NAME`: (string) - Example custom variable.
  - `OWNER`: (string) - Example custom variable.

### Response Example
Creates a new project with all tasks from the template.
```

--------------------------------

### Example Task Response with Snake_case Fields

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/VIKUNJA_API_ISSUES.md

Shows a typical JSON response for a task, highlighting the consistent use of snake_case for field names like 'due_date', 'start_date', and 'percent_done'.

```json
{
  "id": 1,
  "title": "Example Task",
  "due_date": "2024-12-31T23:59:59Z",
  "start_date": "2024-01-01T00:00:00Z", 
  "percent_done": 50,
  "hex_color": "#FF0000",
  "repeat_after": 86400,
  "done_at": null,
  "created_by": {...}
}
```

--------------------------------

### Run Security Validation Test

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/REFACTORING_SUMMARY.md

Example command to run a specific security validation test. This verifies that the refactored code correctly rejects invalid filter strings.

```bash
# Security validation works
npm test -- --testNamePattern="should reject filter strings with invalid characters"
# ✅ PASS tests/utils/filters.test.ts
```

--------------------------------

### Environment Variable Configuration for Storage

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/STORAGE.md

Demonstrates how to configure the storage backend and its parameters using environment variables.

```bash
# Storage type (memory, sqlite, postgresql, redis)
export VIKUNJA_MCP_STORAGE_TYPE=sqlite

# SQLite database file path
export VIKUNJA_MCP_STORAGE_DATABASE_PATH=/path/to/filters.db

# Connection string for PostgreSQL/Redis
export VIKUNJA_MCP_STORAGE_CONNECTION_STRING=postgresql://user:pass@host:port/db

# Connection pool size (1-100)
export VIKUNJA_MCP_STORAGE_POOL_SIZE=10

# Connection timeout in milliseconds (1000-60000)
export VIKUNJA_MCP_STORAGE_TIMEOUT=5000

# Enable debug logging
export VIKUNJA_MCP_STORAGE_DEBUG=true
```

--------------------------------

### Load Configuration Early in Application Startup

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/CONFIGURATION.md

Demonstrates the recommended practice of loading configuration at the very beginning of the application's lifecycle. Avoid loading configuration within frequently called functions (hot paths) to prevent performance bottlenecks.

```typescript
// Good: Load configuration at application startup
async function main() {
  const config = await getConfiguration();
  // Initialize components with configuration
}
```

```typescript
// Avoid: Loading configuration in hot paths
async function handleRequest() {
  const config = await getConfiguration(); // Cache hit, but still async
  // Handle request
}
```

--------------------------------

### Replace Regex-Based Metadata Extraction with Frontmatter Parsing

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/TECH_DEBT.md

Replace brittle regex parsing for metadata extraction with a professional frontmatter parsing library for better error handling and adherence to industry standards. This example shows the target setup using `remark-frontmatter`.

```typescript
// Current (25 lines):
const keyValuePattern = /\*?\*?([A-Za-z\s_]+)\*?\*?:\s*(.+)/g;
// Manual regex matching and sanitization
```

```typescript
// Target (5 lines):
import remarkFrontmatter from 'remark-frontmatter';
// Automatic YAML/structured data parsing
```

--------------------------------

### Run Pre-publish Build Step

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/CLAUDE.md

Execute the build steps required before publishing the package. This includes compilation and other necessary preparations.

```bash
npm run prepare
```

--------------------------------

### Programmatic Storage Configuration and Initialization

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/STORAGE.md

Shows how to programmatically create a custom storage configuration and initialize a filter storage instance.

```typescript
import { createStorageConfig, createFilterStorage } from '@democratize-technology/vikunja-mcp/storage';

// Create custom configuration
const config = createStorageConfig({
  type: 'sqlite',
  databasePath: '/custom/path/filters.db',
  timeout: 10000,
  debug: true,
});

// Create storage instance
const storage = await createFilterStorage('session-id', 'user-id', 'api-url');
```

--------------------------------

### Create SQLite backup using cp command

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/STORAGE.md

Create a backup of the SQLite database file by copying it to a specified backup location.

```bash
cp /path/to/filters.db /path/to/backup/filters.db.backup
```

--------------------------------

### Initialize Application Configuration

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/CONFIGURATION.md

Load and validate application configuration at startup. Ensures essential settings like authentication details are available before proceeding.

```typescript
import { ConfigurationManager, getConfiguration } from './config';

async function initializeApplication() {
  try {
    // Load and validate configuration early
    const config = await getConfiguration();
    
    // Use validated configuration
    if (config.auth.vikunjaUrl && config.auth.vikunjaToken) {
      await connectToVikunja(config.auth.vikunjaUrl, config.auth.vikunjaToken);
    }
    
    // Configure components
    const logger = await createLogger(config.logging);
    const rateLimiter = await createRateLimiter(config.rateLimiting);
    
  } catch (error) {
    console.error('Configuration error:', error);
    process.exit(1);
  }
}
```

--------------------------------

### Create a Project with vikunja_projects

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/MCP-TEST-CHECKLIST.md

Creates a new project with a specified title. Verify that the newly created project appears in the project list.

```bash
Use vikunja_projects create with title "Test Project"
```

--------------------------------

### Vikunja Task Filtering Issue

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/VIKUNJA_API_ISSUES.md

These examples demonstrate that the 'filter' parameter in the /tasks/all endpoint does not correctly filter tasks. All examples return all tasks regardless of the filter criteria. Verified on Vikunja v0.22.1.

```bash
curl -X GET 'https://your-vikunja-instance.com/api/v1/tasks/all?filter=done%20%3D%20false' \
  -H 'Authorization: Bearer VALID_TOKEN'
```

```bash
curl -X GET 'https://your-vikunja-instance.com/api/v1/tasks/all?filter=priority%20%3E%3D%204' \
  -H 'Authorization: Bearer VALID_TOKEN'
```

```bash
curl -X GET 'https://your-vikunja-instance.com/api/v1/tasks/all?filter=(done%20%3D%20false%20%26%26%20priority%20%3E%3D%203)' \
  -H 'Authorization: Bearer VALID_TOKEN'
```

--------------------------------

### Get Task

Source: https://context7.com/democratize-technology/vikunja-mcp/llms.txt

Retrieves the details of a specific task by its ID.

```APIDOC
## Get Task

### Description
Retrieves the details of a specific task.

### Method
`vikunja_tasks`

### Parameters
#### Options
- **subcommand** (string) - Required - Must be "get".
- **id** (integer) - Required - The ID of the task to retrieve.
```

--------------------------------

### Performance Monitoring Metrics

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/MIGRATION_GUIDE.md

Illustrates typical performance monitoring metrics, showing reductions in memory usage, response times, and error rates after upgrading.

```bash
# Memory usage reduced
RSS: 45MB → 18MB (60% reduction)

# Response times improved
Average response: 120ms → 75ms (37% improvement)

# Error rates reduced
API errors: 2.1% → 0.8% (62% reduction)
```

--------------------------------

### Get Specific Project

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Retrieve details for a single project by its ID.

```typescript
// Get a specific project
vikunja_projects.get({ id: 1 })
```

--------------------------------

### Production Deployment Settings

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/RATE_LIMITING.md

Recommended environment variables for configuring rate limiting, size limits, and timeouts in a production environment. Includes settings for high-traffic scenarios.

```bash
# Recommended production settings
RATE_LIMIT_PER_MINUTE=30
RATE_LIMIT_PER_HOUR=500
MAX_REQUEST_SIZE=524288        # 512KB
MAX_RESPONSE_SIZE=5242880      # 5MB
TOOL_TIMEOUT=15000             # 15 seconds

# For high-traffic scenarios
EXPENSIVE_RATE_LIMIT_PER_MINUTE=5
BULK_RATE_LIMIT_PER_MINUTE=2
EXPORT_RATE_LIMIT_PER_MINUTE=1
```

--------------------------------

### Ensure directory exists and is writable

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/STORAGE.md

Create the necessary directory for storing database files and set appropriate permissions to ensure the application can write to it.

```bash
mkdir -p ~/.local/share/vikunja-mcp
chmod 755 ~/.local/share/vikunja-mcp
```

--------------------------------

### Get Task Relations

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Retrieves all relationships associated with a specific task.

```APIDOC
## Get Task Relations

### Description
Retrieves all relationships associated with a specific task.

### Method
`vikunja_tasks.relations(options)`

### Parameters
#### Options
- **id** (number) - Required - The ID of the task.

### Request Example
```typescript
// Get all relations for a task
vikunja_tasks.relations({ id: 123 })
```
```

--------------------------------

### Get All Relations for a Task

Source: https://context7.com/democratize-technology/vikunja-mcp/llms.txt

Retrieve a list of all relationships associated with a specific task, identified by its ID.

```typescript
// Get all relations for a task
vikunja_tasks({ subcommand: "relations", id: 100 })
```

--------------------------------

### Create SQLite backup using sqlite3 command

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/STORAGE.md

Utilize the sqlite3 command-line tool to create a backup of the SQLite database.

```bash
sqlite3 /path/to/filters.db ".backup /path/to/backup/filters.db.backup"
```

--------------------------------

### Get Task Details

Source: https://context7.com/democratize-technology/vikunja-mcp/llms.txt

Retrieve the full details of a specific task using its unique ID.

```typescript
// Get task details
vikunja_tasks({ subcommand: "get", id: 123 })
```

--------------------------------

### List Tasks in a Project with vikunja_task_crud

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/MCP-TEST-CHECKLIST.md

Creates multiple tasks and then lists all tasks within the project. Verify that all created tasks appear in the returned list.

```bash
Create 3 tasks, then use vikunja_task_crud to list tasks in the project
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Enable debug logging to get more detailed output from the application. Defaults to false.

```bash
DEBUG=true
```

--------------------------------

### Initialize and Run Schema Migrations

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/STORAGE.md

Initializes the MigrationRunner and performs automatic schema migrations to the latest version. Requires a database instance.

```typescript
import { MigrationRunner } from '@democratize-technology/vikunja-mcp/storage';

const migrationRunner = new MigrationRunner(database);

// Check current version
const currentVersion = migrationRunner.getCurrentVersion();

// Migrate to latest
await migrationRunner.migrateToLatest();

// Get migration status
const status = migrationRunner.getStatus();
console.log(`Current: ${status.currentVersion}, Latest: ${status.latestVersion}`);
```

--------------------------------

### Get User Settings with Vikunja MCP

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Fetch the current user's settings using `vikunja_users.settings()`.

```typescript
// Get current user settings
vikunja_users.settings()
```

--------------------------------

### Get Current User Info with Vikunja MCP

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Retrieve information about the currently authenticated user with `vikunja_users.current()`.

```typescript
// Get current user information
vikunja_users.current()
```

--------------------------------

### Get Specific Label with Vikunja MCP

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Retrieve a single label by its ID using `vikunja_labels.get({ id: 1 })`.

```typescript
// Get a specific label
vikunja_labels.get({ id: 1 })
```

--------------------------------

### Create a Task with vikunja_task_crud

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/MCP-TEST-CHECKLIST.md

Creates a task with a specified title, description, priority, and project. Verify that the response shows the task was created with the correct fields.

```bash
Use vikunja_task_crud to create a task with title "Test Task 1", description "Testing", priority high in the MCP-Test project
```

--------------------------------

### Error Response Example

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/MCP_VALIDATION_REPORT.md

Shows the JSON format for an erroneous operation, detailing the error code and message within the metadata.

```json
{
  "content": "❌ Error in task.create: Failed to create task\n\n**Error Code:** VALIDATION_ERROR\n\n",
  "metadata": {
    "timestamp": "2025-12-16T00:01:17.175Z",
    "success": false,
    "operation": "task.create",
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Failed to create task"
    }
  }
}
```

--------------------------------

### User Management

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Operations for managing user information and settings, including getting current user details and updating settings.

```APIDOC
### User Management Examples

> ⚠️ **Known Issue**: User endpoints may fail with authentication errors even when using valid tokens. This is a known Vikunja API issue. The MCP server will provide helpful error messages when this occurs. If you encounter this issue, please contact your Vikunja server administrator.

### Get current user information
```typescript
vikunja_users.current()
```

### Search for users
```typescript
vikunja_users.search({
  search: "john"
})
```

### Get current user settings
```typescript
vikunja_users.settings()
```

### Update user settings
```typescript
vikunja_users.update-settings({
  name: "John Doe",
  language: "en",
  timezone: "America/New_York",
  weekStart: 1  // Monday
})
```

### Update notification preferences
```typescript
vikunja_users.update-settings({
  emailRemindersEnabled: true,  // Enable email reminders for tasks
  overdueTasksRemindersEnabled: true,  // Enable daily overdue task emails
  overdueTasksRemindersTime: "09:00"  // Time to send overdue task summary
})
```
```

--------------------------------

### Create a Label with vikunja_labels

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/MCP-TEST-CHECKLIST.md

Creates a new label with a specified title and color. Verify that the label is created with the correct fields.

```bash
Use vikunja_labels create with title "test-label", color #22c55e
```

--------------------------------

### Sample Success Response Output

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/SIMPLERESPONSE_MIGRATION_TEST_REPORT.md

Illustrates the JSON structure for a successful operation, including content and metadata.

```json
{
  "content": "✅ task.create: Task created successfully\n\n**id:** 123\n**title:** Test Task\n\n",
  "metadata": {
    "timestamp": "2025-12-15T23:49:18.418Z",
    "success": true,
    "operation": "task.create"
  }
}
```

--------------------------------

### Get Vikunja User Settings

Source: https://context7.com/democratize-technology/vikunja-mcp/llms.txt

Retrieve the current user's settings, including language, timezone, and notification preferences.

```typescript
// Get current user settings
vikunja_users({ subcommand: "settings" })
```

--------------------------------

### vikunja_auth — Authentication Management

Source: https://context7.com/democratize-technology/vikunja-mcp/llms.txt

Manages the connection to a Vikunja instance. Supports `connect`, `status`, `refresh`, and `disconnect` subcommands. Token type is auto-detected: tokens starting with `tk_` are API tokens; tokens starting with `eyJ` with three dot-separated parts are JWT. JWT authentication unlocks additional tools (`vikunja_users`, `vikunja_export_project`). Can also be configured via environment variables `VIKUNJA_URL` and `VIKUNJA_API_TOKEN` for auto-connect at startup.

```APIDOC
## vikunja_auth — Authentication Management

### Description
Manages the connection to a Vikunja instance. Supports `connect`, `status`, `refresh`, and `disconnect` subcommands. Token type is auto-detected: tokens starting with `tk_` are API tokens; tokens starting with `eyJ` with three dot-separated parts are JWT. JWT authentication unlocks additional tools (`vikunja_users`, `vikunja_export_project`). Can also be configured via environment variables `VIKUNJA_URL` and `VIKUNJA_API_TOKEN` for auto-connect at startup.

### Subcommands

#### connect
Connects to a Vikunja instance.

##### Parameters
- **apiUrl** (string) - Required - The URL of the Vikunja API.
- **apiToken** (string) - Required - The API token or JWT for authentication.

##### Request Example
```typescript
vikunja_auth({
  subcommand: "connect",
  apiUrl: "https://vikunja.example.com/api/v1",
  apiToken: "tk_abc123def456"
})
```

#### status
Checks the current authentication status.

##### Parameters
- **subcommand** (string) - Required - Must be "status".

##### Request Example
```typescript
vikunja_auth({ subcommand: "status" })
```

#### disconnect
Disconnects from the Vikunja instance and clears the session.

##### Parameters
- **subcommand** (string) - Required - Must be "disconnect".

##### Request Example
```typescript
vikunja_auth({ subcommand: "disconnect" })
```

### Response Examples

#### Connect Success Response
```json
{
  "success": true,
  "operation": "auth-connect",
  "data": {
    "authenticated": true
  },
  "metadata": {
    "authType": "api-token"
  }
}
```

#### Status Success Response
```json
{
  "success": true,
  "data": {
    "authenticated": true,
    "apiUrl": "https://vikunja.example.com/api/v1",
    "authType": "api-token"
  }
}
```

### Environment Variable Configuration
Auto-connect at startup is possible by setting the following environment variables:
- `VIKUNJA_URL`: The URL of the Vikunja API.
- `VIKUNJA_API_TOKEN`: The API token or JWT for authentication.
```

--------------------------------

### Auto-connect using Environment Variables

Source: https://context7.com/democratize-technology/vikunja-mcp/llms.txt

Configure Vikunja connection details via environment variables for automatic connection on server startup. No manual `vikunja_auth` call is needed.

```bash
VIKUNJA_URL=https://vikunja.example.com/api/v1
VIKUNJA_API_TOKEN=tk_abc123
```

--------------------------------

### Running Tests with npm

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/tests/README.md

Provides commands for executing tests, including running all tests, generating coverage reports, using watch mode, and targeting specific test files.

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm test -- --watch

# Run specific test file
npm test tasks.test.ts
```

--------------------------------

### Rollback to Previous Version (Docker)

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/MIGRATION_GUIDE.md

Dockerfile snippet to install version 0.1.0 of the Vikunja MCP package within a Docker image.

```dockerfile
FROM node:20-alpine
RUN npm install -g @democratize-technology/vikunja-mcp@0.1.0
# ... rest of your configuration
```

--------------------------------

### Improved Error Message Example

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/MIGRATION_GUIDE.md

Shows the difference in error messages before and after v0.2.0, demonstrating enhanced detail for invalid filter syntax.

```text
Before (v0.1.x):
```
Error: Invalid filter syntax
```

After (v0.2.0):
```
Error: Field "priority" requires a numeric value, got "invalid"
Position: 15
Context: priority >= invalid
                          ^
```
```

--------------------------------

### Create a Child Project with vikunja_projects

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/MCP-TEST-CHECKLIST.md

Creates a new project that is a child of an existing project by setting the `parentProjectId`. Verify that the child project correctly references its parent.

```bash
Use vikunja_projects create with parentProjectId set to the project above
```

--------------------------------

### Complex Filter Parsing Example

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/MIGRATION_GUIDE.md

Demonstrates a complex filter string, illustrating the performance improvements in filter parsing between v0.1.x and v0.2.0.

```typescript
// Large complex filter (performance improvement)
const complexFilter = "(priority >= 3 && done = false) || (assignees in user1,user2,user3,user4,user5)";

// v0.1.x: ~50ms parsing time
// v0.2.0: ~30ms parsing time (40% improvement)
```

--------------------------------

### Test Configuration with Injection

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/CONFIGURATION.md

Demonstrates the recommended approach for testing components that rely on configuration. Instead of modifying global environment variables, inject a specific test configuration using `ConfigurationManager.getInstance`.

```typescript
// Good: Inject test configuration
const testManager = ConfigurationManager.getInstance({
  sources: { /* test configuration */ }
});
```

```typescript
// Avoid: Manipulating process.env in tests
process.env.RATE_LIMIT_PER_MINUTE = '30';
```

--------------------------------

### Get Specific Webhook with Vikunja MCP

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Retrieve details of a specific webhook using its project ID and webhook ID with `vikunja_webhooks.get()`.

```typescript
// Get a specific webhook
vikunja_webhooks.get({
  projectId: 1,
  webhookId: 123
})
```

--------------------------------

### Sample Array Formatting Output

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/SIMPLERESPONSE_MIGRATION_TEST_REPORT.md

Demonstrates how SimpleResponse formats lists of items, including a summary count and numbered entries.

```text
✅ task.list: Retrieved 5 tasks

**Results:** 5 item(s)

1. **Task 1** (ID: 1)
2. **Task 2** (ID: 2)
3. **Task 3** (ID: 3)
```

--------------------------------

### Create First Task

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Create your first task in Vikunja using the MCP. Requires a valid project ID and a task title.

```typescript
vikunja_tasks.create({
  projectId: 1,
  title: "My first task via MCP!"
})
```

--------------------------------

### Get Current Vikunja User

Source: https://context7.com/democratize-technology/vikunja-mcp/llms.txt

Retrieve information about the currently authenticated user. This is useful for personalizing the user interface or verifying permissions.

```typescript
// Get current authenticated user
vikunja_users({ subcommand: "current" })
```

--------------------------------

### Configure Vikunja Instance URL

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Set the base URL for your Vikunja instance. This is a required configuration.

```bash
VIKUNJA_URL=https://your-vikunja-instance.com/api/v1
```

--------------------------------

### Get Specific Vikunja Project Template

Source: https://context7.com/democratize-technology/vikunja-mcp/llms.txt

Retrieve details for a specific project template using its ID. This allows viewing the contents of a template.

```typescript
// Get a specific template
vikunja_templates({ subcommand: "get", id: "template_1234567890" })
```

--------------------------------

### Create Project

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Create a new project with a title, description, and optional color. Can also create child projects by specifying a `parentProjectId`.

```typescript
// Create a new project
vikunja_projects.create({
  title: "New Frontend Project",
  description: "React-based web application",
  hexColor: "#4287f5"
})
```

```typescript
// Create a child project
vikunja_projects.create({
  title: "Frontend Module",
  description: "React components",
  parentProjectId: 1,  // Will be a child of project 1
  hexColor: "#3498db"
})
```

--------------------------------

### Update User Settings with Vikunja MCP

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Modify user settings such as name, language, timezone, and week start day using `vikunja_users.update-settings()`.

```typescript
// Update user settings
vikunja_users.update-settings({
  name: "John Doe",
  language: "en",
  timezone: "America/New_York",
  weekStart: 1  // Monday
})
```

--------------------------------

### New Simplified Storage System File Structure

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/ARCHITECTURE_SIMPLIFICATION.md

Shows the drastically simplified file structure of the new storage system, consolidating functionality into a single implementation file.

```tree
src/storage/
├── index.ts           (12 lines - barrel export)
└── SimpleFilterStorage.ts (393 lines - complete implementation)
```

--------------------------------

### Defensive Code Example with Testability Requirement

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/CLAUDE.md

Illustrates a defensive programming pattern that must be testable. Ensure that scenarios where `error.message` is undefined are mocked in tests.

```typescript
// This defensive code MUST be testable
const message = error.message.toLowerCase() || '';
// Test MUST mock scenarios where error.message is undefined
```

--------------------------------

### Bulk Create Tasks with vikunja_task_bulk

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/MCP-TEST-CHECKLIST.md

Creates multiple tasks simultaneously using the bulk create functionality. Verify that all specified tasks are successfully created.

```bash
Use vikunja_task_bulk bulk-create to create 3 tasks
```

--------------------------------

### Instantiate Vikunja Project from Template

Source: https://context7.com/democratize-technology/vikunja-mcp/llms.txt

Create a new project from an existing template, applying variable substitution for dynamic content like project names and dates. Specify the parent project and any custom variables.

```typescript
// Instantiate a project from a template with variable substitution
vikunja_templates({
  subcommand: "instantiate",
  id: "template_1234567890",
  projectName: "{{PROJECT_NAME}} - {{TODAY}}",  // built-in variables
  parentProjectId: 1,
  variables: {
    PROJECT_NAME: "Q3 Sprint 1",
    OWNER: "alice"
  }
})
// Creates a new project with all tasks from the template
```

--------------------------------

### Verify storage configuration

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/docs/STORAGE.md

Check the environment variables related to storage configuration to confirm that the application is set up to use the intended storage backend.

```bash
env | grep VIKUNJA_MCP_STORAGE
```

--------------------------------

### Configure Vikunja API Token

Source: https://github.com/democratize-technology/vikunja-mcp/blob/main/README.md

Provide your Vikunja API token for authentication. This is a required configuration.

```bash
VIKUNJA_API_TOKEN=your-api-token
```