Todo Markdown MCP Server

这是一个基于MCP（模型上下文协议）的服务器，提供基于简单Markdown文件的待办事项功能。该服务器允许AI助手以标准化的Markdown格式管理待办事项。

功能

• 基于Markdown的存储：待办事项存储在一个简单的todo.md文件中，使用标准的复选框语法。
• 完整的CRUD操作：创建、读取、更新和删除待办事项。
• 持久ID：每个待办事项都有一个唯一的标识符，以便可靠地进行更新。
• 符合MCP规范：遵循模型上下文协议规范。
• 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

列出所有待办事项。

参数： 无

返回值： 包含待办事项数组和汇总统计信息的JSON对象

add_todo

添加一个新的待办事项。

参数：

• text (字符串，必需)：待办事项文本

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

update_todo

更新现有的待办事项。

参数：

• id (字符串，必需)：待办事项ID
• text (字符串，可选)：新的待办事项文本
• completed (布尔值，可选)：标记为完成或未完成

返回值： 更新后的待办事项

delete_todo

删除待办事项。

参数：

• id (字符串，必需)：要删除的待办事项ID

返回值： 成功确认

clear_completed

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

参数： 无

返回值： 清除的项目数量

文件格式

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

# 待办事项列表

- [ ] 第一项未完成的任务 <!-- id:550e8400-e29b-41d4-a716-446655440000 -->
- [x] 已完成的任务 <!-- id:6ba7b810-9dad-11d1-80b4-00c04fd430c8 -->
- [ ] 另一项任务 <!-- id:6ba7b811-9dad-11d1-80b4-00c04fd430c8 -->

<!-- 由MCP待办事项服务器生成 -->

每个待办事项包括：

• 标准的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              # 主MCP服务器实现
│   ├── todoManager.ts        # 待办事项CRUD操作和Markdown解析
│   └── types.ts              # TypeScript类型定义
├── tests/
│   └── todoManager.test.ts   # 测试套件
├── dist/                     # 构建的JavaScript文件
├── package.json
├── tsconfig.json
├── .eslintrc.json
├── .prettierrc
├── vitest.config.ts
└── README.md

要求

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

许可证

MIT

贡献

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

模型上下文协议

此服务器实现了模型上下文协议（MCP），这是一种开放协议，标准化了应用程序如何向大型语言模型提供上下文。MCP使安全、受控访问本地和远程资源成为可能。

有关MCP的更多信息，请访问官方文档。