📋 TodoTracker与MCP服务器

TodoTracker Web UI

描述

TodoTracker是一个基于人工智能的todo管理系统，提供一个带有 模型上下文协议（MCP） 服务器与代理代码编辑器（例如Claude、Windsurf、Windows等）一起使用，光标IDE、Codex等）。

利用AI的强大功能在AI聊天窗格中输入待办事项然后在web UI中查看和编辑它们。使用AI更新、研究和执行待办事项聊天。

运作原理

安装程序创建了.todo目录，每个项目都在其中获得自己的独立todo数据库，该数据库带有project.db（SQLlite）。MCP服务器被传递到此的路径 db，并使用它根据您的命令创建和更新todos。

📦 安装

先决条件

Python 3.10或更高版本
pip、pipx或uv（包管理器）

安装依赖项

# Option 1: Using uv (fastest, recommended for 2026)
uv pip install -r requirements.txt

# Option 2: Using pip with --user (PEP 668 compliant)
pip install --user -r requirements.txt

# Option 3: In a virtual environment
python3 -m venv venv
source venv/bin/activate  # On Linux/Mac
pip install -r requirements.txt

🚀 快速开始

1.设置您的项目

选项A：手动设置

# Navigate to your project
cd /path/to/your/project

# Run the setup script (interactive or with project path)
/path/to/todotracker/scripts/setup-project-todos.sh

# Or specify a project path:
/path/to/todotracker/scripts/setup-project-todos.sh /path/to/your/project

# This creates:
#   - .todos/project.db (your project's todo database)
#   - Updates .gitignore

选项B：自动设置（通过MCP）

转到4。AI集成（MCP配置）并在代理代码编辑器中安装MCP服务器。

有关以下配置示例，请参阅下面的步骤4：

光标IDE
克劳德桌面版
帆板运动
通用MCP客户端

你可以简单地说“为这个项目设置一个待办事项跟踪器启动web服务器”，AI将自动处理这两个步骤。

然后TodoTracker在首次使用时自动设置每个项目。

打开项目时，TodoTracker会自动创建 .todos/project.db!

2.启动Web UI

之后，你可以告诉人工智能，“启动todotracker网络服务器”。

# From your project directory
python /path/to/todotracker/todotracker_webserver.py

web UI在可用端口（8070+）打开，显示项目的待办事项。

3.监控多个项目（可选）

跑吧 TodoTracker仪表板 查看所有正在运行的实例：

python /path/to/todotracker/dashboard.py

仪表板在以下位置打开 http://localhost:8069 并显示：

所有正在运行的TodoTracker服务器
每个项目的港口分配
访问每个项目UI的快速链接

4.AI集成（MCP配置）

配置您的MCP客户端以使用TodoTracker。不同工具的示例：

光标IDE (~/.cursor/mcp.json):

{
  "mcpServers": {
    "todotracker": {
      "command": "bash",
      "args": ["/absolute/path/to/todotracker/run_mcp_server.sh", "${workspaceFolder}"]
    }
  }
}

克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "todotracker": {
      "command": "python",
      "args": ["/absolute/path/to/todotracker/src/mcp_server.py"],
      "env": {
        "TODOTRACKER_DB_PATH": "${workspaceFolder}/.todos/project.db"
      }
    }
  }
}

帆板运动 (~/.windsurf/mcp.json):

{
  "mcpServers": {
    "todotracker": {
      "command": "bash",
      "args": ["/absolute/path/to/todotracker/run_mcp_server.sh", "${workspaceRoot}"]
    }
  }
}

通用MCP客户端:

{
  "mcpServers": {
    "todotracker": {
      "command": "bash",
      "args": [
        "-c",
        "cd \"$PROJECT_DIR\" && python /absolute/path/to/todotracker/src/mcp_server.py"
      ]
    }
  }
}

注： TodoTracker不再依赖MCP客户端 cwd 以确定项目。如果您的客户端支持工作区变量，请将工作区/项目根作为第二个论点 run_mcp_server.sh （以上示例）。

配置后，重新启动IDE/客户端并询问：

"Create a feature todo for implementing user authentication"
"What should I work on next?"
"Mark todo #5 as completed"

AI自动：

✅ 首次使用时设置新项目
✅ 查找项目的数据库
✅ 跟踪任务进度
✅ 管理子任务和依赖关系

🎯 每个项目的数据库是如何工作的

自动检测

MCP服务器会自动查找项目的数据库：

游标打开您的项目 （例如。， /home/user/projects/my-app)
MCP服务器正在查找 .todos/project.db 在该文件夹中
如果未找到，在父目录中查找它
AI与该数据库协同工作 -每个项目都不需要配置！

