┌─────────────────────────────────────────────────────┐
│                  AI Assistant (Host)                  │
│  (Claude Code, Cursor, Copilot, Hermes Agent, etc.) │
└────────────────────┬────────────────────────────────┘
                     │ MCP Protocol (stdio/SSE)
                     ▼
┌─────────────────────────────────────────────────────┐
│                  UpworkBridge Server                  │
│                                                       │
│  ┌──────────────┐    ┌───────────────────────────┐   │
│  │  Scanner     │ →  │  Job Search & Scoring     │   │
│  │  Module      │    │  - 25+ predefined queries │   │
│  └──────────────┘    │  - Multi-tier categories  │   │
│                      │  - Smart scoring engine   │   │
│  ┌──────────────┐    └───────────────────────────┘   │
│  │  Proposer    │    ┌───────────────────────────┐   │
│  │  Module      │ →  │  Proposal Generation      │   │
│  └──────────────┘    │  - AI-assisted drafting   │   │
│                      │  - Skill-based templates  │   │
│                      │  - Best practices engine  │   │
│  ┌──────────────┐    └───────────────────────────┘   │
│  │  OAuth       │    ┌───────────────────────────┐   │
│  │  Handler     │ →  │  Token Management         │   │
│  └──────────────┘    │  - OAuth 2.0 auth flow    │   │
│                      │  - Auto token refresh     │   │
│  ┌──────────────┐    └───────────────────────────┘   │
│  │  Config      │    ┌───────────────────────────┐   │
│  │  Engine      │ →  │  Search params, scoring   │   │
│  └──────────────┘    │  weights, user profile    │   │
│                      └───────────────────────────┘   │
└────────────────────┬────────────────────────────────┘
                     │ Upwork API (OAuth 2.0)
                     ▼
┌─────────────────────────────────────────────────────┐
│                  Upwork Platform                      │
│  Job listings · Proposals · Contracts · Messages     │
└─────────────────────────────────────────────────────┘

# Clone the repo
git clone https://github.com/your-org/upworkbridge.git
cd upworkbridge

# Install dependencies
pip install -r requirements.txt

# Configure credentials
cp config.example.py config.py
# Edit config.py with your Upwork Client ID and Secret

# Run initial OAuth authorization
python src/scanner.py --auth

# Search for jobs
python src/scanner.py

# Generate a proposal
python src/propose.py --job-id <JOB_ID>

{
  "mcpServers": {
    "upwork": {
      "command": "python",
      "args": ["/path/to/upworkbridge/src/scanner.py", "--mcp"],
      "env": {
        "UPWORK_CLIENT_ID": "your_client_id",
        "UPWORK_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}