使用说明

所有MCP服务器

一个使用FastMCP构建的模型上下文协议（MCP）服务器，提供全面的待办事项列表管理功能。

特点/功能

✅ 添加、更新和删除待办事项
🏷️ 优先级等级（低、中、高）
📊 状态追踪（待处理，已完成）
🔍 按状态和优先级筛选所有任务
📈 全部统计数据和分析
💾 以JSON格式进行持久化存储
🕒 自动记录创建、更新和完成的时间戳

安装

选项1：使用提供的设置

克隆或下载此仓库
运行项目（这将自动设置一个虚拟环境）：
```
# On Windows
start_server.bat

# On Linux/Mac
python main.py
```

选项2：手动设置

克隆或下载此存储库

创建一个虚拟环境：

python -m venv .venv

# Activate on Windows
.venv\Scripts\activate

# Activate on Linux/Mac
source .venv/bin/activate

安装依赖项：

pip install -r requirements.txt
# OR
pip install fastmcp>=2.12.5

使用方法

运行服务器

python main.py

服务器将启动并监听MCP连接。它将待办事项存储在（某个地方，原文未指明具体存储位置，故翻译为泛指的“某个地方”） todos.json 当前目录中的文件。

可用工具

`add_todo(title, description="", priority="medium")`

添加一个新的待办事项。

title待办事项的标题（必填）
description可选描述
priority优先级级别 - “低”、“中”或“高”（默认：中）

示例：

add_todo("Buy groceries", "Milk, bread, eggs", "high")

`list_todos(status="all", priority="all")`

列出待办事项，并可选择性过滤。

status按状态过滤 - “全部”、“待处理”或“已完成”（默认：“全部”）
priority按优先级过滤 - “全部”、“低”、“中”或“高”（默认：全部）

示例：

list_todos()                          # List all todos
list_todos(status="pending")          # List only pending todos
list_todos(priority="high")           # List only high priority todos
list_todos(status="pending", priority="high")  # List pending high priority todos

`get_todo(todo_id)`

获取特定待办事项的详细信息。

todo_id待办事项的ID

示例：

get_todo(1)

`update_todo(todo_id, title=None, description=None, priority=None)`

更新现有的待办事项。

todo_id要更新的待办事项的ID（必需）
title新标题（可选）
description新描述（可选）
priority新的优先级（可选）

示例：

update_todo(1, title="Buy groceries and cook dinner", priority="high")

`complete_todo(todo_id)`

将待办事项标记为已完成。

todo_id要完成的待办事项的ID

示例：

complete_todo(1)

`reopen_todo(todo_id)`

重新打开已完成的待办事项。

todo_id要重新打开的待办事项的ID

示例：

reopen_todo(1)

`delete_todo(todo_id)`

永久删除一个待办事项。

todo_id要删除的待办事项的ID

示例：

delete_todo(1)

`clear_completed_todos()`

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

示例：

clear_completed_todos()

`get_todo_stats()`

获取你的待办事项统计数据，包括总数、完成率以及优先级细分。

示例：

get_todo_stats()

数据结构

每个待办事项包含：

id唯一标识符
title全部标题
description可选描述
priority优先级（低/中/高）
status当前状态（待处理/已完成）
created_at创建时间戳
updated_at最后更新时间戳
completed_at完成时间戳（未完成时为null）

数据存储

所有的（数据/物品）都存储在一个 todos.json 服务器工作目录中的文件。该文件在首次使用时自动创建，并在待办事项（todos）被修改时自动更新。

MCP配置

要使用此服务器与MCP客户端配合，需将其添加到客户端的配置中。例如，在Claude Desktop中：

{
  "mcpServers": {
    "todo": {
      "command": "python",
      "args": ["path/to/main.py"],
      "cwd": "path/to/todo-mcp-server"
    }
  }
}

测试

你可以使用任何MCP客户端连接到服务器并调用可用工具来测试其功能。服务器提供了全面的待办事项管理功能，这些功能可以通过交互方式进行测试。

项目结构

