The project follows the LM Studio Plugin Development Guide for TypeScript-based plugins, using @lmstudio/sdk for the plugin entry point while retaining a standalone MCP server entry for use with other MCP clients.

Key Features

• 10 MCP tools for full todo lifecycle management
• SQLite persistence — uses sql.js (pure JS, no native compilation) for LM Studio compatibility
• LM Studio Plugin compatible — runs inside LM Studio's built-in Node.js environment
• Standalone MCP server — also works with Claude Desktop, Cursor, and other MCP clients
• Type-safe — built with TypeScript and Zod validation
• Educational — heavily commented source code and included learning guide

🛠️ Tools

This MCP server exposes the following 10 tools:

📦 Installation

Prerequisites

• LM Studio v0.3.17 or higher (with built-in Node.js v22.x)
• LM Studio CLI (lms) — verify with lms --help
• The project files cloned locally

Clone and Install

# Clone the repository
git clone https://github.com/RegiByte/todo-list-mcp.git
cd todo-list-mcp

# Install dependencies
npm install

# Build the project
npm run build

Verify the Build

npm run typecheck   # Type-check with zero errors
npm run build       # Compile to dist/

🚀 Usage

Option 1: Run as an LM Studio Plugin (Recommended)

• Open LM Studio.
• Navigate to the Plugins section.
• Install or load this plugin from the local directory.
• The 10 todo tools will be auto-discovered and available for use with the built-in LLM.

The plugin provides:

• Per-chat configuration — set a per-chat database folder and toggle completed-todo visibility.
• Global configuration — set a global default database path.

Option 2: Run as a Standalone MCP Server

If you prefer to use this with Claude Desktop, Cursor, or any other MCP-compatible client:

# Build the project
npm run build

# Start the MCP server (outputs JSON-RPC to stdout)
npm run mcp

Configuring with Claude Desktop

Add this to your claude_desktop_config.json:

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

Configuring with Cursor

• Go to Cursor Settings → MCP.
• Add a new MCP server with command type.
• Set the command to: node and the args to the absolute path of dist/mcp.js.
• Example: node /absolute/path/to/todo-list-mcp/dist/mcp.js

💡 Example Commands

Once configured, you can try prompts such as:

• "Create a todo to learn MCP with a description explaining why MCP is useful"
• "List all my active todos"
• "Create a todo for tomorrow's meeting with details about the agenda in markdown"
• "Mark my learning MCP todo as completed"
• "Summarize all my active todos"
• "Search todos I created on 2025-01-15"

📁 Project Structure

todo-list-mcp/
├── manifest.json           # Plugin metadata (LM Studio)
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
├── dist/                   # Compiled JavaScript (auto-generated)
│   ├── index.js            # Plugin entry point
│   ├── toolsProvider.js    # LM Studio tool definitions
│   ├── config.js           # UI configuration schemas
│   ├── mcp.js              # Standalone MCP server entry
│   └── core/               # Shared business logic
│       ├── Todo.ts
│       ├── DatabaseService.ts
│       ├── TodoService.ts
│       └── formatters.ts
├── src/
│   ├── index.ts            # Plugin entry point (exports toolsProvider, configSchematics)
│   ├── toolsProvider.ts    # LM Studio tool definitions (using @lmstudio/sdk)
│   ├── config.ts           # UI configuration schemas (createConfigSchematics)
│   ├── mcp.ts              # Standalone MCP server (using @modelcontextprotocol/sdk)
│   └── core/               # Shared business logic (used by both entry points)
├── GUIDE.md                # Original learning guide
├── SKILL.md                # 4B LLM skill documentation
├── README.md               # This file
└── LICENSE                 # MIT License

Module Resolution Fix

This project uses two package.json files to handle different module requirements:

• Root package.json: Does not have "type": "module". This allows Node.js to treat .js files as CommonJS by default, which is required for the lms dev workflow (esbuild bundles use require()).
• dist/package.json: Has "type": "module". This ensures Node.js treats the compiled dist/ files as ES modules, since they use ES module syntax (import/export).

This dual approach ensures both the LM Studio Plugin development workflow (lms dev) and the standalone MCP server (npm run mcp) work correctly.

🔧 Port Summary

This section documents the migration from the original standalone MCP server to an LM Studio Plugin-compatible project.

What Changed

Port Process

