MCP X402 Task Scheduler

🚀 TimeLooker MCP 服务器与 x402 支付集成

TimeLooker MCP 服务器是一个具备 x402 支付集成功能的模型上下文协议（MCP）服务器，提供自动化搜索监控功能。它可以监控搜索查询，利用人工智能重复检测技术发现新内容，并自动处理任务创建的支付。

🚀 快速开始

本地开发设置

1. 安装依赖

cd /path/to/MCP_Server
uv sync

2. 环境配置

复制示例环境文件并进行配置：

cp .env.example .env

编辑 .env 文件，添加你的配置信息：

# x402 支付配置
PAY_TO_ADDRESS=0x671cE47E4F38051ba3A990Ba306E2885C2Fe4102
PRIVATE_KEY=your_ethereum_private_key_here

# API 配置
TASK_MANAGER_API_URL=http://localhost:8000

# OpenAI 配置
OPENAI_API_KEY=your_openai_api_key_here

# 数据库配置（可选）
DATABASE_URL=sqlite:///timelooker.db

AWS 云部署

1. 前提条件

• 配置好具有适当权限的 AWS CLI
• 安装 AWS CDK：npm install -g aws-cdk
• 安装 Python 依赖：uv sync

2. 部署基础设施

# 部署 AWS 基础设施（RDS、Lambda 角色、SES、S3 等）
python scripts/deploy_infrastructure.py

此操作将创建：

• PostgreSQL RDS 数据库（db.t3.micro）
• 用于存储电子邮件模板的 S3 存储桶
• 用于存储 API 密钥的 AWS Secrets Manager
• 用于 Lambda 执行的 IAM 角色
• SES 电子邮件身份

3. 配置密钥

部署完成后，在 AWS Secrets Manager 中更新密钥：

# 更新 OpenAI API 密钥
aws secretsmanager update-secret \
  --secret-id "timelooker/openai/api-key" \
  --secret-string '{"api_key":"your_openai_key_here"}'

# 更新 X402 私钥
aws secretsmanager update-secret \
  --secret-id "timelooker/x402/private-key" \
  --secret-string '{"private_key":"your_private_key_here"}'

4. 验证 SES 电子邮件

前往 AWS 控制台 > SES > 已验证身份，验证你的发件人电子邮件地址。

5. 环境配置

部署脚本会创建包含基础设施详细信息的 .env.aws 文件。更新该文件并添加你的配置信息：

cp .env.aws .env
# 编辑 .env 文件，添加你的私钥和发件人电子邮件

6. 测试密钥集成

验证系统是否可以从 AWS 检索密钥：

# 测试密钥检索
python scripts/test_secrets.py

此操作将显示系统是否可以自动从 AWS Secrets Manager 检索数据库凭证、API 密钥和其他密钥。

数据库管理

初始化数据库

# 基本初始化
python scripts/init_db.py

# 使用示例数据初始化
python scripts/init_db.py --sample

数据库操作

# 检查架构版本
python scripts/init_db.py --version

# 验证数据库完整性
python scripts/init_db.py --validate

# 运行数据库迁移
python scripts/init_db.py --migrate

# 重置数据库（删除并重新创建）
python scripts/init_db.py --reset

# 重置并创建示例数据
python scripts/init_db.py --reset --sample

启动 API 服务器

python run_api_server.py
# 或者
uv run run_api_server.py

配置 Claude 桌面应用

编辑你的 Claude 桌面应用配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

根据你的部署模式选择合适的配置：

本地开发模式

cp claude_desktop_config_local.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

AWS 云部署模式

cp claude_desktop_config_cloud.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
# 然后编辑文件，将 YOUR_ACCOUNT 和端点值替换为部署中的实际值

手动配置

你也可以手动复制 claude_config_example.json 的内容并添加你的配置信息。

重要提示：将 /absolute/path/to/MCP_Server 替换为你实际的绝对路径！

重启 Claude 桌面应用

编辑配置后，完全重启 Claude 桌面应用。

✨ 主要特性

人工智能重复检测

• 使用 OpenAI 技术识别真正的新内容，而非格式变化的重复项。
• 显著减少误报通知。
• 考虑内容相似度、公司和位置等因素。

x402 支付集成

• 自动处理任务创建的支付。
• 除任务创建外，其他操作免费。
• 基于 base-sepolia 网络的以太坊支付。

丰富的搜索结果

• 从网络上的多个来源查找内容。
• 提取标题、描述、URL、位置等信息。
• 结构化数据格式，便于处理。

灵活的监控

• 支持任何搜索查询（如招聘信息、产品、新闻、研究等）。
• 可配置监控频率（从 1 分钟到数天）。
• 可自定义运行时间段（从 1 分钟到数周）。

电子邮件通知

• 发现新内容时自动发送通知。
• 结构化电子邮件格式，包含所有内容详情。
• 可配置发件人和收件人。

