AI-Powered Multi-Service Sync Agent

A Python-based sync agent that integrates Notion, Obsidian, Google Calendar, and Google Tasks. The system is controlled through AI chat interactions and can run as a background service for notifications and monitoring.

Architecture

The system supports three access methods:

1. Cursor IDE (Chat)

• User requests sync via chat
• AI assistant (me) fetches source data via MCP tools (Notion/Obsidian)
• AI calls Python sync functions with MCP data
• Python sync engine processes and maps data
• Python writes to Google APIs directly
• AI reports status back to user

2. Local CLI

• User runs: python main.py --sources notion google_tasks
• Python script uses direct APIs
• Python fetches data and syncs
• CLI outputs status to console

3. Cursor Background Agent (Cloud)

• User triggers sync via Cursor Background Agent (web interface/IDE) from phone
• Python service uses direct APIs only (no MCP access)
• Python fetches data from all sources via direct APIs
• Python sync engine detects changes and processes syncs
• Service logs status and sends notifications

Setup

1. Install dependencies:

   pip install -r requirements.txt

2. Configure environment:

   • Copy .env.example to .env
   • Fill in your Google OAuth2 credentials:
     • GOOGLE_CLIENT_ID
     • GOOGLE_CLIENT_SECRET
     • GOOGLE_PROJECT
   • Add NOTION_API_TOKEN for background agent direct API access

   Important for Google OAuth:

   • If using a Web client type (recommended): Add http://localhost:8080 as an authorized redirect URI in Google Cloud Console
   • If using a Native client type: The out-of-band flow (urn:ietf:wg:oauth:2.0:oob) will be used automatically
   • The code will automatically try the web client flow first, then fall back to native if needed

3. First-time OAuth2 authentication:

   Recommended: Run the OAuth setup script once to authenticate all Google services:

   python scripts/setup_google_oauth.py

   This script will:

   • Request all required scopes (Calendar, Tasks, Drive) in one flow
   • Store refresh tokens securely (encrypted if cryptography is installed)
   • Save tokens to data/google_tokens.json.encrypted

   Alternative: OAuth will also run automatically when you first use any Google API client, but the setup script is recommended for a one-time setup.

   Note: For secure token storage, install cryptography:

   pip install cryptography

Usage

Via AI Chat (Cursor IDE)

Simply ask the AI assistant to sync your data:

"Sync my Notion tasks to Google Tasks"
"Update my calendar from Notion events"
"Sync Obsidian notes to Notion"

The AI assistant will:

1. Fetch data via MCP tools
2. Call Python sync functions
3. Report results back to you

Via Local CLI

python main.py --sources notion google_tasks --dry-run

Create Sample Items (CLI)

Create one Google Task, one Calendar event, and one Notion page:

python main.py --create --notion-parent-page-id <notion-page-id>

Notes:

• Google OAuth requires an interactive terminal the first time (you will be prompted for Tasks and Calendar).
• Notion internal integrations cannot create workspace-level pages. Share a page or database with the integration and pass its ID:
  • --notion-parent-page-id <id> or --notion-parent-database-id <id>
• Public integrations with insert_content can use --notion-parent-workspace.

Via Background Agent

Trigger syncs from your phone via Cursor Background Agent web interface (cloud).

Testing

python -m unittest discover -s tests

See docs/TESTING.md for integration and load tests.

Deployment

See docs/DEPLOYMENT.md for systemd and Windows Task Scheduler examples.

Project Structure

tracker/
├── src/
│   ├── agents/          # Sync agent classes
│   ├── data_models/     # Task, Event, Note models
│   ├── api_clients/     # Google APIs, Notion API clients
│   ├── sync/            # Sync engine (Phase 2)
│   ├── ai_interface/    # Helper functions for AI
│   ├── notifications/   # Email/SMS notifications (Phase 4)
│   └── config/          # Settings and credentials
├── config/
│   └── sync_rules.yaml  # Sync configuration
├── data/                # SQLite database, tokens
├── deploy/              # Deployment configs
├── docs/                # Documentation (setup, testing, deployment)
├── secrets/             # Credentials (gitignored)
└── tests/               # Test files

Data Flow Patterns

IDE Flow (MCP-based)

1. User requests sync via chat
2. AI assistant uses MCP tools to fetch Notion/Obsidian data
3. AI calls Python sync function: sync_notion_to_google_tasks(notion_data)
4. Python converts data models and syncs to Google APIs
5. AI reports status

CLI Flow (Direct APIs)

1. User runs CLI command
2. Python uses direct APIs
3. Python fetches data and syncs
4. CLI outputs status

Background Agent Flow (Direct APIs only)

1. User triggers via web interface
2. Python uses direct APIs (Notion API, Google APIs, Google Drive API)
3. Python fetches data, detects changes, syncs
4. Service logs and sends notifications

Configuration

Edit config/sync_rules.yaml to customize:

• Sync directions (bidirectional, unidirectional)
• Data mappings (property mappings)
• Filters (what to sync)
• Conflict resolution strategies

Security

• OAuth2 tokens stored securely in data/google_tokens.json.encrypted
• Credentials in .env file (gitignored)
• MCP tools use existing Cursor authentication
• No credentials logged or exposed

Development Status

• ✅ Phase 1: Foundation (Complete)

  • Project structure
  • Data models
  • API clients
  • Configuration system
  • AI helper functions

• ✅ Phase 2: Core Sync Logic

• ✅ Phase 3: AI Interface Integration

• ✅ Phase 4: Background Service

• ✅ Phase 5: Production Hardening

• ⏳ Phase 6: Integration & Testing

License

MIT