### Install Todo MD MCP from NPM

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/README.md

Install the package using npm. This is the first step before using the tool.

```bash
npm install @danjdewhurst/todo-md-mcp
```

--------------------------------

### Install and Run MCP Server Globally

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Install the MCP server globally using NPM and set the TODO_FILE_PATH environment variable before running the server command.

```bash
npm install -g @danjdewhurst/todo-md-mcp
export TODO_FILE_PATH="/path/to/todo.md"
mcp-server-todo-md
```

--------------------------------

### Install Local Development Dependencies

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/README.md

Install project dependencies after cloning the repository. This step is crucial for local development and running the build process.

```bash
npm install
```

--------------------------------

### Configure Todo-MD MCP Server (Local Install)

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/README.md

Add this server configuration to your Claude Desktop settings when todo-md-mcp is installed locally.

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

--------------------------------

### List Todos Example Request and Response

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/endpoints.md

Demonstrates a sample request to the 'list_todos' tool and its corresponding JSON response, including a list of todo items and statistics.

```text
Tool: list_todos
Parameters: {}
```

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"todos\": [\n    {\n      \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"text\": \"Buy groceries\",\n      \"completed\": false,\n      \"createdAt\": \"2025-07-08T10:30:00.000Z\"\n    },\n    {\n      \"id\": \"6ba7b810-9dad-11d1-80b4-00c04fd430c8\",\n      \"text\": \"Finish project\",\n      \"completed\": true,\n      \"createdAt\": \"2025-07-08T09:00:00.000Z\",\n      \"completedAt\": \"2025-07-08T11:45:00.000Z\"\n    }\n  ],\n  \"total\": 2,\n  \"completed\": 1,\n  \"pending\": 1\n}"
    }
  ]
}
```

--------------------------------

### Instantiate and Run TodoMCPServer

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-mcp-server.md

This snippet shows how to instantiate the TodoMCPServer and start it. The server runs indefinitely until the process is terminated. This is typically used for command-line server execution.

```typescript
const server = new TodoMCPServer();
await server.run();
```

--------------------------------

### Install Todo Markdown MCP Server via NPM

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/README.md

Install the todo-md-mcp package globally using npm. This command makes the server available system-wide.

```bash
npm install -g @danjdewhurst/todo-md-mcp
```

--------------------------------

### Configure Todo-MD MCP Server (Global NPM Install)

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/README.md

Add this server configuration to your Claude Desktop settings when todo-md-mcp is installed globally via NPM.

```json
{
  "mcpServers": {
    "todo-md": {
      "command": "npx",
      "args": ["@danjdewhurst/todo-md-mcp"]
    }
  }
}
```

--------------------------------

### Add Todo Success Response Example

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/endpoints.md

This is an example of a successful response after adding a todo item. It includes the details of the added todo.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Todo added successfully: {\n  \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"text\": \"Buy groceries\",\n  \"completed\": false,\n  \"createdAt\": \"2025-07-08T10:30:00.000Z\"\n}"
    }
  ]
}
```

--------------------------------

### Example Usage of ListTodosResponse

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/types.md

Shows how to call listTodos and process the response, logging counts and individual todo statuses.

```typescript
const response: ListTodosResponse = await todoManager.listTodos();

console.log(`Total: ${response.total}`);
console.log(`Completed: ${response.completed}`);
console.log(`Pending: ${response.pending}`);

response.todos.forEach(todo => {
  const status = todo.completed ? '✓' : '○';
  console.log(`${status} ${todo.text}`);
});
```

--------------------------------

### TodoItem Example Usage

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/types.md

Illustrates how to create instances of the `TodoItem` interface, showing both an incomplete and a completed todo item. Ensure `createdAt` is a Date object.

```typescript
const todo: TodoItem = {
  id: '550e8400-e29b-41d4-a716-446655440000',
  text: 'Buy groceries',
  completed: false,
  createdAt: new Date('2025-07-08T10:30:00Z'),
  completedAt: undefined
};

const completedTodo: TodoItem = {
  id: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
  text: 'Finish project',
  completed: true,
  createdAt: new Date('2025-07-08T09:00:00Z'),
  completedAt: new Date('2025-07-08T11:45:00Z')
};
```

--------------------------------

