Todo Md MCP

🚀 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

本地開發

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 <!-- 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許可證。

貢獻

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 為新功能添加測試
5. 運行測試套件
6. 提交拉取請求

模型上下文協議

此服務器實現了模型上下文協議（MCP），這是一個開放協議，用於標準化應用程序如何為大語言模型提供上下文。MCP允許安全、可控地訪問本地和遠程資源。

有關MCP的更多信息，請訪問官方文檔。