# Invoice MCP Server

A Model Context Protocol (MCP) server for generating professional invoices as PDFs or sending them via email. This server provides tools that allow Claude to create, customize, and distribute invoices based on a professional template.

## 🚀 Quick Start

### Option 1: NPX (Recommended)
Run directly without installation:
```bash
npx invoice-mcp-server
```

### Option 2: Docker
```bash
# Pull and run
docker run -p 3000:3000 -v $(pwd)/invoices:/app/invoices invoice-mcp-server

# Or build locally
docker build -t invoice-mcp-server .
docker run -p 3000:3000 -v $(pwd)/invoices:/app/invoices invoice-mcp-server
```

### Option 3: Traditional Installation
```bash
git clone https://github.com/kmexnx/invoice-mcp-server.git
cd invoice-mcp-server
npm install
npm run build
```

## ✨ Features

- 📄 **PDF Generation**: Create professional invoices as PDF files
- 📧 **Email Integration**: Send invoices directly via email
- 🎨 **Template-based**: Uses a clean, professional invoice template
- 💼 **Business Ready**: Includes all standard invoice fields (tax rates, line items, etc.)
- 🔧 **Customizable**: Easy to modify template and styling
- 🐳 **Docker Support**: Run in containers for easy deployment
- ⚡ **NPX Ready**: No installation required with npx
- 📁 **Smart Directory Handling**: Automatic directory creation with fallbacks

## 📋 Prerequisites

### For NPX/Local Installation:
- Node.js 18+
- For email functionality: SMTP server credentials

### For Docker:
- Docker installed
- For email functionality: SMTP server credentials

## 🛠️ Installation & Setup

### Method 1: NPX (Zero Installation)

The easiest way to get started:

```bash
# Run directly
npx invoice-mcp-server

# With custom output directory
OUTPUT_DIR=/Users/yourname/Documents/invoices npx invoice-mcp-server

# With environment variables
SMTP_HOST=smtp.gmail.com SMTP_USER=you@gmail.com OUTPUT_DIR=/tmp/invoices npx invoice-mcp-server
```

### Method 2: Docker Setup

1. **Create a docker-compose.yml**:
```yaml
version: '3.8'
services:
  invoice-mcp:
    image: invoice-mcp-server
    ports:
      - "3000:3000"
    volumes:
      - ./invoices:/app/invoices
      - ./.env:/app/.env
    environment:
      - SMTP_HOST=smtp.gmail.com
      - SMTP_PORT=587
      - SMTP_USER=your-email@gmail.com
      - SMTP_PASS=your-app-password
      - FROM_EMAIL=your-email@gmail.com
      - FROM_NAME=Your Company Name
      - OUTPUT_DIR=/app/invoices
```

2. **Run with Docker Compose**:
```bash
docker-compose up -d
```

### Method 3: Traditional Installation

1. **Clone and install**:
```bash
git clone https://github.com/kmexnx/invoice-mcp-server.git
cd invoice-mcp-server
npm install
npm run setup  # Creates directories and checks permissions
```

2. **Configure environment**:
```bash
cp .env.example .env
# Edit .env with your settings
```

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

## 📁 Directory Configuration

The server needs a directory to save generated PDF invoices. It uses this priority order:

1. **Custom Directory** (Recommended): Set `OUTPUT_DIR` environment variable
2. **Default Local**: `./invoices` in current directory
3. **Fallback**: System temporary directory

### Setting Custom Output Directory

#### For NPX users:
```bash
# Set for current session
export OUTPUT_DIR=/Users/yourname/Documents/invoices
npx invoice-mcp-server

# Or inline
OUTPUT_DIR=/path/to/your/invoices npx invoice-mcp-server
```

#### For permanent setup:
Add to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):
```bash
export OUTPUT_DIR=/Users/yourname/Documents/invoices
```

#### For Docker users:
```bash
docker run -e OUTPUT_DIR=/app/invoices -v /your/local/path:/app/invoices invoice-mcp-server
```

### Directory Permissions

The server automatically:
- ✅ Creates the output directory if it doesn't exist
- ✅ Tests write permissions
- ✅ Falls back to temporary directories if needed
- ✅ Provides clear error messages

If you encounter permission issues:
```bash
# Create and set permissions manually
mkdir -p /path/to/your/invoices
chmod 755 /path/to/your/invoices

# Or use a directory you own
export OUTPUT_DIR=$HOME/Documents/invoices
```

## 🔧 Claude Desktop Configuration

Add this server to your Claude Desktop configuration:

### For NPX Usage:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "invoice-server": {
      "command": "npx",
      "args": ["invoice-mcp-server"],
      "env": {
        "OUTPUT_DIR": "/Users/yourname/Documents/invoices",
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_USER": "your-email@gmail.com",
        "SMTP_PASS": "your-app-password",
        "FROM_EMAIL": "your-email@gmail.com",
        "FROM_NAME": "Your Company Name"
      }
    }
  }
}
```

### For Docker Usage:
```json
{
  "mcpServers": {
    "invoice-server": {
      "command": "docker",
      "args": ["exec", "invoice-mcp-container", "node", "/app/dist/index.js"],
      "env": {
        "OUTPUT_DIR": "/app/invoices",
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_USER": "your-email@gmail.com",
        "SMTP_PASS": "your-app-password"
      }
    }
  }
}
```

### For Local Installation:
```json
{
  "mcpServers": {
    "invoice-server": {
      "command": "node",
      "args": ["/path/to/invoice-mcp-server/dist/index.js"],
      "env": {
        "OUTPUT_DIR": "/Users/yourname/Documents/invoices",
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_USER": "your-email@gmail.com",
        "SMTP_PASS": "your-app-password"
      }
    }
  }
}
```

## 💬 Usage Examples

### Basic Invoice Creation
```
Claude, create me an invoice for "Acme Corp" for the amount of $5000
```

### Detailed Invoice
```
Claude, create an invoice with the following details:
- Client: TechStart Inc.
- Services: Web Development (40 hours at $125/hour), Logo Design ($500)
- Tax rate: 8.5%
- Due date: 30 days from today
- Save as PDF and email to client@techstart.com
```

### Multiple Line Items
```
Claude, generate an invoice for:
- Company: Global Solutions LLC
- Item 1: Consulting Services - $2,500
- Item 2: Project Management - $1,200
- Item 3: Documentation - $800
- Tax rate: 7.25%
- Email it to accounting@globalsolutions.com
```

## 🛠️ Available Tools

### 1. `create_invoice_pdf`
Generates a PDF invoice file.

**Parameters:**
- `invoice_data`: Complete invoice information
- `filename`: Optional custom filename

### 2. `send_invoice_email`
Creates and sends an invoice via email.

**Parameters:**
- `invoice_data`: Complete invoice information
- `recipient_email`: Email address to send to
- `subject`: Optional custom email subject
- `message`: Optional custom email message

### 3. `get_invoice_template`
Returns the current invoice template structure for reference.

## 📊 Invoice Data Structure

```typescript
{
  // Company Information
  company: {
    name: string;
    address: string;
    city: string;
    state: string;
    zipCode: string;
    phone?: string;
    fax?: string;
    email?: string;
  };
  
  // Client Information
  billTo: {
    name: string;
    company?: string;
    address: string;
    city: string;
    state: string;
    zipCode: string;
    phone?: string;
  };
  
  // Invoice Details
  invoiceNumber: string;
  date: string;
  dueDate?: string;
  
  // Line Items
  items: Array<{
    description: string;
    amount: number;
  }>;
  
  // Financial Details
  taxRate?: number; // as percentage (e.g., 8.5 for 8.5%)
  other?: number;   // additional fees/discounts
}
```

## 🔍 Environment Variables

| Variable | Description | Required | Default | Example |
|----------|-------------|----------|---------|---------|
| `OUTPUT_DIR` | **PDF output directory** | **Recommended** | `./invoices` | `/Users/name/Documents/invoices` |
| `SMTP_HOST` | SMTP server host | No* | - | `smtp.gmail.com` |
| `SMTP_PORT` | SMTP server port | No | `587` | `587` |
| `SMTP_USER` | SMTP username | No* | - | `you@gmail.com` |
| `SMTP_PASS` | SMTP password | No* | - | `your-app-password` |
| `FROM_EMAIL` | From email address | No | `SMTP_USER` | `billing@company.com` |
| `FROM_NAME` | From name | No | - | `Your Company Name` |
| `TEMP_DIR` | Temporary files directory | No | System temp | `/tmp` |

*Required only for email functionality

### Important Notes:

- **OUTPUT_DIR**: Highly recommended to set this to avoid permission issues
- **SMTP credentials**: Only needed if you want to email invoices
- **Paths**: Use absolute paths for best results
- **Permissions**: Ensure the OUTPUT_DIR is writable

## 🐳 Docker Configuration

### Dockerfile
```dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY dist ./dist
COPY .env.example ./.env

RUN mkdir -p invoices

EXPOSE 3000

CMD ["node", "dist/index.js"]
```

### Docker Environment
```bash
# Run with environment variables
docker run -e SMTP_HOST=smtp.gmail.com \
           -e SMTP_USER=you@gmail.com \
           -e SMTP_PASS=yourpassword \
           -e OUTPUT_DIR=/app/invoices \
           -v $(pwd)/invoices:/app/invoices \
           invoice-mcp-server
```

## 🧪 Development

### Project Structure

```
invoice-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── invoice-generator.ts  # PDF generation logic
│   ├── email-service.ts      # Email functionality
│   ├── invoice-template.ts   # HTML template
│   └── setup.js             # Setup script
├── dist/                     # Compiled JavaScript
├── invoices/                 # Generated PDFs (created by setup)
├── Dockerfile               # Docker configuration
├── docker-compose.yml       # Docker Compose setup
├── package.json
└── README.md
```

### NPM Scripts

```bash
npm run build      # Compile TypeScript
npm run dev        # Development mode with watch
npm start          # Run compiled server
npm run setup      # Create directories and check setup
npm run clean      # Clean build directory
npm run docker     # Build Docker image
```

### Testing

Test the server using the MCP inspector:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

### Setup Script

The setup script (`npm run setup`) will:
- ✅ Create necessary directories
- ✅ Test write permissions
- ✅ Check Node.js version
- ✅ Verify package structure
- ✅ Display helpful diagnostics

## 🐛 Troubleshooting

### Common Issues

#### Directory Permission Errors
```bash
# Solution 1: Set custom directory
export OUTPUT_DIR=/Users/yourname/Documents/invoices
mkdir -p $OUTPUT_DIR

# Solution 2: Use setup script
npm run setup

# Solution 3: Use temporary directory
export OUTPUT_DIR=/tmp/invoices
```

#### NPX Issues
- **Package not found**: Ensure you have npm 5.2+ for npx support
- **Permission errors**: Try setting OUTPUT_DIR to a directory you own
- **Directory creation fails**: Use `OUTPUT_DIR=/tmp/invoices npx invoice-mcp-server`

#### Docker Issues  
- **Port conflicts**: Change port mapping `-p 3001:3000`
- **Volume issues**: Ensure local directories exist and are writable
- **Memory limits**: Increase Docker memory for large invoices

#### Email Issues
- **Gmail**: Use App Passwords instead of regular password
- **SMTP Errors**: Verify host, port, and credentials
- **Firewall**: Ensure SMTP ports aren't blocked

#### PDF Generation Issues
- **Missing fonts**: Install system fonts or use web fonts
- **Memory issues**: Increase Node.js memory limit
- **Puppeteer errors**: Install Chrome dependencies

### Debug Mode

Enable debug logging:
```bash
DEBUG=invoice-mcp:* npx invoice-mcp-server
```

### Environment Diagnostics

Run the setup script to diagnose issues:
```bash
npm run setup
```

This will show:
- ✅ Directory creation status
- ✅ Write permissions
- ✅ Node.js version
- ✅ Environment information
- ✅ Troubleshooting suggestions

## 📈 Performance

### Optimization Tips

1. **Use custom OUTPUT_DIR** for faster file access
2. **Docker multi-stage builds** for smaller images
3. **PDF caching** for repeated templates
4. **Email queuing** for bulk operations
5. **Resource limits** for container deployments

### Scaling

- Use Redis for session storage
- Implement queue system for PDF generation
- Load balance multiple containers
- Use external SMTP service

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🆘 Support

- 📋 **Issues**: [GitHub Issues](https://github.com/kmexnx/invoice-mcp-server/issues)
- 📖 **Examples**: See [EXAMPLES.md](EXAMPLES.md)
- 📚 **MCP Docs**: [MCP Documentation](https://spec.modelcontextprotocol.io/)
- 🐳 **Docker**: [Docker Hub](https://hub.docker.com/r/invoice-mcp-server)

---

**Quick Start Example:**

1. **Set your directory**: `export OUTPUT_DIR=/Users/yourname/Documents/invoices`
2. **Run**: `npx invoice-mcp-server`
3. **Configure Claude Desktop** (see above)
4. **Ask Claude**: *"Create an invoice for ABC Company for $2,500"*
5. **Claude handles the rest automatically!** 🎉

The server handles all formatting, calculations, and delivery automatically while saving PDFs to your specified directory.