### Run Todo MCP Server

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-mcp-server.md

Starts the Todo MCP Server and handles potential fatal errors during startup or runtime. This is the main entry point when executed as a script.

```typescript
async function main(): Promise<void> {
  const server = new TodoMCPServer();
  await server.run();
}

main().catch((error) => {
  console.error('Server error:', error);
  process.exit(1);
});
```

--------------------------------

### Run MCP Server with NPX

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Execute the MCP server using NPX without global installation. Set the TODO_FILE_PATH environment variable before execution.

```bash
TODO_FILE_PATH="/path/to/todo.md" npx @danjdewhurst/todo-md-mcp
```

--------------------------------

### Example AddTodoRequest

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/types.md

Demonstrates how to create an AddTodoRequest object for adding a new todo item.

```typescript
const request: AddTodoRequest = {
  text: 'Complete project documentation'
};

const todo = await todoManager.addTodo(request);
```

--------------------------------

### Error Message Format Example

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/errors.md

Illustrates the standard format for error messages, including type, description, and suggested action.

```text
Permission denied: Cannot write to /path/to/file. Check file permissions or set TODO_FILE_PATH environment variable to a writable location.
```

--------------------------------

### Dockerfile for MCP Server Deployment

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

A Dockerfile to build an image for the MCP server. It installs the package globally, sets the environment variable for the todo file path, and defines the entrypoint.

```dockerfile
FROM node:18

RUN npm install -g @danjdewhurst/todo-md-mcp

ENV TODO_FILE_PATH="/app/todo.md"
WORKDIR /app

ENTRYPOINT ["mcp-server-todo-md"]
```

--------------------------------

### Example UpdateTodoRequests

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/types.md

Illustrates various ways to use the UpdateTodoRequest, including updating only the text, marking a todo as complete, or updating both fields simultaneously.

```typescript
// Update text only
const updateText: UpdateTodoRequest = {
  id: 'abc-123',
  text: 'Updated task description'
};

// Mark as complete
const markComplete: UpdateTodoRequest = {
  id: 'abc-123',
  completed: true
};

// Update both fields
const fullUpdate: UpdateTodoRequest = {
  id: 'abc-123',
  text: 'Finished task',
  completed: true
};

await todoManager.updateTodo(updateText);
```

--------------------------------

### Add Todo Request Example

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/endpoints.md

This snippet shows how to call the add_todo tool with the required 'text' parameter to add a new todo item.

```json
Tool: add_todo
Parameters: {
  "text": "Buy groceries"
}
```

--------------------------------

### Example Usage of DeleteTodoRequest

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/types.md

Demonstrates how to create and use the DeleteTodoRequest object when calling the deleteTodo method.

```typescript
const request: DeleteTodoRequest = {
  id: '550e8400-e29b-41d4-a716-446655440000'
};

await todoManager.deleteTodo(request);
```

--------------------------------

### Todo Manager Markdown Format Example

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-manager.md

Illustrates the expected markdown structure for todos, including incomplete and completed tasks with persistent IDs. The parser supports custom headers and footers.

```markdown
# Todo List

- [ ] Incomplete task <!-- id:550e8400-e29b-41d4-a716-446655440000 -->
- [x] Completed task <!-- id:6ba7b810-9dad-11d1-80b4-00c04fd430c8 -->

<!-- Generated by MCP Todo Server -->
```

--------------------------------

### Temporary/Test File Setup

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Initialize a TodoManager instance using a temporary file path for testing purposes. This is useful for isolated testing without affecting persistent todo files.

```typescript
import { TodoManager } from '@danjdewhurst/todo-md-mcp';
import { tmpdir } from 'os';
import { join } from 'path';

// Use temporary directory for testing
const testManager = new TodoManager(join(tmpdir(), 'test-todo.md'));
```

--------------------------------

### Successful Todo Update Response

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/endpoints.md

This is an example of a successful response after updating a todo item. It includes the updated item's details.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Todo updated successfully: {
  \"id\": \"550e8400-e29b-41d4-a716-446655440000\",
  \"text\": \"Buy groceries and cook dinner\",
  \"completed\": true,
  \"createdAt\": \"2025-07-08T10:30:00.000Z\",
  \"completedAt\": \"2025-07-08T14:15:00.000Z\"
}"
    }
  ]
}
```

--------------------------------

### Clear Completed Todos Success Response (0 items)

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/endpoints.md

This is an example of a successful response when no completed todo items are found. The content indicates that 0 items were cleared.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Cleared 0 completed todo(s)"
    }
  ]
}
```

