AI导哈

任务管理服务器

一个基于FastMCP构建的全面任务管理MCP服务器，支持完整的CRUD操作、智能过滤和生产力导向的提示功能。

  • by chukaibejih
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 chukaibejih/mcp-task-manager

使用说明

任务管理器MCP服务器

使用FastMCP构建的全面任务管理MCP服务器，具有完整的CRUD操作、智能过滤和以生产力为中心的提示。该项目是构建生产就绪的MCP多租户服务器的第一阶段。

特性

🛠️ 工具（动作）

  • 创建任务：创建具有优先级、截止日期和标签的新任务
  • list_tasks：列出按状态和优先级筛选的任务
  • 获取任务：获取特定任务的详细信息
  • update_task：更新现有任务的任何方面
  • 删除任务：从系统中删除任务
  • 完成任务：快速将任务标记为已完成
  • get_task_summary：获取全面的任务统计信息

📄 资源（数据访问）

  • tasks://all：所有任务的格式化列表
  • tasks://task/｛id｝：具体任务的详细视图
  • tasks://status/{状态}：按状态筛选的任务
  • tasks://priority/{优先级}：按优先级筛选的任务
  • tasks://summary：任务统计仪表板
  • tasks://overdue：所有带有紧迫性指标的逾期任务

💬 提示（AI协助）

  • 日计划：了解当前任务状态的日常计划
  • 任务分解：将复杂任务分解为可管理的子任务
  • 每周回顾：生产力审查和成绩跟踪
  • 项目规划：全面的项目规划援助
  • 任务优先级：使用当前数据进行系统任务优先级排序

安装

  1. 克隆和设置：
git clone <repository>
cd task-manager
uv venv && source .venv/bin/activate
uv add "mcp[cli]" pydantic python-dotenv
  1. 配置环境：
cp .env.example .env
# Edit .env with your preferences
  1. 运行服务器：
python -m server.task_server

发展历程和解决的挑战

这个项目是作为一个学习练习而构建的，目的是在构建多租户架构之前了解MCP（模型上下文协议）的基本原理。以下是遇到的主要挑战和实施的解决方案：

挑战1：Python模块路径问题

问题: ModuleNotFoundError: No module named 'database' 运行服务器时。

根本原因：Python找不到 database 模块，因为它不在Python路径中。

解决方案：在Python路径中添加了项目根 server/task_server.py:

import sys
import os
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

替代解决方案：使用模块语法从项目根运行：

python -m server.task_server

挑战2：Pydantic验证错误

问题: ValidationError: Field required 服务器启动时出错 TaskSummary 模型。

根本原因：Pydantic模型定义的字段比数据库查询提供的字段多。

解决方案：更新了 get_summary() 方法in database/connection.py 提供所有必填字段：

return TaskSummary(
    total_tasks=total_tasks,
    pending_tasks=pending_tasks,
    in_progress_tasks=in_progress_tasks,
    completed_tasks=completed_tasks,
    cancelled_tasks=cancelled_tasks,  # Added missing field
    high_priority_tasks=high_priority_tasks,
    medium_priority_tasks=medium_priority_tasks,  # Added missing field
    low_priority_tasks=low_priority_tasks,  # Added missing field
    over_due_tasks=over_due_tasks,
)

挑战3：日期时间类型不匹配

问题: ValidationError: Input should be a valid string 用于日期时间字段。

根本原因：Pydantic模型预期字符串日期，但SQLite返回 datetime 物体。

解决方案：更新了 Task 中的模型 database/models.py 要使用正确的日期时间类型：

class Task(BaseModel):
    created_at: Optional[datetime] = None  # Changed from str to datetime
    updated_at: Optional[datetime] = None  # Changed from str to datetime
    due_date: Optional[datetime] = None    # Changed from str to datetime

挑战4：WSL+Windows Claude桌面集成

问题：在WSL（Ubuntu）中开发，但Claude Desktop在Windows上运行，导致路径和执行问题。

根本原因：Windows上的Claude Desktop无法直接访问WSL文件路径和命令。

尝试的解决方案:

  1. WSL直接路径 -没用
  2. 将代码复制到Windows -可以工作，但需要同步
  3. WSL集成 -最终工作解决方案

工作溶液：Claude Desktop配置中的WSL命令集成：

{
  "mcpServers": {
    "task-manager": {
      "command": "wsl",
      "args": ["-d", "Ubuntu", "-e", "bash", "-c", "cd /home/ibejih/projects/task-manager && /home/ibejih/.local/bin/uv run python -m server.task_server"]
    }
  }
}

关键发现:

  • 用过的 which uv 要查找完整的uv路径： /home/ibejih/.local/bin/uv
  • PowerShell需要 $env:APPDATA 而不是 %APPDATA%
  • Claude桌面配置位置： %APPDATA%\Claude\claude_desktop_config.json

挑战5：克劳德桌面不显示工具

问题：配置后工具未出现在Claude Desktop界面中。

根本原因：Claude Desktop进程未完全重新启动。

