使用说明

待办事项列表MCP服务器

用于管理待办事项列表的生产就绪模型上下文协议（MCP）服务器。该服务器可以通过HTTP（SSE传输）进行web集成，也可以通过Claude Desktop的stdio传输进行访问，从而通过自然语言实现AI驱动的任务管理。

🌟 什么是MCP？

模型上下文协议（MCP）是一种开放协议，可实现AI模型与外部数据源或工具之间的无缝集成。它为AI助手与您的应用程序、数据库和服务交互提供了一种标准化的方式。

苏格兰和南方能源公司与标准运输公司

此服务器支持两种传输方式：

SSE（服务器发送事件）
- 用于基于HTTP的通信
- 非常适合web应用程序、API和云部署
- 允许通过网络进行远程访问
- 非常适合与OpenAI等服务集成
标准输入/输出
- 用于本地进程间通信
- Claude Desktop集成所需
- 更安全（仅限本地）
- 本地应用程序的延迟更低

🚀 特性

完整的CRUD操作：创建、读取、更新、删除待办事项
自然语言处理：使用对话命令进行交互
优先级管理：按优先级（高、中、低）组织任务
智能过滤：查看所有、已完成或待处理的待办事项
统计仪表板：了解您的生产力
永久存储：待办事项以JSON格式保存在本地
多运输支持：SSE（HTTP）和stdio模式
AI集成就绪：与Claude Desktop配合使用
Docker支持：已准备好进行集装箱化部署
云原生：专为Google Cloud Run和类似平台设计

📋 可用的MCP工具

工具	说明	示例用法
`create_todo`	创建一个带有标题、描述和优先级的新待办事项	“添加一个高优先级任务来审查预算”
`list_todos`	列出带有筛选选项的待办事项	“显示所有待处理任务”
`get_todo`	获取特定待办事项的详细信息	“获取待办事项_20240115_143022_0的详细信息”
`update_todo`	更新待办事项标题、描述或优先级	“将预算审查优先级更改为中等”
`complete_todo`	将待办事项标记为已完成	“完成待办事项_20240115_143022_0”
`complete_todo_by_number`	按位置完成待办事项	“完成第二项任务”
`uncomplete_todo`	将待办事项标记为待定	“重新打开预算审查任务”
`delete_todo`	删除特定待办事项	“删除待办事项_20240115_143022_0”
`clear_completed_todos`	删除所有已完成的待办事项	“清除所有已完成任务”
`get_todo_stats`	获取您待办事项的统计数据	“显示我的生产力统计数据”

🏃 快速开始

先决条件

Python 3.8或更高版本
pip（Python包管理器）
Docker（可选，用于容器化部署）
Claude桌面（可选，用于Claude集成）
OpenAI API密钥（可选，用于GPT-4.1集成）

安装

克隆存储库：

git clone https://github.com/enesbasbug/ToDo-MCP-Server.git
cd ToDo-MCP-Server

创建虚拟环境（推荐）：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

安装依赖项：

pip install -r requirements.txt

🖥️ 本地运行

选项1:SSE模式（HTTP服务器）

将此模式用于web应用程序、API访问或AI集成：

python server.py

服务器将于启动 http://localhost:8050/sse

测试SSE服务器：

python client.py

输出：

Todo List MCP Client
1. Run automated tests
2. Interactive mode
Select mode (1 or 2): X

选择模式1进行自动测试，或选择模式2进行交互模式。

选项2：标准模式（克劳德桌面）

有关Claude Desktop集成，请参阅我们的详细指南： Claude桌面设置指南

快速概述：

使用stdio传输进行本地通信
通过Claude实现自然语言待办事项管理
需要在Claude Desktop设置中进行配置

看看它在行动：

Creating todos naturally

Managing your tasks

→ 完整的Claude桌面设置说明

选项3:Docker

# Build the image
docker build -t todo-mcp-server .

# Run with SSE mode
docker run -p 8050:8050 todo-mcp-server

# Run with persistent storage
docker run -p 8050:8050 -v $(pwd)/todos_data:/app/data todo-mcp-server

🤖 AI集成

OpenAI GPT-4.1集成

该服务器可以与OpenAI的GPT-4.1集成，以实现自然语言待办事项管理：

设置您的OpenAI API密钥：

# Create .env file
echo "OPENAI_API_KEY=your-api-key-here" > .env

运行OpenAI客户端：
```
python openai_client.py
```

自然互动：

You: I need to prepare for tomorrow's team meeting and review the Q3 reports
Assistant: I'll help you organize these tasks. Let me create them for you...
[Creates two todos with appropriate priorities]

You: What's on my plate for today?
Assistant: Here are your pending tasks for today:
1. [HIGH] Review Q3 reports
2. [HIGH] Prepare for team meeting
3. [MEDIUM] Update project documentation

You: I finished reviewing the reports
Assistant: Great! I'll mark the Q3 reports review as completed.

如何与LLMs合作

自然语言理解：法学硕士解释了你的意图
工具选择：它选择合适的MCP工具
参数提取：从您的邮件中提取必要的信息
动作执行：调用MCP服务器执行操作
响应生成：提供人性化的响应

LLM整合的好处

没有要记住的命令请自然地说话
情境感知：AI会记住你的对话（目前仅适用于本地对话（Claude Desktop）。)
聪明的建议：获得智能任务优先级
批量操作：在一个请求中处理多个任务