--------------------------------

### Clear Completed Todos Success Response (3 items)

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/endpoints.md

This is an example of a successful response when 3 completed todo items are cleared. The content indicates the number of items cleared.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Cleared 3 completed todo(s)"
    }
  ]
}
```

--------------------------------

### Build and Run Local MCP Server

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Build the project locally and then run the MCP server using Node.js. Ensure the TODO_FILE_PATH environment variable is set.

```bash
cd /path/to/todo-md-mcp
npm run build
TODO_FILE_PATH="/path/to/todo.md" node dist/index.js
```

--------------------------------

### Multiple MCP Server Instances for Different Todo Files

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Set up multiple instances of todo-md-mcp, each configured with a different TODO_FILE_PATH for managing separate todo lists.

```json
{
  "mcpServers": {
    "personal-todos": {
      "command": "npx",
      "args": ["@danjdewhurst/todo-md-mcp"],
      "env": {
        "TODO_FILE_PATH": "/Users/yourname/Documents/personal-todo.md"
      }
    },
    "work-todos": {
      "command": "npx",
      "args": ["@danjdewhurst/todo-md-mcp"],
      "env": {
        "TODO_FILE_PATH": "/Users/yourname/Documents/work-todo.md"
      }
    }
  }
}
```

--------------------------------

### Run Test Suite

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/README.md

Executes the project's comprehensive test suite using npm.

```bash
npm test
```

--------------------------------

### Verify Configuration by Listing Todos

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Instantiate the TodoManager and list todos to verify that the server can access and read the configured todo file. This confirms basic configuration validity.

```typescript
import { TodoManager } from '@danjdewhurst/todo-md-mcp';

const manager = new TodoManager();

// List todos to verify file access
const todos = await manager.listTodos();
console.log(`Loaded ${todos.total} todos`);
console.log('Configuration is valid');
```

--------------------------------

### Add and List Todos for a Project

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/README.md

Initializes a project-specific todo list by adding multiple todos and then lists the remaining pending tasks.

```typescript
import { TodoManager } from '@danjdewhurst/todo-md-mcp';

const projectManager = new TodoManager('./project-todo.md');

// Initialize project todos
const initial = [
  { text: 'Set up CI/CD' },
  { text: 'Write documentation' },
  { text: 'Configure deployment' }
];

for (const item of initial) {
  await projectManager.addTodo(item);
}

