Todo Markdown MCP Server

Instructions

Implementation Reference

• src/todoManager.ts:97-119 (handler)

  Core handler function that lists todos by checking if the todo file exists, reading and parsing its markdown content, calculating statistics (total, completed, pending), and returning a ListTodosResponse.

  async listTodos(): Promise<ListTodosResponse> {
    if (!(await this.fileExists())) {
      return {
        todos: [],
        total: 0,
        completed: 0,
        pending: 0,
      };
    }
  
    const content = await readFile(this.todoFilePath, 'utf-8');
    const todos = this.parseTodoMarkdown(content);
  
    const completed = todos.filter((todo) => todo.completed).length;
    const pending = todos.length - completed;
  
    return {
      todos,
      total: todos.length,
      completed,
      pending,
    };
  }

• src/index.ts:117-127 (handler)

  MCP CallToolRequest handler case for 'list_todos' that delegates to todoManager.listTodos() and returns the result as JSON-formatted text content.

  case 'list_todos': {
    const result = await this.todoManager.listTodos();
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/index.ts:40-48 (registration)

  Tool registration in ListToolsRequest handler, defining the 'list_todos' tool name, description, and empty input schema (no parameters required).

  {
    name: 'list_todos',
    description: 'List all todos from the markdown file',
    inputSchema: {
      type: 'object',
      properties: {},
      additionalProperties: false,
    },
  },

• src/types.ts:28-33 (schema)

  TypeScript interface defining the structure of the response returned by the list_todos tool.

  export interface ListTodosResponse {
    todos: TodoItem[];
    total: number;
    completed: number;
    pending: number;
  }

• src/todoManager.ts:44-83 (helper)

  Helper function to parse TodoItem objects from markdown file content by matching checkbox lines and extracting ID comments.

  private parseTodoMarkdown(content: string): TodoItem[] {
    const lines = content.split('\n');
    const todos: TodoItem[] = [];
  
    for (const line of lines) {
      const trimmed = line.trim();
  
      // Match markdown checkbox format: - [ ] text or - [x] text
      const checkboxMatch = trimmed.match(/^-\s*\[([x\s])\]\s*(.+)$/i);
      if (checkboxMatch) {
        const [, checkbox, text] = checkboxMatch;
        if (!checkbox || !text) continue;
  
        const completed = checkbox.toLowerCase() === 'x';
  
        // Extract ID from text if it exists (format: text <!-- id:uuid -->)
        const idMatch = text.match(/^(.*?)\s*<!--\s*id:([a-f0-9-]+)\s*-->$/);
        let todoText: string;
        let id: string;
  
        if (idMatch) {
          todoText = idMatch[1]?.trim() || '';
          id = idMatch[2] || randomUUID();
        } else {
          todoText = text.trim();
          id = randomUUID();
        }
  
        todos.push({
          id,
          text: todoText,
          completed,
          createdAt: new Date(),
          ...(completed && { completedAt: new Date() }),
        });
      }
    }
  
    return todos;
  }