• Analyzed the original project — Reviewed all source files in RegiByte/todo-list-mcp to understand the 10 tools, SQLite persistence, and error-handling patterns.
• Created the LM Studio Plugin structure — Set up manifest.json, package.json, and tsconfig.json per the official LM Studio Plugin Development Guide.
• Moved core logic to src/core/ — Relocated Todo.ts, DatabaseService.ts, TodoService.ts, and formatters.ts into a shared src/core/ module, following the guide's "write core once, two entry points" best practice.
• Built src/toolsProvider.ts — Ported all 10 tools to use @lmstudio/sdk's tool() function with zod parameter schemas and the required { signal, status, warn } implementation signature.
• Created src/config.ts — Defined per-chat and global configuration schemas using createConfigSchematics() for LM Studio's auto-generated UI.
• Created src/mcp.ts — Retained a standalone MCP server entry point using @modelcontextprotocol/sdk for compatibility with Claude Desktop, Cursor, and other MCP clients.
• Updated src/index.ts — Rewrote as the LM Studio Plugin entry point, exporting toolsProvider, configSchematics, and globalConfigSchematics.
• Updated README.md — Documented the LM Studio Plugin version, installation, usage, tools, port summary, and credits.
• Created SKILL.md — Produced an LLM-friendly skill document for 4B-parameter models.
• Verified the build — Confirmed npm run build compiles cleanly and the MCP server responds to tool/list requests with all 10 tools registered.

Key Design Decisions

• MIT License preserved — The original MIT License is retained unchanged.
• All 10 tools retained — No functionality was removed during the port.
• Dual-purpose project — The project works both as an LM Studio Plugin and as a standalone MCP server.
• Core logic shared — Business logic lives in src/core/ and is reused by both entry points, avoiding duplication.

📚 Learning from This Project

This project is designed as an educational resource. To get the most out of it:

• Read the GUIDE.md for a comprehensive explanation of the original design.
• Read the SKILL.md for LLM-friendly usage instructions and practical scenarios.
• Study the heavily commented source code in src/core/ to understand implementation details.
• Experiment with adding your own tools or extending the existing ones.

📄 License

This project is licensed under the MIT License. The original MIT License text is included in the LICENSE file and is retained from the original RegiByte/todo-list-mcp repository.

🙏 Credits & Acknowledgements

We would like to express our deepest gratitude to the original project:

RegiByte/todo-list-mcp
Author: Reginaldo Junior (RegiByte)
License: MIT

The original repository provided a clean, well-structured, and educational example of an MCP server implementation. This port builds upon that foundation to bring todo list functionality to the LM Studio Plugin ecosystem.

Ported and maintained with ❤️ for the LM Studio community.

The project follows the LM Studio Plugin Development Guide for TypeScript-based plugins, using @lmstudio/sdk for the plugin entry point while retaining a standalone MCP server entry for use with other MCP clients.

Key Features

• 10 MCP tools for full todo lifecycle management
• SQLite persistence — uses sql.js (pure JS, no native compilation) for LM Studio compatibility
• LM Studio Plugin compatible — runs inside LM Studio's built-in Node.js environment
• Standalone MCP server — also works with Claude Desktop, Cursor, and other MCP clients
• Type-safe — built with TypeScript and Zod validation
• Educational — heavily commented source code and included learning guide

🛠️ Tools

This MCP server exposes the following 10 tools:

📦 Installation

Prerequisites

• LM Studio v0.3.17 or higher (with built-in Node.js v22.x)
• LM Studio CLI (lms) — verify with lms --help
• The project files cloned locally

Clone and Install

# Clone the repository
git clone https://github.com/RegiByte/todo-list-mcp.git
cd todo-list-mcp

# Install dependencies
npm install

# Build the project
npm run build

Verify the Build

npm run typecheck   # Type-check with zero errors
npm run build       # Compile to dist/

🚀 Usage

Option 1: Run as an LM Studio Plugin (Recommended)

• Open LM Studio.
• Navigate to the Plugins section.
• Install or load this plugin from the local directory.
• The 10 todo tools will be auto-discovered and available for use with the built-in LLM.

The plugin provides:

• Per-chat configuration — set a per-chat database folder and toggle completed-todo visibility.
• Global configuration — set a global default database path.

Option 2: Run as a Standalone MCP Server

If you prefer to use this with Claude Desktop, Cursor, or any other MCP-compatible client:

# Build the project
npm run build

# Start the MCP server (outputs JSON-RPC to stdout)
npm run mcp

Configuring with Claude Desktop

Add this to your claude_desktop_config.json:

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

Configuring with Cursor

• Go to Cursor Settings → MCP.
• Add a new MCP server with command type.
• Set the command to: node and the args to the absolute path of dist/mcp.js.
• Example: node /absolute/path/to/todo-list-mcp/dist/mcp.js

💡 Example Commands

Once configured, you can try prompts such as:

