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.

<� Architecture Overview

The system consists of multiple components working together:

Core Components

• src/api/task_manager_api.py - FastAPI service with x402 payment middleware
• src/api/task_manager_client.py - HTTP client with x402 payment support
• src/mcp/searcher_mcp.py - MCP server exposing tools to Claude Desktop
• src/core/search_engine.py - Web search execution and AI comparison
• src/core/task_manager.py - Database operations and task management
• src/core/models.py - SQLAlchemy database models

Payment Integration

• x402 Protocol - Automatic payments for task creation ($1.00 per task)
• Payment Address - 0x671cE47E4F38051ba3A990Ba306E2885C2Fe4102
• Network - base-sepolia
• Free Endpoints - All operations except task creation

=' Setup Instructions

Option A: Local Development Setup

1. Install Dependencies

2. Environment Configuration

Copy the example environment file and configure it:

Edit .env with your configuration:

Option B: AWS Cloud Deployment

1. Prerequisites

• AWS CLI configured with appropriate permissions
• AWS CDK installed: npm install -g aws-cdk
• Python dependencies: uv sync

2. Deploy Infrastructure

This creates:

• PostgreSQL RDS database (db.t3.micro)
• S3 bucket for email templates
• AWS Secrets Manager for API keys
• IAM roles for Lambda execution
• SES email identity

3. Configure Secrets

After deployment, update the secrets in AWS Secrets Manager:

4. Verify SES Email

Go to AWS Console > 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:

6. Test Secrets Integration

Verify that the system can retrieve secrets from AWS:

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

Database Operations

4. Start the API Server

5. Configure Claude Desktop

Edit your Claude Desktop configuration file:

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

Choose the appropriate configuration based on your deployment mode:

For Local Development:

For AWS Cloud 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:

=

create_search_task (Requires Payment) Create automated monitoring tasks for any search query

• Payment: $1.00 per task creation
• Parameters: query, frequency (min 1 min), email, runtime, sender email
• Cloud Mode: Automatically deploys Lambda function + EventBridge schedule
• Local Mode: Creates task in database for manual execution
• Example: "Create a search task to monitor AI Ethics job postings every hour for the next 3 days"

� execute_search (Free)

Run a search for an existing task and get new results

• Parameters: task_id
• Example: "Execute search for task 1"

=� list_search_tasks (Free)

View all your active monitoring tasks

• Example: "Show me all my search tasks"

=� get_task_status (Free)

Get detailed status and execution history for a task

• Parameters: task_id, number of recent executions to show
• Example: "What's the status of task 2?"

=� delete_search_task (Free)

Deactivate a monitoring task

• Parameters: task_id
• Example: "Delete task 3"

=@ search_preview (Free)

Preview search results without creating a task

• Parameters: query, max_results
• Example: "Preview search results for 'Python developer remote jobs'"

=� Usage Examples

Once configured, you can use natural language in Claude Desktop:

Creating Tasks (Requires Payment)

• "Create a search task to monitor new iPhone releases every 2 hours for the next week"
• "Set up monitoring for 'remote Python jobs' checking every 5 minutes for 1 hour"
• "Monitor AI safety research papers, check daily for 2 weeks"

Managing Tasks (Free)

• "Show me all my active search tasks"
• "What's the status of my first search task?"
• "Execute a search for task 2"
• "Delete the iPhone monitoring task"

Previewing (Free)

• "Preview search results for 'Machine Learning conferences 2025'"
• "Show me what results I'd get for monitoring crypto news"

( Key Features

> AI-Powered Duplicate Detection

• Uses OpenAI to identify genuinely new items vs. formatting variations
• Significantly reduces false notifications
• Considers content similarity, company, and location

=� x402 Payment Integration

• Automatic payment processing for task creation
• Free access to all other operations
• Ethereum-based payments on base-sepolia network

=

Rich Search Results

• Finds items from multiple sources across the web
• Extracts titles, descriptions, URLs, locations, and more
• Structured data format for easy processing

� Flexible Monitoring

• Any search query (jobs, products, news, research, etc.)
• Configurable frequency (1 minute to days)
• Customizable runtime periods (1 minute to weeks)

=� Email Notifications

• Automatic notifications when new items are found
• Structured email format with all item details
• Configurable sender/recipient

=� Full History Tracking

• Complete execution history for each task
• Performance metrics and error tracking
• Easy status monitoring through Claude Desktop

🗄️ Robust Database Management

• Automated schema migrations and version tracking
• Database integrity validation and orphan detection
• Consistent session management with automatic cleanup
• Comprehensive CLI tools for database operations

<�

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

Option 2: Background Service

=' 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

• Testing: tests/test_search_quality.py, tests/quick_quality_test.py, tests/monitor_query_test.py
• Lambda: scripts/lambda_function.py, tests/test_lambda.py
• Automation: scripts/run_scheduled_tasks.py
• Entry Points: run_mcp_server.py, run_api_server.py

🧪 Testing

The project includes a comprehensive test suite covering search quality, payment integration, and API functionality.

Quick Test Run

Test Categories

1. Search Quality Tests

Validate search result quality and duplicate detection:

2. X402 Payment Integration Tests

Test payment flows with mocked x402 client:

Tests include:

• TaskManager initialization with payment config
• Create task with payment flow (mocked)
• Free endpoints work without payment
• Missing private key handling
• Payment failure scenarios

3. API Integration Tests

Test FastAPI endpoints and database integration:

Tests include:

• Health endpoint functionality
• Free endpoints (GET requests)
• Payment-required endpoints (POST /tasks/)
• Database model operations

4. Lambda Function Tests

Test AWS Lambda compatibility:

Test Configuration

For API integration tests, ensure you have:

• API server running on localhost:8000
• Valid environment variables in .env
• Database initialized with python scripts/init_db.py

Environment Variables for Testing

Test Results

The test suite validates:

• ✅ Search result quality and consistency
• ✅ AI-powered duplicate detection accuracy
• ✅ Payment integration flows
• ✅ API endpoint functionality
• ✅ Database operations
• ✅ Error handling and edge cases

This system provides powerful search monitoring capabilities with seamless payment integration through the x402 protocol!