DEV Community: Fairen

Complete Tutorial: Creating an MCP Task Manager Server from Scratch

Fairen — Thu, 06 Nov 2025 16:14:42 +0000

📖 Table of Contents

Introduction to Model Context Protocol (MCP)
Prerequisites and Installation
Project Structure
Basic Configuration
MCP Server Implementation
Endpoints: Tools
Endpoints: Resources
Endpoints: Prompts
Error Handling
Main Server
Code Organization and Patterns
Testing and Validation
Docker Deployment
Additional Resources

1. Introduction to Model Context Protocol (MCP)

What is MCP?

The Model Context Protocol (MCP) is a standardized communication protocol that allows Large Language Models (LLMs) to interact with external systems in a secure and structured manner. It uses JSON-RPC 2.0 for communication.

Main Components

Tools: Actions that the LLM can execute (create, modify, delete)
Resources: Data that the LLM can read (files, databases)
Prompts: Predefined templates to guide interactions

MCP Session Lifecycle

sequenceDiagram
    Client->>Server: initialize
    Server->>Client: capabilities
    Client->>Server: tools/list
    Client->>Server: resources/list
    Client->>Server: prompts/list
    Client->>Server: tools/call | resources/read | prompts/get

2. Prerequisites and Installation

Required Technologies

Node.js 18+ with TypeScript
@modelcontextprotocol/sdk for MCP implementation
Zod for schema validation
Database (SQLite for this tutorial)

Installation

# Create the project
mkdir mcp-task-manager
cd mcp-task-manager

# Initialize Node.js
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk zod sqlite3
npm install -D typescript @types/node ts-node nodemon

# TypeScript configuration
npx tsc --init

3. Project Structure

mcp-task-manager/
├── src/
│   ├── server.ts           # MCP server entry point
│   ├── database/
│   │   ├── db.ts          # Database configuration
│   │   └── schema.sql     # Table schema
│   ├── tools/
│   │   ├── index.ts       # Tools export
│   │   ├── create-task.ts
│   │   ├── update-task.ts
│   │   ├── complete-task.ts
│   │   └── delete-task.ts
│   ├── resources/
│   │   ├── index.ts       # Resources export
│   │   ├── task-list.ts
│   │   ├── task-stats.ts
│   │   └── task-detail.ts
│   ├── prompts/
│   │   ├── index.ts       # Prompts export
│   │   ├── weekly-review.ts
│   │   └── sprint-planning.ts
│   ├── types/
│   │   └── task.ts        # TypeScript types
│   └── utils/
│       └── errors.ts      # Error handling
├── Dockerfile             # Multi-stage Docker configuration
├── docker-compose.yml     # Docker orchestration
├── .dockerignore          # Files to ignore for Docker
├── .env.example           # Environment variables example
├── package.json
├── tsconfig.json
└── README.md

4. Basic Configuration

package.json

{
  "name": "mcp-task-manager",
  "version": "1.0.0",
  "description": "MCP server for task management",
  "main": "dist/server.js",
  "scripts": {
    "build": "tsc && mkdir -p dist/database && cp src/database/schema.sql dist/database/",
    "start": "node dist/server.js",
    "dev": "nodemon src/server.ts",
    "test": "jest",
    "docker:build": "docker build -t task-manager-mcp-server .",
    "docker:run": "docker run -d --name task-manager-mcp-server -p 3000:3000 task-manager-mcp-server",
    "docker:stop": "docker stop task-manager-mcp-server && docker rm task-manager-mcp-server",
    "docker:logs": "docker logs task-manager-mcp-server"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.21.0",
    "sqlite3": "^5.1.7",
    "zod": "^3.25.76"
  },
  "devDependencies": {
    "@types/node": "^24.10.0",
    "nodemon": "^3.1.10",
    "ts-node": "^10.9.2",
    "typescript": "^5.9.3"
  }
}

tsconfig.json

{
  // Visit https://aka.ms/tsconfig to read more about this file
  "compilerOptions": {
    // File Layout
    "outDir": "./dist",
    "rootDir": "./src",

    // Environment Settings
    // See also https://aka.ms/tsconfig/module
    "module": "commonjs",
    "target": "ES2022",
    "esModuleInterop": true,
    // For nodejs:
    "lib": ["ES2022"],
    "types": ["node"],
    // and npm install -D @types/node

    // Other Outputs
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,

    // Stricter Typechecking Options
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,

    // Style Options
    // "noImplicitReturns": true,
    // "noImplicitOverride": true,
    // "noUnusedLocals": true,
    // "noUnusedParameters": true,
    // "noFallthroughCasesInSwitch": true,
    // "noPropertyAccessFromIndexSignature": true,

    // Recommended Options
    "strict": true,
    "skipLibCheck": true,
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

5. MCP Server Implementation

Basic Types (`src/types/task.ts`)

The system uses Zod for validation and TypeScript type generation:

import { z } from 'zod';

// Main schema with complete validation
export const TaskSchema = z.object({
  id: z.string().optional(),                           // Auto-generated
  title: z.string().min(1).max(200),                  // Required title (1-200 chars)
  description: z.string().optional(),                  // Optional description
  priority: z.enum(['low', 'medium', 'high', 'urgent']).default('medium'),
  status: z.enum(['pending', 'in_progress', 'completed', 'cancelled']).default('pending'),
  due_date: z.string().datetime().optional(),         // ISO 8601 format
  tags: z.array(z.string()).default([]),              // Array of strings
  assignee: z.string().optional(),                    // Assigned user
  created_at: z.string().datetime().optional(),       // Creation timestamp
  updated_at: z.string().datetime().optional(),       // Modification timestamp
  completed_at: z.string().datetime().optional()      // Completion timestamp
});

// TypeScript type automatically inferred
export type Task = z.infer<typeof TaskSchema>;

// Derived schemas for CRUD operations
export const CreateTaskSchema = TaskSchema.omit({ 
  id: true, 
  created_at: true, 
  updated_at: true, 
  completed_at: true 
});

export const UpdateTaskSchema = TaskSchema.partial().extend({
  id: z.string()                                      // Required ID for updates
});

export const CompleteTaskSchema = z.object({
  task_id: z.string(),
  completion_notes: z.string().optional(),
  time_spent: z.number().min(0).optional()           // Time in minutes
});

Advantages of this approach:

Type Safety: Automatic runtime validation
Living documentation: Schemas serve as reference
Reusability: One schema, multiple uses (API, DB, validation)
Explicit errors: Clear error messages for clients

Validation example:

// ✅ Valid
const task = CreateTaskSchema.parse({
  title: "New task",
  priority: "high",
  tags: ["urgent", "feature"]
});

// ❌ Validation error
const invalid = CreateTaskSchema.parse({
  title: "",  // Error: minimum 1 character
  priority: "invalid"  // Error: unauthorized value
});

Database Configuration (`src/database/db.ts`)

import sqlite3 from 'sqlite3';
import path from 'path';
import fs from 'fs';
import { Task } from '../types/task';

export class TaskDatabase {
  private db: sqlite3.Database;

  constructor(dbPath: string = './tasks.db') {
    this.db = new sqlite3.Database(dbPath);
    this.initializeDatabase();
  }

  private async initializeDatabase() {
    const schemaPath = path.join(__dirname, 'schema.sql');
    const schema = fs.readFileSync(schemaPath, 'utf8');

    return new Promise<void>((resolve, reject) => {
      this.db.exec(schema, (err) => {
        if (err) reject(err);
        else resolve();
      });
    });
  }

  async createTask(task: Omit<Task, 'id' | 'created_at' | 'updated_at'>): Promise<string> {
    const sql = `
      INSERT INTO tasks (title, description, priority, status, due_date, tags, assignee)
      VALUES (?, ?, ?, ?, ?, ?, ?)
    `;

    return new Promise((resolve, reject) => {
      this.db.run(sql, [
        task.title,
        task.description || null,
        task.priority,
        task.status || 'pending',
        task.due_date || null,
        JSON.stringify(task.tags || []),
        task.assignee || null
      ], function(err) {
        if (err) reject(err);
        else resolve(`task-${this.lastID}`);
      });
    });
  }

  async getTask(id: string): Promise<Task | null> {
    const sql = 'SELECT * FROM tasks WHERE id = ?';

    return new Promise((resolve, reject) => {
      this.db.get(sql, [id.replace('task-', '')], (err, row: any) => {
        if (err) reject(err);
        else if (!row) resolve(null);
        else {
          resolve({
            id: `task-${row.id}`,
            title: row.title,
            description: row.description,
            priority: row.priority,
            status: row.status,
            due_date: row.due_date,
            tags: JSON.parse(row.tags || '[]'),
            assignee: row.assignee,
            created_at: row.created_at,
            updated_at: row.updated_at,
            completed_at: row.completed_at
          });
        }
      });
    });
  }

  async getAllTasks(): Promise<Task[]> {
    const sql = 'SELECT * FROM tasks ORDER BY created_at DESC';

    return new Promise((resolve, reject) => {
      this.db.all(sql, [], (err, rows: any[]) => {
        if (err) reject(err);
        else {
          const tasks = rows.map(row => ({
            id: `task-${row.id}`,
            title: row.title,
            description: row.description,
            priority: row.priority,
            status: row.status,
            due_date: row.due_date,
            tags: JSON.parse(row.tags || '[]'),
            assignee: row.assignee,
            created_at: row.created_at,
            updated_at: row.updated_at,
            completed_at: row.completed_at
          }));
          resolve(tasks);
        }
      });
    });
  }

  async updateTask(id: string, updates: Partial<Task>): Promise<boolean> {
    const fields = [];
    const values: string[] = [];

    Object.entries(updates).forEach(([key, value]) => {
      if (key !== 'id' && value !== undefined) {
        fields.push(`${key} = ?`);
        values.push(key === 'tags' ? JSON.stringify(value) : String(value));
      }
    });

    if (fields.length === 0) return false;

    fields.push('updated_at = CURRENT_TIMESTAMP');
    const sql = `UPDATE tasks SET ${fields.join(', ')} WHERE id = ?`;
    values.push(id.replace('task-', ''));

    return new Promise((resolve, reject) => {
      this.db.run(sql, values, function(err) {
        if (err) reject(err);
        else resolve(this.changes > 0);
      });
    });
  }

  async completeTask(id: string, notes?: string, timeSpent?: number): Promise<boolean> {
    const sql = `
      UPDATE tasks 
      SET status = 'completed', 
          completed_at = CURRENT_TIMESTAMP,
          completion_notes = ?,
          time_spent = ?,
          updated_at = CURRENT_TIMESTAMP
      WHERE id = ?
    `;

    return new Promise((resolve, reject) => {
      this.db.run(sql, [notes || null, timeSpent || null, id.replace('task-', '')], function(err) {
        if (err) reject(err);
        else resolve(this.changes > 0);
      });
    });
  }

  async deleteTask(id: string): Promise<boolean> {
    const sql = 'DELETE FROM tasks WHERE id = ?';

    return new Promise((resolve, reject) => {
      this.db.run(sql, [id.replace('task-', '')], function(err) {
        if (err) reject(err);
        else resolve(this.changes > 0);
      });
    });
  }

  async getStats(): Promise<any> {
    const sql = `
      SELECT 
        COUNT(*) as total_tasks,
        SUM(CASE WHEN status = 'pending' THEN 1 ELSE 0 END) as pending,
        SUM(CASE WHEN status = 'in_progress' THEN 1 ELSE 0 END) as in_progress,
        SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed,
        SUM(CASE WHEN status = 'cancelled' THEN 1 ELSE 0 END) as cancelled,
        SUM(CASE WHEN priority = 'urgent' THEN 1 ELSE 0 END) as urgent,
        SUM(CASE WHEN priority = 'high' THEN 1 ELSE 0 END) as high,
        SUM(CASE WHEN priority = 'medium' THEN 1 ELSE 0 END) as medium,
        SUM(CASE WHEN priority = 'low' THEN 1 ELSE 0 END) as low,
        AVG(time_spent) as avg_completion_time
      FROM tasks
    `;

    return new Promise((resolve, reject) => {
      this.db.get(sql, [], (err, row: any) => {
        if (err) reject(err);
        else resolve(row);
      });
    });
  }
}

Database Schema (`src/database/schema.sql`)

CREATE TABLE IF NOT EXISTS tasks (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  title TEXT NOT NULL,
  description TEXT,
  priority TEXT DEFAULT 'medium' CHECK (priority IN ('low', 'medium', 'high', 'urgent')),
  status TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'in_progress', 'completed', 'cancelled')),
  due_date TEXT,
  tags TEXT DEFAULT '[]',
  assignee TEXT,
  completion_notes TEXT,
  time_spent INTEGER,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  completed_at DATETIME
);

CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
CREATE INDEX IF NOT EXISTS idx_tasks_priority ON tasks(priority);
CREATE INDEX IF NOT EXISTS idx_tasks_assignee ON tasks(assignee);
CREATE INDEX IF NOT EXISTS idx_tasks_due_date ON tasks(due_date);

6. Endpoints: Tools

Task Creation (`src/tools/create-task.ts`)

import { Tool } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';
import { CreateTaskSchema } from '../types/task.js';
import { McpError, ErrorCode } from '../utils/errors.js';

export const createTaskTool: Tool = {
  name: 'create_task',
  description: 'Create a new task in the system',
  inputSchema: {
    type: 'object',
    properties: {
      title: {
        type: 'string',
        description: 'Task title',
        minLength: 1,
        maxLength: 200
      },
      description: {
        type: 'string',
        description: 'Detailed task description'
      },
      priority: {
        type: 'string',
        enum: ['low', 'medium', 'high', 'urgent'],
        default: 'medium',
        description: 'Priority level'
      },
      due_date: {
        type: 'string',
        format: 'date-time',
        description: 'Due date (ISO 8601)'
      },
      tags: {
        type: 'array',
        items: { type: 'string' },
        description: 'List of associated tags'
      },
      assignee: {
        type: 'string',
        description: 'Person assigned to the task'
      }
    },
    required: ['title'],
    additionalProperties: false
  }
};

export async function handleCreateTask(args: any, db: TaskDatabase) {
  try {
    // Argument validation
    const validatedArgs = CreateTaskSchema.parse(args);

    // Task creation
    const taskId = await db.createTask(validatedArgs);

    return {
      content: [{
        type: 'text',
        text: 'Task created successfully'
      }],
      task_id: taskId,
      created_at: new Date().toISOString(),
      status: 'pending'
    };
  } catch (error) {
    if (error instanceof Error) {
      throw new McpError(ErrorCode.INVALID_PARAMS, `Validation error: ${error.message}`);
    }
    throw new McpError(ErrorCode.INTERNAL_ERROR, 'Internal error during creation');
  }
}

Task Update (`src/tools/update-task.ts`)

import { Tool } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';
import { UpdateTaskSchema } from '../types/task.js';
import { McpError, ErrorCode } from '../utils/errors.js';

export const updateTaskTool: Tool = {
  name: 'update_task',
  description: 'Update an existing task',
  inputSchema: {
    type: 'object',
    properties: {
      task_id: {
        type: 'string',
        description: 'Task identifier to modify'
      },
      title: {
        type: 'string',
        minLength: 1,
        maxLength: 200
      },
      description: { type: 'string' },
      priority: {
        type: 'string',
        enum: ['low', 'medium', 'high', 'urgent']
      },
      status: {
        type: 'string',
        enum: ['pending', 'in_progress', 'completed', 'cancelled']
      },
      due_date: {
        type: 'string',
        format: 'date-time'
      },
      tags: {
        type: 'array',
        items: { type: 'string' }
      },
      assignee: { type: 'string' }
    },
    required: ['task_id'],
    additionalProperties: false
  }
};

export async function handleUpdateTask(args: any, db: TaskDatabase) {
  try {
    const { task_id, ...updates } = args;

    // Check if task exists
    const existingTask = await db.getTask(task_id);
    if (!existingTask) {
      throw new McpError(ErrorCode.TASK_NOT_FOUND, `Task ${task_id} not found`);
    }

    // Check if task is already completed
    if (existingTask.status === 'completed') {
      throw new McpError(ErrorCode.TASK_ALREADY_COMPLETED, 'Cannot modify a completed task');
    }

    // Update
    const success = await db.updateTask(task_id, updates);

    if (success) {
      const updatedTask = await db.getTask(task_id);
      return {
        content: [{
          type: 'text',
          text: 'Task updated successfully'
        }],
        task: updatedTask
      };
    } else {
      throw new McpError(ErrorCode.INTERNAL_ERROR, 'Update failed');
    }
  } catch (error) {
    if (error instanceof McpError) throw error;
    throw new McpError(ErrorCode.INTERNAL_ERROR, 'Internal error during update');
  }
}

Task Completion (`src/tools/complete-task.ts`)

import { Tool } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';
import { CompleteTaskSchema } from '../types/task.js';
import { McpError, ErrorCode } from '../utils/errors.js';

export const completeTaskTool: Tool = {
  name: 'complete_task',
  description: 'Mark a task as completed',
  inputSchema: {
    type: 'object',
    properties: {
      task_id: {
        type: 'string',
        description: 'Task identifier to complete'
      },
      completion_notes: {
        type: 'string',
        description: 'Notes about task completion'
      },
      time_spent: {
        type: 'number',
        minimum: 0,
        description: 'Time spent in minutes'
      }
    },
    required: ['task_id'],
    additionalProperties: false
  }
};

