# Checkvist MCP Server

MCP server for Checkvist API integration, enabling Claude to read and write to Checkvist checklists.

## Features

- Complete checklist CRUD operations (list, get, create, update, delete)
- Complete task management (create, update, close, reopen, delete, invalidate)
- Repeating task configuration
- Task assignment to users
- Import multiple tasks at once
- Complete notes/comments management (get, create, update, delete)
- User profile information
- Full support for Checkvist's smart syntax (^due dates, #tags, !priority)
- Helpful error messages with actionable tips

## Installation

```bash
npm install
npm run build
```

## Configuration

1. Get your Checkvist API key from your profile page: https://checkvist.com/auth/profile
2. Create a `.env` file:

```bash
cp .env.example .env
```

3. Edit `.env` and add your credentials:

```
CHECKVIST_USERNAME=your_email@example.com
CHECKVIST_API_KEY=your_api_key_here
```

## Claude Desktop Configuration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "checkvist": {
      "command": "node",
      "args": [
        "/Users/matsingerdal/Developer/GitHub/checkvist-mcp/dist/index.js"
      ]
    }
  }
}
```

## Available Tools

### Checklist Management
- `checkvist_list_checklists` - Get all checklists (read-only)
- `checkvist_get_checklist` - Get specific checklist info (read-only)
- `checkvist_create_checklist` - Create a new checklist
- `checkvist_update_checklist` - Update checklist name or visibility
- `checkvist_delete_checklist` - Delete checklist (marks for deletion)

### Task Management
- `checkvist_get_tasks` - Get all tasks as raw JSON (read-only)
- `checkvist_get_tasks_summary` - Get all tasks in readable text format (read-only)
- `checkvist_get_tasks_paginated` - Get tasks in pages to read entire large checklists (RECOMMENDED, read-only)
- `checkvist_get_task` - Get specific task with parent hierarchy as JSON (read-only)
- `checkvist_get_task_tree` - Get a specific task and ALL its subtasks in readable text (read-only)
- `checkvist_create_task` - Create a new task (supports assignee_ids)
- `checkvist_update_task` - Update existing task (supports assignee_ids)
- `checkvist_close_task` - Mark task as complete
- `checkvist_reopen_task` - Reopen completed task
- `checkvist_delete_task` - Delete task and children
- `checkvist_invalidate_task` - Mark task as invalidated (status=2)
- `checkvist_set_repeating_task` - Configure repeating task schedule
- `checkvist_import_tasks` - Import multiple tasks at once

### Notes/Comments
- `checkvist_get_notes` - Get all notes for a task (read-only)
- `checkvist_create_note` - Add a note to a task
- `checkvist_update_note` - Update existing note
- `checkvist_delete_note` - Delete a note

### User Information
- `checkvist_get_current_user` - Get authenticated user profile (read-only)

## Reading Large Checklists

For large checklists with many tasks, use the right approach based on checklist size:

### Strategy 1: Quick Preview (BEST for VERY large checklists) ⭐

**`checkvist_get_tasks_summary` with `preview: true`**
- Shows **ONLY top-level tasks** (no subtasks)
- Minimal data, perfect for huge checklists (1000+ tasks)
- Automatically uses compact mode
- Get quick overview, then drill down with get_task_tree
- Example:
  ```
  checkvist_get_tasks_summary(
    checklist_id: 941803,
    preview: true
  )
  ```
- Output:
  ```
  📋 Checklist Summary (5 top-level tasks, 847 total)
  ⚡ PREVIEW MODE: Showing only top-level tasks

  [ ] Main Project [12345]
  [ ] Archive [12350]
  [ ] Notes [12351]
  [ ] Resources [12352]
  [ ] Templates [12353]

  💡 TIP: Use checkvist_get_task_tree with a specific task ID to explore subtasks
  ```

### Strategy 2: See Full Structure (for medium/large checklists)

**`checkvist_get_tasks_summary` with `compact: true`**
- Shows **ENTIRE checklist** in ultra-compact format
- Only displays: status, title, and ID (no metadata, no notes)
- Works for hundreds of tasks
- Example:
  ```
  checkvist_get_tasks_summary(
    checklist_id: 941803,
    compact: true,
    max_depth: 2
  )
  ```

### Strategy 3: Explore Specific Branches

**`checkvist_get_task_tree`** (for detailed view of one branch)
- Get ONE specific task and ALL its subtasks with full details
- Shows metadata, notes, due dates, priorities, tags
- Perfect when you found interesting task in compact view
- Example: `checkvist_get_task_tree(checklist_id: 941803, task_id: 71218558)`

### Strategy 4: Full Details for Smaller Checklists

**`checkvist_get_tasks_summary` with `compact: false`** (default)
- Shows everything with full metadata and notes
- Only use for checklists with <50 tasks
- May be too large for bigger checklists

**`checkvist_get_tasks`**
- Returns raw JSON structure
- May be stored in files that are harder to read
- Use only when you need to process JSON programmatically

### Recommended Workflows

**Option 1: Read Everything in Pages** ⭐ (BEST for reading entire checklist)
```
1. checkvist_get_tasks_paginated(checklist_id: X, page: 1)
   → Shows first 3 top-level tasks with ALL their subtasks
2. checkvist_get_tasks_paginated(checklist_id: X, page: 2)
   → Shows next 3 top-level tasks with ALL their subtasks
3. Continue until you've read all pages
```
Claude can read ALL tasks this way without hitting size limits!

**Option 2: Preview + Drill Down** (faster for finding specific info)
```
1. checkvist_get_tasks_summary(checklist_id: X, preview: true)
   → See all top-level tasks (just 5-10 items)
2. Find interesting task in the preview
3. checkvist_get_task_tree(checklist_id: X, task_id: Y)
   → Get all details for that specific branch
```

## Smart Syntax Support

Checkvist supports smart syntax in task content:

- `^tomorrow` - Set due date
- `#tag` - Add tag
- `!3` - Set priority (0-9)
- `@username` - Assign to user

Enable parsing with `parse_tasks: true` or `parse: true` parameters.

## Development

```bash
# Watch mode
npm run dev

# Build
npm run build

# Start
npm start
```

## API Documentation

Full Checkvist API docs: https://checkvist.com/auth/api