Todo-mcp-server/
├── main.py                    # Main MCP server implementation
├── requirements.txt          # Python dependencies
├── pyproject.toml           # Project configuration
├── uv.lock                  # UV dependency lock file
├── README.md                # This documentation
├── DEPLOYMENT.md            # Comprehensive deployment guide
├── Dockerfile               # Docker container configuration
├── docker-compose.yml       # Docker Compose setup
├── .dockerignore           # Docker build exclusions
├── .gitignore              # Git ignore patterns
├── .python-version         # Python version specification
├── .env.example            # Environment configuration template
├── .env.development        # Development environment settings
├── .env.production         # Production environment settings
├── start_server.bat        # Windows startup script (local)
├── deploy-docker.bat       # Windows Docker deployment script
├── deploy-docker.sh        # Unix Docker deployment script
├── stop-docker.bat         # Windows Docker stop script
├── todos.json              # Data storage (created automatically)
├── todo_server.log         # Application logs (created automatically)
├── .vscode/                # VS Code configuration
│   └── mcp.json            # MCP server configuration for VS Code
└── configs/                # Client configuration examples
    ├── claude-desktop.json           # Claude Desktop (local Python)
    ├── claude-desktop-docker.json    # Claude Desktop (Docker)
    ├── claude-desktop-unix.json      # Claude Desktop (Unix systems)
    ├── vscode-mcp.json              # VS Code MCP extension
    ├── vscode-mcp-docker.json       # VS Code MCP extension (Docker)
    └── nodejs-client-example.js     # Node.js client example

生产部署

Docker 部署（推荐）

使用 Docker Compose 构建并运行：

# Windows
deploy-docker.bat

# Linux/Mac
chmod +x deploy-docker.sh
./deploy-docker.sh

手动Docker命令：

# Build the image
docker-compose build

# Start the server
docker-compose up -d

# View logs
docker-compose logs -f todo-mcp-server

# Stop the server
docker-compose down

环境配置：
- 复制 .env.example to .env 并根据需要进行修改
- 使用 .env.production 用于生产环境设置
- 使用 .env.development 用于开发设置

环境变量

TODO_FILEtodos 数据文件的路径（默认： todos.json)
LOG_LEVEL日志级别 - DEBUG（调试）、INFO（信息）、WARNING（警告）、ERROR（错误）（默认： INFO)
MAX_TODOS允许的最大待办事项数量（默认值： 1000)
MAX_TITLE_LENGTH待办事项标题的最大长度（默认： 200）
MAX_DESCRIPTION_LENGTH描述的最大长度（默认： 1000)

客户集成

Claude Desktop（可译为“克劳德桌面版”或根据具体语境简化为“克劳德桌面”）

本地Python安装： 在您的Claude Desktop配置文件中添加：

{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "C:\\path\\to\\Todo-mcp-server",
      "env": {
        "TODO_FILE": "todos.json",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Docker 安装：

{
  "mcpServers": {
    "todo-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "todo_data:/data",
        "-v", "todo_logs:/app/logs",
        "todo-mcp-server"
      ]
    }
  }
}

配置文件位置：
- Windows： %APPDATA%\Claude\claude_desktop_config.json
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux： ~/.config/Claude/claude_desktop_config.json

VS Code MCP 扩展

安装MCP扩展 适用于 VS Code

添加服务器配置 到您的工作区设置或用户设置中：

{
  "mcp.servers": [
    {
      "name": "todo-server",
      "command": {
        "type": "stdio",
        "program": "python",
        "args": ["main.py"],
        "cwd": "${workspaceFolder}/Todo-mcp-server"
      }
    }
  ]
}

其他MCP客户端

Cline（VS Code 扩展）

在您的Cline设置中添加：

{
  "cline.mcp.servers": {
    "todo-server": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "/path/to/Todo-mcp-server"
    }
  }
}

继续（VS Code 扩展）

在您的继续配置中添加：

{
  "mcpServers": {
    "todo-server": {
      "transport": {
        "type": "stdio"
      },
      "command": ["python", "main.py"],
      "cwd": "/path/to/Todo-mcp-server"
    }
  }
}