export async function handleCompleteTask(args: any, db: TaskDatabase) {
  try {
    const validatedArgs = CompleteTaskSchema.parse(args);

    // Check if task exists
    const existingTask = await db.getTask(validatedArgs.task_id);
    if (!existingTask) {
      throw new McpError(ErrorCode.TASK_NOT_FOUND, `Task ${validatedArgs.task_id} not found`);
    }

    // Check if task is already completed
    if (existingTask.status === 'completed') {
      throw new McpError(ErrorCode.TASK_ALREADY_COMPLETED, 'Task already completed');
    }

    // Complete the task
    const success = await db.completeTask(
      validatedArgs.task_id,
      validatedArgs.completion_notes,
      validatedArgs.time_spent
    );

    if (success) {
      return {
        content: [{
          type: 'text',
          text: 'Task completed successfully'
        }],
        completed_at: new Date().toISOString(),
        total_time: validatedArgs.time_spent
      };
    } else {
      throw new McpError(ErrorCode.INTERNAL_ERROR, 'Completion failed');
    }
  } catch (error) {
    if (error instanceof McpError) throw error;
    throw new McpError(ErrorCode.INTERNAL_ERROR, 'Internal error during completion');
  }
}

Task Deletion (`src/tools/delete-task.ts`)

import { Tool } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';
import { McpError, ErrorCode } from '../utils/errors.js';

export const deleteTaskTool: Tool = {
  name: 'delete_task',
  description: 'Permanently delete a task',
  inputSchema: {
    type: 'object',
    properties: {
      task_id: {
        type: 'string',
        description: 'Task identifier to delete'
      },
      confirm: {
        type: 'boolean',
        description: 'Deletion confirmation (security)',
        default: false
      }
    },
    required: ['task_id', 'confirm'],
    additionalProperties: false
  }
};

export async function handleDeleteTask(args: any, db: TaskDatabase) {
  try {
    const { task_id, confirm } = args;

    // Check confirmation
    if (!confirm) {
      throw new McpError(ErrorCode.INVALID_PARAMS, 'Confirmation required to delete a task');
    }

    // Check if task exists
    const existingTask = await db.getTask(task_id);
    if (!existingTask) {
      throw new McpError(ErrorCode.TASK_NOT_FOUND, `Task ${task_id} not found`);
    }

    // Save information before deletion
    const taskInfo = {
      id: existingTask.id,
      title: existingTask.title,
      status: existingTask.status
    };

    // Delete the task
    const success = await db.deleteTask(task_id);

    if (success) {
      return {
        content: [{
          type: 'text',
          text: `Task "${taskInfo.title}" deleted successfully`
        }],
        deleted_task: taskInfo,
        deleted_at: new Date().toISOString()
      };
    } else {
      throw new McpError(ErrorCode.INTERNAL_ERROR, 'Deletion failed');
    }
  } catch (error) {
    if (error instanceof McpError) throw error;
    throw new McpError(ErrorCode.INTERNAL_ERROR, 'Internal error during deletion');
  }
}

Tools Export (`src/tools/index.ts`)

import { createTaskTool, handleCreateTask } from './create-task.js';
import { updateTaskTool, handleUpdateTask } from './update-task.js';
import { completeTaskTool, handleCompleteTask } from './complete-task.js';
import { deleteTaskTool, handleDeleteTask } from './delete-task.js';

export const tools = [
  createTaskTool,
  updateTaskTool,
  completeTaskTool,
  deleteTaskTool
];

export const toolHandlers = {
  create_task: handleCreateTask,
  update_task: handleUpdateTask,
  complete_task: handleCompleteTask,
  delete_task: handleDeleteTask
};

7. Endpoints: Resources

Task List (`src/resources/task-list.ts`)

import { Resource } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';

export const taskListResource: Resource = {
  uri: 'task://list',
  name: 'Task List',
  description: 'All active tasks in the system',
  mimeType: 'application/json'
};

export async function handleTaskListResource(db: TaskDatabase) {
  try {
    const tasks = await db.getAllTasks();

    return {
      contents: [{
        uri: 'task://list',
        mimeType: 'application/json',
        text: JSON.stringify({
          tasks: tasks.map(task => ({
            id: task.id,
            title: task.title,
            status: task.status,
            priority: task.priority,
            assignee: task.assignee,
            due_date: task.due_date,
            created_at: task.created_at
          })),
          total: tasks.length
        }, null, 2)
      }]
    };
  } catch (error) {
    throw new Error('Error retrieving tasks');
  }
}

Statistics (`src/resources/task-stats.ts`)

import { Resource } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';

export const taskStatsResource: Resource = {
  uri: 'task://stats',
  name: 'Task Statistics',
  description: 'Global statistics of the task system',
  mimeType: 'application/json'
};

export async function handleTaskStatsResource(db: TaskDatabase) {
  try {
    const stats = await db.getStats();
    const tasks = await db.getAllTasks();

    // Calculate overdue tasks
    const now = new Date();
    const overdueTasks = tasks.filter(task => 
      task.due_date && 
      new Date(task.due_date) < now && 
      task.status !== 'completed'
    ).length;

    // Calculate completion rate
    const completionRate = stats.total_tasks > 0 
      ? (stats.completed / stats.total_tasks) * 100 
      : 0;

    const statsData = {
      total_tasks: stats.total_tasks,
      by_status: {
        pending: stats.pending,
        in_progress: stats.in_progress,
        completed: stats.completed,
        cancelled: stats.cancelled
      },
      by_priority: {
        urgent: stats.urgent,
        high: stats.high,
        medium: stats.medium,
        low: stats.low
      },
      overdue_tasks: overdueTasks,
      completion_rate: Math.round(completionRate * 10) / 10,
      average_completion_time: stats.avg_completion_time || 0
    };

    return {
      contents: [{
        uri: 'task://stats',
        mimeType: 'application/json',
        text: JSON.stringify(statsData, null, 2)
      }]
    };
  } catch (error) {
    throw new Error('Error retrieving statistics');
  }
}

Task Detail (`src/resources/task-detail.ts`)

import { Resource } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';
import { McpError, ErrorCode } from '../utils/errors.js';

export const taskDetailResource: Resource = {
  uri: 'task://detail/{id}',
  name: 'Task Detail',
  description: 'Detailed information of a specific task',
  mimeType: 'application/json'
};

export async function handleTaskDetailResource(uri: string, db: TaskDatabase) {
  try {
    // Extract ID from URI
    const match = uri.match(/task:\/\/detail\/(.+)/);
    if (!match) {
      throw new McpError(ErrorCode.INVALID_PARAMS, 'Invalid URI for task detail');
    }

    const taskId = match[1];
    if (!taskId) {
      throw new McpError(ErrorCode.INVALID_PARAMS, 'Missing task ID in URI');
    }

    const task = await db.getTask(taskId);

    if (!task) {
      throw new McpError(ErrorCode.TASK_NOT_FOUND, `Task ${taskId} not found`);
    }

    return {
      contents: [{
        uri: uri,
        mimeType: 'application/json',
        text: JSON.stringify(task, null, 2)
      }]
    };
  } catch (error) {
    if (error instanceof McpError) throw error;
    throw new Error('Error retrieving task detail');
  }
}

Resources Export (`src/resources/index.ts`)

import { taskListResource, handleTaskListResource } from './task-list.js';
import { taskStatsResource, handleTaskStatsResource } from './task-stats.js';
import { taskDetailResource, handleTaskDetailResource } from './task-detail.js';

export const resources = [
  taskListResource,
  taskStatsResource,
  taskDetailResource
];

export const resourceHandlers = {
  taskList: handleTaskListResource,
  taskStats: handleTaskStatsResource,
  taskDetail: handleTaskDetailResource
};

8. Endpoints: Prompts

Weekly Review (`src/prompts/weekly-review.ts`)

import { Prompt } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';

export const weeklyReviewPrompt: Prompt = {
  name: 'weekly_review',
  description: 'Generate a weekly review report',
  arguments: [
    {
      name: 'week_number',
      description: 'Week number to analyze',
      required: false
    },
    {
      name: 'team',
      description: 'Filter by specific team',
      required: false
    }
  ]
};

export async function handleWeeklyReviewPrompt(args: any, db: TaskDatabase) {
  try {
    const weekNumber = args.week_number || getCurrentWeekNumber();
    const team = args.team || 'all teams';

    // Retrieve data
    const tasks = await db.getAllTasks();
    const stats = await db.getStats();

    // Filter by team if specified
    const filteredTasks = args.team 
      ? tasks.filter(task => task.assignee?.includes(args.team))
      : tasks;

    const description = `Weekly review ${team} - Week ${weekNumber}`;

    return {
      description,
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `Generate a detailed review for week ${weekNumber} of ${team} with:

📊 **Available Data:**
- Total tasks: ${filteredTasks.length}
- Completed tasks: ${filteredTasks.filter(t => t.status === 'completed').length}
- In progress tasks: ${filteredTasks.filter(t => t.status === 'in_progress').length}
- Pending tasks: ${filteredTasks.filter(t => t.status === 'pending').length}

📋 **Requested Analysis:**
1. **Tasks completed this week**
2. **Tasks in progress with their progression**
3. **Identified blockers and solutions**
4. **Performance metrics**
5. **Recommendations for next week**

Use a structured format with emojis and clear sections.`
          }
        },
        {
          role: 'assistant',
          content: {
            type: 'text',
            text: `I will analyze the data for week ${weekNumber} for ${team} and generate a comprehensive report...`
          }
        }
      ]
    };
  } catch (error) {
    throw new Error('Error generating weekly review prompt');
  }
}

