Todo Markdown MCP Server

# Todo Markdown MCP Server [](https://badge.fury.io/js/@danjdewhurst%2Ftodo-md-mcp) [](https://opensource.org/licenses/MIT) [](https://github.com/danjdewhurst/todo-md-mcp/actions/workflows/test.yml) [](https://github.com/danjdewhurst/todo-md-mcp/actions/workflows/lint-and-format.yml) [](https://www.typescriptlang.org) [](https://modelcontextprotocol.io/) An MCP (Model Context Protocol) server that provides todo list functionality backed by a simple markdown file. This server allows AI assistants to manage todo items in a standardized markdown format. ## Features - **Markdown-based storage**: Todos are stored in a simple `todo.md` file using standard checkbox syntax - **Full CRUD operations**: Create, read, update, and delete todo items - **Persistent IDs**: Each todo has a unique identifier for reliable updates - **MCP compliance**: Follows the Model Context Protocol specification - **TypeScript**: Fully typed implementation with comprehensive error handling - **Testing**: Complete test suite with Vitest ## Installation ### From NPM ```bash npm install -g @danjdewhurst/todo-md-mcp ``` ### Local Development 1. Clone this repository: ```bash git clone https://github.com/danjdewhurst/todo-md-mcp.git cd todo-md-mcp ``` 2. Install dependencies: ```bash npm install ``` 3. Build the project: ```bash npm run build ``` ## Usage ### With Claude Desktop Add this server to your Claude Desktop configuration: ```json { "mcpServers": { "todo-md": { "command": "node", "args": ["/path/to/todo-md-mcp/dist/index.js"] } } } ``` Or if installed globally via NPM: ```json { "mcpServers": { "todo-md": { "command": "npx", "args": ["@danjdewhurst/todo-md-mcp"] } } } ``` #### Configuring Todo File Location By default, the server creates a `todo.md` file in the current working directory. When using Claude Desktop, this might be a system directory where you don't have write permissions. To specify a custom location for your todo file, use the `TODO_FILE_PATH` environment variable: ```json { "mcpServers": { "todo-md": { "command": "npx", "args": ["@danjdewhurst/todo-md-mcp"], "env": { "TODO_FILE_PATH": "/Users/yourname/Documents/todo.md" } } } } ``` This solves the common "read-only file system" error by ensuring the todo file is created in a location where you have write permissions. **Recommended locations:** - `~/Documents/todo.md` - Your Documents folder - `~/Desktop/todo.md` - Your Desktop - `/path/to/your/project/todo.md` - Within a specific project **Important:** Make sure the directory exists and you have write permissions to the specified location. ### Available Tools The server provides the following MCP tools: #### `list_todos` Lists all todo items from the markdown file. **Parameters:** None **Returns:** JSON object with todos array and summary statistics #### `add_todo` Adds a new todo item. **Parameters:** - `text` (string, required): The todo item text **Returns:** The created todo item with generated ID #### `update_todo` Updates an existing todo item. **Parameters:** - `id` (string, required): The todo item ID - `text` (string, optional): New text for the todo - `completed` (boolean, optional): Mark as completed/incomplete **Returns:** The updated todo item #### `delete_todo` Deletes a todo item. **Parameters:** - `id` (string, required): The todo item ID to delete **Returns:** Success confirmation #### `clear_completed` Removes all completed todo items. **Parameters:** None **Returns:** Number of items cleared ## File Format The server manages a `todo.md` file in your project root with the following format: ```markdown # Todo List - [ ] First incomplete task <!-- id:550e8400-e29b-41d4-a716-446655440000 --> - [x] Completed task <!-- id:6ba7b810-9dad-11d1-80b4-00c04fd430c8 --> - [ ] Another task <!-- id:6ba7b811-9dad-11d1-80b4-00c04fd430c8 --> <!-- Generated by MCP Todo Server --> ``` Each todo item includes: - Standard markdown checkbox syntax (`- [ ]` or `- [x]`) - The todo text - A hidden HTML comment with a unique ID for tracking ## Development ### Scripts - `npm run build` - Build the TypeScript project - `npm run dev` - Build and run the server - `npm run watch` - Watch for changes and rebuild - `npm test` - Run the test suite - `npm run test:watch` - Run tests in watch mode - `npm run lint` - Run ESLint - `npm run format` - Format code with Prettier ### Testing The project includes comprehensive tests covering all functionality: ```bash npm test ``` Tests cover: - Markdown parsing and generation - CRUD operations - Error handling - File management ### Project Structure ``` todo-md-mcp/ ├── src/ │ ├── index.ts # Main MCP server implementation │ ├── todoManager.ts # Todo CRUD operations and markdown parsing │ └── types.ts # TypeScript type definitions ├── tests/ │ └── todoManager.test.ts # Test suite ├── dist/ # Built JavaScript files ├── package.json ├── tsconfig.json ├── .eslintrc.json ├── .prettierrc ├── vitest.config.ts └── README.md ``` ## Requirements - Node.js 18 or higher - An MCP-compatible client (like Claude Desktop) ## License MIT ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests for new functionality 5. Run the test suite 6. Submit a pull request ## Model Context Protocol This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), an open protocol that standardizes how applications provide context to Large Language Models. MCP enables secure, controlled access to local and remote resources. For more information about MCP, visit the [official documentation](https://modelcontextprotocol.io/introduction).