AI导哈

任务管理MCP服务器

一个基于Python和FastMCP构建的轻量级任务管理MCP服务器，提供交互式UI组件用于ChatGPT应用。

  • by graphcs
  • HTML
  • 本地部署
  • 更新于
在 GitHub 查看 graphcs/TaskPilot

使用说明

TaskPilot-用于ChatGPT应用程序的MCP服务器

使用Python和FastMCP构建的最小但功能齐全的MCP（模型上下文协议）服务器，演示了使用ChatGPT的交互式UI组件进行任务管理。

特性

  • 两个核心工具:

    • add_task(text: str) -向列表中添加新任务
    • list_tasks() -使用统计信息检索所有任务

  • 其他工具:

    • complete_task(task_id: int) -将任务标记为已完成
    • delete_task(task_id: int) -从列表中删除任务

  • 交互式UI小部件:

    • 美观、响应迅速的任务列表界面
    • 直接从小部件添加任务
    • 单击以完成/不完成任务
    • 确认后删除任务
    • 实时统计（总计、待处理、已完成）
    • 暗模式支持

  • 内存存储：任务存储在内存中（服务器重启时重置）

需求

  • Python 3.8或更高版本
  • pip（Python包管理器）

安装

1.克隆或下载

导航到项目目录：

cd TaskPilot

2.创建虚拟环境（推荐）

python -m venv venv

# On macOS/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

3.安装依赖项

pip install -r requirements.txt

在本地运行服务器

使用以下命令启动服务器：

python server.py

您应该看到如下输出：

============================================================
TaskPilot MCP Server Starting...
============================================================

Server will be available at: http://localhost:8000

To expose this server to ChatGPT:
  1. Install ngrok: https://ngrok.com/download
  2. Run: ngrok http 8000
  3. Copy the HTTPS URL from ngrok
  4. In ChatGPT, go to Developer Mode > Create Connector
  5. Enter the ngrok URL

============================================================

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

服务器现在正在运行 http://localhost:8000.

暴露于ChatGPT

由于ChatGPT需要HTTPS访问您的服务器，因此您需要创建一个安全的隧道。您有两个主要选择：

选项1：使用ngrok（推荐）

  1. 安装ngrok:

    • 下载地址：https://ngrok.com/download
    • 或者通过包管理器：
      # macOS
brew install ngrok

# Linux
snap install ngrok

  2. 注册并配置 （免费等级就足够了）：

    ngrok config add-authtoken YOUR_AUTH_TOKEN

  3. 启动隧道 （在新航站楼中）：

    ngrok http 8000

  4. 复制HTTPS URL 从输出中：

    Forwarding  https://abcd-1234-5678.ngrok-free.app -> http://localhost:8000

    复制HTTPS URL（例如。， https://abcd-1234-5678.ngrok-free.app)

选项2：使用Cloudflare隧道

  1. 安装cloudflared:

    • 下载地址：https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/

  2. 启动隧道 （在新航站楼中）：

    cloudflared tunnel --url http://localhost:8000

  3. 复制HTTPS URL 从输出

连接到ChatGPT

  1. 打开ChatGPT 并确保您可以访问ChatGPT应用程序（需要ChatGPT Plus或团队）

  2. 启用开发人员模式:

    • 转到“设置”→ ChatGPT应用程序
    • 启用“开发人员模式”

  3. 创建新连接器:

    • 点击“创建连接器”或“+”按钮
    • 选择“MCP服务器”作为连接器类型

  4. 配置连接器:

    • 名字：TaskPilot
    • 统一资源定位符：粘贴您的ngrok/cloudflared HTTPS URL
    • MCP端点: /mcp （如果自动检测到，则保留默认值）

  5. 保存并测试:

    • 点击“保存”或“创建”
    • ChatGPT将验证连接
    • 您应该看到列出的工具： add_task, list_tasks, complete_task, delete_task

在ChatGPT中使用TaskPilot

连接后，您可以直接在ChatGPT中与TaskPilot交互：

示例提示：

"Show me my tasks"
→ ChatGPT calls list_tasks() and displays the interactive widget

"Add a task to buy groceries"
→ ChatGPT calls add_task(text="buy groceries") and shows updated list

"Mark task 1 as completed"
→ ChatGPT calls complete_task(task_id=1)

"Delete task 2"
→ ChatGPT calls delete_task(task_id=2)

交互式小部件：

当您要求查看任务时，ChatGPT将显示一个交互式小部件，您可以在其中：

  • 查看所有带有统计信息的任务
  • 使用输入字段添加新任务
  • 单击任务以切换完成
  • 使用回收站图标删除任务
  • 查看任务元数据（ID、创建日期）

项目结构

TaskPilot/
├── server.py           # Main FastMCP server with tool definitions
├── task_list.html      # Interactive UI widget component
├── requirements.txt    # Python dependencies
└── README.md          # This file

运作原理

