radiumce/checklist-mcp-server

Checklist MCP Server

A Model Context Protocol (MCP) server for hierarchical checklist management with session-based task organization and tree visualization, supporting HTTP streamable transport.

Overview

The Checklist MCP Server provides a robust solution for managing hierarchical task lists through the Model Context Protocol. It enables AI assistants and other MCP clients to create, update, and track tasks in a structured, tree-like format with support for multiple concurrent sessions. The server supports both HTTP streamable transport (recommended) and stdio transport (legacy). It can significantly enhance the agent's ability to adhere to the task plan during task execution.

🚀 Quick Start

Get started in seconds with npx (no installation required):

# Start the server (HTTP mode, port 8585)
npx checklist-mcp-server

# The server will show:
# Starting Checklist MCP Server in HTTP mode...
# HTTP server will run on port 8585
# MCP endpoint: http://localhost:8585/mcp
# Checklist MCP HTTP server running on port 8585

Installation Options

# Option 1: Use with npx (recommended, no installation)
npx checklist-mcp-server

# Option 2: Install globally
npm install -g checklist-mcp-server
checklist-mcp-server

# Option 3: Install locally in project
npm install checklist-mcp-server
npx checklist-mcp-server

Then configure your MCP client:

{
  "mcpServers": {
    "checklist": {
      "transport": "http",
      "url": "http://localhost:8585/mcp"
    }
  }
}

That's it! No installation required. 🎉

📖 See for more detailed examples and integration guides.

Features

• HTTP Streamable Transport: Modern HTTP-based communication for better performance and scalability
• Hierarchical Task Management: Create nested task structures with unlimited depth
• Session-Based Isolation: Multiple independent task lists per session
• Visual Tree Display: ASCII tree visualization with status indicators (✓ for DONE, ○ for TODO)
• Path-Based Operations: Update tasks at specific hierarchy levels using path notation
• Flexible Task IDs: Support for alphanumeric characters and common symbols (1-20 characters)
• Comprehensive Validation: Input validation with detailed error messages
• Real-time Updates: Immediate task status changes with full hierarchy display
• Work Information Management: LRU cache-based system for storing and sharing work summaries between agents
• Session Association: Link work information with task sessions to capture task state snapshots
• Agent Handoffs: Enable seamless work context transfer between LLM agents
• Memory Management: Automatic LRU-based session cleanup to prevent memory growth in long-running deployments

⚠️ Important: Transport Protocol Change

This version no longer supports stdio transport. The server has been migrated to use HTTP streamable transport exclusively for improved performance and better integration with modern MCP clients.

Migration from stdio to HTTP

If you were previously using stdio configuration:

// ❌ Old stdio configuration (no longer supported)
{
  "mcpServers": {
    "checklist": {
      "command": "npx",
      "args": ["checklist-mcp-server"],
      "env": {}
    }
  }
}

Update to HTTP configuration:

// ✅ New HTTP configuration
{
  "mcpServers": {
    "checklist": {
      "transport": "http",
      "url": "http://localhost:8585/mcp"
    }
  }
}

Installation and Setup

Quick Start with npx (Recommended)

The easiest way to use the server is with npx - no installation required:

# Start HTTP server (recommended, default port 8585)
npx checklist-mcp-server

# Start HTTP server on custom port
npx checklist-mcp-server --port 3000

# Start stdio server (legacy mode)
npx checklist-mcp-server stdio

# Show help
npx checklist-mcp-server --help

Installation

For frequent use, you can install globally:

npm install -g checklist-mcp-server

# Then run directly
checklist-mcp-server
checklist-mcp-server --port 3000
checklist-mcp-server stdio

Alternative Running Methods

# Using specific binaries
npx checklist-mcp-server-http        # HTTP server only
npx checklist-mcp-server-stdio       # stdio server only

# Using npm scripts (for development)
npm run start:http                   # HTTP server
npm run start                        # stdio server

MCP Configuration

HTTP Transport (Recommended)

Configure your MCP client to connect to the HTTP server:

{
  "mcpServers": {
    "checklist": {
      "transport": "http",
      "url": "http://localhost:8585/mcp"
    }
  }
}

