使用说明

基于Git的MCP Todo服务器

使用Git作为协作todo系统后端的模型上下文协议（MCP）服务器。用户通过Claude Desktop或Claude Code进行交互，并通过Git同步更改，利用Git的权限系统和版本控制进行团队协作。

特性

Git备份存储：所有待办事项都存储在Git存储库中以进行版本控制
协作的：多个用户可以通过Git处理同一待办事项列表
冲突解决：用于并发编辑的自动上次写入获胜（LWW）合并策略
自动同步：可选的与远程存储库的自动同步
丰富的Todo功能：优先级、项目、标签、受让人、截止日期、评论等
MCP集成：与Claude Desktop和Claude Code无缝协作
基于Web的看板：交互式Svelte 5 UI，具有拖放、过滤和实时更新功能
电报机器人：通过基于命令的界面通过Telegram群聊管理待办事项

建筑

MCP集成（克劳德桌面/Claude代码）

Claude Desktop ←→ MCP Server (Node.js) ←→ Local Git Repo ←→ Remote Git (GitHub/GitLab)

基于Web的看板

Web Browser (Svelte) ←→ API Server (Express) ←→ MCP Server (Node.js) ←→ Local Git Repo ←→ Remote Git

电报机器人

Telegram User ←→ Telegram Bot API ←→ TodoBot (Node.js) ←→ MCP Server (stdio) ←→ Local Git Repo ←→ Remote Git

系统提供三个接口：

MCP接口：通过stdio与Claude Desktop和Claude Code直接集成
web界面：通过REST API的基于浏览器的看板
电报机器人：Telegram群聊中基于命令的待办事项管理

安装

先决条件

Node.js 20+
Git
克劳德桌面版

设置

克隆此存储库：

git clone https://github.com/yourusername/our_todo.git
cd our_todo

安装依赖项：

npm install

构建项目：

npm run build

创建您的todos存储库：

mkdir ~/my-todos
cd ~/my-todos
git init
git commit --allow-empty -m "Initial commit"
# Optional: Add remote repository
git remote add origin https://github.com/yourusername/my-todos.git
git push -u origin main

备注：系统将在首次使用时自动创建目录结构。如果你有一个现有的 todos.json 文件，它将自动迁移到新的目录结构，并创建备份。

配置克劳德桌面或克劳德代码：

配置文件

将以下配置添加到：

克劳德桌面版: ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）
克劳德代码: .claude/config.json 在您的项目目录中

{
  "mcpServers": {
    "git-todo": {
      "command": "node",
      "args": ["/absolute/path/to/our_todo/dist/index.js"],
      "env": {
        "TODO_REPO_PATH": "/Users/you/my-todos",
        "TODO_REPO_URL": "https://github.com/you/my-todos.git",
        "GIT_USER_NAME": "Your Name",
        "GIT_USER_EMAIL": "you@example.com",
        "AUTO_SYNC": "true",
        "SYNC_INTERVAL_SECONDS": "300"
      }
    }
  }
}

备注：替换 /absolute/path/to/our_todo 使用系统上此存储库的实际路径，并使用您的特定配置更新环境变量。

Claude代码的替代设置

如果您已经在Claude Desktop中配置了MCP服务器，则可以通过运行以下命令轻松地将其添加到Claude Code中：

claude mcp add-from-claude-desktop

这将自动将配置从Claude Desktop设置复制到Claude Code。

运行基于Web的看板

看板为管理待办事项提供了一个可视化界面，具有拖放功能、内联过滤和实时统计。

建筑

看板由两个部分组成：

API服务器 （Express）：连接web前端和MCP服务器
Web前端 （Svelte 5）：交互式看板UI

快速入门（推荐）

通过创建 .env 文件：

cp .env.example .env
# Edit .env with your TODO_REPO_PATH and Git credentials

使用提供的启动脚本以获得最简单的体验：

# Terminal 1: Start backend
./start-backend.sh

# Terminal 2: Start frontend
./start-frontend.sh

然后打开http://localhost:31415在您的浏览器中。

备注：如果未设置环境变量，启动脚本将使用默认值，但建议进行配置 .env 使用您的实际存储库路径。

看 QUICKSTART.md 有关详细说明和故障排除。

手动设置和运行

安装后端和前端的依赖关系：

# Install backend dependencies (if not already done)
npm install

# Install frontend dependencies
cd web
npm install
cd ..

构建MCP服务器：

npm run build

配置环境变量：

选项A：创建.env文件（推荐）

创建一个 .env 项目根目录中包含您的配置的文件：

