HacknPlan MCP Server

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): ``bash 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