@mindops/zapsign-mcp

Сервер Model Context Protocol, который предоставляет REST API ZapSign в виде MCP-инструментов. Подключите его к любому MCP-совместимому хосту (Claude Desktop, VS Code, Cursor, собственное приложение на SDK) и позвольте LLM управлять документооборотом: создавать документы, управлять подписантами, заполнять шаблоны DOCX, запускать проверки, управлять вебхуками.

Что входит

Инструменты сгруппированы по ресурсам ZapSign. Набор соответствует публичному REST API один в один; каждый инструмент оборачивает ровно одну конечную точку.

• Документы — создание из URL PDF / base64 / шаблона, список, детали, обновление, удаление, изменение порядка отображения, размещение подписей, oneclick, дополнительные документы, журнал активности подписантов

• Подписанты — добавление, обновление, детали, удаление, массовое подписание, отказ, отказ по пользователю, сброс попыток аутентификации, повторная отправка уведомлений, сведения о верификации, группы подписантов

• Шаблоны — создание из DOCX, обновление полей формы, список, детали, обновление, удаление

• Пользователи — создание, список, удаление, информация о тарифе

• Вебхуки — создание, удаление (полезные нагрузки событий — это справочная документация, а не конечные точки API)

• Аутентификация (JWT) — получение токена, обновление токена (альтернатива статическому API-токену)

• Проверки — создание проверки физического/юридического лица, список, детали

• Метка времени — применение метки времени к подписанному PDF или к произвольному PDF без изменения подписей

• Валидация — проверка подписанного PDF

• Партнёр — управление компаниями-партнёрами, обновление статусов платежей, CSV-отчёт об использовании тарифа

Установка

После публикации в реестре:

npm install -g @mindops/zapsign-mcp
# or run on demand with npx (no global install):
npx -y @mindops/zapsign-mcp

Локальная установка (до публикации)

cd /path/to/zapsign-mcp
npm install
npm run build
npm link            # exposes `zapsign-mcp` on $PATH globally

Первая публикация

Пакет предназначен для области видимости @mindops на npmjs.org с доступом restricted. Чтобы опубликовать:

npm login                      # authenticate against registry.npmjs.org
npm publish --access restricted   # or just `npm publish` — restricted is the publishConfig default

Если организации @mindops ещё нет на npm, сначала создайте её на https://www.npmjs.com/org/create.

Настройка

Создайте файл .env (или задайте переменные окружения в конфигурации вашего MCP-хоста):

ZAPSIGN_API_TOKEN=your-permanent-system-user-token
ZAPSIGN_ENV=production       # or 'sandbox' for the test environment

Рекомендуется: постоянный токен системного пользователя (Configurações → API → Tokens в панели ZapSign). Токены, привязанные к пользователю, истекают и нарушают автоматизацию.

Использование из MCP-хоста

Claude Desktop / Claude Code

Добавьте в конфигурацию MCP (обычно ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "zapsign": {
      "command": "npx",
      "args": ["-y", "@mindops/zapsign-mcp"],
      "env": {
        "ZAPSIGN_API_TOKEN": "...",
        "ZAPSIGN_ENV": "production"
      }
    }
  }
}

VS Code / Cursor

Та же структура — добавьте его в раздел MCP-серверов ваших настроек.

Локально во время разработки

npm install
npm run build
ZAPSIGN_API_TOKEN=... ZAPSIGN_ENV=sandbox node dist/index.js

Сервер работает через stdio; подключитесь любым MCP-клиентом, чтобы просмотреть инструменты.

Соглашения об именовании инструментов

• имена в snake_case, соответствующие терминологии ресурсов ZapSign (create_document, add_signer, delete_template и т.д.)

• Имена полей во входных данных инструментов сохраняют написание API ZapSign (phone_country, phone_number, auth_mode, url_pdf...), чтобы тело запроса в точности соответствовало ожиданиям API.

• Параметры пути появляются как поля верхнего уровня с теми же именами (doc_token, signer_token, template_token).

Разработка

npm install
npm run typecheck
npm run build

Добавляйте новые конечные точки, создавая определение в src/tools/<resource>.ts, и повторно запуская npm run build. Каждый инструмент — это тонкая обёртка:

registerTool(server, client, {
  name: 'create_document',
  description: 'Create a new document from a public PDF URL.',
  inputSchema: z.object({ /* fields */ }),
  handler: async (input, { client }) => client.post('/docs/', input),
});

Вспомогательная функция обрабатывает форматирование конверта ошибок и преобразование в JSON для MCP-транспорта.

Версионирование

Этот пакет соответствует API ZapSign v1. ZapSign версионирует свои конечные точки за /api/v1/; если/когда выйдет v2, этот сервер получит параллельный модуль, а не заменит v1 на месте.

Лицензия

Проприетарная (внутренняя для MindOps). Свяжитесь с MindOps перед распространением.