Smarttask Orchestrator MCP

智能任务编排器MCP

SmartTask Assistant MCP是一个用于日常执行任务的AI操作层。用户用自然语言编写一条指令，后端用GPT解释它，用业务上下文丰富它，然后触发正确的n8n工作流来执行电子邮件和任务操作。

该平台设计用于实际的团队使用：快速的请求接收、结构化的操作提取、联系人授权检查，以及通过单个API和仪表板提供可靠的自动化反馈。

主要流程：

• 模型：GPT-4o-mini提取动作、收件人、日期、时间、优先级和元数据。
• 背景：业务验证、联系人匹配、规范化、置信度评分。
• 协议：n8n webhook执行和结构化响应处理。

web UI可在 http://localhost:8000 编排贯穿n8n http://localhost:5678.

1） 项目架构

核心文件：

• main.py：FastAPI服务器、MCP编排、API端点。
• model/gpt_client.py：OpenAI异步客户端和指令解析器。
• context/context.py：丰富上下文、联系授权、信心评分。
• protocol/n8n_api.py：webhook负载生成器和n8n执行客户端。
• workflow_n8n_optimized.json：n8n工作流（v6）用于导入和发布。
• templates/index.html：前端仪表板。

2） 先决条件

• Python 3.11+
• Docker桌面（适用于n8n）
• OpenAI API密钥
• 谷歌帐户（如果您在n8n中使用Gmail+谷歌表格节点）

3） 安装和运行（Windows PowerShell）

从项目根目录运行：

py -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
docker compose up -d n8n
python main.py

访问权限：

• 应用程序UI： http://localhost:8000
• n8n： http://localhost:5678
• 健康API： http://localhost:8000/health

compose中的默认n8n基本身份验证：

• 用户： admin
• 密码： smarttask2024

4） 环境配置

应用程序从以下位置加载环境值 config.env.

最低要求值：

OPENAI_API_KEY=your_openai_key
N8N_WEBHOOK_URL=http://localhost:5678
N8N_WEBHOOK_PATH=/webhook/smarttask
USER_NAME=Your Name
USER_EMAIL=your.email@example.com

笔记：

• 代码读取 N8N_WEBHOOK_URL 在 protocol/n8n_api.py.
• 如果 N8N_WEBHOOK_URL 缺失，默认为 http://localhost:5678.

5） n8n工作流设置

1. 打开n8n http://localhost:5678.
2. 导入 workflow_n8n_optimized.json.
3. 在节点中配置凭据：

- Gmail Sender ->Gmail OAuth2（如果需要电子邮件操作） - Google Sheets Writer ->Google表格OAuth2（如果需要附加任务表）

1. 保存工作流。
2. 发布工作流（在某些n8n UI上，这会取代“激活”）。
3. 在 SmartTask Webhook，确保：

- 路径： smarttask - 生产URL包含 /webhook/smarttask

6） API终点

• GET / ->web界面
• POST /process-instruction ->主MCP处理端点
• GET /health ->健康检查(gpt_client, n8n_client)

7） 快速测试

A） 从应用程序API端到端

$form = @{ instruction = "Envoie un email a Bilal pour la reunion de demain a 14h" }
Invoke-RestMethod -Method Post -Uri "http://localhost:8000/process-instruction" -Form $form | ConvertTo-Json -Depth 10

B） 直接webhook测试URL（n8n编辑器模式）

$body = @{
  workflow_type = "create_task"
  sheet_gid = "gid=0"
  task = @{
    title = "Test SmartTask"
    description = "Validation webhook test"
  }
  contact = @{
    name = "Your Name"
    email = "your.email@example.com"
  }
} | ConvertTo-Json -Depth 6

Invoke-RestMethod -Method Post -Uri "http://localhost:5678/webhook-test/smarttask" -ContentType "application/json" -Body $body | ConvertTo-Json -Depth 12

C） 直接webhook生产URL

仅在工作流发布后使用：

Invoke-RestMethod -Method Post -Uri "http://localhost:5678/webhook/smarttask" -ContentType "application/json" -Body $body | ConvertTo-Json -Depth 12

8） 常见问题

404 webhook未注册

错误：

The requested webhook "POST smarttask" is not registered

修复：

• 在n8n中保存和发布工作流。
• 验证webhook路径是否 smarttask.
• 使用生产URL /webhook/smarttask 只有在出版之后。

Google表格“找不到名称为任务的表格”

修复：

• 在 Google Sheets Writer，选择正确的工作表选项卡。
• 在该工作流程中， sheet_gid 可以在有效载荷中发送（默认 gid=0).

n8n中的OAuth错误（谷歌）

典型原因：

• 重定向URI不匹配
• 帐户未添加为OAuth测试用户
• 错误的谷歌云项目/API配置

9） 停止服务

应用内终端：

Ctrl + C

然后停止n8n：

docker compose down

10） 安全说明

• 不要提交真正的API密钥或OAuth机密。
• 保持 config.env 私人。
• 如果密钥被暴露，请立即旋转/撤销它。

11） 作者

• 埃尔巴特赫·艾哈迈德