cp .env.example .env
# Edit .env with your values

示例 .env 文件：

# Path to your Git repository for storing todos
TODO_REPO_PATH=/Users/you/my-todos

# Optional: Remote Git repository URL for syncing
TODO_REPO_URL=https://github.com/you/my-todos.git

# Git user configuration
GIT_USER_NAME=Your Name
GIT_USER_EMAIL=you@example.com

# Optional: Auto-sync configuration
AUTO_SYNC=false
SYNC_INTERVAL_SECONDS=300

# API server configuration
PORT=3001
CORS_ORIGIN=http://localhost:5173
NODE_ENV=development

选项B：手动导出环境变量

export TODO_REPO_PATH="/Users/you/my-todos"
export TODO_REPO_URL="https://github.com/you/my-todos.git"
export GIT_USER_NAME="Your Name"
export GIT_USER_EMAIL="you@example.com"

启动API服务器：

# If using .env file, it will be loaded automatically
npm run start:api

在单独的终端中，启动web前端：

cd web
npm run dev

打开浏览器 http://localhost:31415

API服务器的环境变量

API服务器使用 相同的环境变量 克劳德桌面/Claude代码：

TODO_REPO_PATH：本地Git存储库的路径（默认值： ~/my-todos)
TODO_REPO_URL：远程Git存储库URL（可选）
GIT_USER_NAME：提交的Git用户名
GIT_USER_EMAIL：Git用户提交电子邮件
PORT：API服务器端口（默认值：3001）
CORS_ORIGIN：web前端的CORS源（默认值： http://localhost:31415)
NODE_ENV：环境模式（开发/生产）

使用Docker运行

Telegram机器人可以使用Docker进行部署，以提高可靠性和简化管理。Docker提供自动重启、隔离环境和简化部署。

快速开始:

# 1. Create environment file
cp .env.telegram.example .env.telegram

# 2. Edit with your configuration
nano .env.telegram

# 3. Build and start
docker build -f Dockerfile.telegram -t todo-telegram-bot:latest .
docker compose -f docker-compose.telegram.yml up -d

# 4. View logs
docker logs -f todo-telegram-bot

有关Docker部署说明、故障排除和生产设置的详细信息，请参阅 Docker部署指南.

发展模式

对于自动重新加载的开发：

# Terminal 1: Start API server in watch mode
npm run dev:api

# Terminal 2: Start web frontend in dev mode
cd web
npm run dev

生产建设

构建后端和前端：

# Build backend
npm run build

# Build frontend
cd web
npm run build
cd ..

服务于生产建设：

# Start API server
npm run start:api

# In another terminal, preview the built frontend
cd web
npm run preview

看板功能

四列：待办、进行中、已阻止、已完成
拖放：在列之间移动待办事项以更改状态
内联过滤器：按搜索文本、项目、优先级、标签和受让人筛选
有源滤波器显示：使用单独的清除按钮查看所有活动过滤器
统计：实时完成率和状态细分
添加所有：使用智能项目自动完成功能直接从板上创建新的待办事项
编辑所有：双击任何卡片以查看详细信息并编辑所有字段
项目自动完成：搜索现有项目或创建新项目-防止拼写错误和重复
优先颜色：低、中、高和紧急优先事项的视觉指标
响应式设计：适用于台式机和移动设备

共享同一Todo存储库

API服务器连接到与您的Claude Desktop/Claude Code MCP服务器相同的Git存储库。这意味着：

在Claude Desktop中创建的待办事项出现在看板上
在看板中创建的待办事项出现在Claude Desktop中
两个接口共享相同的Git历史记录和版本控制
使用“最后写入获胜”策略自动解决冲突

只需确保MCP服务器（Claude Desktop配置）和API服务器使用相同的 TODO_REPO_PATH.

配置

环境变量

TODO_REPO_PATH：本地Git存储库的路径（默认值： ~/my-todos)
TODO_REPO_URL：远程Git存储库URL（可选）
GIT_USER_NAME：提交的Git用户名
GIT_USER_EMAIL：Git用户提交电子邮件
AUTO_SYNC：启用自动同步（true/false，默认值：false）
SYNC_INTERVAL_SECONDS：同步间隔（秒）（默认值：300）

用法

您可以通过两种方式与您的待办事项进行交互：

通过克劳德桌面或克劳德代码 使用自然语言
通过基于Web的看板 使用可视化界面

MCP命令（克劳德桌面/Claude代码）

配置后，您可以在Claude中使用自然语言命令：

