quick-start.md

Quick Start Guide

← Back to Index | ← Configuration

---

Get up and running with HacknPlan MCP in 5 minutes.

Prerequisites

• ✅ Server installed
• ✅ Configuration complete
• ✅ API key set in environment

---

Environment Setup

# Set your HacknPlan API key (required)
export HACKNPLAN_API_KEY="your-api-key-here"

# Optional: Set default project to avoid passing projectId in every call
export HACKNPLAN_DEFAULT_PROJECT="230954"

# Optional: Configure deletion cache size (default: 1000)
export HACKNPLAN_DELETION_CACHE_SIZE="1000"

Windows (PowerShell):

$env:HACKNPLAN_API_KEY="your-api-key-here"
$env:HACKNPLAN_DEFAULT_PROJECT="230954"

---

Your First API Calls

1. List All Projects

const projects = await callTool('list_projects', {});

// Response:
{
  items: [
    { projectId: 230954, name: "My Game Project", ... },
    { projectId: 230955, name: "Prototype", ... }
  ],
  total: 2,
  offset: 0,
  limit: 50,
  hasMore: false
}

2. Get Work Items for a Sprint

const workItems = await callTool('list_work_items', {
  projectId: 230954,
  boardId: 650299  // Optional: filter by sprint/board
});

// Response: Array of work items with details

3. Create a New Task

const newTask = await callTool('create_work_items', {
  projectId: 230954,
  items: [{
    title: 'Implement user authentication',
    categoryId: 'programming',  // Supports name resolution!
    estimatedCost: 8,
    boardId: 650299,
    tagIds: ['backend', 'security']  // Tag names auto-resolved
  }]
});

// Response: { items: [...], created: 1, failed: 0 }

---

Common Workflows

Workflow 1: Start Working on a Task

// 1. Find your tasks
const myTasks = await callTool('get_my_current_tasks', {
  projectId: 230954
});

// 2. Start a task (auto-starts time tracking)
await callTool('start_task', {
  workItemId: 12345,
  comment: "Starting backend implementation"
});

// 3. Work on the task...

// 4. Complete the task (auto-logs elapsed time)
await callTool('complete_task', {
  workItemId: 12345,
  comment: "Authentication flow complete, tests passing"
});

Time tracking is automatic! See Automatic Time Tracking Guide.

Workflow 2: Batch Create Subtasks

// Create multiple related tasks at once
await callTool('create_work_items', {
  projectId: 230954,
  items: [
    {
      title: 'Design authentication schema',
      categoryId: 'design',
      estimatedCost: 3,
      boardId: 650299
    },
    {
      title: 'Implement login endpoint',
      categoryId: 'programming',
      estimatedCost: 5,
      boardId: 650299
    },
    {
      title: 'Write authentication tests',
      categoryId: 'programming',
      estimatedCost: 4,
      boardId: 650299
    }
  ]
});

See Array-Based API Guide for batch operations.

Workflow 3: Search and Filter Tasks

// Find all high-priority backend tasks
const urgentTasks = await callTool('search_work_items', {
  projectId: 230954,
  importanceLevels: ['urgent', 'high'],  // Name resolution
  tags: ['backend'],
  isCompleted: false
});

---

Name Resolution Magic

The MCP supports string names instead of numeric IDs for:

Categories

categoryId: 'programming'  // Instead of categoryId: 1
// Supported: 'programming', 'design', 'writing', 'ideas', 'bug'

Importance Levels

importanceLevelId: 'high'  // Instead of importanceLevelId: 2
// Supported: 'urgent', 'high', 'normal', 'low'

Tags

tagIds: ['backend', 'security', 'urgent']  // Instead of [1, 5, 8]
// Auto-creates tags if they don't exist (when updating work items)

---

Error Handling

Invalid Project ID

// ❌ Wrong project ID
await callTool('list_work_items', { projectId: 99999 });

// ✅ Server response includes helpful suggestions:
{
  error: "Project not found: 99999",
  availableProjects: [
    { projectId: 230954, name: "My Game Project" },
    { projectId: 230955, name: "Prototype" }
  ],
  suggestion: "Use one of these project IDs or set HACKNPLAN_DEFAULT_PROJECT"
}

Missing Required Fields

// ❌ Missing required fields
await callTool('create_work_items', {
  items: [{ title: 'New task' }]  // Missing categoryId
});

// ✅ Validation error with details:
{
  error: "Validation failed for item 0: categoryId is required"
}

---

Next Steps

Core Features

• Work Items Guide - Complete CRUD operations
• Project Management - Managing projects and configuration
• Boards & Sprints - Sprint planning and management

Advanced Features

• Automatic Time Tracking - Zero-effort time logging
• Deletion Safety - Recovery and confirmation system
• Slim Mode - Optimize context usage (71% reduction)
• Batch Operations - Efficient multi-item updates

Reference

• Common Patterns - Recipes for common tasks
• Error Handling - Dealing with errors
• Best Practices - Tips and recommendations

---

See Also:

• Full API Reference - All available tools
• Usage Examples - Real-world examples
• Troubleshooting - Common issues and solutions