# eSign MCP Server

An MCP (Model Context Protocol) server that provides tools for signing PDF documents by adding signature images at specified coordinates.

## Credits

This MCP server is built upon the excellent [signpdf](https://github.com/yourcelf/signpdf) project by **Charlie DeTar** (cfd@media.mit.edu). The original signpdf utility provides the core PDF signing functionality that this MCP server wraps with a modern MCP interface.

## Features

- **sign_pdf**: Add signature images to PDF documents with precise positioning
- **get_pdf_info**: Get PDF metadata including page count and dimensions
- Input validation and error handling
- Support for PNG and JPG signature images
- Optional date stamping
- Base64 encoding for file transfer

## Tools

### sign_pdf

Signs a PDF document by adding a signature image at the specified coordinates.

**Parameters:**
- `pdf_data` (string): Base64 encoded PDF file content
- `signature_data` (string): Base64 encoded signature image (PNG, JPG)
- `page_number` (int, optional): Page number to sign (1-based indexing, default: 1)
- `x` (float, optional): X coordinate from bottom-left corner in PDF units (default: 100)
- `y` (float, optional): Y coordinate from bottom-left corner in PDF units (default: 100)
- `width` (float, optional): Width of the signature in PDF units (default: 125)
- `height` (float, optional): Height of the signature in PDF units (default: 40)
- `add_date` (bool, optional): Whether to add current date next to signature (default: false)

**Returns:** Base64 encoded signed PDF content

### get_pdf_info

Get information about a PDF document including page count and dimensions.

**Parameters:**
- `pdf_data` (string): Base64 encoded PDF file content

**Returns:** 
```json
{
  "num_pages": 1,
  "pages": [
    {
      "page_number": 1,
      "width": 612.0,
      "height": 792.0
    }
  ]
}
```

## Installation

### Prerequisites

- Python 3.11+
- `uv` package manager (recommended) or `pip`

### Local Installation

1. Clone or download this repository
2. Install dependencies:
   ```bash
   uv pip install -r requirements.txt
   ```

### Running the Server

To run the MCP server:

```bash
uv run python mcp_server.py
```

The server will start with stdio transport by default.

## Testing

A test script is provided to verify the server functionality:

```bash
uv run python test_server.py
```

This will:
1. Create a test PDF document
2. Generate a test signature image
3. Test the `get_pdf_info` tool
4. Test the `sign_pdf` tool
5. Save the signed PDF as `test_signed.pdf`

## Docker Deployment

The server includes Docker support for containerized deployment:

```bash
# Build the image
docker build -t pdf-signer-mcp .

# Run the container
docker run -p 8000:8000 pdf-signer-mcp
```

## Smithery Deployment

This server is configured for deployment on Smithery with the included `smithery.yaml` configuration file.

### Configuration Files

- `Dockerfile`: Container build instructions
- `smithery.yaml`: Smithery deployment configuration
- `requirements.txt`: Python dependencies

## Usage Examples

### Using with Claude Desktop

1. **Install Claude Desktop** from [claude.ai/download](https://claude.ai/download)
2. **Clone this repository**:
   ```bash
   git clone https://github.com/adamanz/esign-mcp.git
   cd esign-mcp
   ```
3. **Install dependencies**:
   ```bash
   uv pip install -r requirements.txt
   ```
4. **Configure Claude Desktop** by editing your configuration file:

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

**Configuration:**
```json
{
  "mcpServers": {
    "esign-mcp": {
      "command": "uv",
      "args": [
        "run", 
        "python", 
        "/ABSOLUTE/PATH/TO/esign-mcp/mcp_server.py"
      ]
    }
  }
}
```

5. **Restart Claude Desktop** to load the MCP server
6. **Look for the MCP tools** - you should see a 🔨 hammer icon indicating available tools

### Using with Claude Code

1. **Install Claude Code** (if not already installed)
2. **Clone this repository** in your project directory:
   ```bash
   git clone https://github.com/adamanz/esign-mcp.git
   cd esign-mcp
   uv pip install -r requirements.txt
   ```
3. **Start the MCP server** in your terminal:
   ```bash
   uv run python mcp_server.py
   ```
4. **In Claude Code**, the MCP server will be automatically detected when running in stdio mode
5. **Use the tools** directly in your conversations with Claude Code

### Using with Cursor

1. **Install Cursor** from [cursor.sh](https://cursor.sh)
2. **Set up the MCP server** by adding it to your project:
   ```bash
   git clone https://github.com/adamanz/esign-mcp.git
   cd esign-mcp
   uv pip install -r requirements.txt
   ```
3. **Configure Cursor** to use the MCP server by creating or editing your Cursor MCP configuration
4. **Run the server**:
   ```bash
   uv run python mcp_server.py
   ```
5. **Access tools** through Cursor's AI assistant interface

### Alternative: Using without uv

If you prefer using standard pip:

```bash
git clone https://github.com/adamanz/esign-mcp.git
cd esign-mcp
pip install -r requirements.txt
python mcp_server.py
```

Update your configuration to use `python` instead of `uv run python`.

### Example Tool Calls

**Get PDF Info:**
```json
{
  "tool": "get_pdf_info",
  "arguments": {
    "pdf_data": "JVBERi0xLjQK..."
  }
}
```

**Sign PDF:**
```json
{
  "tool": "sign_pdf",
  "arguments": {
    "pdf_data": "JVBERi0xLjQK...",
    "signature_data": "iVBORw0KGgoAAAA...",
    "page_number": 1,
    "x": 100,
    "y": 100,
    "width": 125,
    "height": 40,
    "add_date": true
  }
}
```

### Practical Usage Examples

Once your MCP server is running, you can use natural language to interact with the PDF signing tools:

**Example conversations:**

1. **Getting PDF Information:**
   > "I have a PDF file. Can you tell me how many pages it has and what the dimensions are?"
   
   The AI will ask you to provide the PDF file, then use the `get_pdf_info` tool to analyze it.

2. **Signing a PDF:**
   > "I need to sign this contract PDF on the first page. Can you add my signature image in the bottom right corner?"
   
   The AI will use the `sign_pdf` tool with appropriate coordinates for bottom-right placement.

3. **Multiple signatures:**
   > "Please add my signature to page 2 of this PDF, positioned at coordinates 200, 150, and make it 100x30 pixels. Also add today's date."
   
   The AI will use precise coordinates and enable date stamping.

4. **Getting help with coordinates:**
   > "I want to sign this PDF but I'm not sure where to place the signature. Can you help me understand the coordinate system?"
   
   The AI can explain PDF coordinates and help you choose appropriate values.

## Technical Notes

### PDF Coordinates

- Coordinates use PDF standard units (1/72 inch)
- Origin (0,0) is at the bottom-left corner of the page
- X increases rightward, Y increases upward

### Supported Image Formats

- PNG (recommended for transparency support)
- JPG/JPEG

### File Handling

- All file operations use temporary files that are automatically cleaned up
- Input validation prevents common errors
- Proper error handling with descriptive messages

## Dependencies

- `fastmcp`: FastMCP framework for MCP server implementation
- `pypdf`: PDF reading and writing library
- `reportlab`: PDF generation and image placement
- `pillow`: Image processing (dependency of reportlab)

## Troubleshooting

### Common Issues

1. **"Module not found" errors**
   ```bash
   # Make sure dependencies are installed
   uv pip install -r requirements.txt
   # Or with pip
   pip install -r requirements.txt
   ```

2. **MCP server not appearing in Claude Desktop**
   - Check that the path in `claude_desktop_config.json` is absolute (not relative)
   - Restart Claude Desktop after making configuration changes
   - Check Claude Desktop logs: `~/Library/Logs/Claude/mcp*.log` (macOS)

3. **"Command not found: uv"**
   - Install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`
   - Or use regular pip instead: replace `uv run python` with `python`

4. **Permission errors**
   ```bash
   # Make sure the script is executable
   chmod +x mcp_server.py
   ```

5. **PDF signing fails**
   - Ensure your PDF and signature image are valid
   - Check that coordinates are within the page boundaries
   - Use `get_pdf_info` first to understand page dimensions

### Getting Help

- Check the [GitHub Issues](https://github.com/adamanz/esign-mcp/issues) for common problems
- Run the test script to verify installation: `uv run python test_server.py`
- For Claude Desktop specific issues, check the [MCP troubleshooting guide](https://docs.anthropic.com/en/docs/claude-code/troubleshooting)

## License

MIT License - This project maintains the same license as the original [signpdf](https://github.com/yourcelf/signpdf) project by Charlie DeTar.

## Original Project

The core PDF signing functionality is based on the [signpdf](https://github.com/yourcelf/signpdf) utility by Charlie DeTar. This MCP server extends that work to provide MCP-compatible tools for modern AI integration.

## Contributing

1. Test your changes with the provided test script
2. Ensure all dependencies are properly specified
3. Update documentation as needed
4. Follow the existing code style and patterns