MCP服务器架构

  1. FastMCP服务器：使用FastMCP库创建符合MCP的HTTP服务器
  2. 工具注册：工具已注册 @mcp.tool() 装饰器
  3. UI资源：HTML小部件已注册 @mcp.resource() 装饰器
  4. 工具结果：每个工具都使用以下方式返回结构化数据 ToolResult 类

工具响应格式

每个工具返回：

  • 内容：ChatGPT对话的人类可读文本
  • 结构化内容：小部件的机器可读JSON数据
  • 元：元数据，包括用于UI渲染的OpenAI特定字段

示例响应来自 list_tasks():

ToolResult(
    content=[TextContent(
        type="text",
        text="Found 3 task(s): 2 pending, 1 completed"
    )],
    structured_content={
        "tasks": [
            {"id": 1, "text": "Buy groceries", "status": "pending", ...},
            {"id": 2, "text": "Write report", "status": "completed", ...}
        ],
        "total": 2,
        "pending": 1,
        "completed": 1
    },
    meta={
        "operation": "list_tasks",
        "timestamp": "2025-01-15T10:30:00"
    }
)

UI小部件集成

HTML小部件：

  1. 接收 structured_content 通过 window.openai.toolOutput
  2. 使用交互元素呈现任务列表
  3. 通过以下方式调用工具 window.openai.callTool(name, args)
  4. ChatGPT在工具调用后自动刷新小部件

小部件渲染元数据

工具包括OpenAI特定的元数据：

meta={
    "openai/outputTemplate": "ui://taskwidget/task_list.html",
    "openai/widgetAccessible": True,
    "openai/resultCanProduceWidget": True,
    "openai/toolInvocation/invoking": "Loading tasks...",
    "openai/toolInvocation/invoked": "Tasks loaded"
}

此操作会通知ChatGPT：

  • 渲染指定的HTML模板
  • 使小部件具有交互性
  • 显示加载/完成消息

发展

以开发模式运行

默认情况下，服务器在启用自动重新加载的情况下运行：

python server.py

对以下内容的任何更改 server.py 将自动重新启动服务器。

修改UI

编辑 task_list.html 自定义小部件的外观或行为。服务器动态读取此文件，因此您需要重新启动服务器才能使更改生效。

添加新工具

通过装饰功能添加新工具 @mcp.tool():

@mcp.tool(
    meta={
        "openai/outputTemplate": "ui://taskwidget/task_list.html",
        "openai/widgetAccessible": True
    }
)
def my_new_tool(param: str) -> ToolResult:
    """Tool description for the model."""
    return ToolResult(
        content=[TextContent(type="text", text="Result text")],
        structured_content={"data": "value"},
        meta={"custom": "metadata"}
    )

故障排除

服务器无法启动

  • 确保端口8000未被使用： lsof -i :8000 （macOS/Linux）
  • 检查Python版本： python --version （要求3.8+）
  • 验证依赖关系： pip install -r requirements.txt

ChatGPT无法连接

  • 验证您的隧道是否正在运行（ngrok/cloudflared）
  • 确保您使用的是HTTPS URL（不是HTTP）
  • 检查中的CORS设置 server.py （应该允许 chatgpt.com)
  • 验证MCP端点是否可访问： https://your-url.ngrok.app/mcp

小部件未显示

  • 检查浏览器控制台是否存在JavaScript错误
  • 验证 task_list.html 与存在于同一目录中 server.py
  • 确保MIME类型为 text/html+skybridge
  • 验证URI模式： ui://taskwidget/task_list.html

工具未显示

  • 检查工具登记 server.py
  • 验证工具架构是否有效
  • 代码更改后重新启动服务器
  • 在ChatGPT中重新创建连接器

生产部署

对于生产使用，请考虑：

  1. 永久存储：用数据库（SQLite、PostgreSQL等）替换内存存储
  2. 认证：添加API密钥验证或OAuth
  3. 错误处理：增强错误消息和日志记录
  4. 速率限制：对API端点实施速率限制
  5. 托管：部署到云平台（Railway、Render、Heroku、AWS等）
  6. 环境变量：使用环境变量进行配置

生产启动示例：

uvicorn server:app --host 0.0.0.0 --port 8000 --workers 4

技术规格

  • MCP协议版本: 2025-06-18
  • FastMCP版本: 2.0+
  • 内容类型: text/html+skybridge
  • 工具响应格式：具有结构化内容的ToolResult
  • UI协议: ui:// 资源URI

许可证

MIT许可证-可根据需要自由使用和修改。

资源

  • FastMCP文档: https://gofastmcp.com
  • MCP规范: https://modelcontextprotocol.io
  • OpenAI应用软件开发工具包: https://developers.openai.com/apps-sdk
  • ChatGPT应用指南: https://help.openai.com/en/articles/chatgpt-apps

支持

对于问题或疑问：

  • FastMCP GitHub：https://github.com/jlowin/fastmcp
  • MCP GitHub：https://github.com/modelcontextprotocol
  • OpenAI开发者论坛：https://community.openai.com

快乐任务管理！ 🚀

相关 MCP