function getCurrentWeekNumber(): number {
  const now = new Date();
  const start = new Date(now.getFullYear(), 0, 1);
  const days = Math.floor((now.getTime() - start.getTime()) / (24 * 60 * 60 * 1000));
  return Math.ceil((days + start.getDay() + 1) / 7);
}

Sprint Planning (`src/prompts/sprint-planning.ts`)

import { Prompt } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';

export const sprintPlanningPrompt: Prompt = {
  name: 'sprint_planning',
  description: 'Assist with sprint planning with velocity analysis',
  arguments: [
    {
      name: 'sprint_duration',
      description: 'Sprint duration in days (default: 14)',
      required: false
    },
    {
      name: 'team_capacity',
      description: 'Team capacity in person-days',
      required: false
    }
  ]
};

export async function handleSprintPlanningPrompt(args: any, db: TaskDatabase) {
  try {
    const sprintDuration = args.sprint_duration || 14;
    const teamCapacity = args.team_capacity;

    const tasks = await db.getAllTasks();
    const stats = await db.getStats();

    // Analyze priority tasks
    const highPriorityTasks = tasks.filter(t => 
      ['urgent', 'high'].includes(t.priority) && 
      t.status === 'pending'
    );

    // Calculate average velocity
    const completedTasks = tasks.filter(t => t.status === 'completed');
    const avgCompletionTime = stats.avg_completion_time || 0;

    return {
      description: `Sprint planning - ${sprintDuration} days`,
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `Help me plan the next sprint with this data:

🏃‍♂️ **Sprint Parameters:**
- Duration: ${sprintDuration} days
- Team capacity: ${teamCapacity || 'not specified'}

📊 **Task Analysis:**
- Priority tasks (urgent/high): ${highPriorityTasks.length}
- Pending tasks: ${tasks.filter(t => t.status === 'pending').length}
- Average completion time: ${avgCompletionTime} minutes
- Current completion rate: ${((stats.completed / stats.total_tasks) * 100).toFixed(1)}%

🎯 **Request:**
1. **Suggest optimal task distribution**
2. **Identify critical dependencies**
3. **Propose realistic timeline**
4. **Anticipate potential risks**
5. **Recommend tracking metrics**

Generate a detailed plan with clear milestones.`
          }
        },
        {
          role: 'assistant',
          content: {
            type: 'text',
            text: `Let's analyze the data to create an optimal sprint plan...`
          }
        }
      ]
    };
  } catch (error) {
    throw new Error('Error generating sprint planning prompt');
  }
}

Prompts Export (`src/prompts/index.ts`)

import { weeklyReviewPrompt, handleWeeklyReviewPrompt } from './weekly-review.js';
import { sprintPlanningPrompt, handleSprintPlanningPrompt } from './sprint-planning.js';

export const prompts = [
  weeklyReviewPrompt,
  sprintPlanningPrompt
];

export const promptHandlers = {
  weekly_review: handleWeeklyReviewPrompt,
  sprint_planning: handleSprintPlanningPrompt
};

9. Error Handling

Error Codes (`src/utils/errors.ts`)

export enum ErrorCode {
  // Standard JSON-RPC errors
  PARSE_ERROR = -32700,
  INVALID_REQUEST = -32600,
  METHOD_NOT_FOUND = -32601,
  INVALID_PARAMS = -32602,
  INTERNAL_ERROR = -32603,

  // Task Manager specific errors
  TASK_NOT_FOUND = -32000,
  PERMISSION_DENIED = -32001,
  TASK_ALREADY_COMPLETED = -32002,
  INVALID_DATE_FORMAT = -32003,
  QUOTA_EXCEEDED = -32004
}

export class McpError extends Error {
  constructor(
    public code: ErrorCode,
    message: string,
    public data?: any
  ) {
    super(message);
    this.name = 'McpError';
  }

  toJsonRpc() {
    return {
      code: this.code,
      message: this.message,
      ...(this.data && { data: this.data })
    };
  }
}

export function getErrorMessage(code: ErrorCode): string {
  switch (code) {
    case ErrorCode.TASK_NOT_FOUND:
      return 'Task not found';
    case ErrorCode.PERMISSION_DENIED:
      return 'Permission denied';
    case ErrorCode.TASK_ALREADY_COMPLETED:
      return 'Task already completed';
    case ErrorCode.INVALID_DATE_FORMAT:
      return 'Invalid date format';
    case ErrorCode.QUOTA_EXCEEDED:
      return 'Quota exceeded';
    default:
      return 'Internal error';
  }
}

10. Main Server

Hybrid HTTP/STDIO Architecture

The TaskManagerServer supports two communication modes:

1. HTTP Mode (Recommended)

private createHttpServer() {
  return http.createServer(async (req, res) => {
    // CORS configuration for web integration
    res.setHeader('Access-Control-Allow-Origin', '*');
    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');

    // Handle OPTIONS requests (CORS preflight)
    if (req.method === 'OPTIONS') {
      res.writeHead(200);
      res.end();
      return;
    }

    // Health check endpoint
    if (req.method === 'GET' && req.url === '/health') {
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ 
        status: 'healthy', 
        timestamp: new Date().toISOString() 
      }));
      return;
    }

    // Main MCP endpoint
    if (req.method === 'POST' && req.url === '/mcp') {
      // JSON-RPC request processing
      // ...
    }
  });
}

HTTP Mode Advantages:

✅ Simplified integration with Claude Desktop
✅ Easy debugging with curl, Postman, etc.
✅ Health check for monitoring
✅ CORS enabled for web applications
✅ Scalability for multiple clients

2. STDIO Mode (Legacy)

if (process.env.MCP_TRANSPORT === 'stdio') {
  const transport = new StdioServerTransport();
  await this.server.connect(transport);
  console.error('Task Manager MCP Server started (stdio)');
}

MCP Request Handling

The server implements a JSON-RPC translation layer:

private async handleMcpRequest(request: any) {
  const { method, params } = request;

  switch (method) {
    case 'initialize':
      return {
        jsonrpc: '2.0',
        id: request.id,
        result: {
          protocolVersion: '1.0',
          serverInfo: { name: 'task-manager-server', version: '1.0.0' },
          capabilities: { tools: {}, resources: {}, prompts: {} }
        }
      };

    case 'tools/list':
      return { jsonrpc: '2.0', id: request.id, result: { tools } };

    case 'tools/call':
      // Validation and tool execution
      const { name, arguments: args } = params;
      if (!toolHandlers[name as keyof typeof toolHandlers]) {
        throw new McpError(ErrorCode.METHOD_NOT_FOUND, `Tool ${name} not found`);
      }
      const result = await toolHandlers[name as keyof typeof toolHandlers](args, this.database);
      return { jsonrpc: '2.0', id: request.id, result };

    // Other methods...
  }
}

Centralized Error Handling

try {
  const request = JSON.parse(body);
  const response = await this.handleMcpRequest(request);

  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify(response));
} catch (error) {
  res.writeHead(500, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ 
    error: 'Internal server error', 
    message: error instanceof Error ? error.message : 'Unknown error' 
  }));
}

Main Entry Point (`src/server.ts`)

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { 
  ListToolsRequestSchema,
  CallToolRequestSchema,
  ListResourcesRequestSchema,
  ReadResourceRequestSchema,
  ListPromptsRequestSchema,
  GetPromptRequestSchema
} from '@modelcontextprotocol/sdk/types.js';
import * as http from 'http';
import { TaskDatabase } from './database/db.js';
import { tools, toolHandlers } from './tools/index.js';
import { resources, resourceHandlers } from './resources/index.js';
import { prompts, promptHandlers } from './prompts/index.js';
import { McpError, ErrorCode } from './utils/errors.js';

class TaskManagerServer {
  private server: Server;
  private database: TaskDatabase;
  private httpServer?: http.Server;

  constructor() {
    this.database = new TaskDatabase();
    this.server = new Server(
      {
        name: 'task-manager-server',
        version: '1.0.0'
      },
      {
        capabilities: {
          tools: {},
          resources: {},
          prompts: {}
        }
      }
    );

    this.setupHandlers();
  }