Start the server with: npx checklist-mcp-server

Stdio Transport (Legacy)

For legacy stdio transport:

{
  "mcpServers": {
    "checklist": {
      "command": "npx",
      "args": ["checklist-mcp-server", "stdio"]
    }
  }
}

Note: HTTP transport is recommended for better performance and features.

HTTP Server Configuration

Environment Variables

• PORT: Server port (default: 8585)
• NODE_ENV: Environment mode (development/production)
• MAX_SESSIONS: Maximum number of concurrent sessions to keep in memory (default: 100)

Server Endpoints

• POST /mcp: Main MCP endpoint for all tool calls and protocol communication

Development Mode

For development with auto-reload:

npm run dev:http

Production Deployment

For production deployment, build the project first:

npm run build
npm run start:http

Memory Management

The server includes automatic memory management to prevent unlimited memory growth in long-running deployments:

# Set maximum number of concurrent sessions (default: 100)
export MAX_SESSIONS=200
npm run start:http

Key Features:

• LRU Eviction: Automatically removes least recently used sessions when limit is reached
• Configurable Limit: Set MAX_SESSIONS environment variable (default: 100)
• Transparent Operation: No changes needed to existing client code
• Access-Based Tracking: Sessions are kept alive based on recent usage, not time

Example with custom session limit:

# For high-traffic deployments
MAX_SESSIONS=500 npm run start:http

# For resource-constrained environments  
MAX_SESSIONS=50 npm run start:http

Health Check

The server logs startup confirmation:

Checklist MCP HTTP server running on port 8585

Client Connection

Use the StreamableHTTPClientTransport from the MCP SDK:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('http://localhost:8585/mcp')
);
const client = new Client({
  name: 'your-client-name',
  version: '1.0.0',
});

await client.connect(transport);

Available Tools

The server provides six MCP tools for comprehensive task and work information management:

Task Management Tools

1. update_tasks

Updates tasks at a specific hierarchy level within a session.

Parameters:

• sessionId (string, required): Unique session identifier (1-100 characters, alphanumeric with hyphens/underscores)
• path (string, optional): Hierarchical path specifying where to update tasks (default: "/")
• tasks (array, required): Array of task objects to set at the specified path

Task Object Structure:

{
  taskId: string;        // 1-20 characters, letters/numbers/symbols (excluding / \ : * ? " < > |)
  description: string;   // Human-readable task description (max 1000 characters)
  status?: 'TODO' | 'DONE'; // Task status (default: 'TODO')
  children?: Task[];     // Optional array of subtasks
}

Path Examples:

• "/" - Root level (replaces entire task list)
• "/auth1/" - Children of task 'auth1'
• "/auth1/api2/" - Children of task 'api2' under 'auth1'

Example Usage:

{
  "sessionId": "project-alpha",
  "path": "/",
  "tasks": [
    {
      "taskId": "setup",
      "description": "Project setup tasks",
      "status": "TODO",
      "children": [
        {
          "taskId": "deps",
          "description": "Install dependencies",
          "status": "DONE"
        },
        {
          "taskId": "config",
          "description": "Configure environment",
          "status": "TODO"
        }
      ]
    }
  ]
}

2. get_all_tasks

Retrieves all tasks for a session with formatted tree visualization.

Parameters:

• sessionId (string, required): Session identifier to retrieve tasks from

Response: Returns a formatted ASCII tree showing the complete task hierarchy with status indicators.

Example Usage:

{
  "sessionId": "project-alpha"
}

Example Response:

├── ○ setup: Project setup tasks
│   ├── ✓ deps: Install dependencies
│   └── ○ config: Configure environment
└── ○ testing: Testing tasks
    └── ○ unit: Write unit tests

3. mark_task_as_done

Marks a specific task as 'DONE' using hierarchical task search.

Parameters:

• sessionId (string, required): Session identifier containing the task
• taskId (string, required): Unique identifier of the task to mark as done

Features:

