About This Project

This Todo List MCP Server is designed to be a clear, educational example of how to build an MCP server. It implements a complete todo list management system that can be used by Claude or other MCP-compatible systems.

Learning Objectives

By studying this codebase, you can learn:

• How to structure an MCP server project
• How to implement CRUD operations via MCP tools
• Best practices for error handling and validation
• How to format responses for AI consumption
• How the MCP protocol works in practice

Codebase Structure and Design Philosophy

The project follows several key design principles:

1. Clear Separation of Concerns

The codebase is organized into distinct layers:

• Models (src/models/): Data structures and validation schemas
• Services (src/services/): Business logic and data access
• Utils (src/utils/): Helper functions and formatters
• Entry Point (src/index.ts): MCP server definition and tool implementations

This separation makes the code easier to understand, maintain, and extend.

2. Type Safety and Validation

The project uses TypeScript and Zod for comprehensive type safety:

• TypeScript Interfaces: Define data structures with static typing
• Zod Schemas: Provide runtime validation with descriptive error messages
• Consistent Validation: Each operation validates its inputs before processing

3. Error Handling

A consistent error handling approach is used throughout:

• Central Error Processing: The safeExecute function standardizes error handling
• Descriptive Error Messages: All errors provide clear context about what went wrong
• Proper Error Responses: Errors are formatted according to MCP requirements

4. Data Persistence

The project uses SQLite for simple but effective data storage:

• File-based Database: Easy to set up with no external dependencies
• SQL Operations: Demonstrates parameterized queries and basic CRUD operations
• Singleton Pattern: Ensures a single database connection throughout the application

Key Implementation Patterns

The Tool Definition Pattern

Every MCP tool follows the same pattern:

server.tool(
  "tool-name",            // Name: How the tool is identified
  "Tool description",     // Description: What the tool does
  { /* parameter schema */ },  // Schema: Expected inputs with validation
  async (params) => {     // Handler: The implementation function
    // 1. Validate inputs
    // 2. Execute business logic
    // 3. Format and return response
  }
);

Error Handling Pattern

The error handling pattern ensures consistent behavior:

const result = await safeExecute(() => {
  // Operation that might fail
}, "Descriptive error message");

if (result instanceof Error) {
  return createErrorResponse(result.message);
}

return createSuccessResponse(formattedResult);

Response Formatting Pattern

Responses are consistently formatted for easy consumption by LLMs:

// Success responses
return createSuccessResponse(`✅ Success message with ${formattedData}`);

// Error responses
return createErrorResponse(`Error: ${errorMessage}`);

How to Learn from This Project

For Beginners

• Start by understanding the Todo model in src/models/Todo.ts
• Look at how tools are defined in src/index.ts
• Explore the basic CRUD operations in src/services/TodoService.ts
• See how responses are formatted in src/utils/formatters.ts

For Intermediate Developers

• Study the error handling patterns throughout the codebase
• Look at how validation is implemented with Zod schemas
• Examine the database operations and SQL queries
• Understand how the MCP tools are organized and structured

For Advanced Developers

• Consider how this approach could be extended for more complex applications
• Think about how to add authentication, caching, or more advanced features
• Look at the client implementation to understand the full MCP communication cycle
• Consider how to implement testing for an MCP server

Running and Testing

Local Testing

Use the provided test client to see the server in action:

npm run build
node dist/client.js

This will run through a complete lifecycle of creating, updating, completing, and deleting a todo.

Integration with Claude for Desktop

To use this server with Claude for Desktop, add it to your claude_desktop_config.json:

{
  "mcpServers": {
    "todo": {
      "command": "node",
      "args": ["/absolute/path/to/todo-list-mcp/dist/index.js"]
    }
  }
}

Common Patterns and Best Practices Demonstrated

• Singleton Pattern: Used for database and service access
• Repository Pattern: Abstracts data access operations
• Factory Pattern: Creates new Todo objects with consistent structure
• Validation Pattern: Validates inputs before processing
• Error Handling Pattern: Centralizes and standardizes error handling
• Formatting Pattern: Consistently formats outputs for consumption
• Configuration Pattern: Centralizes application settings

Conclusion

This Todo List MCP Server demonstrates a clean, well-structured approach to building an MCP server. By studying the code and comments, you can gain a deep understanding of how MCP works and how to implement your own MCP servers for various use cases.

The project emphasizes not just what code to write, but why specific approaches are taken, making it an excellent learning resource for understanding both MCP and general best practices in TypeScript application development.