  private setupHandlers() {
    // Handler for tools with MCP schemas
    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools
    }));

    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;

      if (!toolHandlers[name as keyof typeof toolHandlers]) {
        throw new McpError(ErrorCode.METHOD_NOT_FOUND, `Tool ${name} not found`);
      }

      try {
        return await toolHandlers[name as keyof typeof toolHandlers](args, this.database);
      } catch (error) {
        if (error instanceof McpError) {
          throw error;
        }
        throw new McpError(ErrorCode.INTERNAL_ERROR, 'Internal server error');
      }
    });

    // Handler for resources
    this.server.setRequestHandler(ListResourcesRequestSchema, async () => ({
      resources
    }));

    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
      const { uri } = request.params;

      // Route to appropriate handler based on URI
      if (uri === 'task://list') {
        return await resourceHandlers.taskList(this.database);
      } else if (uri === 'task://stats') {
        return await resourceHandlers.taskStats(this.database);
      } else if (uri.startsWith('task://detail/')) {
        return await resourceHandlers.taskDetail(uri, this.database);
      } else {
        throw new McpError(ErrorCode.METHOD_NOT_FOUND, `Resource ${uri} not found`);
      }
    });

    // Handler for prompts
    this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
      prompts
    }));

    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;

      if (!promptHandlers[name as keyof typeof promptHandlers]) {
        throw new McpError(ErrorCode.METHOD_NOT_FOUND, `Prompt ${name} not found`);
      }

      return await promptHandlers[name as keyof typeof promptHandlers](args || {}, this.database);
    });
  }

  async start() {
    const port = process.env.PORT || 3000;

    if (process.env.MCP_TRANSPORT === 'stdio') {
      const transport = new StdioServerTransport();
      await this.server.connect(transport);
      console.error('Task Manager MCP Server started (stdio)');
    } else {
      this.httpServer = this.createHttpServer();
      this.httpServer.listen(port, () => {
        console.error(`Task Manager MCP Server started on port ${port} (HTTP)`);
      });
    }
  }

  async stop() {
    if (this.httpServer) {
      this.httpServer.close();
    }
  }
}

// Start the server
const server = new TaskManagerServer();
server.start().catch(console.error);

Advanced Error Handling Pattern

// src/utils/error-handling.ts
export class TaskManagerError extends Error {
  constructor(
    public code: string,
    message: string,
    public details?: any
  ) {
    super(message);
    this.name = 'TaskManagerError';
  }
}

export function createErrorResponse(error: unknown, id: number | string) {
  if (error instanceof TaskManagerError) {
    return {
      jsonrpc: '2.0',
      id,
      error: {
        code: -32000,
        message: error.message,
        data: { code: error.code, details: error.details }
      }
    };
  }

  return {
    jsonrpc: '2.0',
    id,
    error: {
      code: -32603,
      message: 'Internal error',
      data: { originalError: error instanceof Error ? error.message : String(error) }
    }
  };
}

Resource Caching Pattern

// src/utils/cache.ts
export class ResourceCache {
  private cache = new Map<string, { data: any; timestamp: number; ttl: number }>();

  set(key: string, data: any, ttlMs: number = 60000) {
    this.cache.set(key, {
      data,
      timestamp: Date.now(),
      ttl: ttlMs
    });
  }

  get(key: string): any | null {
    const entry = this.cache.get(key);
    if (!entry) return null;

    if (Date.now() - entry.timestamp > entry.ttl) {
      this.cache.delete(key);
      return null;
    }

    return entry.data;
  }

  clear() {
    this.cache.clear();
  }
}

// Usage in resources
export async function handleTaskListResource(database: TaskDatabase): Promise<Resource> {
  const cacheKey = 'task-list';
  const cached = resourceCache.get(cacheKey);

  if (cached) {
    return {
      contents: [{
        type: 'text',
        text: cached
      }]
    };
  }

  const tasks = await database.getAllTasks();
  const result = JSON.stringify({ tasks, total: tasks.length, cached: false }, null, 2);

  resourceCache.set(cacheKey, result, 30000); // 30 seconds TTL

  return {
    contents: [{
      type: 'text',
      text: result
    }]
  };
}

Applied patterns:

✅ Promisification of SQLite callbacks
✅ Data transformation (ID prefixing)
✅ Explicit null handling
✅ Type safety with TypeScript

11. Code Organization and Patterns

Structuring Pattern

The project follows a clear modular architecture:

src/
├── server.ts          # Entry point and orchestration
├── database/          # Persistence layer
│   ├── db.ts         # Database logic
│   └── schema.sql    # Table structure
├── tools/            # MCP Actions (Create, Update, Delete)
├── resources/        # MCP Data (Read-only)
├── prompts/          # LLM interaction templates
├── types/            # TypeScript schemas and types
└── utils/            # Cross-cutting utilities

Export Pattern

Each module exposes a consistent pattern:

// tools/index.ts
export const tools = [createTaskTool, updateTaskTool, ...];
export const toolHandlers = {
  create_task: handleCreateTask,
  // ...
};

Benefits:

✅ Centralized imports from main server
✅ Automatic discovery of new tools
✅ Type safety with object keys
✅ Simplified maintenance

Validation Pattern

Layered validation with Zod:

export async function handleCreateTask(args: any, db: TaskDatabase) {
  try {
    // 1. Schema validation
    const validatedArgs = CreateTaskSchema.parse(args);

    // 2. Business logic validation
    if (validatedArgs.due_date && new Date(validatedArgs.due_date) < new Date()) {
      throw new McpError(ErrorCode.INVALID_PARAMS, 'Due date cannot be in the past');
    }

    // 3. Database operation
    const task = await db.createTask(validatedArgs);

    return {
      task_id: `task-${task.id}`,
      status: task.status,
      created_at: task.created_at
    };
  } catch (error) {
    if (error instanceof z.ZodError) {
      throw new McpError(ErrorCode.INVALID_PARAMS, `Validation failed: ${error.message}`);
    }
    throw error;
  }
}

Database Pattern

Encapsulation with promisification:

async getTask(id: string): Promise<Task | null> {
  const sql = 'SELECT * FROM tasks WHERE id = ?';
  return new Promise((resolve, reject) => {
    this.db.get(sql, [id.replace('task-', '')], (err, row) => {
      if (err) reject(err);
      else if (!row) resolve(null);
      else resolve({
        ...row,
        id: `task-${row.id}`,
        tags: row.tags ? JSON.parse(row.tags) : []
      });
    });
  });
}

Applied patterns:

✅ Promisification of SQLite callbacks
✅ Data transformation (ID prefixing)
✅ Explicit null handling
✅ Type safety with TypeScript

12. Testing and Validation

Jest Configuration (`jest.config.js`)

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  roots: ['<rootDir>/src', '<rootDir>/tests'],
  testMatch: ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'],
  transform: {
    '^.+\\.ts$': 'ts-jest',
  },
  collectCoverageFrom: [
    'src/**/*.ts',
    '!src/**/*.d.ts',
  ],
  moduleFileExtensions: ['ts', 'js', 'json'],
};

Integration Tests (`tests/integration.test.ts`)

import { TaskDatabase } from '../src/database/db';
import { handleCreateTask } from '../src/tools/create-task';
import { handleTaskListResource } from '../src/resources/task-list';

describe('Task Manager Integration Tests', () => {
  let db: TaskDatabase;

  beforeEach(() => {
    // Use in-memory database for tests
    db = new TaskDatabase(':memory:');
  });

  test('Creating and retrieving a task', async () => {
    // Create a task
    const result = await handleCreateTask({
      title: 'Test Task',
      description: 'Task for testing',
      priority: 'high',
      tags: ['test', 'automation']
    }, db);

    expect(result.task_id).toBeDefined();
    expect(result.status).toBe('pending');

    // Retrieve task list
    const listResult = await handleTaskListResource(db);
    const tasks = JSON.parse(listResult.contents[0].text);

    expect(tasks.tasks).toHaveLength(1);
    expect(tasks.tasks[0].title).toBe('Test Task');
    expect(tasks.tasks[0].priority).toBe('high');
  });

  test('Error handling - non-existent task', async () => {
    const task = await db.getTask('task-999');
    expect(task).toBeNull();
  });
});

Manual Test Script (`scripts/test-mcp.js`)

#!/usr/bin/env node

const { spawn } = require('child_process');

function testMcpServer() {
  console.log('🧪 Testing MCP Task Manager server...\n');

  const server = spawn('npm', ['run', 'dev']);

  // Initialization test
  const initMessage = {
    jsonrpc: '2.0',
    id: 1,
    method: 'initialize',
    params: {
      protocolVersion: '1.0',
      clientInfo: { name: 'test-client', version: '1.0.0' }
    }
  };

  server.stdin.write(JSON.stringify(initMessage) + '\n');

  server.stdout.on('data', (data) => {
    try {
      const response = JSON.parse(data.toString());
      console.log('✅ Response received:', response);
    } catch (error) {
      console.log('📝 Output:', data.toString());
    }
  });

  server.stderr.on('data', (data) => {
    console.error('❌ Error:', data.toString());
  });

  // Stop after 5 seconds
  setTimeout(() => {
    server.kill();
    console.log('\n🏁 Test completed');
  }, 5000);
}

testMcpServer();

13. Docker Deployment

Multi-stage Dockerfile

Create an optimized Dockerfile with multi-stage build:

# Task Manager MCP Server Dockerfile
# Multi-stage build for optimized production image

# Stage 1: Build stage
FROM node:20-alpine AS builder

# Set working directory
WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies (including dev dependencies for building)
RUN npm ci

# Copy source code
COPY src/ ./src/
COPY tsconfig.json ./

# Build the application
RUN npm run build

# Stage 2: Production stage
FROM node:20-alpine AS production

# Install dumb-init for proper signal handling
RUN apk add --no-cache dumb-init

# Create app user for security
RUN addgroup -g 1001 -S mcpuser && \
    adduser -S mcpuser -u 1001

# Set working directory
WORKDIR /app

# Copy package files
COPY package*.json ./