// Use throughout project
const todos = await projectManager.listTodos();
console.log(`${todos.pending} tasks remaining`);
```

--------------------------------

### Multiple Projects Configuration

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Set up Todo-MD MCP to manage todo files for different projects independently. Each project has its own command and TODO_FILE_PATH.

```json
{
  "mcpServers": {
    "project-a-todos": {
      "command": "node",
      "args": ["/projects/a/node_modules/.bin/mcp-server-todo-md"],
      "env": {
        "TODO_FILE_PATH": "/projects/a/todo.md"
      }
    },
    "project-b-todos": {
      "command": "node",
      "args": ["/projects/b/node_modules/.bin/mcp-server-todo-md"],
      "env": {
        "TODO_FILE_PATH": "/projects/b/todo.md"
      }
    }
  }
}
```

--------------------------------

### Configure Claude Desktop for Todo MD

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/README.md

Configure Claude Desktop to use the Todo MD MCP server. Specify the command to run and the path to your todo markdown file.

```json
{
  "mcpServers": {
    "todo-md": {
      "command": "npx",
      "args": ["@danjdewhurst/todo-md-mcp"],
      "env": {
        "TODO_FILE_PATH": "/Users/username/Documents/todo.md"
      }
    }
  }
}
```

--------------------------------

### Clone Todo Markdown MCP Server Repository

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/README.md

Clone the official repository to set up the project for local development. This is the first step for contributing or running the server locally.

```bash
git clone https://github.com/danjdewhurst/todo-md-mcp.git
cd todo-md-mcp
```

--------------------------------

### List Todos Input Schema

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-mcp-server.md

Schema for listing all todos. No parameters are required.

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

--------------------------------

### MCP Server Configuration for Local Development

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Configure todo-md-mcp for local development by pointing to the compiled JavaScript file. Ensure TODO_FILE_PATH is set.

```json
{
  "mcpServers": {
    "todo-md-dev": {
      "command": "node",
      "args": ["/path/to/todo-md-mcp/dist/index.js"],
      "env": {
        "TODO_FILE_PATH": "/Users/yourname/Documents/todo.md"
      }
    }
  }
}
```

--------------------------------

### Project Directory Structure

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/README.md

Illustrates the organization of files and directories within the todo-md-mcp project.

```tree
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
```

--------------------------------

### Personal Use Configuration (Single File)

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Configure Todo-MD MCP to use a single todo file for personal use. Ensure the TODO_FILE_PATH environment variable is set correctly.

```json
{
  "mcpServers": {
    "todo-md": {
      "command": "npx",
      "args": ["@danjdewhurst/todo-md-mcp"],
      "env": {
        "TODO_FILE_PATH": "~/Documents/todo.md"
      }
    }
  }
}
```

--------------------------------

### Importing Todo Types

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/types.md

Demonstrates how to import individual type definitions from the library or specific types within your own project.

```typescript
// Import individual types
import type {
  TodoItem,
  TodoFile,
  AddTodoRequest,
  UpdateTodoRequest,
  DeleteTodoRequest,
  ListTodosResponse
} from '@danjdewhurst/todo-md-mcp/types';

// Or in your own code:
import type { TodoItem } from './types.js';
```

--------------------------------

### Ensure Parent Directory Exists (Bash)

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Use mkdir -p to create the necessary parent directories for your TODO_FILE_PATH, resolving 'No such file or directory' errors. This command creates intermediate directories as needed.

```bash
# Ensure parent directory exists
mkdir -p ~/Documents
```

--------------------------------

### TodoMCPServer Class Methods

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/README.md

The TodoMCPServer class implements the MCP protocol server, enabling interaction with todo management functionalities through defined tools and handlers.

```APIDOC
## TodoMCPServer Class

### Description
MCP protocol server implementation.

### Methods

#### `constructor()`
Initialize MCP server.

#### `run()`
Start server and listen on stdio.

### MCP Tool Definitions and Handlers
This class also manages MCP tool definitions and their corresponding handlers.
```

--------------------------------

### Run Node.js with Specific Version

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Execute a Node.js script using a specific version of Node.js. Ensure the desired Node.js version is available in your environment.

```bash
node --version
```

--------------------------------

### Manage Multiple Independent Todo Lists

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/README.md

Demonstrates creating and managing separate todo lists for different purposes, such as personal, work, and shopping.

```typescript
const personal = new TodoManager('~/personal-todo.md');
const work = new TodoManager('~/work-todo.md');
const shopping = new TodoManager('~/shopping-list.md');

// Each manager operates independently
const personalTodos = await personal.listTodos();
const workTodos = await work.listTodos();
const shoppingList = await shopping.listTodos();
```

--------------------------------

### MCP Server Configuration with Multiple Environment Variables

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Configure an MCP server for todo-md-mcp, setting both TODO_FILE_PATH and NODE_ENV environment variables. This allows for custom file paths and production mode.

```json
{
  "mcpServers": {
    "todo-md": {
      "command": "npx",
      "args": ["@danjdewhurst/todo-md-mcp"],
      "env": {
        "TODO_FILE_PATH": "/path/to/todo.md",
        "NODE_ENV": "production"
      }
    }
  }
}
```

--------------------------------

### Configure Todo File Path with Environment Variable

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/README.md

Specify a custom location for the todo.md file using the TODO_FILE_PATH environment variable to avoid 'read-only file system' errors.

```json
{
  "mcpServers": {
    "todo-md": {
      "command": "npx",
      "args": ["@danjdewhurst/todo-md-mcp"],
      "env": {
        "TODO_FILE_PATH": "/Users/yourname/Documents/todo.md"
      }
    }
  }
}
```

--------------------------------

### Build the Project Locally

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/README.md

Build the TypeScript project for local development or deployment. This command compiles the source code into executable JavaScript.

```bash
npm run build
```

--------------------------------

### Set Directory Permissions for Todo Files

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Ensure the parent directory is writable to allow the creation of new todo files. Use 755 for general access (owner rwx, others rx) or 700 for restricted access (owner rwx, others none).

```bash
# Parent directory must allow writes
chmod 755 /path/to/documents  # Owner rwx, others rx
chmod 700 /path/to/documents  # Owner rwx, others none
```

--------------------------------

### Initialize TodoManager with Custom Directory Path

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-manager.md

Instantiate the TodoManager by providing a directory path. The manager will look for 'todo.md' within this directory.

```typescript
const manager = new TodoManager('/home/user/Documents');
```

--------------------------------

### Check Directory Permissions

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Display directory ownership and permissions using 'ls -ld'. This is useful for verifying that the server has the necessary access to the directory containing the todo file.

```bash
ls -ld /path/to/directory
```

--------------------------------

### Set File Permissions for Todo File

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Configure read and write permissions for the todo markdown file. Use 644 for personal use (owner read/write, others read) or 600 for user-only access (owner read/write).

```bash
# For personal use
chmod 644 todo.md   # Owner read+write, others read-only