全部列出：“显示我的待办事项”
创建待办事项：“添加待办事项：实现用户身份验证”
批量创建：“创建多个待办事项：设置项目、安装依赖项、配置linter”
更新待办事项：“将todo 123标记为进行中”
完成待办事项：“完成待办事项456”
删除待办事项：“删除待办事项789”
搜索：“搜索关于身份验证的待办事项”
过滤器：“在后端项目中显示高优先级待办事项”
添加评论：“向todo 123添加评论：已开始处理此问题”
获取统计数据：“显示待办事项统计信息”
手动同步：“同步存储库”

Todo属性

text：待办事项描述（必填）
project：项目名称（必填）
status：待办、进行中、已阻止、已完成
priority：低、中、高、紧急
tags：标签数组
assignee：分配给todo的用户
dueDate：ISO 8601格式的到期日
description：详细说明
dependencies：这取决于todo ID数组
subtasks：子任务数组
comments：评论数组

数据模型

基于目录的存储

Todos存储在目录结构中，以实现更好的可扩展性、工件支持和减少合并冲突：

todos/
├── tasks/                          # Primary storage
│   ├── {task-id}/
│   │   ├── task.json              # Todo metadata
│   │   ├── README.md              # Long descriptions (>300 chars)
│   │   └── artifacts/             # Attached files (future)
│   └── {task-id-2}/
│       └── task.json
├── by-project/                     # Symlink views
│   ├── work/
│   │   └── {task-id} → ../../tasks/{task-id}/
│   └── personal/
│       └── {task-id} → ../../tasks/{task-id}/
├── by-status/
│   ├── todo/ → ../../tasks/{task-id}/
│   ├── in-progress/
│   ├── blocked/
│   └── done/
├── by-priority/
│   ├── urgent/
│   ├── high/
│   ├── medium/
│   └── low/
├── by-tag/
│   └── {tag}/ → ../../tasks/{task-id}/
└── by-assignee/
    └── {user}/ → ../../tasks/{task-id}/

Todo JSON结构

每 task.json 文件包含：

{
  "id": "uuid",
  "text": "Task description",
  "status": "todo",
  "priority": "medium",
  "project": "work",
  "tags": ["backend", "urgent"],
  "assignee": "user-id",
  "createdBy": "user-id",
  "createdAt": "ISO8601",
  "modifiedAt": "ISO8601",
  "dueDate": "ISO8601",
  "completedAt": "ISO8601",
  "dependencies": ["todo-id"],
  "subtasks": [{"id": "uuid", "text": "Subtask", "completed": false}],
  "comments": [{"id": "uuid", "user": "user-id", "text": "Comment", "timestamp": "ISO8601"}],
  "fieldTimestamps": {
    "text": "ISO8601",
    "status": "ISO8601"
  }
}

益处

工件支持：将图像、文档和文件与任务一起存储
减少冲突：每个任务文件最小化合并冲突范围
可扩展性：高效处理10000多项任务
灵活的组织：通过符号链接的多个视图（按项目、状态、优先级、标签、受让人）
元数据：支持README.md文件以获取详细说明
Git友好：粒度差异和清晰的历史

自动迁移

如果你有一个现有的 todos.json 文件，首次使用时会自动迁移到目录结构：

创建备份为 todos.json.backup
将所有待办事项转换为目录格式
重建所有符号链接视图
提交迁移到Git
保证零数据丢失

冲突解决

系统在现场级别使用最后写入获胜（LWW）策略：

每个字段都有自己的时间戳 fieldTimestamps
当发生冲突时，具有最新时间戳的字段获胜
两个版本中的非冲突字段被合并
按文件解决：冲突由个人解决 task.json 水平，而非全球
README.md冲突使用任务的修改时间 modifiedAt 领域

发展

运行测试

# All tests
npm test

# Unit tests only
npm run test:unit

# Integration tests
npm run test:integration

# Test coverage
npm run test:coverage

# Watch mode
npm run test:watch

项目结构

