HacknPlan MCP Server
by Lint111
README.md
# HacknPlan MCP Server
[](https://www.typescriptlang.org/)
[](https://github.com/yourusername/hacknplan-mcp)
[](LICENSE)
A Model Context Protocol (MCP) server that provides a **pure API wrapper** for the [HacknPlan](https://hacknplan.com) 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 →](docs/INDEX.md)
---
## 🚀 Quick Start
### 1. Install
```bash
git clone https://github.com/yourusername/hacknplan-mcp.git
cd hacknplan-mcp
npm install
npm run build
```
**[→ Full Installation Guide](docs/getting-started/installation.md)**
---
### 2. Configure
```bash
claude mcp add hacknplan -s user \
-e HACKNPLAN_API_KEY=your-api-key \
-- node /path/to/hacknplan-mcp/dist/index.js
```
**[→ Configuration Guide](docs/getting-started/configuration.md)**
---
### 3. Use
```javascript
// 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](docs/getting-started/quick-start.md)**
---
## 📚 Documentation
**[→ Complete Documentation Index](docs/INDEX.md)**
### Essential Guides
| Guide | Description |
|-------|-------------|
| **[Quick Start](docs/getting-started/quick-start.md)** | Your first API calls (5 min) |
| **[Work Items](docs/core-api/work-items.md)** | Task management reference |
| **[Time Tracking](docs/features/time-tracking.md)** | Automatic time logging |
| **[Deletion Safety](docs/features/deletion-safety.md)** | Recovery system |
| **[Common Patterns](docs/reference/common-patterns.md)** | Real-world recipes |
### By Experience Level
**Beginner:**
[Installation](docs/getting-started/installation.md) →
[Configuration](docs/getting-started/configuration.md) →
[Quick Start](docs/getting-started/quick-start.md) →
[Work Items](docs/core-api/work-items.md)
**Intermediate:**
[Time Tracking](docs/features/time-tracking.md) →
[Workflow Shortcuts](docs/advanced/workflow-shortcuts.md) →
[Batch Operations](docs/advanced/batch-operations.md)
**Advanced:**
[Slim Mode](docs/features/slim-mode.md) →
[Tool Search](docs/features/tool-search.md) →
[Caching](docs/advanced/caching.md) →
[Best Practices](docs/reference/best-practices.md)
---
## 🎯 Use Cases
### Sprint Planning
```javascript
// 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](docs/reference/common-patterns.md#sprint-management)**
---
### Automatic Time Tracking
```javascript
// 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](docs/features/time-tracking.md)**
---
### Batch Operations
```javascript
// 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](docs/features/array-api.md)**
---
## 🛡️ Safety Features
### Deletion Recovery (v7.2.0)
All deletions automatically stored in recovery cache for 30 days:
```javascript
// 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](docs/features/deletion-safety.md)**
---
## ⚡ 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](docs/features/tool-search.md)**
**Smart Caching** (80% fewer API calls):
- Automatic 5-minute cache on all GET requests
- **[→ Caching Guide](docs/advanced/caching.md)**
---
## 📖 Complete Documentation
**[→ Documentation Index (docs/INDEX.md)](docs/INDEX.md)**
### Core API
- [Projects](docs/core-api/projects.md) - Project management
- [Boards & Sprints](docs/core-api/boards.md) - Sprint planning
- [Work Items](docs/core-api/work-items.md) - Tasks, bugs, features
- [Comments](docs/core-api/comments.md) - Markdown comments
- [Milestones](docs/core-api/milestones.md) - Major deliverables
- [Design Elements](docs/core-api/design-elements.md) - Game design docs
### Features
- [Deletion Safety](docs/features/deletion-safety.md) - Recovery system
- [Automatic Time Tracking](docs/features/time-tracking.md) - Zero-effort logging
- [Slim Mode](docs/features/slim-mode.md) - Context optimization
- [Array-Based API](docs/features/array-api.md) - Batch operations
- [Tool Search](docs/features/tool-search.md) - Dynamic tool discovery
### Advanced
- [Workflow Shortcuts](docs/advanced/workflow-shortcuts.md) - Combined operations
- [Batch Operations](docs/advanced/batch-operations.md) - Search & analytics
- [Metadata & Config](docs/advanced/metadata-config.md) - Stages, tags, users
- [Caching](docs/advanced/caching.md) - Performance optimization
### Reference
- [Common Patterns](docs/reference/common-patterns.md) - Real-world recipes
- [Error Handling](docs/reference/error-handling.md) - Error types & recovery
- [Best Practices](docs/reference/best-practices.md) - Optimization tips
---
## 🔧 Configuration
### Environment Variables
```bash
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](docs/getting-started/configuration.md)**
---
## 🤝 Contributing
Contributions welcome! Please see:
- **Issues:** [GitHub Issues](https://github.com/yourusername/hacknplan-mcp/issues)
- **Pull Requests:** Follow standard GitHub PR workflow
- **Documentation:** Help improve [docs/](docs/)
---
## 📄 License
MIT License - See [LICENSE](LICENSE) for details
---
## 🔗 Links
- **Documentation:** [docs/INDEX.md](docs/INDEX.md)
- **API Reference:** [API-REFERENCE.md](API-REFERENCE.md) (Complete technical reference)
- **Claude.ai Guide:** [CLAUDE.md](CLAUDE.md) (AI assistant integration)
- **HacknPlan API:** [Official Docs](https://app.hacknplan.com/api/v0/docs)
- **GitHub:** [yourusername/hacknplan-mcp](https://github.com/yourusername/hacknplan-mcp)
---
## 🆘 Support
**Need help?**
1. **[Quick Start Guide](docs/getting-started/quick-start.md)** - Get running in 5 minutes
2. **[Common Patterns](docs/reference/common-patterns.md)** - Real-world recipes
3. **[Error Handling](docs/reference/error-handling.md)** - Troubleshooting guide
4. **[GitHub Issues](https://github.com/yourusername/hacknplan-mcp/issues)** - Report bugs or request features
---
**Version:** 7.2.0 | **Last Updated:** December 21, 2025
TDQS
B3.3/5.0
Scored across 91 tools
Disambiguation3/5
Many tools have clearly distinct purposes, but there are overlapping pairs like get_my_current_tasks vs get_my_tasks, and multiple create work item tools (create_work_items, create_work_item_atomic, create_subtask, create_from_template) which may confuse an agent. The deletion workflow also has several steps (batch_delete_work_items, confirm_deletion, cancel_deletion) that could be grouped.
Naming Consistency4/5
Naming largely follows a verb_noun pattern with underscores (e.g., create_work_items, list_projects). Minor inconsistencies include mixed verb prefixes (add_comments vs create_comments) and compound names like get_active_sprint_overview, but overall the pattern is predictable.
Tool Count2/5
With 91 tools, the server is extremely heavy. Typical MCP servers have 3-15 tools; this is far beyond and likely to overwhelm agents. Many tools could be consolidated (e.g., batch operations combined with single-item calls).
Completeness5/5
The tool set covers nearly every aspect of the domain: full CRUD for work items, boards, milestones, projects, design elements, comments, attachments, dependencies, time tracking, user info, cache management, and even administrative controls like setting default project. No obvious gaps are apparent.
Maintenance
ActivityInactive
ResponsivenessNo issues