JinDaGe - todo-md-mcp MCP Details

article

README

🚀 Todo Markdown MCP Server

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

🚀 快速开始

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

✨ 主要特性

基于Markdown的存储：待办事项以标准的复选框语法存储在简单的 todo.md 文件中。
完整的CRUD操作：支持创建、读取、更新和删除待办事项。
持久化ID：每个待办事项都有唯一的标识符，确保可靠的更新操作。
符合MCP标准：遵循模型上下文协议规范。
TypeScript实现：完全类型化的实现，并具备全面的错误处理机制。
完善的测试：使用Vitest进行完整的测试套件。

📦 安装指南

从NPM安装

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

本地开发

克隆此仓库：

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

安装依赖：
```
npm install
```
构建项目：
```
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 <!-- 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 -->

每个待办事项包括：

标准的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许可证。

贡献

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

模型上下文协议

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

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

todo-md-mcp