解决方案：使用任务管理器完成流程终止：

  1. 按 Ctrl+Shift+Esc 打开任务管理器
  2. 查找所有“Claude”进程
  3. 在每个流程上单击鼠标右键并“结束任务”
  4. 从“开始”菜单重新启动Claude Desktop

经验教训：简单地关闭窗口并不能完全重新启动Claude Desktop-必须杀死所有进程。

测试

综合测试套件

运行完整的测试套件以验证所有功能：

python test_complete.py

该测试：

  • ✅ 数据库操作（CRUD）
  • ✅ MCP工具功能
  • ✅ MCP资源服务
  • ✅ MCP提示生成

手动测试命令

使用以下命令使用Claude Desktop进行测试：

"Create a task to review quarterly reports with high priority"
"Show me all my current tasks"
"Give me a task summary"
"Help me plan my day focusing on development work"

Claude桌面集成

适用于WSL+Windows用户

  1. 在WSL中查找您的紫外线路径：
which uv
# Output: /home/username/.local/bin/uv
  1. 在以下位置创建配置文件 %APPDATA%\Claude\claude_desktop_config.json:
{
  "mcpServers": {
    "task-manager": {
      "command": "wsl",
      "args": ["-d", "Ubuntu", "-e", "bash", "-c", "cd /path/to/your/task-manager && /path/to/uv run python -m server.task_server"]
    }
  }
}
  1. 首先测试WSL命令：
wsl -d Ubuntu -e bash -c "cd /path/to/task-manager && /path/to/uv run python -m server.task_server"
  1. 完全重新启动克劳德桌面：
  • 使用任务管理器结束所有Claude进程
  • 从“开始”菜单重新启动

适用于原生Linux/macOS用户

{
  "mcpServers": {
    "task-manager": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/task-manager",
        "run",
        "python",
        "-m",
        "server.task_server"
      ]
    }
  }
}

建筑与设计决策

数据库设计

  • 数据库：非常适合学习和单租户运营
  • Pydantic模型：类型安全数据验证和序列化
  • 正确的索引：优化了状态、优先级和截止日期的查询

MCP实施

  • FastMCP SDK：利用Anthropic的官方实施
  • 结构化输出：使用Pydantic模型进行丰富的数据交换
  • 错误处理：在整个堆栈中进行全面验证
  • 上下文集成：适当的日志记录和进度报告

项目结构

task-manager/
├── database/           # Data models and connection logic
│   ├── models.py      # Pydantic models with validation
│   └── connection.py  # Database operations and queries
├── server/            # MCP server implementation
│   ├── task_server.py # Main server with lifecycle management
│   ├── tools.py       # MCP tools (actions)
│   ├── resources.py   # MCP resources (data serving)
│   └── prompts.py     # MCP prompts (AI assistance)
├── test_complete.py   # Comprehensive test suite
└── README.md         # This documentation

使用示例

创建和管理任务

User: "Create a task to review the quarterly reports with high priority and due date 2024-02-15"
Claude: [Calls create_task tool] "I've created the task 'Review quarterly reports' with high priority and due date February 15, 2024."

User: "Show me all pending tasks"
Claude: [Accesses tasks://status/pending resource] "Here are your pending tasks: ..."

User: "Mark task 1 as completed"
Claude: [Calls complete_task tool] "Task 1 has been marked as completed."

规划和生产力

User: "Help me plan my day focusing on development work"
Claude: [Uses daily_planning prompt with current task data] "Based on your current tasks, here's a focused plan for your development work today..."

关键学习成果

该项目展示了：

  • ✅ MCP协议理解：完成工具、资源和提示的实施
  • ✅ 生产模式：错误处理、验证和生命周期管理
  • ✅ 数据库集成：具有适当连接管理的SQLite
  • ✅ 跨平台开发：WSL+Windows集成策略
  • ✅ 结构化数据交换：类型安全MCP通信的Pydantic模型

下一步：多租户架构

该服务器是构建多租户MCP平台的第一阶段基础。下一阶段将包括：

  1. 租户隔离：每个租户的架构数据库设计
  2. 服务器工厂：程序化MCP服务器实例创建
  3. Django集成：用于租户管理的REST API
  4. 生产部署：可扩展的多租户基础设施

从这个项目中获得的对MCP基本原理的扎实理解使多租户挑战变得更容易管理。

故障排除

常见问题

导入错误：确保从项目根目录或使用模块语法运行 验证错误：检查Pydantic模型是否与数据库模式匹配 Claude桌面连接：验证配置文件位置并重新启动所有进程 WSL集成：在添加到Claude Desktop配置之前手动测试WSL命令

调试命令

# Test basic functionality
python test_complete.py

# Test MCP Inspector (alternative to Claude Desktop)
uv run mcp dev server/task_server.py

# Check database operations
python -c "from database.connection import get_database; print(get_database().get_summary())"

贡献

这个项目是作为学习练习而建立的，但欢迎改进！重点领域：

  • 其他MCP工具实现
  • 增强的提示模板
  • 更好的错误消息
  • 性能优化

许可证

MIT许可证-专为学习和共享MCP实现模式而构建。

相关 MCP