# Cover Letter MCP Server

A Model Context Protocol (MCP) server that generates professional PDF cover letters using LaTeX. This server integrates seamlessly with Claude Desktop to create beautifully formatted cover letters with a clean, professional design and advanced folder management capabilities.

## Features

- 🎯 **Professional Design**: Clean, modern layout matching professional resume standards
- 📄 **PDF Generation**: High-quality PDF output using LaTeX
- 🔧 **Claude Desktop Integration**: Works directly within Claude Desktop interface
- 📁 **Advanced Folder Management**: Create custom folders and organize cover letters by job, company, or category
- 🗂️ **Directory Navigation**: List and browse your cover letter collection with built-in file explorer
- ⚡ **Fast Generation**: Dockerized environment for consistent, quick processing
- 🛡️ **Input Sanitization**: Automatic escaping of special characters for LaTeX safety
- 🔒 **Secure Paths**: Built-in path sanitization prevents security issues

## Prerequisites

- **Docker**: Make sure Docker Desktop is installed and running
- **Claude Desktop**: Latest version with MCP support
- **Git**: For cloning the repository

## Quick Start

### 1. Clone the Repository

```bash
git clone https://github.com/YOUR_USERNAME/cover-letter-mcp.git
cd cover-letter-mcp
```

### 2. Create Downloads Directory

```bash
mkdir downloads
```

### 3. Build the Docker Image

```bash
docker build -t cover-letter-mcp .
```

### 4. Configure Claude Desktop

Add the following configuration to your Claude Desktop config file:

**Location of config file:**

- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`


**Configuration:**

```json
{
  "mcpServers": {
    "cover-letter-generator": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/your/cover-letter-mcp/downloads:/downloads",
        "cover-letter-mcp",
        "python",
        "server.py"
      ]
    }
  }
}
```

**Replace `/path/to/your/cover-letter-mcp/downloads` with your actual path:**

- **Windows**: `"C:/Users/YourUsername/path/to/cover-letter-mcp/downloads:/downloads"`
- **macOS/Linux**: `"/Users/YourUsername/path/to/cover-letter-mcp/downloads:/downloads"`

### 5. Restart Claude Desktop

Restart Claude Desktop to load the new MCP server configuration.

## Usage

Once configured, you can generate cover letters directly in Claude Desktop with advanced organization features:

### Example Usage

#### Basic Cover Letter Generation

```
Generate a cover letter for:
- Name: John Smith
- Company: Tech Innovations Inc
- Position: Software Engineer
- Body: I am writing to express my interest in the Software Engineer position at your company. With 5 years of experience in software development, I believe I would be a great fit for your team. My skills in JavaScript and Python align well with your requirements. I look forward to discussing this opportunity further.
```

#### Organized Cover Letter with Custom Folder

```
Generate a cover letter for Jane Doe applying to Google for a Senior Developer position and save it in the "FAANG-applications/google" folder
```

#### Advanced Organization

```
Create a cover letter for the Product Manager role at Netflix. Save it in "streaming-companies/netflix" with filename "pm-application-2024"
```

#### Folder Management

```
Create a folder structure for organizing my job applications: "job-search-2024/tech-companies" and "job-search-2024/startups"
```

```
Show me what cover letters I have in my "tech-companies" folder
```

### Smart Organization Features

- **🗂️ Auto-Folder Creation** - Folders are created automatically when generating cover letters
- **📁 Custom Directory Structure** - Organize by company, role type, industry, or any system that works for you
- **🔍 Directory Browser** - List contents of any folder to see your cover letter collection
- **📊 File Information** - View file sizes, creation dates, and organize by metadata
- **🛡️ Path Security** - Built-in sanitization prevents directory traversal and invalid characters

### Organization Examples

**By Company:**

- `applications/google/`
- `applications/microsoft/`
- `applications/amazon/`

**By Role Type:**

- `roles/software-engineer/`
- `roles/product-manager/`
- `roles/data-scientist/`

**By Industry:**

- `industries/fintech/`
- `industries/healthcare/`
- `industries/gaming/`

**By Status:**

- `drafts/`
- `submitted/2024/`
- `archived/old-versions/`

### Advanced Options

**Custom filename with organization:**

```
Generate a cover letter with filename "tech_innovations_application" for John Smith applying to Tech Innovations Inc and save it in the "applications/tech-startups" folder
```

**Multiple applications organization:**

```
I'm applying to several FAANG companies. Create cover letters for:
1. Google - Software Engineer role (save in "faang/google")
2. Meta - Frontend Developer role (save in "faang/meta")
3. Amazon - Backend Engineer role (save in "faang/amazon")
```

## API Reference

### Tools Available

#### `generate_cover_letter`

Generates a PDF cover letter from structured data with optional folder organization.

**Parameters:**

- `name` (string): Full name of the applicant
- `company` (string): Company name
- `position` (string): Position being applied for
- `body` (string): Main body text of the cover letter
- `filename` (string, optional): Custom filename (without .pdf extension)
- `folderPath` (string, optional): Custom folder path within downloads directory

**Example:**

```json
{
  "name": "John Smith",
  "company": "Tech Corp",
  "position": "Software Engineer",
  "body": "I am writing to express my strong interest...",
  "filename": "john-smith-tech-corp-application",
  "folderPath": "job-applications/tech-companies/tech-corp"
}
```

#### `create_folder`

Creates a new folder within the downloads directory.

**Parameters:**

- `folderPath` (string): Folder path to create (supports nested folders)

**Example:**

```json
{
  "folderPath": "applications/2024/q1"
}
```

#### `list_folders`

Lists all folders and files in the downloads directory.

**Parameters:**

- `path` (string, optional): Specific subdirectory to list

**Example:**

```json
{
  "path": "applications/tech-companies"
}
```

## File Structure

```
cover-letter-mcp/
├── server.py              # Main MCP server with folder management
├── Dockerfile             # Docker container configuration
├── requirements.txt       # Python dependencies
├── downloads/             # Generated PDFs organized in folders
│   ├── applications/
│   │   ├── google/
│   │   │   ├── john-smith-swe-2024.pdf
│   │   │   └── jane-doe-pm-2024.pdf
│   │   ├── microsoft/
│   │   └── startups/
│   ├── drafts/
│   └── templates/
└── README.md             # This file
```

## Technical Details

### LaTeX Template

The server uses a custom LaTeX template that creates:

- Clean, centered header with applicant name
- Professional spacing and typography
- Automatic date insertion
- Proper business letter formatting
- High-quality PDF output

### Security Features

- **Input Sanitization**: All user input is properly escaped for LaTeX
- **Filename Safety**: Generated filenames are sanitized to prevent path traversal
- **Path Security**: Folder paths are sanitized to prevent directory traversal attacks
- **Isolated Environment**: Docker container provides secure, isolated execution
- **Character Filtering**: Removes or replaces invalid filesystem characters

### MCP Protocol

This server implements the Model Context Protocol specification:

- **Tools**: `generate_cover_letter`, `create_folder`, `list_folders`
- **Resources**: Lists and provides access to generated PDFs (including nested folders)
- **Capabilities**: Full read/write access to cover letter generation and folder management

## Troubleshooting

### Common Issues

**"Docker command not found"**

- Ensure Docker Desktop is installed and running
- Verify Docker is in your system PATH

**"Permission denied" on Windows**

- Make sure Docker Desktop has access to your drive
- Try running PowerShell as Administrator
- Ensure the downloads folder has write permissions

**"Container not found"**

- Rebuild the Docker image: `docker build -t cover-letter-mcp .`
- Check that the image name matches your configuration

**"LaTeX compilation failed"**

- This usually indicates special characters in the input
- The server automatically escapes most characters, but some complex formatting may need adjustment

**"Folder creation errors"**

- Verify write permissions in the downloads directory
- Check that folder paths don't contain invalid characters
- Ensure Docker has access to the mounted volume

**"Path-related issues"**

- Folder paths are automatically sanitized for security
- Invalid characters are replaced with underscores
- Directory traversal attempts (../) are automatically blocked

### Debug Mode

To see detailed logs from the MCP server, check the Claude Desktop developer console or run the Docker container manually:

```bash
docker run --rm -i -v "./downloads:/downloads" cover-letter-mcp python server.py
```

For verbose debugging:

```bash
docker run --rm -i -v "./downloads:/downloads" -e DEBUG=1 cover-letter-mcp python server.py
```

## Development

### Local Development

For development without Docker:

1. Install Python dependencies:

   ```bash
   pip install -r requirements.txt
   ```

2. Install LaTeX (varies by system):

   ```bash
   # Ubuntu/Debian
   sudo apt-get install texlive-latex-base texlive-latex-recommended

   # macOS with Homebrew
   brew install --cask mactex

   # Windows
   # Download and install MiKTeX or TeX Live
   ```

3. Run the server:
   ```bash
   python server.py
   ```

### Security Considerations

- **Path Validation**: All folder paths are validated and sanitized
- **Input Escaping**: LaTeX special characters are properly escaped
- **Container Isolation**: Docker provides process and filesystem isolation
- **Volume Mounting**: Only the downloads directory is accessible to the container

### Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes
4. Test thoroughly with various folder structures
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

If you encounter issues:

1. Check the [troubleshooting section](#troubleshooting)
2. Review the [Claude Desktop MCP documentation](https://modelcontextprotocol.io)
3. Open an issue on GitHub with:
   - Your operating system
   - Claude Desktop version
   - Docker version
   - Complete error messages
   - Steps to reproduce

## Changelog

### v2.0.0 - Folder Management Update

- ✨ **NEW:** Custom folder organization within downloads directory
- ✨ **NEW:** `create_folder` tool for creating organized directory structures
- ✨ **NEW:** `list_folders` tool for browsing and managing cover letter collections
- ✨ **NEW:** Enhanced `generate_cover_letter` with `folderPath` parameter
- 🛡️ **NEW:** Path sanitization and security features
- 📊 **NEW:** File metadata display (size, date) in directory listings
- 🗂️ **NEW:** Auto-creation of folder paths when generating cover letters
- 📁 **NEW:** Support for nested folder structures
- 🔍 **NEW:** Directory navigation and file organization tools
- 🔒 **NEW:** Enhanced security with Docker volume isolation

### v1.0.0

- Initial release
- Professional LaTeX cover letter generation
- Docker containerization
- Claude Desktop integration
- Basic PDF output to downloads folder

---

**Made with ❤️ for the Claude Desktop and MCP community**