MCP Server ZapSign

A Model Context Protocol (MCP) server that provides comprehensive access to the ZapSign API for electronic document signing and management.

Features

• Complete ZapSign API Integration: All ZapSign API operations available as MCP tools
• Document Management: Create, update, delete, and manage documents
• Template Operations: Work with document templates and forms
• Signer Management: Add, update, and manage document signers
• Background Checks: Perform person and company background checks
• Webhook Management: Create and manage webhooks for real-time notifications
• Timestamp Services: Add timestamps to documents
• Authentication: Support for both main and workspace API keys
• Validation: Comprehensive input validation using Zod schemas
• Logging: Structured logging with Winston
• Health Monitoring: Built-in health checks and monitoring

Prerequisites

• Node.js 18+
• ZapSign API account and API keys
• Access to ZapSign API documentation

Installation

From npm (Recommended)

npm install mcp-server-zapsign

From source

1. Clone the repository:

git clone https://github.com/ZapSign/api-mcp.git
cd api-mcp

2. Install dependencies:

npm install

3. Create environment configuration:

cp .env.example .env

4. Configure your environment variables in .env:

# Server Configuration
PORT=3001
HOST=localhost
NODE_ENV=development

# Server Information
SERVER_NAME=mcp-server-zapsign
SERVER_VERSION=1.0.0

# ZapSign API Configuration
ZAPSIGN_API_KEY=your_zapsign_api_key_here
ZAPSIGN_BASE_URL=https://api.zapsign.com.br
ZAPSIGN_API_VERSION=v1

# Logging Configuration
LOG_LEVEL=info

# Features Configuration
ENABLE_METRICS=false
ENABLE_RATE_LIMITING=true
MAX_REQUESTS_PER_MINUTE=100

Usage

Starting the Server

STDIO Mode (Default)

npm start

SSE Mode (HTTP Server)

npm run start:sse

Development Mode

npm run dev

Server Modes

• STDIO Mode: Standard MCP server using stdin/stdout for communication
• SSE Mode: HTTP server with Server-Sent Events for web-based MCP clients
• Health Check: Available at /health endpoint when running in SSE mode

🐳 Docker Deployment

Quick Start with Traefik (Recommended)

# Clone the repository
git clone https://github.com/ZapSign/api-mcp.git
cd api-mcp

# Copy environment file
cp .env.example .env

# Edit environment variables (set DOMAIN_NAME and CERTBOT_EMAIL)
nano .env

# Set up Traefik directories
chmod +x setup-traefik.sh
./setup-traefik.sh

# Start with Traefik (automatic SSL)
docker-compose up -d

Alternative: Development Setup

# Start with development Docker Compose (no SSL)
docker-compose -f docker-compose.dev.yml up -d

Legacy: Nginx + Certbot Setup

# Use production compose file with Nginx
docker-compose -f docker-compose.prod.yml up -d

# Setup SSL certificates manually
chmod +x nginx/setup-ssl.sh
./nginx/setup-ssl.sh

Docker Compose Files

• docker-compose.yml: Production with Traefik (automatic SSL)
• docker-compose.dev.yml: Development and testing setup
• nginx/: Nginx configuration for manual HTTPS setup
• nginx/setup-ssl.sh: Manual SSL certificate setup script

HTTPS Features

• Traefik Reverse Proxy: Automatic SSL management with Docker labels
• Let's Encrypt Support: Zero-config SSL certificate management
• Nginx Alternative: Manual SSL setup option for advanced users
• Security Headers: XSS protection, content security policy
• Rate Limiting: Configurable request limits per IP
• Gzip Compression: Optimized content delivery
• Automatic Renewal: SSL certificates auto-renew without downtime

For detailed EC2 deployment instructions, see EC2 Deployment Guide.

📋 Docker Compose Configuration

Development Setup (docker-compose.yml)

services:
  mcp-zapsign-server:      # Production server on port 3001
  mcp-zapsign-server-dev:  # Development server on port 3002

Production Setup (docker-compose.prod.yml)

services:
  nginx-proxy:             # HTTPS reverse proxy (ports 80, 443)
  mcp-zapsign-server:      # Production server (internal port 3001)
  certbot:                 # Let's Encrypt SSL certificate manager

Key Features

• Load Balancing: Nginx distributes traffic across multiple instances
• SSL Termination: HTTPS handled at the proxy level
• Health Checks: Automatic service monitoring and restart
• Resource Limits: Memory and CPU constraints for production
• Logging: Centralized log management
• Security: Rate limiting and security headers

Available Tools

Document Operations

