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 TaskPilot2.创建虚拟环境（推荐）
python -m venv venv
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate3.安装依赖项
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（推荐）
- 安装ngrok:
- 下载地址：https://ngrok.com/download - 或者通过包管理器：
# macOS
brew install ngrok
# Linux
snap install ngrok- 注册并配置 （免费等级就足够了）：
ngrok config add-authtoken YOUR_AUTH_TOKEN- 启动隧道 （在新航站楼中）：
ngrok http 8000- 复制HTTPS URL 从输出中：
Forwarding https://abcd-1234-5678.ngrok-free.app -> http://localhost:8000复制HTTPS URL（例如。， https://abcd-1234-5678.ngrok-free.app)
选项2：使用Cloudflare隧道
- 安装cloudflared:
- 下载地址：https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/
- 启动隧道 （在新航站楼中）：
cloudflared tunnel --url http://localhost:8000- 复制HTTPS URL 从输出
连接到ChatGPT
- 打开ChatGPT 并确保您可以访问ChatGPT应用程序（需要ChatGPT Plus或团队）
- 启用开发人员模式:
- 转到“设置”→ ChatGPT应用程序 - 启用“开发人员模式”
- 创建新连接器:
- 点击“创建连接器”或“+”按钮 - 选择“MCP服务器”作为连接器类型
- 配置连接器:
- 名字：TaskPilot - 统一资源定位符：粘贴您的ngrok/cloudflared HTTPS URL - MCP端点: /mcp （如果自动检测到，则保留默认值）
- 保存并测试:
- 点击“保存”或“创建” - 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服务器架构
- FastMCP服务器：使用FastMCP库创建符合MCP的HTTP服务器
- 工具注册：工具已注册
@mcp.tool()装饰器 - UI资源：HTML小部件已注册
@mcp.resource()装饰器 - 工具结果：每个工具都使用以下方式返回结构化数据
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小部件：
- 接收
structured_content通过window.openai.toolOutput - 使用交互元素呈现任务列表
- 通过以下方式调用工具
window.openai.callTool(name, args) - 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中重新创建连接器
生产部署
对于生产使用，请考虑：
- 永久存储：用数据库（SQLite、PostgreSQL等）替换内存存储
- 认证：添加API密钥验证或OAuth
- 错误处理：增强错误消息和日志记录
- 速率限制：对API端点实施速率限制
- 托管：部署到云平台（Railway、Render、Heroku、AWS等）
- 环境变量：使用环境变量进行配置
生产启动示例：
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
______________________________________________________________________
快乐任务管理！ 🚀