# Job Outreach MCP Server

An MCP server for automated job outreach that helps you find companies, discover contacts, generate personalized emails with AI, and track your outreach campaigns.

## Features

| Tool | Description |
|------|-------------|
| `search_companies` | Find companies from job boards (Indeed) or add manually |
| `find_contacts` | Add contacts with automatic email pattern generation and SMTP verification |
| `research_company` | Scrape company websites for personalization data using AI |
| `add_job_posting` | Track specific job postings you're applying to |
| `generate_email` | AI-powered personalized email generation using Claude |
| `schedule_email` | Smart scheduling for optimal delivery times (Tue-Thu, 9-11am) |
| `check_tracking` | Monitor opens, clicks, and replies |
| `schedule_followup` | Automatic follow-up email generation |
| `list_campaigns` | Overview of all your outreach campaigns |

## Setup

1. **Install dependencies:**
   ```bash
   npm install
   ```

2. **Configure settings:**
   ```bash
   cp data/config.example.json data/config.json
   ```
   Edit `data/config.json` with your credentials.

3. **Build:**
   ```bash
   npm run build
   ```

## Configuration

Edit `data/config.json`:

```json
{
  "smtp": {
    "host": "smtp.your-server.com",
    "port": 587,
    "user": "your-username",
    "password": "your-password",
    "from_email": "you@example.com"
  },
  "anthropic_api_key": "sk-ant-...",
  "user_profile": {
    "name": "Your Name",
    "title": "Software Engineer",
    "resume_summary": "Your background...",
    "linkedin_url": "https://linkedin.com/in/you",
    "highlights": ["5+ years experience", "TypeScript expert"]
  },
  "smart_schedule": {
    "timezone": "America/Los_Angeles",
    "preferred_days": [2, 3, 4],
    "preferred_hours": [9, 10, 11]
  },
  "followup": {
    "enabled": true,
    "days_between": 5,
    "max_followups": 2
  },
  "tracking_server": {
    "port": 3847,
    "base_url": "http://your-server:3847"
  }
}
```

## Usage with Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):

```json
{
  "mcpServers": {
    "job-outreach": {
      "command": "node",
      "args": ["/path/to/auto-job-application/dist/index.js"]
    }
  }
}
```

## Running the Email Processor

The email processor sends scheduled emails and handles tracking:

```bash
npm run processor
```

Run this in the background to automatically send emails at their scheduled times.

## Workflow Example

1. **Add a company:**
   ```
   search_companies({ query: "Stripe", source: "manual" })
   ```

2. **Add a contact:**
   ```
   find_contacts({
     company_id: 1,
     contacts: [{ name: "Jane Doe", title: "Recruiter" }]
   })
   ```

3. **Research the company:**
   ```
   research_company({ company_id: 1 })
   ```

4. **Add job posting (optional):**
   ```
   add_job_posting({
     company_id: 1,
     title: "Senior Engineer",
     url: "https://stripe.com/jobs/123"
   })
   ```

5. **Generate personalized email:**
   ```
   generate_email({ contact_id: 1, job_posting_id: 1 })
   ```

6. **Schedule delivery:**
   ```
   schedule_email({ email_id: 1, smart_schedule: true })
   ```

7. **Check status:**
   ```
   check_tracking({ company_id: 1 })
   ```

8. **Schedule follow-up (if no reply):**
   ```
   schedule_followup({ email_id: 1 })
   ```

## Architecture

```
src/
├── index.ts              # MCP server entry point
├── processor.ts          # Background email processor
├── types.ts              # TypeScript types
├── tools/                # MCP tool implementations
│   ├── search-companies.ts
│   ├── find-contacts.ts
│   ├── research-company.ts
│   ├── generate-email.ts
│   ├── schedule-email.ts
│   ├── check-tracking.ts
│   ├── schedule-followup.ts
│   ├── list-campaigns.ts
│   └── add-job-posting.ts
├── services/             # Core services
│   ├── database.ts       # SQLite operations
│   ├── config.ts         # Configuration loader
│   ├── scraper.ts        # Web scraping with Puppeteer
│   ├── email-patterns.ts # Email generation & SMTP verification
│   ├── llm.ts            # Claude API integration
│   ├── scheduler.ts      # Smart scheduling logic
│   └── smtp.ts           # Email sending
└── tracking/
    └── server.ts         # Open/click tracking webhook server
```

## Email Tracking

The tracking server provides:
- **Open tracking:** 1x1 pixel embedded in emails
- **Click tracking:** Link wrapping with redirect
- **Reply webhooks:** Endpoint for email provider callbacks

For tracking to work, the tracking server must be accessible from the internet (use ngrok for testing or deploy the processor).

## Notes

- LinkedIn scraping is not implemented (requires authentication and is against ToS)
- Email SMTP verification may be blocked by some mail servers
- Smart scheduling picks optimal send times: Tuesday-Thursday, 9-11am recipient timezone
- The background processor must be running for scheduled emails to be sent

## License

MIT