文件结构

your-project/
├── .todos/
│   └── project.db          # Your project's todos (SQLite)
├── .gitignore              # .todos/ added here
├── src/
└── ...

多个项目

每个项目都是完全隔离的：

# Example: Recipe sharing website project
cd ~/projects/recipe-sharing-app
./todos_webserver.sh  # Shows recipe-sharing-app todos on port 8070

# Example: API service project  
cd ~/projects/payment-gateway-api
./todos_webserver.sh  # Shows payment-gateway-api todos on port 8071

# Example: Mobile application project
cd ~/projects/fitness-tracker-app
./todos_webserver.sh  # Shows fitness-tracker-app todos on port 8072

目的

当使用人工智能编写代码时，软件开发人员会花更多的时间进行规划以及待办事项列表：使特性、功能和问题描述大大小小。将其与人工智能聊天相结合，可以让人工智能在之前完成的待办事项中引入不同的考虑因素手动，然后允许软件开发人员在指示人工智能实现它们之前对其进行审查。

当你用人工智能生成代码时，你经常在软件领域工作在开发过程中，你有一个大致的了解，但需要人工智能来协助规划的具体细节。

好处

你可以将之前在纯文本文件中键入的待办事项粘贴到聊天中，并指示人工智能将其放入数据库中，它就会这样做。然后，您可以使用web UI添加和编辑任何内容，然后再要求AI执行数据库中的任何任务。如果你在任务中添加注释，人工智能会看到它并在工作中使用它。

您可以让AI分析任何待办事项的需求，并为其添加注释在做了研究之后。（“研究\[待办事项\]并添加关于如何做的注释”）。

你可以用任何类型的命令让它自己做todos：“遍历项目并寻找。..并做待办事项。“然后，你可以检查它做的待办事项在webui中编辑它们。

你告诉人工智能添加到数据库中的简短待办事项将由它自动扩展，并提供改进的描述，使用比你只想为单个待办事项费力理解的更准确和具体的术语，从而产生一个可读的待办事项目录，就像你有一个专家团队成员与你一起工作一样。

你可以告诉你的人工智能执行整个类别的待办事项，它会检索它们，执行它们，然后将其标记为已完成。如果事情没有完全完成，AI 提供字段以更新已完成和未完成的内容。

你可以使用AI以任何你需要的方式为你更新待办事项列表。它将自动填写提供的“已完成工作”、“剩余工作”和“实施问题”后这使您能够跟踪部分完成或更大的任务。

对于不应该立即变成待办事项的人工智能研究，你可以让它做研究将结果添加到“注释”部分，例如生成的关于如何执行功能或状态的报告代码库。这可以让你稍后回来。

在指令中引用多个待办事项，AI可以更新它们。

你可以让人工智能浏览项目并发布项目笔记。

🌟 主要特点

每个项目数据库：每个项目都有自己的 .todos/project.db -孤立和有组织
AI集成：MCP服务器让AI助手智能管理待办事项
多项目仪表板：端口8069上的中央仪表板，用于监控所有正在运行的TodoTracker实例

🌟 Todo功能

执行队列（仅限活动工作）：The queue 字段仅适用于中的待办事项 pending 或 in_progress.如果待办事项变成 completed/cancelled，其 queue 自动清除（设置为 0)并且在详细信息页面上禁用队列控制。
分层待办事项：无限的子任务和关注点
现代Web用户界面：美观、响应迅速的界面，具有自动端口选择功能
智能组织：类别（特性/功能、问题、错误）、状态跟踪、主题和标签。

特性/功能-涵盖主要特性和次要功能。问题-涵盖bug，对项目的总体评论。 Bug-针对小故障。

依赖项：定义和跟踪任务依赖关系
备注：为任何待办事项附加上下文和更新

🔗 了解依赖关系

什么是Todo依赖？

依赖关系允许您指定一个todo必须先完成，然后才能开始另一个。

例子：

全部 A：“设计数据库架构”
全部B：“实现用户身份验证”
所有C：“添加登录页面”

您可以标记：

全部B 取决于 Todo A（在设计模式之前无法实现身份验证）
所有C 取决于 Todo B（在实现身份验证之前无法构建登录页面）

工作原理：

创建依赖关系：“待办事项B取决于待办事项A”

- Todo A是先决条件（必须先完成） - 待办事项B被阻止，直到待办事项A完成

检查相关性：在启动Todo B之前，系统会检查Todo A是否已完成

- 如果待办事项A已完成→ Todo B可以处理 - 如果待办事项A未完成→ Todo B被阻止

