AI导哈

任务管理服务

一个生产级的任务管理系统，通过自然语言与Claude交互，实现跨平台的任务管理、优先级排序和项目组织。

  • by MartyBonacci
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 MartyBonacci/task-manager-mcp

使用说明

任务管理器MCP服务器

用于会话任务管理的生产级模型上下文协议（MCP）服务器，可从Claude.ai、Claude mobile和Claude Code访问。

概述

该项目实现了一个功能齐全的任务管理系统，该系统通过与Claude的自然对话来工作。您只需告诉Claude需要做什么，Claude就可以通过MCP工具管理持久任务数据库，而不是点击UI。

交互示例：

You: "I need to research sublimation options for Custom Cult and update my LinkedIn profile"
Claude: "Added two tasks:
  1. Research sublimation options (Custom Cult, High priority, 2hr)
  2. Update LinkedIn profile (Personal, Medium priority, 30min)"

You: "What should I work on now? I have about an hour free."
Claude: "You could tackle the LinkedIn update (30min, light energy) and still have time left, 
or start the sublimation research if you're feeling focused."

主要特点

  • ✅ 会话界面 -通过Claude实现自然语言任务管理
  • ✅ 交叉平台的 -通过MCP在网络、移动和终端上工作
  • ✅ 永久存储 -任务在对话边界中幸存下来
  • ✅ 智能优先级 -优先级、能量水平和时间估计跟踪
  • ✅ 项目组织机构 -按项目对任务进行分类
  • ✅ OAuth 2.1身份验证 -使用动态客户端注册进行安全身份验证（RFC 7591）
  • ✅ 综合测试 -81个测试，代码覆盖率为66.93%
  • 🚧 日历集成 -（未来）将任务安排为日历事件

文档

该项目包括从头开始构建的全面文档：

📋 项目_规格.md

完整的技术规范包括：

  • 功能要求和范围
  • MCP协议合规性详细信息
  • 数据库模式与API设计
  • 安全要求
  • 每个阶段的成功标准
  • 时间表估计

🏗️ 建筑.md

系统架构和设计决策：

  • 组件细分（API、MCP、业务逻辑、数据层）
  • 数据流程图
  • 身份验证架构
  • 部署策略
  • 性能考虑
  • 项目结构和文件组织

🚀 SETUP_GUIDE.md

分步实施指南：

  • 先决条件和依赖关系
  • 第一阶段：地方发展设置
  • 所有组件的完整代码示例
  • 测试说明
  • 故障排除提示
  • OAuth和部署的下一步

☁️ 部署.md

Google Cloud Run部署指南：

  • 先决条件和GCP设置
  • OAuth凭据配置
  • Docker容器化
  • Cloud Run部署步骤
  • 部署后验证
  • 监控和记录设置
  • 故障排除和回滚程序

📊 项目状态.md

当前实施状态：

  • 阶段完成总结（第1-2阶段完成）
  • 测试覆盖率分析（66.93%）
  • 已应用关键修复
  • 生产准备检查表
  • 经验教训和下一步行动

🧪 TEST_RESULTS.md

详细测试分析：

  • 按模块划分的测试结果（81次测试，100%通过）
  • 基于优先级的修复跟踪
  • 覆盖率报告明细
  • 已知问题和解决方法

快速开始

先决条件

  • Python 3.11+
  • 已安装克劳德代码
  • 谷歌云平台帐户（用于部署）

安装

# Clone repository
git clone https://github.com/MartyBonacci/task-manager-mcp.git
cd task-manager-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment
cp .env.example .env
# Edit .env with your configuration

# Initialize database
python -c "from app.db.database import init_db; init_db()"

# Run server
uvicorn app.main:app --reload

测试IT

# Terminal 1: Server running (from above)

# Terminal 2: Test the API
python scripts/test_local.py

连接到克劳德代码

添加到您的 ~/.claude/mcp_servers.json:

{
  "task-manager": {
    "command": "python",
    "args": ["-m", "uvicorn", "app.main:app", "--port", "8000"],
    "cwd": "/path/to/task-manager-mcp"
  }
}

然后在克劳德代码中：

"Show me my MCP tools"
"Create a task: Build amazing MCP server"
"List all my tasks"

测试

该项目包括全面的测试覆盖率（总体66.93%）：

运行所有测试

# Run complete test suite
pytest tests/ -v

# Run with coverage report
pytest tests/ --cov=app --cov-report=html --cov-report=term-missing

# View coverage report in browser
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

测试模块

  • test_mcp_handlers.py -MCP工具单元测试（10/10通过）
  • test_task_service.py -任务服务业务逻辑（10/10通过）
  • test_mcp_auth.py -MCP认证流程（9/9通过）
  • test_oauth_integration.py -OAuth 2.1端到端流（8/8传递）
  • test_session_validation.py -会话管理（10/10通过）
  • test_user_isolation.py -用户数据隔离（8/8通过）
  • test_dynamics_clients.py -动态客户端注册（18/18通过）
  • test_regression_conftest_hang.py -数据库清理回归（3/3通过）

已知问题

完整的测试套件可能会挂起pytest-asyncio事件循环清理。解决方法：单独或分组运行测试模块。

看 docs/TEST_RESULTS.md 查看详细的测试结果和覆盖率分析。

开发阶段

✅ 第一阶段：地方发展（完成）

  • [x] 带stdio连接的基本MCP服务器
  • [x] 使用SQLAlchemy ORM的SQLite数据库
  • [x] 所有CRUD操作（8个MCP工具）
  • [x] 可从Claude代码本地测试
  • [x] 综合单元测试（10/10通过）