# Install only production dependencies
RUN npm ci --only=production && \
    npm cache clean --force

# Copy built application from builder stage
COPY --from=builder /app/dist ./dist

# Create data directory for SQLite database
RUN mkdir -p /app/data && \
    chown -R mcpuser:mcpuser /app

USER mcpuser

# Expose the port for MCP server (HTTP mode by default)
EXPOSE 3000

# Set environment variables for HTTP mode
ENV MCP_TRANSPORT=http
ENV PORT=3000

# Health check for HTTP MCP server
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

# Use dumb-init to handle signals properly
ENTRYPOINT ["dumb-init", "--"]

# Start the MCP server
CMD ["node", "dist/server.js"]

.dockerignore File

The .dockerignore file optimizes Docker build context by excluding unnecessary files:

node_modules
npm-debug.log
.git
.gitignore
README.md
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
dist
coverage
*.md
.nyc_output
tasks.db

Why these exclusions?

node_modules/: Will be installed in the container
dist/: Will be generated during build
tasks.db: Local development database
.env* files: Prevents accidental inclusion of secrets
*.md: Documentation not needed in production

Docker Scripts in package.json

{
  "scripts": {
    "build": "tsc && mkdir -p dist/database && cp src/database/schema.sql dist/database/",
    "start": "node dist/server.js",
    "dev": "nodemon src/server.ts",
    "test": "jest",
    "docker:build": "docker build -t task-manager-mcp-server .",
    "docker:run": "docker run -d --name task-manager-mcp-server -p 3000:3000 task-manager-mcp-server",
    "docker:stop": "docker stop task-manager-mcp-server && docker rm task-manager-mcp-server",
    "docker:logs": "docker logs task-manager-mcp-server"
  }
}

HTTP API Endpoints

The server exposes the following endpoints:

Health Check

GET /health

Returns the server health status.

MCP Communication

POST /mcp
Content-Type: application/json

Example call to list tools:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Example call to create a task:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_task",
      "arguments": {
        "title": "New task",
        "description": "Task description",
        "priority": "high"
      }
    }
  }'

Deployment Commands

# Build Docker image
npm run docker:build

# Launch container
npm run docker:run

# View logs
npm run docker:logs

# Stop container
npm run docker:stop

# Build and run in one command
npm run docker:build && npm run docker:run

Production Configuration

Environment Variables

The .env.example file defines configuration variables:

NODE_ENV=production
MCP_TRANSPORT=http
PORT=3000
DB_PATH=/app/data/tasks.db
LOG_LEVEL=info

Variable descriptions:

NODE_ENV: Runtime environment (development/production)
MCP_TRANSPORT: Transport mode (http/stdio)
PORT: HTTP server listening port
DB_PATH: Path to SQLite database
LOG_LEVEL: Logging level (debug/info/warn/error)

Usage:

# Copy and customize
cp .env.example .env.production

# Use with Docker
docker run --env-file .env.production task-manager-mcp-server

Transport Mode

The server supports two modes:

HTTP (default): Communication via REST endpoints
STDIO: Communication via stdin/stdout (for direct integration)

Volume for Data Persistence

# Launch with persistent volume
docker run -d \
  --name task-manager-mcp-server \
  -p 3000:3000 \
  -v task-manager-data:/app/data \
  task-manager-mcp-server

Docker Compose (optional)

The docker-compose.yml file simplifies deployment and container management:

version: '3.8'

services:
  task-manager-mcp:
    build: .
    container_name: task-manager-mcp-server
    ports:
      - "3000:3000"
    volumes:
      - task-manager-data:/app/data
    environment:
      - NODE_ENV=production
      - MCP_TRANSPORT=http
      - PORT=3000
      - DB_PATH=/app/data/tasks.db
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  task-manager-data:
    driver: local

Docker Compose advantages:

Data persistence: Named volume for SQLite database
Automatic restart: restart: unless-stopped
HTTP health check: Automatic monitoring via /health
Centralized configuration: Environment variables defined
Simplified management: docker-compose up -d to start everything

Claude Desktop Integration

HTTP Configuration (recommended)

Modify Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "task-mcp": {
      "type": "http",
      "url": "http://localhost:3000"
    }
  }
}

Docker Configuration

To use the server via Docker:

{
  "mcpServers": {
    "task-mcp": {
      "type": "http",
      "url": "http://localhost:3000"
    }
  }
}

Then launch the container:

npm run docker:build
npm run docker:run

STDIO Configuration (alternative)

If you prefer to use stdio communication:

{
  "mcpServers": {
    "task-manager": {
      "command": "node",
      "args": ["/path/to/mcp-task-manager/dist/server.js"],
      "env": {
        "NODE_ENV": "production",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Monitoring and Maintenance

Monitoring with Health Check

The /health endpoint provides status information:

# Simple check
curl http://localhost:3000/health

# Response
{
  "status": "healthy",
  "timestamp": "2025-11-05T16:25:58.230Z"
}

Container Logs

# View logs in real-time
docker logs -f task-manager-mcp-server
npm run docker:logs

# View last lines
docker logs --tail 100 task-manager-mcp-server

Docker Metrics

# Container statistics
docker stats task-manager-mcp-server

# Complete inspection
docker inspect task-manager-mcp-server

Updates

# Method 1: NPM Scripts
npm run docker:stop
npm run docker:build
npm run docker:run

# Method 2: Docker Compose
docker-compose down
docker-compose build
docker-compose up -d

Data Backup

# Create volume backup
docker run --rm -v task-manager-data:/data -v $(pwd):/backup alpine tar czf /backup/tasks-backup.tar.gz -C /data .

# Restore backup
docker run --rm -v task-manager-data:/data -v $(pwd):/backup alpine tar xzf /backup/tasks-backup.tar.gz -C /data

Debug and Troubleshooting

# Access container
docker exec -it task-manager-mcp-server sh

# Check processes
docker exec task-manager-mcp-server ps aux

# Test connectivity
docker exec task-manager-mcp-server wget -qO- http://localhost:3000/health

14. Additional Resources

MCP Documentation

Development Tools

MCP Inspector - Debug tool
Postman MCP Collection - API tests

Possible Extensions

Authentication: JWT, OAuth 2.0
Webhooks: Real-time notifications
Integrations: Slack, Teams, GitHub Issues
Analytics: Advanced metrics, dashboards
REST API: Complementary HTTP interface

Practical Usage Examples

API Testing with curl

# 1. Start server
npm run docker:run

# 2. Check health
curl http://localhost:3000/health

# 3. List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# 4. Create a task
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_task",
      "arguments": {
        "title": "Implement authentication",
        "description": "Add JWT auth to MCP server",
        "priority": "high",
        "tags": ["security", "backend"],
        "assignee": "john.doe@example.com"
      }
    }
  }'

# 5. List tasks
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "resources/read",
    "params": {
      "uri": "task://list"
    }
  }'

# 6. View statistics
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "resources/read",
    "params": {
      "uri": "task://stats"
    }
  }'

Script Integration

#!/bin/bash
# create-task.sh - Script to create tasks via API

TITLE="$1"
DESCRIPTION="$2"
PRIORITY="${3:-medium}"

if [ -z "$TITLE" ]; then
  echo "Usage: $0 <title> [description] [priority]"
  exit 1
fi

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d "{
    \"jsonrpc\": \"2.0\",
    \"id\": 1,
    \"method\": \"tools/call\",
    \"params\": {
      \"name\": \"create_task\",
      \"arguments\": {
        \"title\": \"$TITLE\",
        \"description\": \"$DESCRIPTION\",
        \"priority\": \"$PRIORITY\"
      }
    }
  }" | jq '.'

Usage Examples

# Local development
npm run dev

# Build and test Docker image
npm run docker:build
npm run docker:run
npm run docker:logs

# With docker-compose
docker-compose up -d
docker-compose logs -f

# Production with persistent volume
docker run -d \
  --name task-manager-mcp-server \
  -v $(pwd)/data:/app/data \
  task-manager-mcp-server

🎯 Conclusion

This tutorial has guided you through creating a complete professional MCP Task Manager server. You now have:

✅ Complete MCP Architecture

4 Tools: Create, update, complete, delete tasks
3 Resources: List, statistics, task details
2 Prompts: Weekly review, sprint planning
Zod Validation: Type safety and robust validation

✅ Production-Ready Infrastructure

Hybrid HTTP/STDIO server with REST endpoints
SQLite database with optimized schema
Multi-stage Docker with non-root user
Health checks and integrated monitoring
CORS and error handling professional-grade

✅ Automated Deployment

NPM scripts for Docker (build, run, stop, logs)
Docker Compose with persistent volumes
Configurable environment variables
HTTP health checks for monitoring

✅ Claude Desktop Configuration

{
  "mcpServers": {
    "task-mcp": {
      "type": "http",
      "url": "http://localhost:3000"
    }
  }
}

🚀 Implemented Features

Tools (Actions)

create_task: Creation with complete validation
update_task: Modification with completed task protection
complete_task: Finalization with notes and time tracking
delete_task: Secure deletion with confirmation

Resources (Data)