# For user-only access
chmod 600 todo.md   # Owner read+write, others no access
```

--------------------------------

### Run MCP Server Docker Container

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Run the MCP server Docker container, mapping a local directory to the container's todo path and setting the TODO_FILE_PATH environment variable.

```bash
docker run -e TODO_FILE_PATH=/todos/my-todos.md -v /local/path:/todos myimage
```

--------------------------------

### List Todos and Display Summary

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-manager.md

Retrieve all todo items from the markdown file and log the total, completed, and pending counts, followed by a formatted list of todo items. Handles cases where the todo file might not exist.

```typescript
const manager = new TodoManager();
const result = await manager.listTodos();

console.log(`Total: ${result.total}, Completed: ${result.completed}, Pending: ${result.pending}`);
console.log(result.todos.forEach(todo => {
  console.log(`- [${todo.completed ? 'x' : ' '}] ${todo.text}`);
}));
```

--------------------------------

### Test File Write Permissions

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Check write permissions for a specific file by attempting to create and append to it. This is a basic test for file system access.

```bash
# Test write permissions
touch /path/to/todo.md
echo "test" >> /path/to/todo.md
```

--------------------------------

### Verify File Existence (Bash)

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Confirm that the todo file actually exists at the specified path using ls -la, which helps diagnose issues where changes are not persisting.

```bash
# Verify file exists: ls -la ~/Documents/todo.md
```

--------------------------------

### Initialize TodoManager with Custom File Path

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-manager.md

Instantiate the TodoManager specifying a direct path to the markdown todo file.

```typescript
const manager = new TodoManager('/home/user/Documents/todo.md');
```

--------------------------------

### Check Disk Space (Bash)

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Use df -h to check available disk space on the relevant partition, as a full disk can prevent changes from persisting.

```bash
# Check disk space: df -h ~
```

--------------------------------

### Initialize TodoManager with Default Path

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-manager.md

Instantiate the TodoManager using the default file location, which is 'todo.md' in the current working directory.

```typescript
const manager = new TodoManager();
```

--------------------------------

### Fix File Permissions (Bash)

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Use the chmod command to grant write permissions to the todo file, resolving 'Permission denied' errors. Ensure you have the necessary privileges.

```bash
# Fix file permissions
chmod 644 ~/Documents/todo.md
```

--------------------------------

### Handle File System Errors Safely

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/errors.md

Safely adds a todo item, catching and handling specific file system errors like permission denied or read-only file systems. Unexpected errors are re-thrown.

```typescript
async function safeAddTodo(text: string): Promise<TodoItem | null> {
  try {
    return await todoManager.addTodo({ text });
  } catch (error) {
    if (error instanceof Error) {
      if (error.message.includes('Permission denied') || 
          error.message.includes('Read-only')) {
        // Set environment variable and retry or inform user
        console.error('File system write error:', error.message);
        return null;
      }
    }
    throw error; // Re-throw unexpected errors
  }
}
```

--------------------------------

### Set Alternative Writable Path (Bash)

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

If the default location has permission issues, set TODO_FILE_PATH to a different directory like the Desktop, ensuring it has full write permissions.

```bash
# Or set to different location with full permissions
export TODO_FILE_PATH="$HOME/Desktop/todo.md"
```

--------------------------------

### list_todos

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/endpoints.md

Lists all todo items from the markdown file with summary statistics.

```APIDOC
## list_todos