实际使用：

项目规划：强制执行任务顺序
能见度：查看哪些任务已准备就绪，哪些任务已被阻止
人工智能辅助：帮助确定工作的优先级
自动化：开始任务前检查准备情况

📖 文档

安装.md -适用于所有环境的详细安装指南
QUICKSTART.md -3分钟后开始跑步
ADAPTIVE_PORTS.md -多项目港口管理和仪表板
AI_PROGRES_TRACKING.md -AI如何跟踪任务的工作

🏗️ 建筑

┌─────────────────┐         ┌──────────────────┐
│   Web Browser   │────────▶│   Web Server     │
│   (Human UI)    │         │   (FastAPI)      │
└─────────────────┘         └──────────────────┘
                                     │
                                     ▼
                            ┌──────────────────┐
┌─────────────────┐         │   SQLite DB      │
│  Agentic IDE    │         │   (WAL mode)     │
│  (AI Agent)     │         └──────────────────┘
└─────────────────┘                  ▲
         │                           │
         ▼                           │
┌─────────────────┐                  │
│   MCP Server    │──────────────────┘
│   (stdio)       │
└─────────────────┘

🚀 自适应端口管理

TodoTracker自动管理多个项目中的端口：

运作原理

端口8070+：自动分配给项目
端口8069：保留给TodoTracker仪表板（可选启动）
无冲突：如果一个端口繁忙，系统会尝试下一个端口（8070→8071→8072…）
项目检测：运行同一项目两次会连接到现有服务器，而不是启动新服务器

仪表板

这 TodoTracker仪表板 在港口运行 8069 并提供：

✅ 概述所有正在运行的TodoTracker实例\ ✅ 端口分配 对于每个项目\ ✅ 快速访问 链接到每个项目的UI\ ✅ 状态监测 具有正常运行时间跟踪功能\ ✅ 自动清理 过时的服务器条目

# Start the dashboard
python /path/to/todotracker/dashboard.py

# Visit http://localhost:8069

服务器注册表

TodoTracker在以下位置维护一个注册表 ~/.todotracker/servers.json 跟踪：

活动服务器端口和PID
项目名称和数据库路径
开始时间和健康状况

这实现了无缝的多项目工作流，没有端口冲突！

在Cursor中切换项目，AI会自动切换到该项目的待办事项！

🤖 使用AI（光标IDE）

创建待办事项

You: Create a feature todo for implementing the user profile page 
     with avatar upload and crop functionality.

AI: ✓ Created: "Implement user profile page with avatar upload"
    - Category: feature
    - Status: pending

创建子任务

You: Add subtasks to that todo:
     - Design profile layout
     - Implement avatar upload
     - Add image cropping UI
     - Connect to backend API

AI: ✓ Created 4 subtasks under "Implement user profile page"

跟踪进度

AI使用三个进度字段自动跟踪其工作：

You: I've finished the avatar upload implementation. Update the subtask.

AI: ✓ Updated: "Implement avatar upload"
    - Status: completed
    - Work Completed: Implemented file upload with drag-drop, 
      added validation (max 5MB, jpg/png), integrated with S3 storage
    - Work Remaining: None

查询待办事项

You: What pending bugs do I have?

AI: Here are your pending bugs:
    1. [Bug] Database connection timeout - Status: pending
    2. [Bug] API rate limiting not working - Status: pending
    3. [Bug] Memory leak in worker process - Status: pending

检查状态

You: Give me an overview of my todos.

AI: Project: /home/user/projects/my-app
    - Total: 15 todos
    - Completed: 8 (53%)
    - In Progress: 3
    - Pending: 4

🌐 Web UI功能

访问地址： http://localhost:8070 （跑步后 python /path/to/todotracker/todotracker_webserver.py)

GUI布局（SPA）

TodoTracker的主UI是一个基于Calcite的单页应用程序 主/详图布局:

头球

- 状态分段控制（带计数）: All / Pending / In Progress / Completed / Cancelled / Queue\ 选择一个更新两者左侧列表面板和主面板。 - 辅助导航(navigation-secondary) - 搜索 (Enter)：运行全文搜索并更新两个面板。 - 过滤器（实时）：一个轻量级的客户端过滤器，在不离开页面的情况下缩小两个面板中的结果。

左侧面板（浏览器/列表面板）

- 仅列出 视图，用于快速选择要在详细信息抽屉中打开的待办事项。 - 最小化/扩展切换：将面板向下折叠到窄宽度，这样您就可以将主面板用作“单页”浏览体验，然后在需要时展开列表。

主面板