• create_document_from_upload - Create document from uploaded file
• create_document_from_template - Create document from template
• get_document_details - Get document information
• list_documents - List all documents
• update_document - Update document properties
• delete_document - Delete a document
• add_extra_document - Add extra document to envelope
• place_signatures - Position signatures on document

Template Operations

• list_templates - List available templates
• get_template_details - Get template information
• create_template - Create new template
• update_template - Update template properties
• delete_template - Delete a template

Signer Operations

• add_signer - Add signer to document
• update_signer - Update signer information
• get_signer_details - Get signer information
• delete_signer - Remove signer from document
• sign_in_batch - Batch signing operations

Background Check Operations

• create_person_background_check - Check person background
• create_company_background_check - Check company background
• get_background_check_status - Get check status

Webhook Operations

• create_webhook - Create webhook for notifications
• delete_webhook - Remove webhook
• manage_webhook_headers - Configure webhook headers

Timestamp Operations

• add_timestamp - Add timestamp to document

API Documentation

This server implements all ZapSign API endpoints as documented at:

• ZapSign API Documentation

Key API Features

• Authentication: Bearer token authentication
• Rate Limiting: Configurable request limits
• Error Handling: Comprehensive error responses
• Validation: Input validation using Zod schemas
• Logging: Detailed request/response logging

Configuration

Environment Variables

| Variable | Description | Default | Required | |----------|-------------|---------|----------| | PORT | Server port | 3001 | No | | HOST | Server host | localhost | No | | ZAPSIGN_API_KEY | Main ZapSign API key | - | Yes |

| ZAPSIGN_BASE_URL | ZapSign API base URL | https://api.zapsign.com.br | No | | LOG_LEVEL | Logging level | info | No | | ENABLE_RATE_LIMITING | Enable rate limiting | true | No |

Logging Levels

• error: Only error messages
• warn: Warning and error messages
• info: Information, warning, and error messages
• debug: All messages including debug information

Development

Project Structure

mcp-zapsign-server/
├── lib/
│   ├── config.js           # Configuration management
│   ├── logger.js           # Logging infrastructure
│   ├── tools.js            # Tool discovery
│   └── services/
│       ├── zapsignApi.js   # ZapSign API client
│       ├── auth.js         # Authentication service
│       └── validation.js   # Input validation
├── tools/
│   └── zapsign-workspace/
│       └── api/            # Individual tool implementations
├── mcpServer.js            # Main server file
├── package.json
└── README.md

Adding New Tools

1. Create a new tool file in tools/zapsign-workspace/api/
2. Follow the existing tool structure:

const executeFunction = async (args) => {
  // Tool implementation
};

const apiTool = {
  function: executeFunction,
  definition: {
    type: 'function',
    function: {
      name: 'tool_name',
      description: 'Tool description',
      parameters: {
        // Parameter schema
      }
    }
  }
};

export { apiTool };

3. Add the tool to tools/paths.js

Testing

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test -- --testNamePattern="Tool Name"

Error Handling

The server provides comprehensive error handling:

• Validation Errors: Input validation failures with detailed messages
• API Errors: ZapSign API errors with context information
• Authentication Errors: Invalid or expired API keys
• Network Errors: Connection and timeout issues
• Internal Errors: Server-side processing errors

Monitoring and Health Checks

Health Endpoint

When running in SSE mode, the server provides a health check endpoint:

curl http://localhost:3001/health

Response includes:

• Server status
• Authentication status
• API health
• Tool count
• Timestamp

Logging

All operations are logged with structured data:

• Request/response logging
• Error tracking
• Performance metrics
• Authentication events

Security Considerations

• API keys are stored in environment variables
• Input validation prevents malicious data
• Rate limiting prevents abuse
• Comprehensive error logging for security monitoring
• No sensitive data in logs

Troubleshooting

Common Issues

1. Authentication Failed

   • Verify API keys are correct
   • Check API key permissions
   • Ensure keys are not expired

2. Tool Not Found

   • Verify tool is properly exported
   • Check tool is listed in tools/paths.js
   • Restart server after adding new tools

3. API Errors

   • Check ZapSign API status
   • Verify request parameters
   • Check rate limits

4. Server Won't Start

   • Verify environment variables
   • Check port availability
   • Review error logs

Debug Mode

Enable debug logging:

LOG_LEVEL=debug npm start

Contributing

1. Fork the repository
2. Create a feature branch
3. Implement your changes
4. Add tests for new functionality
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Documentation: ZapSign API Docs
• Issues: GitHub Issues
• Contact: ZapSign Support

Changelog

Version 1.0.0

• Initial release
• Complete ZapSign API integration
• MCP protocol support
• Comprehensive tool set
• Authentication and validation
• Logging and monitoring