✅ 第二阶段：HTTP+OAuth（完成）

  • [x] 具有FastAPI的HTTP端点
  • [x] OAuth 2.1与谷歌身份验证
  • [x] 移动/本地应用程序的动态客户端注册（RFC 7591）
  • [x] MCP规范2025-06-18合规性
  • [x] 使用加密刷新令牌的会话管理
  • [x] 集成测试（8/8 OAuth流测试通过）
  • [x] 错误场景测试（23/23通过）
  • [x] 代码覆盖率：66.93%（1022/1360条语句）

🚧 第三阶段：云部署（NEXT）

  • []Docker容器化
  • []Google Cloud Run部署
  • []OAuth回调配置
  • []可通过Claude.ai和手机访问
  • []生产数据库（PostgreSQL）

🔮 第四阶段：生产波兰语（未来）

  • []全面的错误处理
  • []监控和记录（结构化日志）
  • []性能优化（缓存、查询优化）
  • []日历集成
  • []分析仪表板

项目结构

task-manager-mcp/
├── README.md                    # This file
├── PROJECT_SPEC.md              # Technical specification
├── ARCHITECTURE.md              # System design
├── SETUP_GUIDE.md               # Implementation guide
├── requirements.txt
├── Dockerfile
├── .env.example
│
├── app/
│   ├── main.py                  # FastAPI app entry
│   ├── api/                     # HTTP routes & middleware
│   ├── mcp/                     # MCP server implementation
│   ├── services/                # Business logic
│   ├── db/                      # Database models & connection
│   ├── auth/                    # OAuth implementation
│   ├── config/                  # Configuration
│   └── schemas/                 # Pydantic schemas
│
├── tests/                       # Test suite
└── scripts/                     # Utility scripts

MCP工具

服务器公开了以下MCP工具：

  • task_create -创建一个新任务，包括标题、项目、优先级、能量水平、时间估计
  • 任务列表 -列出带有可选筛选器的任务（项目、优先级、完成状态）
  • 任务集 -按ID获取特定任务
  • 任务更新 -更新所有任务字段
  • 任务完成 -将任务标记为已完成
  • task_delete -删除任务
  • 任务搜索 -按关键字搜索任务
  • task_stats -获取分析（按项目、优先级、完成率计数）

技术栈

  • 框架：FastAPI（异步Python web框架）
  • MCP-SDK：MCP官方Python SDK
  • 数据库：SQLAlchemy ORM与SQLite（开发）/PostgreSQL（产品）
  • 认证：使用谷歌认证的OAuth 2.1
  • 部署：Google Cloud Run（无服务器容器）
  • 测试：支持异步的pytest

使用SpecSwarm构建

该项目旨在使用 SpecSwarm，一个多代理开发协调器。

SpecSwarm方法

主要代理人 （管弦乐队指挥）：

  • 协调整体发展
  • 读取项目_SPEC.md、建筑.md、设置_GUIDE.md
  • 专业代理代表
  • 集成组件

专业代理:

  • 数据库代理：模型、迁移、模式
  • API代理：FastAPI路由、中间件
  • MCP代理：协议合规性、工具处理程序
  • 身份验证代理：OAuth实现
  • 测试代理：单元和集成测试

使用SpecSwarm进行初始化

# In project directory with all .md files present
specswarm init

# SpecSwarm will:
# 1. Read README.md (this file)
# 2. Discover PROJECT_SPEC.md, ARCHITECTURE.md, SETUP_GUIDE.md
# 3. Create work breakdown from specs
# 4. Coordinate specialist agents
# 5. Build the complete system

看 SpecSwarm文档 了解更多详情。

安全

  • OAuth 2.1身份验证
  • 用户数据隔离（用户只能访问自己的任务）
  • 输入验证和净化
  • 参数化SQL查询（防止注入）
  • 仅在生产环境中使用HTTPS
  • 速率限制
  • 日志中没有任务内容

贡献

欢迎投稿！拜托：

  1. 阅读 项目_规格.md 和 建筑.md
  2. 创建要素分支
  3. 添加新功能的测试
  4. 确保所有测试通过
  5. 提交拉取请求

路线图

第二阶段特征:

  • 日历集成（将任务安排为事件）
  • 自然语言到期日期解析
  • 任务模板
  • 分析仪表板

未来的增强功能:

  • 周期性任务
  • 子任务和依赖关系
  • 团队/共享任务列表
  • 时间跟踪
  • 移动推送通知
  • 第三方集成（Slack、GitHub等）

用例

个人生产力:

  • 管理多个商业项目
  • 协调教学准备与发展工作
  • 在技术工作的同时跟踪创意项目

开发项目:

  • 将功能分解为任务
  • 追踪漏洞和技术债务
  • Sprint计划和积压管理

内容创作:

  • 视频制作任务列表
  • 博客帖子想法和大纲
  • 社交媒体内容日历

业务运营:

  • 客户跟进
  • 供应商通信
  • 库存和供应管理

作者

马蒂·博纳奇

  • Deep Dive Coding的编程训练营讲师
  • Custom Cult单板技术创始人
  • SpecSwarm的创造者和四种思维模式
  • 领英
  • GitHub

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

内置：

支持

如有疑问、问题或功能请求：

  • 在GitHub上打开一个问题
  • 联系LinkedIn
  • 检查 SETUP_GUIDE.md 用于故障排除

状态: ✅ 第2阶段完成-实现OAuth 2.1身份验证

测试覆盖率：66.93%（81项测试，全部通过）

下一个里程碑第三阶段：Docker容器化和Google Cloud Run部署

最后更新：2025年12月26日

相关 MCP