- 查看模式控制: Grid | List | Table （替换旧的页面顶部状态按钮）。 - 分页：主面板已分页；使用底部的分页控件导航页面。

主页面

主页（/） -带有实时统计信息的分层待办事项树
所有细节（/todo/{id}） -完整信息、子任务、注释、依赖关系
注释（/注释） -所有笔记（链接和独立）
API文档（/Docs） -交互式API文档

待办事项管理

✅ 创建、更新、删除待办事项
📝 添加说明和注释
🏷️ 分配类别：特性/功能、问题、错误
📊 跟踪状态：待定、进行中、已完成、已取消
🔗 创建子任务（无限制嵌套）
📎 添加待办事项之间的依赖关系
🏷️ 使用主题和标签进行组织
📈 查看进度跟踪（已完成的工作、剩余工作、问题）

📊 MCP工具可用

AI可以使用这些工具：

工具	说明
`list_todos`	获取所有待办事项的分层列表
`get_todo`	获取特定待办事项的详细信息
`get_todos_batch`	在一次通话中按ID获取多个待办事项的详细信息
`create_todo`	创建新的待办事项或子任务
`create_todos_batch`	在一次通话中创建多个待办事项/子任务
`add_concern`	在待办事项下添加关注点
`update_todo`	更新待办事项状态、进度等。
`update_todos_batch`	在一次通话中更新多个待办事项
`create_note`	创建笔记（链接或独立）
`get_notes_batch`	在一次通话中按ID获取多条笔记
`create_notes_batch`	在一次通话中创建多个笔记
`update_note`	更新笔记的内容（和/或关联的todo\\uid）
`delete_note`	按ID删除注释
`search_todos`	按条件搜索/筛选待办事项
`add_dependency`	在待办事项之间创建依赖关系
`add_dependencies_batch`	在一次调用中创建多个依赖关系
`check_dependencies`	检查是否满足todo依赖关系

MCP批次“获取”示例

// Get several todos at once (reduces repetitive get_todo calls)
{
  "tool": "get_todos_batch",
  "args": {
    "project_root": "/path/to/project",
    "todo_ids": [10, 13, 14],
    "include_dependency_status": true,
    "include_dependencies": true
  }
}

// Get several notes at once (reduces repetitive get_note/get_notes calls)
{
  "tool": "get_notes_batch",
  "args": {
    "project_root": "/path/to/project",
    "note_ids": [1, 4, 7]
  }
}

MCP资源

资源	描述
`todos://tree`	完整的分层待办事项树
`todos://stats`	待办事项统计

🔧 高级用法

自定义数据库位置

# Use any location
export TODOTRACKER_DB_PATH="/custom/path/todos.db"
python /path/to/todotracker/todotracker_webserver.py

项目别名

增添 ~/.bashrc 或 ~/.zshrc:

alias fe-todos='cd ~/projects/frontend && python /path/to/todotracker/todotracker_webserver.py'
alias be-todos='cd ~/projects/backend && python /path/to/todotracker/todotracker_webserver.py'
alias app-todos='cd ~/projects/mobile && python /path/to/todotracker/todotracker_webserver.py'

备份项目待办事项

# Backup
cp .todos/project.db .todos/backup-$(date +%Y%m%d).db

# Restore
cp .todos/backup-20260115.db .todos/project.db

与团队共享待办事项

数据库只是一个文件！选项：

承诺使用git：删除 .todos/ 从 .gitignore
直接共享文件：发送 .todos/project.db
通过云同步：Dropbox、谷歌云端硬盘等。

⚠️ 备注：SQLite不能很好地处理网络上的并发写入。供团队使用：

一个人运行web服务器
其他人通过web UI访问
或者每个人都维护自己的数据库

🧪 开发数据库

注：当你奔跑时 python todotracker_webserver.py 直接在todotracker目录中，无需设置 TODOTRACKER_DB_PATH，它使用 ./data/project.db 作为 开发/测试数据库。这是为了测试TodoTracker本身，而不是为了管理您的实际项目待办事项。

要将TodoTracker用于您的项目，请执行以下操作：

在项目目录中运行安装脚本
跑 python todotracker_webserver.py 从项目目录（自动检测 .todos/project.db)
或设置 TODOTRACKER_DB_PATH 到你的项目 .todos/project.db

📋 数据库模式

核心表

待办事项

层次结构（parent_id）
分类：特性/功能、问题、错误
状态：待定、进行中、已完成、已取消
进度跟踪：工作完成、工作维护、实施问题
组织的主题和标签

笔记

可以链接到待办事项或独立
带有时间戳的全文内容

todo_dependency

定义任务依赖关系
检查是否满足先决条件

标签

