MCP Todo Server

This project is a demonstration of a clean architecture implementation using Node.js and TypeScript. It utilizes the MCPServer from the@modelcontextprotocol/sdkto create a server and manage todos through a JSON placeholder API.

This project is built with modern technologies and follows clean architecture principles:

- Node.js: Runtime environment for executing JavaScript code server-side
- TypeScript: Strongly typed programming language that builds on JavaScript
- Model Context Protocol (MCP): Protocol for AI models to interact with external tools and data sources

- @modelcontextprotocol/sdk: Official SDK for creating MCP-compliant servers
- Zod: TypeScript-first schema validation library used for input validation

- Jest: JavaScript testing framework
- Supertest: HTTP assertions library for testing API endpoints

- tsx: TypeScript execution environment with native ESM support
- tsc-alias: Tool for resolving TypeScript path aliases during compilation
- ts-node: TypeScript execution engine for Node.js

- Clean Architecture: The project follows a clean architecture approach with:

- Domain layer: Core business logic and entities
- Application layer: Use cases and application services
- Infrastructure layer: External interactions and implementations
- Presentation layer: API endpoints and request/response handling

- JSONPlaceholder: RESTful API for testing and prototyping providing fake todo data

The following diagram shows how requests flow through the MCP Todo Server:

sequenceDiagram participant Client as MCP Client/Inspector participant Server as McpServer participant Handler as TodoHandlers participant Service as TodoService participant Repository as JsonPlaceholderTodoRepository participant API as JSONPlaceholder API Client->>Server: Tool Call Request (e.g., get_todos) alt Get All Todos Server->>Service: todoService.getAllTodos() Service->>Repository: todoRepository.findAll() Repository->>API: fetch('https://jsonplaceholder.typicode.com/todos') API-->>Repository: JSON Response Repository-->>Service: Todo[] entities Service-->>Server: Todo[] entities Server-->>Client: Formatted JSON Response else Get Todo by ID Client->>Server: get_todo_by_id with id parameter Server->>Service: todoService.getTodoById(id) Service->>Repository: todoRepository.findById(id) Repository->>API: fetch('https://jsonplaceholder.typicode.com/todos/{id}') API-->>Repository: JSON Response Repository-->>Service: Todo entity Service-->>Server: Todo entity Server-->>Client: Formatted JSON Response else Create Todo Client->>Server: create_todo with title, completed Server->>Service: todoService.createTodo(data) Service->>Repository: todoRepository.create(data) Repository->>API: POST fetch('https://jsonplaceholder.typicode.com/todos') API-->>Repository: JSON Response Repository-->>Service: New Todo entity Service-->>Server: New Todo entity Server-->>Client: Formatted JSON Response else Update Todo Client->>Server: update_todo with id, title, completed Server->>Service: todoService.updateTodo(id, data) Service->>Repository: todoRepository.update(id, data) Repository->>API: PUT fetch('https://jsonplaceholder.typicode.com/todos/{id}') API-->>Repository: JSON Response Repository-->>Service: Updated Todo entity Service-->>Server: Updated Todo entity Server-->>Client: Formatted JSON Response else Delete Todo Client->>Server: delete_todo with id Server->>Service: todoService.deleteTodo(id) Service->>Repository: todoRepository.delete(id) Repository->>API: DELETE fetch('https://jsonplaceholder.typicode.com/todos/{id}') API-->>Repository: Response status Repository-->>Service: Boolean result Service-->>Server: Boolean result Server-->>Client: Success/Failure message end

mcp-todo-server ├── src │ ├── domain │ │ ├── entities │ │ │ └── todo.ts │ │ ├── repositories │ │ │ └── todoRepository.ts │ │ └── valueObjects │ │ └── todoId.ts │ ├── application │ │ ├── services │ │ │ └── todoService.ts │ │ └── useCases │ │ ├── createTodo.ts │ │ ├── deleteTodo.ts │ │ ├── getTodoById.ts │ │ ├── getTodos.ts │ │ └── updateTodo.ts │ ├── infrastructure │ │ ├── repositories │ │ │ └── jsonPlaceholderTodoRepository.ts │ │ └── http │ │ └── httpClient.ts │ ├── presentation │ │ └── handlers │ │ └── todoHandlers.ts │ ├── server.ts │ └── index.ts ├── tests │ ├── unit │ │ ├── domain │ │ │ └── entities │ │ │ └── todo.test.ts │ │ ├── application │ │ │ └── services │ │ │ └── todoService.test.ts │ │ └── infrastructure │ │ └── repositories │ │ └── jsonPlaceholderTodoRepository.test.ts │ └── integration │ └── server.test.ts ├── http │ └── todo-api.http ├── package.json ├── tsconfig.json ├── jest.config.js └── README.md

git clone <repository-url> cd mcp-todo-server

The server exposes various endpoints for managing todos. You can use the providedhttp/todo-api.httpfile to test the API endpoints manually.

MCP Inspector is a tool that allows you to interact with MCP-compliant servers directly, testing tool calls and viewing responses without needing to integrate with an AI model.

npm install -g @modelcontextprotocol/inspector

# 1. First, build and start MCP Todo server: npm run build npm start # 2. In a separate terminal, run MCP Inspector and connect it to mcp todo server: mcp-inspector --server "node ./build/index.js" or npx @modelcontextprotocol/inspector node build/index.js # Alternatively, if mcp todo server is already running, can pipe it to the inspector: node ./build/index.js | mcp-inspector # 3. Once connected, the inspector will open in your default web browser, allowing you to: # Browse available tools # Execute tool calls with custom parameters # View responses in a formatted JSON view # Debug request/response cycles

Navigate to the Extensions or AI Tools section

Find "Model Context Protocol" or "MCP Tools" settings mcp.json

{ "mcpServers": { ... other mcp server, "todo-mcp-server": { "command": "node", "args": [ "D:\\dev\\node\\mcp-todo-server\\build\\index.js" ] } } }

To run the unit and integration tests, use the following command:

This project is licensed under the MIT License.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

One shared context layer for AI agents and humans — live API specs, DB schemas, and versioned contracts across repos so every agent and teammate works from the same source of truth.

The MCP server for Bitrix24 provides AI assistants with structured access to the Bitrix24 API. It delivers up-to-date method descriptions, parameters, and valid values, allowing assistants to work with precise data instead of guesswork. This reduces code errors and accelerates Bitrix24 integration development.

Official MCP server for Buildable AI-powered development platform. Enables AI assistants to manage tasks, track progress, get project context, and collaborate with humans on software projects.

Tool platform by IBM to build, test and deploy tools for any data source

One remote MCP server for 500+ production APIs — Stripe, HubSpot, Postgres, Gmail, and more. OAuth and API key auth, credential management, and a CLI.

Objective-native planning board for agent-led development

An MCP server for interacting with the Postman API, requiring an API key.

Arbitrary code execution and tool-use platform for LLMs by Riza

A command-line tool for interacting with Shopify's Admin GraphQL API, Functions, and Polaris Web Components.

Single tool to control all 100+ API integrations, and UI components