完整的历史记录跟踪

• 记录每个任务的完整执行历史。
• 提供性能指标和错误跟踪。
• 通过 Claude 桌面应用轻松监控任务状态。

强大的数据库管理

• 自动进行模式迁移和版本跟踪。
• 验证数据库完整性并检测孤立数据。
• 一致的会话管理和自动清理。
• 提供全面的 CLI 工具进行数据库操作。

📦 安装指南

本地开发模式

• 设置：使用 .env 文件配置本地数据库（SQLite）。
• 任务执行：通过 MCP 工具或定时脚本手动执行。
• API 服务器：使用 python run_api_server.py 本地运行。
• MCP 服务器：使用 python run_mcp_server.py 本地运行。
• 数据库：SQLite 文件。
• 支付：仍通过 x402 协议处理。

AWS 云模式

• 设置：使用 DEPLOY_TO_CLOUD=true 的 .env 文件。
• 任务执行：通过 Lambda 函数和 EventBridge 自动执行。
• 基础设施：RDS PostgreSQL、Lambda 函数、SES、S3。
• 扩展：无服务器架构，自动处理多个任务。
• 成本：典型使用场景下每月约 15 - 30 美元。
• 优点：
  • 无需手动执行任务。
  • 运行时间到期后自动清理。
  • 通过 SES 使用专业的电子邮件模板。
  • 可扩展且容错性高。

混合模式

• API 服务器：本地开发，使用云数据库。
• 任务创建：创建 Lambda 函数进行执行。
• 适用场景：在使用生产基础设施的同时进行开发。

自动化选项

选项 1：Cron 作业

# 每 5 分钟检查一次，运行符合条件的任务
*/5 * * * * cd /path/to/MCP_Server && python scripts/run_scheduled_tasks.py

选项 2：后台服务

# 持续运行，每 60 秒检查一次
python scripts/run_scheduled_tasks.py --daemon --interval 60

💻 使用示例

配置完成后，你可以在 Claude 桌面应用中使用自然语言进行操作：

创建任务（需付费）

• “创建一个搜索任务，每 2 小时监控一次新 iPhone 发布，持续一周”
• “设置对‘远程 Python 工作’的监控，每 5 分钟检查一次，持续 1 小时”
• “监控人工智能安全研究论文，每天检查一次，持续 2 周”

管理任务（免费）

• “显示我所有的活跃搜索任务”
• “我的第一个搜索任务的状态如何？”
• “执行任务 2 的搜索”
• “删除 iPhone 监控任务”

预览（免费）

• “预览‘2025 年机器学习会议’的搜索结果”
• “显示我监控加密新闻会得到的结果”

📚 详细文档

MCP 工具

MCP 服务器为 Claude 桌面应用提供了 6 个强大的工具：

create_search_task（需付费）

为任何搜索查询创建自动化监控任务。

• 费用：每个任务创建费用为 1 美元。
• 参数：查询、频率（最小 1 分钟）、电子邮件、运行时间、发件人电子邮件。
• 云模式：自动部署 Lambda 函数和 EventBridge 调度。
• 本地模式：在数据库中创建任务，需手动执行。
• 示例：“创建一个搜索任务，每小时监控一次人工智能伦理职位发布，持续 3 天”

execute_search（免费）

为现有任务执行搜索并获取新结果。

• 参数：任务 ID。
• 示例：“执行任务 1 的搜索”

list_search_tasks（免费）

查看所有活跃的监控任务。

• 示例：“显示我所有的搜索任务”

get_task_status（免费）

获取任务的详细状态和执行历史。

• 参数：任务 ID、要显示的最近执行次数。
• 示例：“任务 2 的状态如何？”

delete_search_task（免费）

停用监控任务。

• 参数：任务 ID。
• 示例：“删除任务 3”

search_preview（免费）

在不创建任务的情况下预览搜索结果。

• 参数：查询、最大结果数。
• 示例：“预览‘Python 远程开发工作’的搜索结果”

API 端点

FastAPI 服务器提供以下端点：

• POST /tasks/ - 创建任务（需付费）
• GET /tasks/ - 列出活跃任务
• GET /tasks/{task_id} - 获取任务详情
• DELETE /tasks/{task_id} - 停用任务
• POST /executions/ - 创建执行记录
• PUT /executions/{execution_id} - 更新执行记录
• GET /tasks/{task_id}/should-run - 检查任务是否应该运行
• POST /tasks/{task_id}/results - 保存搜索结果
• GET /tasks/{task_id}/results - 获取之前的结果
• POST /tasks/{task_id}/notify - 发送电子邮件通知

🔧 技术细节

架构概述

系统由多个组件协同工作组成：

核心组件

