# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build Commands

```bash
# Build the project
dotnet build EmailSearch/EmailSearch.csproj

# Build release version
dotnet build EmailSearch/EmailSearch.csproj -c Release

# Run the MCP server (connects via stdio)
dotnet run --project EmailSearch/EmailSearch.csproj
```

## Architecture

This is an MCP (Model Context Protocol) server that provides Outlook email search capabilities to LLM clients. It runs as a stdio-based server using the Microsoft.Extensions.Hosting pattern.

**Key Components:**

- `Program.cs` - Entry point that configures the MCP server with stdio transport and registers `EmailSearchTools`
- `EmailSearchTools.cs` - MCP tool implementations decorated with `[McpServerTool]`:
  - `SearchEmails` - Search emails with filters (keywords, sender, subject, date range, folder, attachments, importance, category, flag status)
  - `ReadEmail` - Retrieve full email body by subject and date
  - `MoveToJunk` - Move an email to the Junk folder
  - `AnalyzeSpam` - Analyze a specific email for spam indicators with detailed report
  - `ScanForSpam` - Scan recent emails and return spam scores for potential spam
- `SearchFilters.cs` - Filter parameter container for email searches
- `EmailResult.cs` - DTO for search results with factory method `FromMailItem()`

**Spam Detection (`SpamDetection/` folder):**

- `SpamDetector.cs` - Core rule-based spam detection engine with 50+ heuristic patterns
- `SpamFeatures.cs` - Feature extraction model for spam analysis
- `SpamAnalysisResult.cs` - Result container with score, likelihood, and red flags
- `SpamDetectorConfig.cs` - Configuration model with customizable weights and keyword lists
- `UrlAnalyzer.cs` - URL analysis (IP-based links, URL shorteners)
- `AttachmentAnalyzer.cs` - Attachment risk scoring by file type
- `FeatureExtractors.cs` - Helper methods for URL and header extraction

**Dependencies:**

- `ModelContextProtocol` - MCP SDK for .NET
- `NetOfficeFw.Outlook` - COM interop wrapper for Outlook automation

**Platform:** Windows-only (.NET 9.0-windows) due to Outlook COM dependency

## Spam Detection Features

The spam detection system uses a weighted scoring approach (0.0-1.0) with the following detection patterns:

**Authentication Checks:**
- SPF, DKIM, DMARC authentication failures
- Reply-To domain mismatch

**Identity Spoofing:**
- Display name impersonation (vendor name + different domain)
- Subject domain impersonation
- Unicode/homoglyph attacks in domains
- Generic sender names (noreply, notification, etc.)
- Company subdomain spoofing (e.g., company.fakevoicemail.net)

**Link/URL Analysis:**
- IP address-based URLs
- URL shorteners (bit.ly, tinyurl, etc.)
- Suspicious TLDs (.xyz, .top, .click, etc.)

**Content Red Flags:**
- Keyword bait (invoice, urgent, verify, etc.)
- Placeholder text (failed mail merge)
- Single link with minimal text
- Tracking pixels (1x1 images)
- Zero-width Unicode characters (filter evasion)
- Random reference IDs in subject
- Timestamps in subject (automation indicator)

**Attachment Risk:**
- Weighted scoring by file type (0.0-1.0)
- Critical: .exe, .scr (1.0)
- High: .bat, .cmd, .vbs, .js (0.9-0.95)
- Medium: .docm, .xlsm, .html, .iso (0.6-0.8)
- Low: .zip, .rar (0.3-0.35)

**Advanced Phishing Patterns:**
- Fake quarantine/spam reports
- Fake voicemail notifications
- Fake system notifications (verify email, account suspended)
- Cold email solicitation (SEO, web design spam)

**Configuration:**

Optional `SpamDetectorConfig.json` and `BlockList.txt` files can be placed in the application directory to customize detection patterns, keywords, trusted domains, and score weights.