• Finds tasks at any depth in the hierarchy
• Preserves subtask independence (marking parent doesn't affect children)
• Returns complete updated hierarchy after marking

Example Usage:

{
  "sessionId": "project-alpha",
  "taskId": "config"
}

Work Information Management Tools

4. save_current_work_info

Saves current work information with summary and description to an LRU cache for sharing between agents.

Parameters:

• work_summarize (string, required): Full work summary text describing current progress and context (max 5000 characters)
• work_description (string, required): Short description for easy identification (max 200 characters)
• sessionId (string, optional): Session ID to associate work with current tasks and capture task snapshot

Features:

• Generates unique 8-digit numeric work ID
• Creates human-readable timestamp (ISO format)
• Captures static task snapshot when sessionId provided
• Overwrites existing entry if same sessionId used
• LRU eviction when cache exceeds capacity (default 10 entries)

Example Usage:

{
  "work_summarize": "Completed user authentication API endpoints including login, logout, and token refresh. All endpoints are tested and documented. Next step is to implement password reset functionality.",
  "work_description": "User Auth API - Phase 1 Complete",
  "sessionId": "auth-project-2024"
}

Example Response:

Successfully saved work information with ID: 12345678
Timestamp: 2024-01-15T10:30:45.123Z
Associated with session 'auth-project-2024' and captured task snapshot

5. get_recent_works_info

Retrieves a list of recent work information entries ordered by most recently used.

Parameters: None

Response Format: Returns JSON array with work summaries containing:

• workId: Unique 8-digit identifier
• work_timestamp: Human-readable timestamp
• work_description: Short description for identification

Example Usage:

{}

Example Response:

{
  "works": [
    {
      "workId": "12345678",
      "work_timestamp": "2024-01-15T10:30:45.123Z",
      "work_description": "User Auth API - Phase 1 Complete"
    },
    {
      "workId": "87654321",
      "work_timestamp": "2024-01-15T09:15:22.456Z",
      "work_description": "Database Schema Updates"
    }
  ]
}

6. get_work_by_id

Retrieves detailed work information by workId, including full summary and associated task snapshot.

Parameters:

• workId (string, required): The unique 8-digit numeric identifier of the work to retrieve

Response Format: Returns JSON object containing:

• workId: The work identifier
• work_timestamp: Human-readable timestamp
• work_description: Short description
• work_summarize: Full work summary text
• work_tasks (optional): Static task snapshot from save time if sessionId was provided

Features:

• Updates LRU access order when work is retrieved
• Returns static task snapshot from save time (not current task status)
• Clear error messages for invalid or non-existent work IDs

Example Usage:

{
  "workId": "12345678"
}

Example Response:

{
  "workId": "12345678",
  "work_timestamp": "2024-01-15T10:30:45.123Z",
  "work_description": "User Auth API - Phase 1 Complete",
  "work_summarize": "Completed user authentication API endpoints including login, logout, and token refresh. All endpoints are tested and documented. Next step is to implement password reset functionality.",
  "work_tasks": [
    {
      "taskId": "auth",
      "description": "Authentication system",
      "status": "TODO",
      "children": [
        {
          "taskId": "login",
          "description": "Login endpoint",
          "status": "DONE"
        },
        {
          "taskId": "logout",
          "description": "Logout endpoint", 
          "status": "DONE"
        }
      ]
    }
  ]
}

Work Information Data Format

WorkInfo Structure

interface WorkInfo {
  workId: string;           // 8-digit numeric ID (e.g., "12345678")
  work_timestamp: string;   // ISO format timestamp (e.g., "2024-01-15T10:30:45.123Z")
  work_description: string; // Short description (max 200 chars)
  work_summarize: string;   // Full work summary (max 5000 chars)
  sessionId?: string;       // Optional session association
  work_tasks?: any;         // Static task snapshot from save time
}

LRU Cache Behavior

• Capacity: Default 10 entries, configurable
• Eviction: Least Recently Used when capacity exceeded
• Access Tracking: Updated on save_current_work_info and get_work_by_id operations
• Overwrite Logic: Same sessionId overwrites existing entry
• Memory Management: Automatic cleanup, ~50KB maximum memory usage

Usage Examples

Task Management Examples

Basic Task Management

// Initialize HTTP client
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('http://localhost:8585/mcp')
);
const client = new Client({
  name: 'task-management-client',
  version: '1.0.0',
});