/our_todo/
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── server/
│   │   └── MCPServer.ts         # MCP tool handlers
│   ├── api/                     # API server for web interface
│   │   ├── server.ts            # Express server
│   │   ├── mcpClient.ts         # MCP client for stdio communication
│   │   └── routes/
│   │       └── todos.ts         # Todo REST API endpoints
│   ├── git/
│   │   ├── GitManager.ts        # Git operations
│   │   ├── ConflictResolver.ts  # LWW merge logic
│   │   └── SyncManager.ts       # Sync coordination
│   ├── data/
│   │   ├── TodoRepository.ts    # Todo CRUD operations
│   │   ├── DirectoryManager.ts  # Task directory operations
│   │   └── SymlinkManager.ts    # Symlink view management
│   └── types/
│       └── Todo.ts              # Todo types and validation
├── web/                         # Svelte 5 web frontend
│   ├── src/
│   │   ├── lib/
│   │   │   ├── components/      # Svelte components
│   │   │   │   ├── KanbanBoard.svelte
│   │   │   │   ├── KanbanColumn.svelte
│   │   │   │   ├── TodoCard.svelte
│   │   │   │   └── FilterBar.svelte
│   │   │   ├── stores/          # Svelte stores
│   │   │   │   └── todos.svelte.ts
│   │   │   └── types/           # TypeScript types
│   │   │       └── Todo.ts
│   │   ├── App.svelte           # Main app component
│   │   └── main.ts              # App entry point
│   ├── package.json
│   └── vite.config.ts           # Vite configuration
├── tests/
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   └── performance/             # Performance benchmarks
├── docs/
│   ├── adr/                     # Architecture Decision Records
│   └── releases/                # Release notes
└── dist/                        # Compiled JavaScript

Example todo repository structure (~/my-todos/):
todos/
├── tasks/
│   └── {task-id}/
│       ├── task.json
│       ├── README.md (optional)
│       └── artifacts/ (future)
├── by-project/
├── by-status/
├── by-priority/
├── by-tag/
└── by-assignee/

测试覆盖率

当前测试覆盖率：~94%

Todo模型：100%
冲突解决程序：100%
Git管理器：100%
TodoRepository：100%
SyncManager:70%（与时间相关的测试问题）
MCPServer：56%（部分实施）
API服务器：100%
MCP客户端：100%
Svelte组件：100%（KanbanBoard、KanbanColumn、TodoCard、FilterBar）
所有商店：100%

故障排除

看板问题

API服务器未连接到MCP服务器

确保已构建MCP服务器： npm run build
检查一下 dist/index.js 存在
验证环境变量是否设置正确
检查API服务器日志中的错误

Web前端无法连接到API

确保API服务器正在端口3001上运行
如果在不同端口上运行，请检查CORS设置
验证Vite代理配置 web/vite.config.ts

端口已在使用中

更改端口： PORT=3002 npm run start:api
如有需要，更新CORS_ORIGIN： CORS_ORIGIN=http://localhost:31415
使用端口终止进程： lsof -ti:3001 | xargs kill

Todos不在界面之间同步

确保Claude Desktop配置和API服务器使用相同的配置 TODO_REPO_PATH
检查Git存储库是否存在于指定路径中
验证todo存储库上的文件权限

同步失败

如果同步失败：

检查网络连接
验证Git凭据
手动拉动： cd ~/my-todos && git pull
检查合并冲突

权限问题

确保MCP服务器具有对以下内容的读/写访问权限：

Todo存储库路径
Git配置

调试模式

MCP服务器（克劳德桌面）

在Claude Desktop的开发人员控制台中查看服务器日志或检查stderr输出

API服务器

集 NODE_ENV=development 用于详细记录
检查控制台输出的请求日志和错误
使用浏览器DevTools网络选项卡检查API调用

文档

综合文档可在 docs/ 目录：

QUICKSTART.md -运行看板的快速入门指南
MIGRATION.md -从传统todos.json到目录结构的迁移指南
CLAUDE_CODE_EXAMPLES.md -Claude Code和Claude Desktop的配置和使用示例
测试_用户.md -测试说明和场景
测试_仿真.md -Svelte 5符文的已知测试限制
更改日志.md -版本历史和发行说明
docs/adr/ -架构决策记录
- ADR-002 -基于目录的持久化架构
文档/发布/ -每个版本的详细发行说明

贡献

复刻仓库
创建要素分支
先写测试（TDD）
机具功能
确保所有测试通过
提交拉取请求

许可证

麻省理工学院

致谢

内置：

模型上下文协议SDK -MCP协议实现
Svelte 5 -带有Runes的响应式UI框架
维特 -快速构建工具和开发服务器
快速 -API服务器的Web框架
TypeScript -类型安全的JavaScript
尾风CSS -实用程序优先的CSS框架
简单git -Node.js中的Git操作
萨德 -架构验证
uuidv7 -按时间顺序生成UUID
日期fns -现代数据实用程序库
苗条的动作 -Svelte的拖放操作
测试 & 维测试 -测试框架

支持

有关问题和疑问，请在GitHub上打开问题。