api-mcp by ZapSign - MCP Server

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

Clone the repository:

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

Install dependencies:

npm install

Create environment configuration:

cp .env.example .env

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 .

📋 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

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

Create a new tool file in tools/zapsign-workspace/api/
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 };

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

Authentication Failed
- Verify API keys are correct
- Check API key permissions
- Ensure keys are not expired
Tool Not Found
- Verify tool is properly exported
- Check tool is listed in tools/paths.js
- Restart server after adding new tools
API Errors
- Check ZapSign API status
- Verify request parameters
- Check rate limits
Server Won't Start
- Verify environment variables
- Check port availability
- Review error logs

Debug Mode

Enable debug logging:

LOG_LEVEL=debug npm start

Contributing

Fork the repository
Create a feature branch
Implement your changes
Add tests for new functionality
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