☁️ 云部署

谷歌云运行

准备部署：

# Update deploy.sh with your project ID
chmod +x deploy.sh
./deploy.sh

更新您的客户端URL

部署后，您将收到一个URL，如下所示： https://todo-mcp-server-xxxxx-uc.a.run.app

你必须更新全部使用此URL的客户端代码：
```
# ❌ OLD (localhost)
client = TodoMCPClient("http://localhost:8050/sse")

# ✅ NEW (Cloud Run URL)
client = TodoMCPClient("https://todo-mcp-server-xxxxx-uc.a.run.app/sse")
```

🔧 配置

环境变量

变量	描述	默认值	必填
`PORT`	SSE模式的服务器端口	`8050`	云运行
`TODOS_FILE`	存储待办事项的路径	`todos.json`	所有模式
`OPENAI_API_KEY`	OpenAI API密钥	无	OpenAI集成

🔄 部署后配置（如果已部署）

更新客户端URL

当您从本地开发转向云部署时，请记住更新所有客户端连接：

文件	本地URL	云URL
`openai_client.py`	`http://localhost:8050/sse`	`https://your-service.run.app/sse`
`client.py`	`http://localhost:8050/sse`	`https://your-service.run.app/sse`
自定义脚本	`http://localhost:8050/sse`	`https://your-service.run.app/sse`

专业提示： 为URL使用环境变量：

import os
MCP_URL = os.environ.get('MCP_SERVER_URL', 'http://localhost:8050/sse')
client = TodoMCPClient(MCP_URL)

💾 数据存储

当前实施情况

此服务器使用 JSON文件存储 为了简单和便携。虽然不适合多用户或大批量操作的生产使用，但它非常适合：

学习和尝试MCP
个人待办事项管理
小团队部署
概念验证实施

存储位置

SSE模式: todos.json 在当前目录中
标准模式: ~/todo_mcp_data.json 在主目录中
码头工人：可通过卷装进行配置

生产注意事项

对于生产部署，请考虑：

数据库：适用于单用户应用程序
PostgreSQL/MySQL：适用于多用户应用程序
云火库：用于无服务器部署
雷迪斯：用于高性能缓存

模块化设计使交换存储后端变得容易，而无需更改MCP接口。

📚 使用示例

API直接使用（Python）

import asyncio
from mcp import ClientSession
from mcp.client.sse import sse_client

async def manage_todos():
    async with sse_client("http://localhost:8050/sse") as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # Create a todo
            result = await session.call_tool(
                "create_todo",
                arguments={
                    "title": "Review project proposal",
                    "description": "Review and provide feedback on Q1 project proposal",
                    "priority": "high"
                }
            )
            print(result.content[0].text)
            
            # List all todos
            result = await session.call_tool("list_todos")
            print(result.content[0].text)

asyncio.run(manage_todos())

自然语言示例

使用Claude Desktop或其他支持MCP的应用程序：

"I need to finish three things today: email the client, update the budget spreadsheet, and call the vendor"
→ Creates 3 todos with appropriate details

"Show me what I haven't finished yet"
→ Lists all pending todos

"The client email is done"
→ Marks the email task as completed

"What's my highest priority right now?"
→ Shows high priority pending tasks

🏗️ 建筑

有两种运输方式可供选择：

SSE模式 (server.py)：用于HTTP/API访问、Docker和云部署
标准模式 (server_stdio.py)：适用于克劳德桌面(安装指南)

┌─────────────────┐                    ┌─────────────────┐
│  Claude Desktop │                    │   Web Client    │
│  (Natural Lang) │                    │   (Direct API)  │
└────────┬────────┘                    └────────┬────────┘
         │                                      │
         │ Stdio                                │ HTTP/SSE
         │                                      │
┌────────▼────────┐                    ┌────────▼────────┐
│ server_stdio.py │                    │    server.py    │
│  (Local Only)   │                    │  (Network Ready)│
└────────┬────────┘                    └────────┬────────┘
         │                                      │
         └──────────────┬───────────────────────┘
                        │
                        ▼
                 ┌─────────────┐
                 │  todos.json │
                 │   Storage   │
                 └─────────────┘

📊 监控和记录

地方发展
- 日志随时间戳和严重性级别输出到控制台。

🚨 故障排除

SSE服务器问题

端口已在使用中：

lsof -i :8050  # Find process using port
kill -9 <PID>  # Kill the process

连接被拒绝：
- 检查服务器是否正在运行： ps aux | grep server.py
- 验证防火墙设置
- 确保URL格式正确： http://localhost:8050/sse

Claude桌面问题

服务器未出现：
- 验证配置文件中的JSON语法
- 使用绝对路径
- 重新启动克劳德桌面
工具不工作：
- 检查Python路径： which python
- 验证MCP安装： pip show mcp

OpenAI集成问题

API关键错误：
- 验证.env文件是否存在
- 检查API密钥的有效性
- 确保有足够的API信用
工具执行失败：
- 检查服务器是否正在运行
- 验证网络连接
- 查看错误日志

🤝 贡献

我们欢迎捐款！请参阅我们的投稿指南：

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

内置于模型上下文协议
由...驱动 FastMCP
通过AI集成 OpenAI 和人物克劳德