await client.connect(transport);

// Create initial tasks
await client.callTool({
  name: 'update_tasks',
  arguments: {
    sessionId: 'my-project',
    path: '/',
    tasks: [
      {
        taskId: 'backend',
        description: 'Backend development',
        children: [
          { taskId: 'api', description: 'Build REST API' },
          { taskId: 'db', description: 'Setup database' }
        ]
      },
      {
        taskId: 'frontend',
        description: 'Frontend development'
      }
    ]
  }
});

// Mark a task as done
await client.callTool({
  name: 'mark_task_as_done',
  arguments: {
    sessionId: 'my-project',
    taskId: 'api'
  }
});

// Get current status
await client.callTool({
  name: 'get_all_tasks',
  arguments: {
    sessionId: 'my-project'
  }
});

// Clean up
await transport.close();

Hierarchical Updates

// Add subtasks to existing task
await client.callTool({
  name: 'update_tasks',
  arguments: {
    sessionId: 'my-project',
    path: '/backend/',
    tasks: [
      { taskId: 'api', description: 'Build REST API', status: 'DONE' },
      { taskId: 'db', description: 'Setup database' },
      { taskId: 'auth', description: 'Implement authentication' }
    ]
  }
});

Work Information Management Examples

Agent Work Handoff Workflow

// Agent 1: Save work progress with task association
await client.callTool({
  name: 'save_current_work_info',
  arguments: {
    work_summarize: 'Completed user registration API with validation. Implemented email verification flow and password hashing. All unit tests passing. Ready to start login functionality.',
    work_description: 'User Registration API Complete',
    sessionId: 'user-auth-sprint'
  }
});
// Returns: workId "12345678"

// Agent 2: Get recent work to understand context
await client.callTool({
  name: 'get_recent_works_info',
  arguments: {}
});

// Agent 2: Get detailed work information
await client.callTool({
  name: 'get_work_by_id',
  arguments: {
    workId: '12345678'
  }
});
// Returns full context including task snapshot from when work was saved

Work Progress Tracking

// Save work without session association
await client.callTool({
  name: 'save_current_work_info',
  arguments: {
    work_summarize: 'Researched three different authentication libraries. JWT with refresh tokens seems best approach. Created comparison document and architecture proposal.',
    work_description: 'Auth Library Research Complete'
  }
});

// Update work for same session (overwrites previous entry)
await client.callTool({
  name: 'save_current_work_info',
  arguments: {
    work_summarize: 'Updated authentication implementation. Added JWT middleware and refresh token rotation. All endpoints secured. Performance testing shows 200ms average response time.',
    work_description: 'Auth Implementation Updated',
    sessionId: 'user-auth-sprint'
  }
});

Multi-Agent Collaboration

// Agent A: Complete database work and save progress
await client.callTool({
  name: 'save_current_work_info',
  arguments: {
    work_summarize: 'Database schema finalized with user, session, and audit tables. All migrations tested. Indexes optimized for query performance. Ready for API integration.',
    work_description: 'Database Schema Complete',
    sessionId: 'backend-setup'
  }
});

// Agent B: Check recent work before starting
const recentWorks = await client.callTool({
  name: 'get_recent_works_info',
  arguments: {}
});

// Agent B: Get specific work details to understand database structure
const dbWork = await client.callTool({
  name: 'get_work_by_id',
  arguments: {
    workId: recentWorks.works[0].workId
  }
});

// Agent B: Continue with API development using database context

Error Handling and Troubleshooting

Common Error Scenarios

Task Management Errors

Invalid Session ID:

Error: Session ID can only contain alphanumeric characters, hyphens, and underscores

• Solution: Use only letters, numbers, hyphens, and underscores in session IDs
• Valid: project-alpha, user_auth_2024, sprint1
• Invalid: project@alpha, user auth, sprint#1

Invalid Path:

Error: Invalid path '/nonexistent/' - target task 'nonexistent' not found

• Solution: Ensure parent tasks exist before updating their children
• Check: Use get_all_tasks to verify current task structure

Duplicate Task ID:

Error: Task ID 'auth' already exists at path '/backend/auth'