About This Project

This Todo List MCP Server is designed to be a clear, educational example of how to build an MCP server. It implements a complete todo list management system that can be used by Claude or other MCP-compatible systems.

Learning Objectives

By studying this codebase, you can learn:

• How to structure an MCP server project
• How to implement CRUD operations via MCP tools
• Best practices for error handling and validation
• How to format responses for AI consumption
• How the MCP protocol works in practice

Codebase Structure and Design Philosophy

The project follows several key design principles:

1. Clear Separation of Concerns

The codebase is organized into distinct layers:

• Models (src/models/): Data structures and validation schemas
• Services (src/services/): Business logic and data access
• Utils (src/utils/): Helper functions and formatters
• Entry Point (src/index.ts): MCP server definition and tool implementations

This separation makes the code easier to understand, maintain, and extend.

2. Type Safety and Validation

The project uses TypeScript and Zod for comprehensive type safety:

• TypeScript Interfaces: Define data structures with static typing
• Zod Schemas: Provide runtime validation with descriptive error messages
• Consistent Validation: Each operation validates its inputs before processing

3. Error Handling

A consistent error handling approach is used throughout:

• Central Error Processing: The safeExecute function standardizes error handling
• Descriptive Error Messages: All errors provide clear context about what went wrong
• Proper Error Responses: Errors are formatted according to MCP requirements

4. Data Persistence

The project uses SQLite for simple but effective data storage:

• File-based Database: Easy to set up with no external dependencies
• SQL Operations: Demonstrates parameterized queries and basic CRUD operations
• Singleton Pattern: Ensures a single database connection throughout the application

Key Implementation Patterns

The Tool Definition Pattern

Every MCP tool follows the same pattern:

server.tool(
  "tool-name",            // Name: How the tool is identified
  "Tool description",     // Description: What the tool does
  { /* parameter schema */ },  // Schema: Expected inputs with validation
  async (params) => {     // Handler: The implementation function
    // 1. Validate inputs
    // 2. Execute business logic
    // 3. Format and return response
  }
);

Error Handling Pattern

The error handling pattern ensures consistent behavior:

const result = await safeExecute(() => {
  // Operation that might fail
}, "Descriptive error message");

if (result instanceof Error) {
  return createErrorResponse(result.message);
}

return createSuccessResponse(formattedResult);

Response Formatting Pattern

Responses are consistently formatted for easy consumption by LLMs:

// Success responses
return createSuccessResponse(`✅ Success message with ${formattedData}`);

// Error responses
return createErrorResponse(`Error: ${errorMessage}`);

How to Learn from This Project

For Beginners

• Start by understanding the Todo model in src/models/Todo.ts
• Look at how tools are defined in src/index.ts
• Explore the basic CRUD operations in src/services/TodoService.ts
• See how responses are formatted in src/utils/formatters.ts

For Intermediate Developers

• Study the error handling patterns throughout the codebase
• Look at how validation is implemented with Zod schemas
• Examine the database operations and SQL queries
• Understand how the MCP tools are organized and structured

For Advanced Developers

• Consider how this approach could be extended for more complex applications
• Think about how to add authentication, caching, or more advanced features
• Look at the client implementation to understand the full MCP communication cycle
• Consider how to implement testing for an MCP server

Running and Testing

Local Testing

Use the provided test client to see the server in action:

npm run build
node dist/client.js

This will run through a complete lifecycle of creating, updating, completing, and deleting a todo.

Integration with Claude for Desktop

To use this server with Claude for Desktop, add it to your claude_desktop_config.json:

{
  "mcpServers": {
    "todo": {
      "command": "node",
      "args": ["/absolute/path/to/todo-list-mcp/dist/index.js"]
    }
  }
}

Common Patterns and Best Practices Demonstrated

• Singleton Pattern: Used for database and service access
• Repository Pattern: Abstracts data access operations
• Factory Pattern: Creates new Todo objects with consistent structure
• Validation Pattern: Validates inputs before processing
• Error Handling Pattern: Centralizes and standardizes error handling
• Formatting Pattern: Consistently formats outputs for consumption
• Configuration Pattern: Centralizes application settings

Conclusion

This Todo List MCP Server demonstrates a clean, well-structured approach to building an MCP server. By studying the code and comments, you can gain a deep understanding of how MCP works and how to implement your own MCP servers for various use cases.

The project emphasizes not just what code to write, but why specific approaches are taken, making it an excellent learning resource for understanding both MCP and general best practices in TypeScript application development.