Node.js 应用程序

见 configs/nodejs-client-example.js 以下是一个与Node.js应用程序集成的完整示例。

健康监测

服务器内置了一个健康检查系统：

健康检查工具： 使用 health_check() 用于验证服务器状态的工具
Docker 健康检查： Docker 部署中的自动健康监测
记录日志： 全面记录日志至文件和控制台
错误处理： 优雅的错误处理，附带详细的错误信息

安全特性

输入验证 以及卫生消毒
文件系统安全 在获得适当权限后
非root权限的Docker用户 用于集装箱安全
资源限制 防止滥用
备份和恢复 用于数据完整性

监控和日志

应用程序日志： 有以下可用选项： todo_server.log
Docker 日志： docker-compose logs -f todo-mcp-server
健康状况： 定期进行健康检查并提交状态报告
性能指标： 内置的统计和监控功能

故障排除

常见问题

权限错误：
- 确保数据目录的文件权限设置正确
- 对于 Docker：卷已正确挂载
连接问题：
- 验证服务器是否正在运行： docker-compose ps
- 检查日志： docker-compose logs todo-mcp-server
数据损坏：
- 服务器在保存之前会自动创建备份
- 使用健康检查工具验证数据完整性
资源限制：
- 根据您的使用情况调整环境变量
- 使用 Docker stats 监控资源使用情况

寻求帮助

检查应用程序日志
运行健康检查工具
验证您的客户端配置
确保已安装Docker/Python依赖项

发展

本地开发环境设置

# Clone and setup
git clone <repository>
cd Todo-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Copy environment config
cp .env.example .env

# Run in development mode
python main.py

测试

# Test Docker build
docker-compose build

# Test health check
docker-compose exec todo-mcp-server python -c "from main import health_check; print(health_check())"

# Test server functionality through MCP client
# Use any MCP client to connect and test the available tools

建筑学

该服务器具备生产就绪的功能：

FastMCP框架： 现代Python MCP服务器框架
异步操作： 非阻塞I/O以提高性能
数据持久化： 基于JSON的存储，具备备份/恢复功能
集装箱化： Docker支持便于部署
监测： 健康检查、日志记录和错误追踪
安全： 输入验证、资源限制、安全默认设置

要求

Python 3.12及以上版本 （用于本地安装）
Docker 和 Docker Compose （用于容器化部署）
FastMCP 2.12.5+

许可证

这个项目是开源的，并遵循MIT许可证发布。

使用说明

所有MCP服务器

特点/功能

安装

选项1：使用提供的设置

选项2：手动设置

使用方法

运行服务器

可用工具

add_todo(title, description="", priority="medium")

list_todos(status="all", priority="all")

get_todo(todo_id)

update_todo(todo_id, title=None, description=None, priority=None)

complete_todo(todo_id)

reopen_todo(todo_id)

delete_todo(todo_id)

clear_completed_todos()

get_todo_stats()

数据结构

数据存储

MCP配置

测试

项目结构

生产部署

Docker 部署（推荐）

环境变量

客户集成

Claude Desktop（可译为“克劳德桌面版”或根据具体语境简化为“克劳德桌面”）

VS Code MCP 扩展

其他MCP客户端

Cline（VS Code 扩展）

继续（VS Code 扩展）

Node.js 应用程序

健康监测

安全特性

监控和日志

故障排除

常见问题

寻求帮助

发展

本地开发环境设置

测试

建筑学

要求

许可证

相关 MCP

看板任务管理工具

待办事项MCP服务器

代码代理管理工具

规范工作流MCP服务器

待办事项管理服务

任务管理MCP服务器

`add_todo(title, description="", priority="medium")`

`list_todos(status="all", priority="all")`

`get_todo(todo_id)`

`update_todo(todo_id, title=None, description=None, priority=None)`

`complete_todo(todo_id)`

`reopen_todo(todo_id)`

`delete_todo(todo_id)`

`clear_completed_todos()`

`get_todo_stats()`