HacknPlan MCP Server

A Model Context Protocol (MCP) server that provides a pure API wrapper for the HacknPlan project management API. Enables AI assistants like Claude to manage game development projects, sprints, tasks, and design documents.

---

✨ Key Features

• 🛡️ Deletion Recovery - 30-day recovery cache with crash resilience (v7.2.0)
• ⏱️ Automatic Time Tracking - Zero-effort time logging (v7.1.0+)
• 🚀 Context Optimization - 75-85% token reduction with slim mode + tool search
• 📦 Batch Operations - Update 1-100 items in a single call
• 🔍 Advanced Search - Multi-criteria filtering with name resolution
• 💾 Smart Caching - 80% fewer API calls with automatic 5-minute cache

Full feature list: Documentation →

---

🚀 Quick Start

1. Install

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

→ Full Installation Guide

---

2. Configure

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

→ Configuration Guide

---

3. Use

// 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'
});

→ Quick Start Guide

---

📚 Documentation

→ Complete Documentation Index

Essential Guides

Guide	Description
Quick Start	Your first API calls (5 min)
Work Items	Task management reference
Time Tracking	Automatic time logging
Deletion Safety	Recovery system
Common Patterns	Real-world recipes

By Experience Level

Beginner: Installation → Configuration → Quick Start → Work Items

Intermediate: Time Tracking → Workflow Shortcuts → Batch Operations

Advanced: Slim Mode → Tool Search → Caching → Best Practices

---

🎯 Use Cases

Sprint Planning

// 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
  }))
});

→ More Sprint Patterns

---

Automatic Time Tracking

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

→ Time Tracking Guide

---

Batch Operations

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

→ Array-Based API Guide

---

🛡️ Safety Features

Deletion Recovery (v7.2.0)

All deletions automatically stored in recovery cache for 30 days:

// 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] });

→ Deletion Safety Guide

---

⚡ Performance

Context Optimization

Slim Mode (75% token reduction):

HACKNPLAN_SLIM_MODE=true
HACKNPLAN_OUTPUT_VERBOSITY=slim

Tool Search (85% reduction on tool loading):

• Loads only 8 core tools initially
• Discovers 88 additional tools on-demand
• → Tool Search Guide

Smart Caching (80% fewer API calls):

• Automatic 5-minute cache on all GET requests
• → Caching Guide

---

📖 Complete Documentation

→ Documentation Index (docs/INDEX.md)

Core API

• Projects - Project management
• Boards & Sprints - Sprint planning
• Work Items - Tasks, bugs, features
• Comments - Markdown comments
• Milestones - Major deliverables
• Design Elements - Game design docs

Features

• Deletion Safety - Recovery system
• Automatic Time Tracking - Zero-effort logging
• Slim Mode - Context optimization
• Array-Based API - Batch operations
• Tool Search - Dynamic tool discovery

Advanced

• Workflow Shortcuts - Combined operations
• Batch Operations - Search & analytics
• Metadata & Config - Stages, tags, users
• Caching - Performance optimization

Reference

• Common Patterns - Real-world recipes
• Error Handling - Error types & recovery
• Best Practices - Optimization tips

---

🔧 Configuration

Environment Variables

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

→ Complete Configuration Guide

---

🤝 Contributing

Contributions welcome! Please see:

• Issues: GitHub Issues
• Pull Requests: Follow standard GitHub PR workflow
• Documentation: Help improve docs/

---

📄 License

MIT License - See LICENSE for details

---

🔗 Links

• Documentation: docs/INDEX.md
• API Reference: API-REFERENCE.md (Complete technical reference)
• Claude.ai Guide: CLAUDE.md (AI assistant integration)
• HacknPlan API: Official Docs
• GitHub: yourusername/hacknplan-mcp

---

🆘 Support

Need help?

1. Quick Start Guide - Get running in 5 minutes
2. Common Patterns - Real-world recipes
3. Error Handling - Troubleshooting guide
4. GitHub Issues - Report bugs or request features

---

Version: 7.2.0 | Last Updated: December 21, 2025