TimeLooker MCP Server

TimeLooker MCP Server with x402 Payment Integration

A Model Context Protocol (MCP) server that provides automated search monitoring functionality with x402 payment integration. Monitor search queries, detect new content using AI-powered duplicate detection, and automatically process payments for task creation.

\ SES > Verified identities and verify your sender email address.

5. Environment Configuration

The deployment script creates .env.aws with the infrastructure details. Update it with your values:

cp .env.aws .env
# Edit .env to add your private key and sender email

6. Test Secrets Integration

Verify that the system can retrieve secrets from AWS:

# Test secrets retrieval
python scripts/test_secrets.py

This will show whether the system can automatically retrieve database credentials, API keys, and other secrets from AWS Secrets Manager.

3. Database Management

Initialize Database

# Basic initialization
python scripts/init_db.py

# Initialize with sample data
python scripts/init_db.py --sample

Database Operations

# Check schema version
python scripts/init_db.py --version

# Validate database integrity
python scripts/init_db.py --validate

# Run database migrations
python scripts/init_db.py --migrate

# Reset database (drop and recreate)
python scripts/init_db.py --reset

# Reset and create sample data
python scripts/init_db.py --reset --sample

4. Start the API Server

python run_api_server.py
# or
uv run run_api_server.py

5. Configure Claude Desktop

Edit your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

Choose the appropriate configuration based on your deployment mode:

For Local Development:

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

For AWS Cloud Deployment:

cp claude_desktop_config_cloud.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Then edit the file to replace YOUR_ACCOUNT and endpoint values with actual values from deployment

Manual Configuration:

You can also manually copy the contents from claude_config_example.json and add your values.

Important: Replace /absolute/path/to/MCP_Server with your actual absolute path!

6. Restart Claude Desktop

Completely restart Claude Desktop after editing the configuration.

=� MCP Tools Available

The MCP server provides 6 powerful tools for Claude Desktop:

=

创建搜索任务 （需要付款） 为任何搜索查询创建自动监控任务

• 支付：每个任务创建1.00美元
• 参数：查询、频率（至少1分钟）、电子邮件、运行时、发件人电子邮件
• 云模式：自动部署Lambda函数+EventBridge计划
• 本地模式：在数据库中创建手动执行的任务
• 示例: *“创建一个搜索任务，在接下来的3天里每小时监控一次人工智能道德职位发布”*

� 执行搜索 （免费）

搜索现有任务并获取新结果

• 参数：task_id
• 示例: *“执行任务1的搜索”*

=� list_search_tasks （免费）

查看所有活动的监控任务

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

=� get_task_status （免费）

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

• 参数：task_id，要显示的最近执行次数
• 示例: *“任务2的状态如何？”*

=� 删除搜索任务 （免费）

停用监控任务

• 参数：task_id
• 示例: *“删除任务3”*

=@ 搜索_查看 （免费）

预览搜索结果而不创建任务

• 参数：query，max_results
• 示例: *“预览‘Python开发人员远程工作’的搜索结果”*

=� 使用示例

配置后，您可以在Claude Desktop中使用自然语言：

创建任务（需要付款）

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

管理任务（免费）

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

预览（免费）

• *“预览‘2025年机器学习会议’的搜索结果”*
• *“告诉我监控加密货币新闻会得到什么结果”*

（主要特征

> AI驱动的重复检测

• 使用OpenAI识别真正的新项目与格式变化
• 显著减少虚假通知
• 考虑内容相似性、公司和位置

=� x402支付集成

• 任务创建的自动支付处理
• 免费访问所有其他操作
• 基于以太坊的基础sepolia网络支付

=

丰富的搜索结果

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

� 灵活监控

• 任何搜索查询（职位、产品、新闻、研究等）
• 可配置频率（1分钟到几天）
• 可定制的运行时间（1分钟到几周）

=� 电子邮件通知

• 发现新项目时自动通知
• 包含所有项目详细信息的结构化电子邮件格式
• 可配置的发件人/收件人

=� 完整历史跟踪

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

🗄️ 稳健的数据库管理

• 自动模式迁移和版本跟踪
• 数据库完整性验证和孤立检测
• 具有自动清理功能的一致会话管理
• 用于数据库操作的全面CLI工具

\<�

B Deployment Options

Local Development Mode

• Setup: Use .env with local database (SQLite)
• Task Execution: Manual via MCP tools or scheduled scripts
• API Server: Run locally with python run_api_server.py
• MCP Server: Run locally with python run_mcp_server.py
• Database: SQLite file
• Payments: Still processed via x402

AWS Cloud Mode