### Description
Lists all todo items from the markdown file with summary statistics.

### Method
N/A (MCP Tool Call)

### Endpoint
N/A (MCP Tool Call)

### Parameters
None

### Request Example
```
Tool: list_todos
Parameters: {}
```

### Response
#### Success Response (200)
- **todos** (Array) - Array of todo items
- **todos[].id** (string) - UUID identifier for the todo
- **todos[].text** (string) - Todo item text
- **todos[].completed** (boolean) - Completion status
- **todos[].createdAt** (string) - ISO timestamp of creation
- **todos[].completedAt** (string) - ISO timestamp of completion (if completed)
- **total** (number) - Total count of all todos
- **completed** (number) - Count of completed todos
- **pending** (number) - Count of pending todos

#### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"todos\": [\n    {\n      \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"text\": \"Buy groceries\",\n      \"completed\": false,\n      \"createdAt\": \"2025-07-08T10:30:00.000Z\"\n    },\n    {\n      \"id\": \"6ba7b810-9dad-11d1-80b4-00c04fd430c8\",\n      \"text\": \"Finish project\",\n      \"completed\": true,\n      \"createdAt\": \"2025-07-08T09:00:00.000Z\",\n      \"completedAt\": \"2025-07-08T11:45:00.000Z\"\n    }\n  ],\n  \"total\": 2,\n  \"completed\": 1,\n  \"pending\": 1\n}"
    }
  ]
}
```
```

--------------------------------

### Mark Todo as Complete

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/endpoints.md

Use this snippet to mark an existing todo item as completed. Provide the 'id' and set 'completed' to true.

```json
Tool: update_todo
Parameters: {
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "completed": true
}
```

--------------------------------

### Initialize TodoManager using Environment Variable

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-manager.md

Configure the TodoManager to use a custom todo file path defined by the TODO_FILE_PATH environment variable. No constructor argument is needed if the variable is set.

```typescript
process.env.TODO_FILE_PATH = '/home/user/my-todos.md';
const manager = new TodoManager();
```

--------------------------------

### listTodos

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-manager.md

Lists all todo items from the markdown file and provides summary statistics including total, completed, and pending todos.

```APIDOC
## listTodos

### Description
Lists all todo items from the markdown file with summary statistics.

### Method
`async listTodos(): Promise<ListTodosResponse>`

### Parameters
None

### Return Type
`ListTodosResponse`

#### Response Body
- **todos** (TodoItem[]) - Array of all todo items
- **total** (number) - Total count of all todos
- **completed** (number) - Count of completed todos
- **pending** (number) - Count of pending (incomplete) todos

### Behavior
If the todo file does not exist, returns an empty response with all counts set to 0.

### Example
```typescript
const manager = new TodoManager();
const result = await manager.listTodos();

console.log(`Total: ${result.total}, Completed: ${result.completed}, Pending: ${result.pending}`);
console.log(result.todos.forEach(todo => {
  console.log(`- [${todo.completed ? 'x' : ' '}] ${todo.text}`);
}));
```
```

--------------------------------

### Add Todo Response Format

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-mcp-server.md

Format for the response when a todo is added successfully.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Todo added successfully: { \"id\": \"...\", \"text\": \"...\", ... }"
    }
  ]
}
```

--------------------------------

### TodoManager Constructor

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-manager.md

Initializes the TodoManager. It can be configured with a custom path for the todo file, which can be a directory or a specific file.

```APIDOC
## Constructor TodoManager

### Description
Initializes the TodoManager with the todo file path. The path resolution follows this precedence: 1. Explicit `customPath` parameter (if provided) 2. `TODO_FILE_PATH` environment variable (if set) 3. Current working directory + `todo.md` (default).

### Parameters
#### Path Parameters
- **customPath** (string) - Optional - Custom path for the todo file. If ends with `.md`, treated as file path; otherwise as directory. Priority: customPath > `TODO_FILE_PATH` env var > current working directory + `todo.md`

