# Todo Markdown MCP Server

[![npm version](https://badge.fury.io/js/@danjdewhurst%2Ftodo-md-mcp.svg)](https://badge.fury.io/js/@danjdewhurst%2Ftodo-md-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Test](https://github.com/danjdewhurst/todo-md-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/danjdewhurst/todo-md-mcp/actions/workflows/test.yml)
[![Lint and Format](https://github.com/danjdewhurst/todo-md-mcp/actions/workflows/lint-and-format.yml/badge.svg)](https://github.com/danjdewhurst/todo-md-mcp/actions/workflows/lint-and-format.yml)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](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).