MCP 服务器

HacknPlan MCP Server

Enables AI assistants to manage game development projects, sprints, tasks, and design documents via the HacknPlan API.

README

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