task://list: Overview with metadata
task://stats: Dashboards and metrics
task://detail/{id}: Detailed information per task

Prompts (LLM Templates)

weekly_review: Weekly performance analysis
sprint_planning: Task planning and distribution

🔧 Extensibility

The modular architecture facilitates adding new features:

// New tool in src/tools/
export const archiveTaskTool: Tool = { /* ... */ };
export async function handleArchiveTask(args: any, db: TaskDatabase) { /* ... */ }

// New resource in src/resources/
export const taskCalendarResource: Resource = { /* ... */ };
export async function handleTaskCalendarResource(db: TaskDatabase) { /* ... */ }

// New prompt in src/prompts/
export const standupPrompt: Prompt = { /* ... */ };
export async function handleStandupPrompt(args: any, db: TaskDatabase) { /* ... */ }

🛠 Suggested Next Steps

Authentication and Authorization

   // JWT middleware to secure API
   import jwt from 'jsonwebtoken';

   const authMiddleware = (req, res, next) => {
     const token = req.headers.authorization?.split(' ')[1];
     if (!token || !jwt.verify(token, process.env.JWT_SECRET)) {
       return res.status(401).json({ error: 'Unauthorized' });
     }
     next();
   };

External Integrations

   // Webhooks for notifications
   export const webhookTool: Tool = {
     name: 'setup_webhook',
     description: 'Configure external notifications',
     // ...
   };

   // Calendar synchronization
   export const calendarSyncTool: Tool = {
     name: 'sync_calendar',
     description: 'Synchronize with Google Calendar/Outlook',
     // ...
   };

Web Interface (Optional)

   # React/Vue frontend for administration
   npm create vite@latest task-manager-ui -- --template react-ts
   cd task-manager-ui
   npm install axios @tanstack/react-query

Advanced Database

   // Migration to PostgreSQL for production
   import { Pool } from 'pg';

   export class PostgresTaskDatabase extends TaskDatabase {
     private pool: Pool;
     // ...
   }

Analytics and Monitoring

   // Prometheus metrics
   import prometheus from 'prom-client';

   const taskCreationCounter = new prometheus.Counter({
     name: 'tasks_created_total',
     help: 'Total number of tasks created'
   });

The MCP Task Manager server is now ready for production use and can serve as a solid foundation for more complex task management and productivity applications!

📚 Reference Documentation

Conventional Changelog support

Fairen — Mon, 31 Aug 2020 12:43:09 +0000

Photo by Daniel McCullough on Unsplash

Introduction

This post takes place in a series aiming to show how to build an Angular application from scratch.

We will see how to scaffold an enterprise-scale angular application with all the assets needed to easily develop and maintain it.

This post will show you how to add support for conventional changelog generation for your application on Gitlab and add it to your CI tool chain.

Our goal will be to automate changelog generation on the master branch and generate a tag with the changelog updated :

[Manual] Merge develop to master (by Pull Request).
[Manual] Tag master with prerelease-X.Y.Z (on Gitlab or with git cli).
[Automatic] CI triggered to update CHANGELOG.md and package.json + remove prerelease-X.Y.Z tag.
[Automatic] Push to master and add tag X.Y.Z, release ready.

Git Workflow

git checkout develop
git pull
# Retrieve the last develop version

git checkout -b feature/changelog
# Feature Branch creation

Make your repository Comitizen friendly

First, install the Commitizen cli tools:

npm install commitizen --save --save-exact --save-dev

Next, initialize your project to use the cz-conventional-changelog adapter by typing:

commitizen init cz-conventional-changelog --save-dev --save-exact

The above command does three things for you.

Installs the cz-conventional-changelog adapter npm module.
Saves it to package.json's dependencies or devDependencies.
Adds the config.commitizen key to the root of your package.json as shown here:

...
    "devDependencies": {
        ....
        "cz-conventional-changelog": "^3.1.0",
    }
...
    "config": {
        "commitizen": {
            "path": "./node_modules/cz-conventional-changelog"
        }
    }
...

This just tells Commitizen which adapter we actually want our contributors to use when they try to commit to this repo.

Use Comitizen

Add comitizen script to your package.json.

    "scripts": {
        ...
        "commit": "git-cz"
        ...
    },

Use npm run commit instead of git commit to enjoy!

When you're working in a Commitizen friendly repository, you'll be prompted to fill in any required fields and your commit messages will be formatted according to the standards you defined above.

Use Conventional Changelog

Install the Conventional Changelog CLI :

npm install conventional-changelog-cli --save --save-exact --save-dev

Update your package.json to include the followings script :

"scripts": {
    ...
    "init-changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
    "version": "conventional-changelog -p angular -i CHANGELOG.md -s && git add CHANGELOG.md"
    ...
}

Initialise the Changelog :

npm run init-changelog

Update your Node configuration

With the new npm script version, we will add some logic to the npm versionlife-cyle. The .npmrc file helps us to define some variables used when npm version is called.

Update your .npmrc file or create one with :

tag-version-prefix=""
message="chore(release): Version %s"

For more informations about the npm versionlife-cycle, refer to :
https://docs.npmjs.com/cli/version

Update your CI

Generate your GitLab access token

Go to your Gitlab, User Settings > Access Token and create a new token named GIT_ACCESS_TOKEN with the api scope checked.
Your new personal access token will be prompt, save it :

Now, go to your project Settings > CI/CD panel

Expand the Variable panel and click on Add Variable.

Name the variable GIT_ACCESS_TOKEN and past the personal access token saved from before, make sure protected and masked are unchecked.

The variable $GIT_ACCESS_TOKEN can now be accessed from your CI jobs and enable credential to write/read your git repository.

Update your CI jobs

Update your .gitlab-ci.yml to add a publish-version step.
This step will be triggered when tagging your code with prerelease-X.Y.Z tags (ie. prerelease-1.0.0).

It will :

Retrieve the current prerelease-X.Y.Z tag.
Update your application version (in package.json, package-lock.json and npm-shrinkwrap.json) to the X.Y.Z value.
Run the npm version command and commit and tag in git.
Under the hood, run the version script defined above to update the CHANGELOG.md and add it to the commit.
Remove the prerelease-X.Y.Z tag from your repository.
Add the updated file to git and push the modifications to the master branch and tag it as X.Y.Z.

image: node:latest

stages:
  - CodeQuality
  - Release

test:
  stage: CodeQuality
  script: 
    - npm ci
    - npm run ci:test

lint:
  stage: CodeQuality
  script:
    - npm ci
    - npm run ci:lint

publish-version:
  image: node:12.16.1
  stage: Release
  rules:
     - if: '$CI_COMMIT_TAG =~ /^prerelease-\d+.\d+.\d+/'
  before_script:
    - npm ci
    - npm config set unsafe-perm true
  script:
    - TAG_VERSION=`echo $CI_COMMIT_TAG | sed "s/.*prerelease-\([^ ]*\).*/\1/"`
    - git config --global user.name "$GITLAB_USER_NAME"
    - git config --global user.email "$GITLAB_USER_EMAIL"
    - git remote set-url origin "https://gitlab-ci-token:$GIT_ACCESS_TOKEN@$CI_SERVER_HOST/$CI_PROJECT_PATH.git"
    - git tag -d $CI_COMMIT_TAG
    - git push origin --delete $CI_COMMIT_TAG
    - npm version $TAG_VERSION
    - git push origin HEAD:master --tags

Push your modifications.

git add package.json package-lock.json .gitlab-ci.yml CHANGELOG.md .npmrc

# Use the magic !!
npm run commit

git push -u origin feature/changelog

Each time you tag your master branch with a tag prerelease-X.Y.Z, the CI will take care of updating your application version and generating the corresponding Changelog.

Setup a basic CI

Fairen — Wed, 29 Jul 2020 09:48:49 +0000

Photo by Daniel McCullough on Unsplash

Introduction

This post takes place in a series aiming to show how to build an angular application from scratch.

We will see how to scaffold an enterprise-scale angular application with all the assets needed to easily develop and maintain it.

This post will show you how to setup a basic CI toolchain (test and lint your code) for your application on Gitlab.

Git Workflow

git checkout master
git pull
# Retrieve the last master version

git checkout -b develop
# Branch develop creation

Setup tests scripts

We will need to adapt our testing environment to work on the Gitlab CI environment.

Add the follwing lines to your package.json :

"scripts": {
    ...
    "ci:test": "ng test --browsers PhantomJS --watch=false",
    "ci:lint": "ng lint",
    ...
}

Add PhantomJs support :

npm install karma-phantomjs-launcher phantomjs core-js --save --save-exact

Update `karma.conf.js` :

plugins: [
    ...,
    require('karma-phantomjs-launcher')
],

Update `polyfill.ts` :

# Add core-js imports
import 'core-js/es/symbol';
import 'core-js/es/object';
import 'core-js/es/function';
import 'core-js/es/parse-int';
import 'core-js/es/parse-float';
import 'core-js/es/number';
import 'core-js/es/math';
import 'core-js/es/string';
import 'core-js/es/date';
import 'core-js/es/array';
import 'core-js/es/regexp';
import 'core-js/es/map';
import 'core-js/es/weak-map';
import 'core-js/es/set';