• "Create a todo to learn MCP with a description explaining why MCP is useful"
• "List all my active todos"
• "Create a todo for tomorrow's meeting with details about the agenda in markdown"
• "Mark my learning MCP todo as completed"
• "Summarize all my active todos"
• "Search todos I created on 2025-01-15"

📁 Project Structure

todo-list-mcp/
├── manifest.json           # Plugin metadata (LM Studio)
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
├── dist/                   # Compiled JavaScript (auto-generated)
│   ├── index.js            # Plugin entry point
│   ├── toolsProvider.js    # LM Studio tool definitions
│   ├── config.js           # UI configuration schemas
│   ├── mcp.js              # Standalone MCP server entry
│   └── core/               # Shared business logic
│       ├── Todo.ts
│       ├── DatabaseService.ts
│       ├── TodoService.ts
│       └── formatters.ts
├── src/
│   ├── index.ts            # Plugin entry point (exports toolsProvider, configSchematics)
│   ├── toolsProvider.ts    # LM Studio tool definitions (using @lmstudio/sdk)
│   ├── config.ts           # UI configuration schemas (createConfigSchematics)
│   ├── mcp.ts              # Standalone MCP server (using @modelcontextprotocol/sdk)
│   └── core/               # Shared business logic (used by both entry points)
├── GUIDE.md                # Original learning guide
├── SKILL.md                # 4B LLM skill documentation
├── README.md               # This file
└── LICENSE                 # MIT License

Module Resolution Fix

This project uses two package.json files to handle different module requirements:

• Root package.json: Does not have "type": "module". This allows Node.js to treat .js files as CommonJS by default, which is required for the lms dev workflow (esbuild bundles use require()).
• dist/package.json: Has "type": "module". This ensures Node.js treats the compiled dist/ files as ES modules, since they use ES module syntax (import/export).

This dual approach ensures both the LM Studio Plugin development workflow (lms dev) and the standalone MCP server (npm run mcp) work correctly.

🔧 Port Summary

This section documents the migration from the original standalone MCP server to an LM Studio Plugin-compatible project.

What Changed

Port Process

• Analyzed the original project — Reviewed all source files in RegiByte/todo-list-mcp to understand the 10 tools, SQLite persistence, and error-handling patterns.
• Created the LM Studio Plugin structure — Set up manifest.json, package.json, and tsconfig.json per the official LM Studio Plugin Development Guide.
• Moved core logic to src/core/ — Relocated Todo.ts, DatabaseService.ts, TodoService.ts, and formatters.ts into a shared src/core/ module, following the guide's "write core once, two entry points" best practice.
• Built src/toolsProvider.ts — Ported all 10 tools to use @lmstudio/sdk's tool() function with zod parameter schemas and the required { signal, status, warn } implementation signature.
• Created src/config.ts — Defined per-chat and global configuration schemas using createConfigSchematics() for LM Studio's auto-generated UI.
• Created src/mcp.ts — Retained a standalone MCP server entry point using @modelcontextprotocol/sdk for compatibility with Claude Desktop, Cursor, and other MCP clients.
• Updated src/index.ts — Rewrote as the LM Studio Plugin entry point, exporting toolsProvider, configSchematics, and globalConfigSchematics.
• Updated README.md — Documented the LM Studio Plugin version, installation, usage, tools, port summary, and credits.
• Created SKILL.md — Produced an LLM-friendly skill document for 4B-parameter models.
• Verified the build — Confirmed npm run build compiles cleanly and the MCP server responds to tool/list requests with all 10 tools registered.

Key Design Decisions

• MIT License preserved — The original MIT License is retained unchanged.
• All 10 tools retained — No functionality was removed during the port.
• Dual-purpose project — The project works both as an LM Studio Plugin and as a standalone MCP server.
• Core logic shared — Business logic lives in src/core/ and is reused by both entry points, avoiding duplication.

📚 Learning from This Project

This project is designed as an educational resource. To get the most out of it:

• Read the GUIDE.md for a comprehensive explanation of the original design.
• Read the SKILL.md for LLM-friendly usage instructions and practical scenarios.
• Study the heavily commented source code in src/core/ to understand implementation details.
• Experiment with adding your own tools or extending the existing ones.

📄 License

This project is licensed under the MIT License. The original MIT License text is included in the LICENSE file and is retained from the original RegiByte/todo-list-mcp repository.

🙏 Credits & Acknowledgements

We would like to express our deepest gratitude to the original project:

RegiByte/todo-list-mcp
Author: Reginaldo Junior (RegiByte)
License: MIT

The original repository provided a clean, well-structured, and educational example of an MCP server implementation. This port builds upon that foundation to bring todo list functionality to the LM Studio Plugin ecosystem.

Ported and maintained with ❤️ for the LM Studio community.