Glama
Todo List MCP Server

# Todo List MCP Server: A Learning Guide

## Introduction to Model Context Protocol (MCP)

The Model Context Protocol (MCP) is a specification that enables AI models like Claude to interact with external tools and services. It creates a standardized way for LLMs to discover, understand, and use tools provided by separate processes.

### Why MCP Matters

1. **Extended Capabilities**: MCP allows AI models to perform actions beyond just generating text (database operations, file management, API calls, etc.)
2. **Standardization**: Creates a consistent interface for tools regardless of implementation
3. **Controlled Access**: Provides a secure way to expose specific functionality to AI models
4. **Real-time Integration**: Enables AI to access up-to-date information and perform real-world actions

## 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:

1. How to structure an MCP server project
2. How to implement CRUD operations via MCP tools
3. Best practices for error handling and validation
4. How to format responses for AI consumption
5. 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:

```typescript
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:

```typescript
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:

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

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

## How to Learn from This Project

### For Beginners

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

### For Intermediate Developers

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

### For Advanced Developers

1. Consider how this approach could be extended for more complex applications
2. Think about how to add authentication, caching, or more advanced features
3. Look at the client implementation to understand the full MCP communication cycle
4. 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:

```bash
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`:

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

## Common Patterns and Best Practices Demonstrated

1. **Singleton Pattern**: Used for database and service access
2. **Repository Pattern**: Abstracts data access operations
3. **Factory Pattern**: Creates new Todo objects with consistent structure
4. **Validation Pattern**: Validates inputs before processing
5. **Error Handling Pattern**: Centralizes and standardizes error handling
6. **Formatting Pattern**: Consistently formats outputs for consumption
7. **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. 