git clone https://github.com/yourusername/hacknplan-mcp.git
cd hacknplan-mcp
npm install
npm run build

claude mcp add hacknplan -s user \
  -e HACKNPLAN_API_KEY=your-api-key \
  -- node /path/to/hacknplan-mcp/dist/index.js

// Create a task
await callTool('create_work_items', {
  items: [{
    title: 'Implement OAuth',
    categoryId: 'programming',    // Name resolution
    importanceLevelId: 'high',   // Name resolution
    tagIds: ['backend', 'security']  // Auto-creates tags
  }]
});

// Start working (automatic time tracking)
await callTool('start_task', { workItemId: 123 });

// Complete (auto-logs hours)
await callTool('complete_task', {
  workItemId: 123,
  comment: 'OAuth implementation complete'
});

// Create sprint
const sprint = await callTool('create_boards', {
  boards: [{
    name: 'Sprint 4: Authentication',
    startDate: '2026-01-01T00:00:00Z',
    endDate: '2026-01-14T23:59:59Z'
  }]
});

// Get backlog and assign to sprint
const backlog = await callTool('get_backlog', {});
await callTool('update_work_items', {
  items: backlog.items.slice(0, 10).map(item => ({
    workItemId: item.workItemId,
    boardId: sprint.items[0].boardId
  }))
});

// Start task (begins tracking)
await callTool('start_task', { workItemId: 123 });

// ... work for 2.5 hours ...

// Complete (auto-logs 2.5h)
await callTool('complete_task', {
  workItemId: 123,
  comment: 'Feature complete, tests passing'
});
// ✅ Automatically logged 2.5 hours

// Create multiple tasks at once
await callTool('create_work_items', {
  items: [
    { title: 'Design API', categoryId: 'design', estimatedCost: 4 },
    { title: 'Implement endpoints', categoryId: 'programming', estimatedCost: 8 },
    { title: 'Write tests', categoryId: 'programming', estimatedCost: 6 }
  ]
});
// ✅ 3 tasks created in 1 API call

// Delete with automatic recovery
await callTool('delete_work_items', { workItemIds: [123, 124, 125] });

// Later, recover if needed (up to 30 days)
await callTool('recover_deleted_items', { workItemIds: [123, 124, 125] });

HACKNPLAN_SLIM_MODE=true
HACKNPLAN_OUTPUT_VERBOSITY=slim

HACKNPLAN_API_KEY=your-key              # Required: API authentication
HACKNPLAN_DEFAULT_PROJECT=230954        # Optional: Default project ID
HACKNPLAN_SLIM_MODE=true                # Optional: Enable 26-tool slim mode
HACKNPLAN_OUTPUT_VERBOSITY=slim         # Optional: Minimal response fields
HACKNPLAN_DELETION_CACHE_SIZE=1000      # Optional: Recovery cache capacity