### Example
```typescript
// Use default location (current working directory/todo.md)
const manager = new TodoManager();

// Use custom file path
const manager = new TodoManager('/home/user/Documents/todo.md');

// Use custom directory path
const manager = new TodoManager('/home/user/Documents');

// Use environment variable (no parameter needed)
process.env.TODO_FILE_PATH = '/home/user/my-todos.md';
const manager = new TodoManager();
```
```

--------------------------------

### Verify TODO_FILE_PATH (Bash)

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Check the current value of the TODO_FILE_PATH environment variable using echo to verify it is set correctly, helping to diagnose issues with changes not persisting.

```bash
# Verify file path is correct: echo $TODO_FILE_PATH
```

--------------------------------

### Check Write Permissions (Bash)

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Use ls -l with the path from TODO_FILE_PATH to check the write permissions of the todo file, aiding in troubleshooting changes not persisting.

```bash
# Check write permissions: ls -l $(TODO_FILE_PATH)
```

--------------------------------

### List Todos Response Format

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-mcp-server.md

Format for the response when listing todos, containing todo details and counts.

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ \"todos\": [...], \"total\": 0, \"completed\": 0, \"pending\": 0 }"
    }
  ]
}
```

--------------------------------

### Set Working Directory and Run Node.js

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Change the current working directory before running a Node.js script. This affects the default location for files like 'todo.md'.

```bash
cd /home/user/Documents && node dist/index.js
```

--------------------------------

### Handle Permission Denied Error

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/errors.md

Catch and handle 'Permission denied' errors when writing to the todo file. This typically occurs when the process lacks write permissions. Provides guidance on checking file permissions or setting the TODO_FILE_PATH.

```typescript
try {
  await todoManager.addTodo({ text: 'New task' });
} catch (error) {
  if (error instanceof Error && error.message.includes('Permission denied')) {
    console.error('Cannot write to todo file. Possible solutions:');
    console.error('1. Check file permissions: chmod 644 todo.md');
    console.error('2. Change directory ownership: chown $USER todo.md');
    console.error('3. Set TODO_FILE_PATH to a writable location');
  }
}
```

--------------------------------

### MCP Tool Usage

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/README.md

The Todo-MD MCP tool provides a set of commands to manage todo items via the MCP protocol.

```APIDOC
## MCP Tools

### Description
Command-line tools for managing todo items through the MCP protocol.

### Available Tools

| Tool | Input | Output |
|---|---|---|
| `list_todos` | (none) | todos[], total, completed, pending |
| `add_todo` | text | TodoItem with generated ID |
| `update_todo` | id, text?, completed? | Updated TodoItem |
| `delete_todo` | id | Confirmation message |
| `clear_completed` | (none) | Count of removed todos |
```

--------------------------------

### Set Writable File Location (JSON Config)

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Configure the TODO_FILE_PATH within the JSON configuration to ensure the application can write to the specified file, addressing 'Read-only file system' issues.

```json
"env": {
  "TODO_FILE_PATH": "/Users/username/Documents/todo.md"
}
```

--------------------------------

### list_todos

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/README.md

Lists all todo items from the markdown file. Returns a JSON object containing an array of todos and summary statistics.

```APIDOC
## list_todos

### Description
Lists all todo items from the markdown file. Returns a JSON object with todos array and summary statistics.

### Parameters
None

### Returns
JSON object with todos array and summary statistics
```

--------------------------------

### list_todos

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-mcp-server.md

Lists all todos from the markdown file. It returns a JSON-formatted string containing a ListTodosResponse object.

