TaskFlow MCP Server

使用说明（Markdown 格式）

• 项目简介

  • 该仓库实现了一个基于 MCP（Model Context Protocol）的后端服务器，用于向 LLM 客户端提供统一的上下文信息、工具执行能力和提示渲染。核心组件包括 MCP 服务器、8 个 MCP 工具、以及通过 PostgreSQL 的会话记忆与多用户数据隔离等特性，便于在 AI 场景中进行任务管理与对话协作。
  • MCP 服务器通过一个名为 FastMCP 的框架搭建，提供工具注册、消息路由、会话管理等能力，并与现有 FastAPI 等后端服务通过 BackendClient 进行数据访问与操作。

• 主要功能点

  • MCP 核心能力：实现对 MCP 请求/响应的处理，提供标准化的工具调用、资源操作以及提示渲染能力。
  • 工具集（8 个 MCP Tools）：add_task、list_tasks、get_task、update_task、delete_task、complete_task、search_tasks、filter_tasks，用于对后端任务数据的增删改查及过滤。
  • 会话记忆与持久化：通过 Memory/ConversationMemory 与 PostgreSQL 数据库实现对话历史的记忆和持久化，确保对话在重启后可恢复。
  • 后端对接：BackendClient 封装对现有 FastAPI 后端的调用接口，实现对任务数据的实际访问和修改。
  • 安全与鉴权：提供 MCP 端点的鉴权/令牌处理逻辑，确保请求的身份校验与数据访问控制。
  • NLP 与 prompts：整合简单的自然语言处理（解析日期、优先级、标签等）与系统提示，提升对话式任务管理的体验。

• 安装步骤（简要）

  • 克隆仓库并进入项目根目录。
  • 安装依赖（例如 Python 环境与所需的包，可以用 Poetry/uv 或直接 pip 根据项目需求）。
  • 配置环境变量：
    • MCP 服务器端口通常为 8001（可通过 MCP_SERVER_PORT 指定）。
    • MCP 后端地址 MCP_BACKEND_URL 指向现有的 FastAPI 后端服务（任务数据等的实际存取端点）。
    • OpenAI/模型相关密钥（如 OPENAI_API_KEY）按需设置，用于与 MCP Agent 的对接。
  • 启动后端（FastAPI）服务并确保可访问。
  • 启动 MCP 服务器：
    • 推荐命令形式之一：uv run python -m src.mcp_server.server
    • 或直接运行 Python 模块：python -m src.mcp_server.server
  • 如部署在 Kubernetes/HF Spaces，请参照项目文档中的 Phase IV/Phase III 部署示例进行配置。

• 服务器配置示例（MCP 客户端无需，提供给 MCP 客户端的注释性说明）

  • 服务器名称（server name）: taskflow-mcp-server
  • 启动命令（command）: python
  • 参数（args）: -m src.mcp_server.server
  • 端口: 8001（默认 MCP 服务器端口，可通过 MCP_SERVER_PORT 修改）
  • 说明：以上配置用于在客户端发起 MCP 请求时，MCP 服务器应以该命令启动并监听端口。客户端不需要额外的实现细节，MCP 客户端通过定义的接口与该服务器进行交互。

• 基本使用方法

  • 连接与调用：LLM 客户端通过 MCP 服务器暴露的工具接口，发起对 add_task、list_tasks 等工具的调用，请求以 MCP 的格式传递，服务器返回标准的 JSON-RPC 风格响应或错误信息。
  • 会话记忆与上下文：对话历史通过 PostgreSQL 进行持久化，确保跨会话的上下文可用；工具调用也会在后端记忆中记录相关信息以便后续引用。
  • 安全性与扩展：通过鉴权组件对请求进行校验，确保访问的用户具有相应的权限；可按需扩展更多工具、 memory 方案与 NLP 能力。

• 备注

  • 本实现支持多阶段应用场景（Phase I~Phase III），包括控制台、Web、AI 聊天与 Kubernetes 部署等，从而提供端到端的 MCP 服务器能力。
  • 如需与前端推送/订阅等传输协议（如 SSE/WebSocket/StdIO），可在进一步的部署配置中扩展传输适配层。