Todo MD MCP

Todo Markdown MCP 服务

一个 MCP（Model Context Protocol）服务，通过简单的 Markdown 文件提供待办事项列表功能。该服务支持 AI 助手以标准化的 Markdown 格式管理待办事项。

功能

• 基于 Markdown 的存储：待办事项保存在简单的 todo.md 文件中，使用标准复选框语法
• 完整的 CRUD 操作：创建、读取、更新和删除待办事项
• 持久化 ID：每项待办事项都有唯一标识符，便于可靠地更新
• 符合 MCP 规范：遵循 Model Context Protocol 规范
• TypeScript：完全类型化的实现，并提供全面的错误处理
• 测试：使用 Vitest 编写的完整测试套件

安装

从 NPM 安装

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

本地开发

1. 克隆此仓库：

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

2. 安装依赖：

   npm install
   

3. 构建项目：

   npm run build
   

使用方法

搭配 Claude Desktop 使用

将此服务添加到 Claude Desktop 配置中：

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

或者，如果通过 NPM 全局安装：

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

配置待办文件位置

默认情况下，服务会在当前工作目录中创建 todo.md 文件。使用 Claude Desktop 时，该目录可能是你没有写入权限的系统目录。若要指定待办文件的自定义位置，请使用 TODO_FILE_PATH 环境变量：

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

这样可以解决常见的“只读文件系统”错误，确保待办文件创建在你有写入权限的位置。

推荐位置：

• ~/Documents/todo.md - 文稿文件夹
• ~/Desktop/todo.md - 桌面
• /path/to/your/project/todo.md - 特定项目目录中

**重要提示：**请确保目录已存在，并且你对指定位置拥有写入权限。

可用工具

此服务提供以下 MCP 工具：

list_todos

列出 Markdown 文件中的所有待办事项。

**参数：**无

**返回：**包含待办事项数组和摘要统计信息的 JSON 对象

add_todo

添加一项待办事项。

参数：

• text（字符串，必填）：待办事项文本

**返回：**已创建的待办事项及其生成的 ID

update_todo

更新现有待办事项。

参数：

• id（字符串，必填）：待办事项 ID
• text（字符串，可选）：待办事项的新文本
• completed（布尔值，可选）：标记为已完成／未完成

**返回：**已更新的待办事项

delete_todo

删除一项待办事项。

参数：

• id（字符串，必填）：要删除的待办事项 ID

**返回：**操作成功确认

clear_completed

移除所有已完成的待办事项。

**参数：**无

**返回：**已清除的事项数量

文件格式

此服务会在项目根目录中管理 todo.md 文件，格式如下：

# Todo List

- [ ] First incomplete task 
- [x] Completed task 
- [ ] Another task 

每项待办事项包含：

• 标准 Markdown 复选框语法（- [ ] 或 - [x]）
• 待办事项文本
• 包含唯一追踪 ID 的隐藏 HTML 注释

开发

脚本

• npm run build - 构建 TypeScript 项目
• npm run dev - 构建并运行服务
• npm run watch - 监视更改并重新构建
• npm test - 运行测试套件
• npm run test:watch - 在监视模式下运行测试
• npm run lint - 运行 ESLint
• npm run format - 使用 Prettier 格式化代码

测试

项目包含全面的测试，涵盖所有功能：

npm test

测试涵盖：

• Markdown 解析与生成
• CRUD 操作
• 错误处理
• 文件管理

项目结构

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

要求

• Node.js 18 或更高版本
• 兼容 MCP 的客户端（例如 Claude Desktop）

许可证

MIT

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 运行测试套件
6. 提交拉取请求

模型上下文协议

此服务实现了 模型上下文协议（MCP），这是一种开放协议，用于标准化应用向大语言模型提供上下文的方式。MCP 支持安全、受控地访问本地和远程资源。

如需了解更多信息，请访问 官方文档。