```APIDOC
## list_todos

### Description
Lists all todos from the markdown file. It returns a JSON-formatted string containing a ListTodosResponse object.

### Method
N/A (MCP Tool)

### Endpoint
N/A (MCP Tool)

### Parameters
None

### Response
#### Success Response
- **content** (array) - Contains a text object with a JSON-formatted string.
  - **text** (string) - JSON string representing the todos, total count, completed count, and pending count.

### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "{ \"todos\": [...], \"total\": 0, \"completed\": 0, \"pending\": 0 }"
    }
  ]
}
```
```

--------------------------------

### Todo Markdown File Format

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/README.md

Defines the structure of the todo.md file, including task status, text, and a unique ID comment.

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

--------------------------------

### Team Shared File Configuration

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Configure Todo-MD MCP to use a shared todo file for a team. Be aware of potential concurrency issues and data loss with multiple writers.

```json
{
  "mcpServers": {
    "team-todos": {
      "command": "npx",
      "args": ["@danjdewhurst/todo-md-mcp"],
      "env": {
        "TODO_FILE_PATH": "/shared/team-todo.md"
      }
    }
  }
}
```

--------------------------------

### Initialize TodoManager with Custom Paths

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Instantiate TodoManager using default locations, a specific file path, a directory path, or a relative path. The constructor accepts an optional string for a custom path.

```typescript
import { TodoManager } from '@danjdewhurst/todo-md-mcp';

// Use default location (cwd/todo.md or TODO_FILE_PATH env var)
const manager1 = new TodoManager();

// Use specific file path
const manager2 = new TodoManager('/home/user/Documents/todo.md');

// Use directory path (appends todo.md)
const manager3 = new TodoManager('/home/user/Documents');

// Use relative path
const manager4 = new TodoManager('./todos/my-tasks.md');
```

--------------------------------

### Add Todo Input Schema

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-mcp-server.md

Schema for adding a new todo item. Requires the 'text' parameter.

```json
{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "The todo item text"
    }
  },
  "required": ["text"],
  "additionalProperties": false
}
```

--------------------------------

### Set TODO_FILE_PATH Environment Variable

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/configuration.md

Use this to specify the location of your markdown todo file. It can be a full file path or a directory, in which case `todo.md` is appended.

```bash
export TODO_FILE_PATH="/home/user/Documents/todo.md"
```

```bash
export TODO_FILE_PATH="/home/user/Documents"
```

--------------------------------

### Clear Completed Todos Request

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/endpoints.md

Use this snippet to send a request to the clear_completed tool. It requires an empty parameter object.

```text
Tool: clear_completed
Parameters: {}
```

--------------------------------

### Todo Request and Response Types

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/types.md

Defines the structure for adding, updating, and deleting todos, as well as the response format for listing todos and the structure of a single todo item.

```plaintext
AddTodoRequest
  └─ { text: string }
  └─> TodoManager.addTodo() returns TodoItem

UpdateTodoRequest
  └─ { id: string, text?: string, completed?: boolean }
  └─> TodoManager.updateTodo() returns TodoItem

DeleteTodoRequest
  └─ { id: string }
  └─> TodoManager.deleteTodo() returns void

ListTodosResponse
  ├─ todos: TodoItem[]
  ├─ total: number
  ├─ completed: number
  └─ pending: number

TodoItem
  ├─ id: string (UUID)
  ├─ text: string
  ├─ completed: boolean
  ├─ createdAt: Date
  └─ completedAt?: Date

TodoFile (internal)
  ├─ todos: TodoItem[]
  └─ lastModified: Date
```

--------------------------------

### Use Todo MD MCP as a Library

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/README.md

Manage todo lists programmatically using the TodoManager class. Supports listing, adding, updating, deleting, and clearing completed todos.

```typescript
import { TodoManager } from '@danjdewhurst/todo-md-mcp';

const manager = new TodoManager();

// List todos
const todos = await manager.listTodos();
console.log(`Total: ${todos.total}, Completed: ${todos.completed}`);

// Add todo
const newTodo = await manager.addTodo({ text: 'Buy groceries' });

// Update todo
await manager.updateTodo({ id: newTodo.id, completed: true });

// Delete todo
await manager.deleteTodo({ id: newTodo.id });

// Clear completed
const cleared = await manager.clearCompleted();
```

--------------------------------

### Add Todo Error Response

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-mcp-server.md

Error response format when the 'text' parameter is missing or not a string.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Error: Text is required and must be a string"
    }
  ],
  "isError": true
}
```

--------------------------------

### Update Todo Response Format

Source: https://github.com/danjdewhurst/todo-md-mcp/blob/main/_autodocs/api-reference/todo-mcp-server.md

Format for the response when a todo is updated successfully.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Todo updated successfully: { \"id\": \"...\", \"text\": \"...\", ... }"
    }
  ]
}
```