• Solution: Use unique task IDs within the session or update at the correct path
• Note: Task IDs must be unique across the entire session hierarchy

Invalid Task ID Format:

Error: Task ID 'task/with/slashes' has invalid format

• Solution: Avoid these characters in task IDs: / \ : * ? " < > |
• Valid: task-1, auth_api, user@login, step.1

Work Information Errors

Invalid Work ID:

Error: Input validation failed: workId must be exactly 8 digits

• Solution: Use the exact 8-digit work ID returned by save_current_work_info
• Example: 12345678 (not 1234567 or 123456789)

Work Not Found:

Error: Work not found: No work information exists for workId '99999999'

• Solution: Verify work ID exists using get_recent_works_info
• Note: Work may have been evicted from LRU cache if capacity exceeded

Input Validation:

Error: Input validation failed: work_description cannot exceed 200 characters

• Solution: Keep descriptions concise (≤200 chars) and summaries detailed (≤5000 chars)

Session Association Warning:

Warning: sessionId 'nonexistent-session' does not exist in task store

• Impact: Work is saved but no task snapshot captured
• Solution: Create tasks in session first, or save work without sessionId

Best Practices

Task Management

1. Use descriptive task IDs: user-login instead of task1
2. Keep descriptions clear: Include enough context for other agents
3. Validate paths: Check task structure with get_all_tasks before complex updates
4. Handle errors gracefully: Check for error messages in responses

Work Information Management

1. Write comprehensive summaries: Include current state, completed work, and next steps
2. Use meaningful descriptions: Help other agents quickly identify relevant work
3. Associate with sessions: Link work to task sessions for complete context
4. Monitor cache capacity: Recent work may be evicted after 10 entries
5. Handle missing work: Check get_recent_works_info if specific work ID not found

Agent Collaboration

1. Check recent work first: Use get_recent_works_info to understand current context
2. Save progress frequently: Don't lose work context between agent handoffs
3. Include next steps: Help subsequent agents understand what to do next
4. Use consistent session IDs: Enable work association and task context sharing

Debugging Tips

1. Enable logging: Check server logs for detailed error information
2. Validate inputs: Ensure all required fields are provided with correct formats
3. Test incrementally: Start with simple operations before complex workflows
4. Check cache state: Use get_recent_works_info to understand current work cache
5. Verify task structure: Use get_all_tasks to confirm session task hierarchy
6. HTTP connectivity: Ensure the server is running and accessible at the configured URL
7. Transport cleanup: Always close HTTP transports properly to avoid connection leaks

Troubleshooting npx Usage

Server won't start:

# Check if port is in use
lsof -i :8585

# Use different port
npx checklist-mcp-server --port 3000

# Check for errors
npx checklist-mcp-server 2>&1 | tee server.log

npx command not found:

# Update npm/node
npm install -g npm@latest

# Clear npx cache
npx --yes checklist-mcp-server

Permission issues:

# On Unix systems, ensure execute permissions
chmod +x ~/.npm/_npx/*/node_modules/.bin/checklist-mcp-server

Testing

Running Tests

The project includes comprehensive test suites for both core functionality and HTTP integration:

# Run all tests
npm test

# Run core functionality tests
npm run test:core

# Run HTTP integration tests (requires server to be built)
npm run test:http

# Run integration tests
npm run test:integration

HTTP Integration Tests

The HTTP integration tests automatically:

1. Start the HTTP server on port 8585
2. Create an HTTP client with StreamableHTTPClientTransport
3. Test all MCP tools over HTTP
4. Clean up server and client connections

Example test output:

🚀 Setting up HTTP Integration Test Suite
✅ Server started, initializing client...
🧪 Running HTTP Integration Tests
✅ PASS update_tasks over HTTP
✅ PASS get_all_tasks over HTTP  
✅ PASS mark_task_as_done over HTTP
🎉 All HTTP integration tests passed!

Manual Testing with curl

You can also test the HTTP endpoint directly:

# Start the server
npm run start:http

# Test with curl (example MCP request)
curl -X POST http://localhost:8585/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_all_tasks",
      "arguments": {
        "sessionId": "test-session"
      }
    }
  }'