可重复使用的组织标签
34个股票标签已预填充

📁 项目结构

todotracker/
├── src/                    # Python source code
│   ├── crud.py             # Database operations
│   ├── db.py               # SQLAlchemy models
│   ├── schemas.py          # Pydantic schemas
│   ├── web_server.py       # FastAPI web server
│   ├── mcp_server.py       # MCP server for AI
│   ├── migrations.py       # Database migrations
│   └── version.py          # Version tracking
├── scripts/                # Utility scripts
│   ├── setup-project-todos.sh
│   └── migrate_cli.py
├── docs/                   # Documentation
├── data/                   # Development database
├── templates/              # Jinja2 HTML templates
├── static/                 # CSS/JS assets
├── todotracker_webserver.py              # Main launcher
└── requirements.txt        # Python dependencies

🔒 安全

仅限本地：默认情况下，服务器在本地主机上运行
无需认证：专为单用户设计，本地使用
MCP同意书：光标显示AI工具调用的提示
SQLite WAL：web UI和MCP之间的安全并发访问

🐛 故障排除

端口已在使用中

# Kill process on port 8070
lsof -ti:8070 | xargs kill -9

MCP未连接

检查 ~/.cursor/mcp.json 具有绝对路径
手动测试： bash /path/to/todotracker/run_mcp_server.sh "$(pwd)"
检查Cursor的MCP日志（帮助→ 显示MCP日志）
重新启动游标IDE

数据库问题

# Check database version
python scripts/migrate_cli.py --check

# Run migration if needed
python scripts/migrate_cli.py --migrate

# Verify version
python todotracker_webserver.py --version

AI找不到项目数据库

确保 .todos/project.db 存在于您的项目中
检查光标是否打开到正确的文件夹
验证MCP配置是否将您的工作区文件夹传递给 run_mcp_server.sh （并且不依赖 cwd)

🎯 常见工作流

启动新项目

# 1. Navigate to project
cd ~/projects/my-new-app

# 2. Initialize todos
/path/to/todotracker/scripts/setup-project-todos.sh

# 3. Launch web UI
python /path/to/todotracker/todotracker_webserver.py

# 4. Or use AI in Cursor/Claude/Windsurf
"Create a todo for setting up the project structure"

日常发展

# Check todos in web UI
python /path/to/todotracker/todotracker_webserver.py

# Or ask AI
"What should I work on next?"
"Mark todo #5 as in progress"
"I've completed the API endpoint, update todo #7"

切换项目

# No special steps needed!
cd ~/projects/frontend  # AI uses frontend todos
cd ~/projects/backend   # AI uses backend todos

💡 最佳实践

运行安装脚本 每个项目（一次性）
使用描述性标题 -帮助AI理解上下文
分解复杂特征 进入子任务
让AI跟踪进度 -它更新已完成的工作、正在维护的工作和问题
使用主题和标签 组织相关的待办事项
添加关注点 当你发现潜在问题时
检查相关性 开始工作前
web UI中的审核 用于视觉概述

📄 许可证

MIT许可证

🙏 致谢

MCP-SDK -模型上下文协议
快速API -Web框架
埃斯里方解石 -UI设计系统
SQLAlchemy -数据库ORM
JsRender/JsViews -JavaScript模板

📚 资源

______________________________________________________________________

当前版本：1.5.0（架构v7）

todotracker (Noctivagous)

快速接入

详细介绍

📋 TodoTracker与MCP服务器

📦 安装

先决条件

安装依赖项

🚀 快速开始

1.设置您的项目

2.启动Web UI

3.监控多个项目（可选）

4.AI集成（MCP配置）

🎯 每个项目的数据库是如何工作的

自动检测

文件结构

多个项目

🌟 主要特点

🌟 Todo功能

🔗 了解依赖关系

📖 文档

🏗️ 建筑

🚀 自适应端口管理

运作原理

仪表板

服务器注册表

🤖 使用AI（光标IDE）

创建待办事项

创建子任务

跟踪进度

查询待办事项

检查状态

🌐 Web UI功能

GUI布局（SPA）

主页面

待办事项管理

📊 MCP工具可用

MCP批次“获取”示例

MCP资源

🔧 高级用法

自定义数据库位置

项目别名

备份项目待办事项

与团队共享待办事项

🧪 开发数据库

📋 数据库模式

核心表

📁 项目结构

🔒 安全

🐛 故障排除

端口已在使用中

MCP未连接

数据库问题

AI找不到项目数据库

🎯 常见工作流

启动新项目

日常发展

切换项目

💡 最佳实践

📄 许可证

🙏 致谢

📚 资源

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP