hacknplan-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

HacknPlan MCP Server - A Model Context Protocol server providing a pure API wrapper for the HacknPlan project management API. Enables AI assistants to manage game development projects, sprints, tasks, and design documents.

Version: 7.2.0 Language: 100% TypeScript (ESM modules) Runtime: Node.js 18+

Build & Development Commands

npm install          # Install dependencies
npm run build        # Compile TypeScript to dist/
npm run watch        # Auto-rebuild on changes
npm run dev          # Development mode with tsx (hot reload)
npm test             # Build and run all tests
npm run clean        # Remove dist/ directory

Testing

Tests use Node.js built-in test runner. Run npm test which builds first then executes:

• dist/index.test.js - Unit tests (cache, transactions, search, batching)
• dist/tool-integration.test.js - Integration tests for tool workflows

Additional integration tests are available in tests/integration/:

• Test files: test-*.js (deletion, name resolution, workflow shortcuts, etc.)
• Test fixtures: tests/fixtures/ (sample data files)
• Test scripts: tests/scripts/ (setup and runner scripts)

Running the Server

# Direct execution (requires HACKNPLAN_API_KEY env var)
HACKNPLAN_API_KEY=your-key node dist/index.js

# With Claude Code
claude mcp add hacknplan -s user -e HACKNPLAN_API_KEY=key -- node /path/to/dist/index.js

Architecture

Module Organization

src/
├── index.ts              # MCP server entry point, HTTP client, main server setup
├── api/                  # API-layer utilities
│   ├── metadata.ts       # Project metadata caching (stages, categories, tags)
│   ├── search.ts         # Multi-criteria work item search
│   └── templates.ts      # Work item templates (bug-report, feature, research)
├── core/                 # Infrastructure
│   ├── cache.ts          # LRU cache with TTL support
│   ├── client.ts         # HTTP client helpers (used by some modules)
│   └── transaction.ts    # Atomic operations with rollback
├── cache/                # Specialized caches
│   ├── staging-cache.ts      # 2-step deletion confirmation staging
│   ├── recovery-cache.ts     # Persistent LRU cache for deleted item recovery
│   └── time-tracking-cache.ts # Automatic work session time tracking
├── tools/                # MCP tool implementations (one file per domain)
│   ├── registry.ts       # Tool registration system with duplicate detection
│   ├── types.ts          # ToolDefinition, ToolContext, ToolRegistry types
│   ├── projects.ts       # Project CRUD + metrics
│   ├── boards.ts         # Sprint/board management
│   ├── work-items.ts     # Tasks/bugs/features CRUD
│   ├── deletion-confirmation.ts  # Batch delete staging/confirmation
│   ├── deletion-recovery.ts      # Recovery cache management tools
│   ├── advanced.ts       # Slim variants, batch ops, summaries
│   └── ...               # Other domain tools
├── types/                # Type definitions
│   ├── hacknplan.ts      # HacknPlan API types
│   ├── deletion.ts       # Deletion staging types
│   └── recovery.ts       # Recovery cache types
└── utils/                # Shared utilities
    ├── batch.ts          # Generic batch operation wrapper
    ├── pagination.ts     # Pagination helpers
    ├── resolution.ts     # ID/name resolution (tag names → IDs)
    ├── validation.ts     # Input validation
    └── errors.ts         # Error handling utilities