# Uncomment zone polyfills
(window as any).__Zone_disable_requestAnimationFrame = true; // disable patch requestAnimationFrame
(window as any).__Zone_disable_on_property = true; // disable patch onProperty such as onclick
(window as any).__zone_symbol__BLACK_LISTED_EVENTS = ['scroll', 'mousemove']; // disable patch specified eventNames
(window as any).__Zone_enable_cross_context_check = true;

Update your `tsconfig.json` :

{
  "compileOnSave": false,
  "compilerOptions": {
    "baseUrl": "./",
    "outDir": "./dist/out-tsc",
    "sourceMap": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "declaration": false,
    "module": "es2015",
    "moduleResolution": "node",
    "target": "es5",
    "typeRoots": [
      "node_modules/@types"
    ],
    "lib": [
      "es2017",
      "es2019",
      "dom",
      "esnext.asynciterable"
    ],
    "resolveJsonModule": true
  }
}

Write your CI configuration file

Create a file .gitlab-ci.yml with the following content :

image: node:latest

stages:
  - CodeQuality

test:
  stage: CodeQuality
  script: 
    - npm ci
    - npm run ci:test

lint:
  stage: CodeQuality
  script:
    - npm ci
    - npm run ci:lint

Each time someone commit on a branch, the CodeQuality stages above will be triggerred.

From the NPM documentation about npm ci:
This command is similar to npm install, except it’s meant to be used in automated environments such as test platforms, continuous integration, and deployment – or any situation where you want to make sure you’re doing a clean install of your dependencies. It can be significantly faster than a regular npm install by skipping certain user-oriented features. It is also more strict than a regular install, which can help catch errors or inconsistencies caused by the incrementally-installed local environments of most npm users.

Push your modifications

git add .gitlab-ci.yml package.json package-lock.json karma.conf.js src/polyfills.ts tsconfig.json
git commit -m "core(ci): Add gitlab CI file and scripts"
git push -u origin develop

Check your CI

For now, your CI will run

npm run ci:test

and

npm run ci:lint

You can now follow the state of your CI on Gitlab.
Go to CI/CD > Pipelines :

Click on the corresponding pipeline to show the stages details :

Create your repository

Fairen — Tue, 28 Jul 2020 12:35:21 +0000

Photo by Daniel McCullough on Unsplash

Introduction

This post takes place in a series aiming to show how to build an angular application from scratch.
We will see how to scaffold an enterprise-scale angular application with all the assets needed to easily develop and maintain it.

This post doesn't dive deep into how git nor gitlab works. For more informations about them, refer to their documentations.

This post will show you how to setup a gitlab repository and push your application created before.

Create your project on Gitlab

Create a new project :

Setup the project configuration :

Upload your first commit

To upload your existing files generated by angular cli use the instructions bellow.

Git global setup

git config --global user.name "<your_gitlab_username>" 
git config --global user.email "<your_gitlab_email>"

Push an existing folder

cd ng-shadow
git remote add origin https://gitlab.com/<your_gitlab_username>/ng-shadow.git
git push -u origin master

Create an Angular application

Fairen — Mon, 27 Jul 2020 14:17:01 +0000

Photo by Daniel McCullough on Unsplash

Introduction

This post is a first of a series aiming to show how to build an angular application from scratch.
We will see how to scaffold an enterprise-scale angular application with all the assets needed to easily develop and maintain it.

This first post doesn't dive deep into how git, node nor angular-cli works. It paraphrases their documentations and gather the informationinto one post. For more informations about them, refer to their documentations.

Getting Started

Start by creating a new angular workspace and application using git & angular-cli.

Install Git

Follow the instruction here.

Install Nodejs and Npm

Install Nodejs and Npm here.

You can find a lot of great article on dev.to to help you install Nodejs and Npm if you have any trouble with the official documentation.

Install NVM (Linux only, sorry not sorry :p)

NVM helps you install and change the node version used according to the directory/project you are working in.

To install or update nvm, you should run the install script. To do that, you may either download and run the script manually, or use the following cURL or Wget command:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash

Running either of the above commands downloads a script and runs it. The script clones the nvm repository to ~/.nvm, and attempts to add the source lines from the snippet below to the correct profile file (~/.bash_profile, ~/.zshrc, ~/.profile, or ~/.bashrc).

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

To use it :

nvm install 10 # only install a version once
nvm use 10 # nvm use 8, adapt on the project your work

Install the latest Angular CLI

Install the Angular CLI globally.
To install the CLI using npm, open a terminal/console window and enter the following command:

npm install -g @angular/cli

Create a workspace and initial application

You develop apps in the context of an Angular workspace.
To create a new workspace and initial starter app:
Run the CLI command ng new and provide the application name (ie. ng-shadow), as shown here:

ng new ng-shadow

The ng new command prompts you for information about features to include in the initial app. Accept the defaults (except for stylesheet by chosing SCSS) by pressing the Enter or Return key.
The Angular CLI installs the necessary Angular npm packages and other dependencies. This can take a few minutes.
The CLI creates a new workspace and a simple Welcome app, ready to run.

Run the application

The Angular CLI includes a server, so that you can easily build and serve your app locally.
Go to the workspace folder (ie. ng-shadow).
Launch the server by using the CLI command ng serve, with the --open option.

cd ng-shadow
ng serve --open

The ng serve command launches the server, watches your files, and rebuilds the app as you make changes to those files.

The --open (or just -o) option automatically opens your browser to http://localhost:4200/.

DEV Community: Fairen

Complete Tutorial: Creating an MCP Task Manager Server from Scratch

📖 Table of Contents

1. Introduction to Model Context Protocol (MCP)

What is MCP?

Main Components

MCP Session Lifecycle

2. Prerequisites and Installation

Required Technologies

Installation

3. Project Structure

4. Basic Configuration

package.json

tsconfig.json

5. MCP Server Implementation

Basic Types (src/types/task.ts)

Database Configuration (src/database/db.ts)

Database Schema (src/database/schema.sql)

6. Endpoints: Tools

Task Creation (src/tools/create-task.ts)

Task Update (src/tools/update-task.ts)

Task Completion (src/tools/complete-task.ts)

Task Deletion (src/tools/delete-task.ts)

Tools Export (src/tools/index.ts)

7. Endpoints: Resources

Task List (src/resources/task-list.ts)

Statistics (src/resources/task-stats.ts)

Task Detail (src/resources/task-detail.ts)

Resources Export (src/resources/index.ts)

8. Endpoints: Prompts

Weekly Review (src/prompts/weekly-review.ts)

Sprint Planning (src/prompts/sprint-planning.ts)

Prompts Export (src/prompts/index.ts)

9. Error Handling

Error Codes (src/utils/errors.ts)

10. Main Server

Hybrid HTTP/STDIO Architecture

1. HTTP Mode (Recommended)

2. STDIO Mode (Legacy)

MCP Request Handling

Centralized Error Handling

Main Entry Point (src/server.ts)

Advanced Error Handling Pattern

Resource Caching Pattern

11. Code Organization and Patterns

Structuring Pattern

Export Pattern

Validation Pattern

Database Pattern

12. Testing and Validation

Jest Configuration (jest.config.js)

Integration Tests (tests/integration.test.ts)

Manual Test Script (scripts/test-mcp.js)

13. Docker Deployment

Multi-stage Dockerfile

.dockerignore File

Docker Scripts in package.json

HTTP API Endpoints

Health Check

MCP Communication

Deployment Commands

Production Configuration

Environment Variables

Transport Mode

Volume for Data Persistence

Docker Compose (optional)

Claude Desktop Integration

HTTP Configuration (recommended)

Docker Configuration

STDIO Configuration (alternative)

Monitoring and Maintenance

Monitoring with Health Check

Container Logs

Docker Metrics

Updates

Data Backup

Debug and Troubleshooting

14. Additional Resources

MCP Documentation

Development Tools

Basic Types (`src/types/task.ts`)

Database Configuration (`src/database/db.ts`)

Database Schema (`src/database/schema.sql`)

Task Creation (`src/tools/create-task.ts`)

Task Update (`src/tools/update-task.ts`)

Task Completion (`src/tools/complete-task.ts`)

Task Deletion (`src/tools/delete-task.ts`)

Tools Export (`src/tools/index.ts`)

Task List (`src/resources/task-list.ts`)

Statistics (`src/resources/task-stats.ts`)

Task Detail (`src/resources/task-detail.ts`)

Resources Export (`src/resources/index.ts`)

Weekly Review (`src/prompts/weekly-review.ts`)

Sprint Planning (`src/prompts/sprint-planning.ts`)

Prompts Export (`src/prompts/index.ts`)

Error Codes (`src/utils/errors.ts`)

Main Entry Point (`src/server.ts`)

Jest Configuration (`jest.config.js`)

Integration Tests (`tests/integration.test.ts`)

Manual Test Script (`scripts/test-mcp.js`)

Update `karma.conf.js` :

Update `polyfill.ts` :

Update your `tsconfig.json` :