• src/api/task_manager_api.py - 带有 x402 支付中间件的 FastAPI 服务
• src/api/task_manager_client.py - 支持 x402 支付的 HTTP 客户端
• src/mcp/searcher_mcp.py - 向 Claude 桌面应用暴露工具的 MCP 服务器
• src/core/search_engine.py - 执行网络搜索和人工智能比较
• src/core/task_manager.py - 数据库操作和任务管理
• src/core/models.py - SQLAlchemy 数据库模型

支付集成

• x402 协议：任务创建自动支付（每个任务 1 美元）
• 支付地址：0x671cE47E4F38051ba3A990Ba306E2885C2Fe4102
• 网络：base-sepolia
• 免费端点：除任务创建外的所有操作

📄 许可证

未提及相关内容，跳过该章节。

⚠️ 故障排除

MCP 服务器未显示

1. 检查 Claude 桌面应用日志：~/Library/Logs/Claude/mcp*.log
2. 验证配置文件中的绝对路径
3. 确保所有依赖项已安装
4. 完全重启 Claude 桌面应用

支付问题

1. 验证 .env 文件中是否设置了 PRIVATE_KEY
2. 确保你在 base-sepolia 网络上有足够的资金
3. 检查私钥是否有效（无 0x 前缀）

搜索错误

1. 验证 OPENAI_API_KEY 或 ANTHROPIC_API_KEY 是否设置且有效
2. 检查网络连接
3. 查看 API 服务器日志以获取详细错误信息

数据库问题

1. 检查 timelooker.db 是否存在且可写
2. 运行 python scripts/init_db.py --validate 检查数据库完整性
3. 如果数据库损坏，运行 python scripts/init_db.py --reset 重新初始化
4. 运行 python scripts/init_db.py --version 检查架构版本
5. 验证环境变量中的 SQLAlchemy 连接字符串

⏰ 任务频率指南

• 实时测试：1 - 5 分钟（短时间）
• 突发新闻：5 - 30 分钟
• 招聘信息：1 - 6 小时
• 产品发布：6 - 24 小时
• 研究论文：1 - 7 天

注意：非常频繁的检查适用于测试，但对于长时间运行的任务，请注意 OpenAI API 的成本。

📁 相关文件

项目结构

MCP_Server/
├── src/
│   ├── api/          # HTTP API 层
│   ├── core/         # 核心业务逻辑
│   └── mcp/          # MCP 服务器接口
├── tests/            # 所有测试文件
├── scripts/          # 实用脚本
├── run_mcp_server.py # MCP 服务器入口点
└── run_api_server.py # API 服务器入口点

• 测试文件：tests/test_search_quality.py、tests/quick_quality_test.py、tests/monitor_query_test.py
• Lambda 函数：scripts/lambda_function.py、tests/test_lambda.py
• 自动化脚本：scripts/run_scheduled_tasks.py
• 入口文件：run_mcp_server.py、run_api_server.py

🧪 测试

项目包含一个全面的测试套件，涵盖搜索质量、支付集成和 API 功能。

快速测试运行

# 运行所有测试
python tests/run_all_tests.py

# 交互式测试选择
python tests/run_quality_tests.py

测试类别

1. 搜索质量测试

验证搜索结果质量和重复检测：

python tests/quick_quality_test.py
python tests/test_search_quality.py

2. X402 支付集成测试

使用模拟的 x402 客户端测试支付流程：

python tests/test_x402_integration.py

测试内容包括：

• 带有支付配置的任务管理器初始化
• 模拟支付流程创建任务
• 免费端点无需支付即可工作
• 处理缺少私钥的情况
• 支付失败场景

3. API 集成测试

测试 FastAPI 端点和数据库集成：

# 首先启动 API 服务器
python run_api_server.py

# 在另一个终端中运行测试
python tests/test_api_integration.py

测试内容包括：

• 健康端点功能
• 免费端点（GET 请求）
• 需要支付的端点（POST /tasks/）
• 数据库模型操作

4. Lambda 函数测试

测试 AWS Lambda 兼容性：

python tests/test_lambda.py

测试配置

对于 API 集成测试，确保你具备以下条件：

• API 服务器在本地主机端口 8000 上运行
• .env 文件中包含有效的环境变量
• 使用 python scripts/init_db.py 初始化数据库

测试环境变量

# 支付测试所需
PRIVATE_KEY=your_test_private_key_here
PAY_TO_ADDRESS=0x671cE47E4F38051ba3A990Ba306E2885C2Fe4102
X402_NETWORK=base-sepolia

# 搜索测试所需
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# 测试可选
DATABASE_URL=sqlite:///test.db
LOG_LEVEL=INFO

测试结果

测试套件验证了以下内容：

• ✅ 搜索结果质量和一致性
• ✅ 人工智能重复检测准确性
• ✅ 支付集成流程
• ✅ API 端点功能
• ✅ 数据库操作
• ✅ 错误处理和边缘情况

这个系统通过 x402 协议提供强大的搜索监控功能和无缝的支付集成！