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 協議提供強大的搜索監控功能和無縫的支付集成！