• Setup: Use .env with DEPLOY_TO_CLOUD=true
• Task Execution: Automatic via Lambda functions + EventBridge
• Infrastructure: RDS PostgreSQL, Lambda functions, SES, S3
• Scaling: Serverless, automatically handles multiple tasks
• Cost: ~$15-30/month for typical usage
• Benefits:

- No manual task execution needed - Automatic cleanup after runtime expires - Professional email templates via SES - Scalable and fault-tolerant

Hybrid Mode

• API Server: Local development with cloud database
• Task Creation: Creates Lambda functions for execution
• Best for: Development while using production infrastructure

Automation Options

Option 1: Cron Job

# Check every 5 minutes, run eligible tasks
*/5 * * * * cd /path/to/MCP_Server && python scripts/run_scheduled_tasks.py

Option 2: Background Service

# Run continuously, checking every 60 seconds
python scripts/run_scheduled_tasks.py --daemon --interval 60

=' API Endpoints

The FastAPI server provides these endpoints:

• POST /tasks/ - Create task (requires payment)
• GET /tasks/ - List active tasks
• GET /tasks/{task_id} - Get task details
• DELETE /tasks/{task_id} - Deactivate task
• POST /executions/ - Create execution record
• PUT /executions/{execution_id} - Update execution
• GET /tasks/{task_id}/should-run - Check if task should run
• POST /tasks/{task_id}/results - Save search results
• GET /tasks/{task_id}/results - Get previous results
• POST /tasks/{task_id}/notify - Send email notification

= Troubleshooting

MCP Server Not Showing Up

1. Check Claude Desktop logs: ~/Library/Logs/Claude/mcp*.log
2. Verify the absolute path in your configuration
3. Ensure all dependencies are installed
4. Restart Claude Desktop completely

Payment Issues

1. Verify PRIVATE_KEY is set in .env
2. Ensure you have funds on base-sepolia network
3. Check that the private key is valid (without 0x prefix)

Search Errors

1. Verify OPENAI_API_KEY or ANTHROPIC_API_KEY is set and valid
2. Check internet connection
3. Look at API server logs for detailed error messages

Database Issues

1. Check if timelooker.db exists and is writable
2. Run python scripts/init_db.py --validate to check database integrity
3. Run python scripts/init_db.py --reset to reinitialize if corrupted
4. Use python scripts/init_db.py --version to check schema version
5. Verify SQLAlchemy connection string in environment variables

=� Task Frequency Guidelines

• Real-time Testing: 1-5 minutes (short duration)
• Breaking News: 5-30 minutes
• Job Postings: 1-6 hours
• Product Releases: 6-24 hours
• Research Papers: 1-7 days

Note: Very frequent checks are great for testing, but be mindful of OpenAI API costs for long-running tasks.

= Related Files

Project Organization

MCP_Server/
├── src/
│   ├── api/          # HTTP API layer
│   ├── core/         # Core business logic  
│   └── mcp/          # MCP server interface
├── tests/            # All test files
├── scripts/          # Utility scripts
├── run_mcp_server.py # MCP server entry point
└── run_api_server.py # API server entry point

• Testing: tests/test_search_quality.py, tests/quick_quality_test.py, tests/monitor_query_test.py
• 拉姆达: scripts/lambda_function.py, tests/test_lambda.py
• 自动化: scripts/run_scheduled_tasks.py
• 入口点: run_mcp_server.py, run_api_server.py

🧪 测试

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

快速试运行

# Run all tests
python tests/run_all_tests.py

# Interactive test selection
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

测试包括：

• 使用支付配置初始化TaskManager
• 使用支付流创建任务（模拟）
• 免费端点无需付费即可工作
• 缺少私钥处理
• 支付失败场景

3.API集成测试

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

# Start API server first
python run_api_server.py

# In another terminal, run tests
python tests/test_api_integration.py

测试包括：

• 健康端点功能
• 自由端点（GET请求）
• 需要付款的端点（POST/任务/）
• 数据库模型操作

4.Lambda函数测试

测试AWS Lambda兼容性：

python tests/test_lambda.py

测试配置

对于API集成测试，请确保您具备：

• API服务器在本地主机上运行：8000
• 中的有效环境变量 .env
• 数据库已初始化 python scripts/init_db.py

测试环境变量

# Required for payment tests
PRIVATE_KEY=your_test_private_key_here
PAY_TO_ADDRESS=0x671cE47E4F38051ba3A990Ba306E2885C2Fe4102
X402_NETWORK=base-sepolia

# Required for search tests  
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Optional for testing
DATABASE_URL=sqlite:///test.db
LOG_LEVEL=INFO

测试结果

测试套件验证：

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

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