Локальный EDS MCP Server (ЭЦП НУЦ РК)

Этот проект представляет собой локальный MCP-сервер (Model Context Protocol) для работы с казахстанской электронной цифровой подписью (ЭЦП НУЦ РК). Он позволяет AI-агентам (таким как Claude Desktop, Cursor, Claude Code и др.) безопасно подписывать данные и файлы на вашем компьютере, используя Kalkan SDK.

Принцип безопасности: Ваш приватный ключ (.p12 / .pfx) и пароль от него никогда не передаются AI-агенту. Все операции подписи происходят локально на вашем компьютере. При запросе подписи от AI-агента всплывает системное окно macOS (AppleScript) для ввода пароля и подтверждения операции.

Требования к системе

1. Java Runtime Environment (JRE) / JDK (версия 8 или новее) — необходима для выполнения криптографических операций через официальный Java-пакет Kalkan SDK (kalkancrypt.jar). Убедитесь, что команда java -version доступна в терминале.

2. Node.js (версия 18 или новее) и npm — для запуска и работы MCP-сервера.

3. macOS — проект настроен на отображение всплывающих окон подтверждения (AppleScript-диалоги) для безопасного ввода пароля.

Related MCP server: PiQrypt MCP Server

Установка и сборка проекта

Перед использованием сервер необходимо скомпилировать. Для этого выполните в корневой директории проекта следующие команды:

1. Установите зависимости:

   npm install

2. Соберите Java-компонент (Signer) и TypeScript-пакеты:

   npm run build

   Эта команда скомпилирует KalkanSigner.java в директорию native/kalkan/bin и транспилирует TypeScript-код пакетов и приложения в dist директории.

Настройка MCP-клиентов

Чтобы ваш AI-агент мог использовать этот сервер, добавьте его в конфигурационный файл вашего MCP-клиента.

1. Claude Desktop (macOS)

Откройте файл конфигурации Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Добавьте сервер в секцию mcpServers:

{
  "mcpServers": {
    "eds-mcp-server": {
      "command": "node",
      "args": [
        "/Users/anarbek/Documents/personal/project/eds-mcp-server/apps/mcp-server/dist/index.js"
      ]
    }
  }
}

Примечание: Укажите точный абсолютный путь к файлу /apps/mcp-server/dist/index.js в вашей системе.

2. Cursor

1. Перейдите в Settings (Настройки) -> Features -> MCP.

2. Нажмите кнопку + Add New MCP Server.

3. Установите параметры:

   • Name: eds-mcp-server

   • Type: stdio

   • Command: node /Users/anarbek/Documents/personal/project/eds-mcp-server/apps/mcp-server/dist/index.js (укажите ваш абсолютный путь к файлу)

4. Нажмите Save.

3. Claude Code

Запустите следующую команду в консоли:

claude mcp add eds-mcp-server node /Users/anarbek/Documents/personal/project/eds-mcp-server/apps/mcp-server/dist/index.js

4. Antigravity IDE

Настроить сервер можно двумя способами:

• Через интерфейс (рекомендуется):

  1. Откройте панель агента (Agent Panel).

  2. Перейдите на вкладку Integrations (или выберите пункт Manage MCP Servers в меню ... в правом верхнем углу панели агента).

  3. Нажмите кнопку добавления нового MCP-сервера и заполните параметры (Name: eds-mcp-server, Command: node, Args: ["/Users/anarbek/Documents/personal/project/eds-mcp-server/apps/mcp-server/dist/index.js"]).

• Вручную через файл конфигурации: Откройте или создайте файл ~/.gemini/antigravity-ide/mcp_config.json и добавьте в секцию mcpServers:

  {
    "mcpServers": {
      "eds-mcp-server": {
        "command": "node",
        "args": [
          "/Users/anarbek/Documents/personal/project/eds-mcp-server/apps/mcp-server/dist/index.js"
        ]
      }
    }
  }

Конфигурация сервера

При первом запуске сервер автоматически создаст конфигурационный файл в домашней директории пользователя: ~/.eds-mcp/config.json

Пример конфигурации:

{
  "provider": "kalkan",
  "security": {
    "requireConfirmation": true,
    "allowedDirectories": [
      "~/Documents",
      "~/.eds-mcp/workspace"
    ]
  },
  "signing": {
    "defaultFormat": "CMS",
    "detached": true
  },
  "audit": {
    "enabled": true,
    "path": "~/.eds-mcp/logs/audit.log"
  }
}

Описание параметров:

• security.requireConfirmation (true / false): При значении true (рекомендуется) перед каждой операцией подписи на экране будет появляться системное диалоговое окно с запросом пароля и информацией о файле (имя, размер, SHA-256 хэш и данные сертификата). При значении false подпись будет происходить без подтверждения пользователя (небезопасно).

• security.allowedDirectories: Массив путей, из которых сервер имеет право читать/подписывать файлы. Попытка подписать файл вне этих директорий вызовет ошибку безопасности. Вы можете добавить сюда рабочие директории ваших проектов (например, ["~/Documents", "/Users/anarbek/Projects"]).

• audit.enabled и audit.path: Включает ведение журнала аудита операций в указанный файл.

Доступные инструменты (Tools) для AI

После подключения сервера AI-агент получит доступ к следующим инструментам:

• eds_list_certificates — возвращает список сертификатов из хранилища .p12.

  • Аргументы: p12Path (путь к файлу ключа).

• eds_get_certificate — возвращает подробную информацию о выбранном по алиасу сертификате.

  • Аргументы: p12Path, alias.

• eds_sign_data — подписывает переданную Base64 строку.

  • Аргументы: p12Path, alias, dataBase64, detached (optional).

• eds_sign_file — подписывает локальный файл и создает подпись в формате .p7s.

  • Аргументы: p12Path, alias, filePath, destPath (optional), detached (optional).

• eds_verify_signature — проверяет CMS/PKCS#7 подпись для указанного файла.

  • Аргументы: signatureFile (путь к файлу подписи), dataFile (путь к оригинальным данным, если подпись отсоединенная).

Ручной запуск и отладка

Для отладки сервера или просмотра выводимых ошибок вы можете запустить его напрямую в терминале:

npm start

Так как MCP-сервер взаимодействует через stdio, все диагностические сообщения выводятся в stderr, а в stdout транслируется JSON-RPC трафик.

Как отключить или удалить сервер

Если вам больше не нужен сервер или вы хотите его временно отключить:

1. В Claude Desktop: Удалите или закомментируйте блок "eds-mcp-server" в конфигурационном файле ~/Library/Application Support/Claude/claude_desktop_config.json. После этого перезапустите Claude Desktop.

2. В Cursor: Перейдите в Settings -> Features -> MCP, найдите сервер eds-mcp-server и нажмите кнопку Delete.

3. В Claude Code: Удалите сервер из списка MCP с помощью команды:

   claude mcp remove eds-mcp-server

4. В Antigravity IDE:

   • В интерфейсе: перейдите на вкладку Integrations в панели агента и удалите или отключите eds-mcp-server.

   • В файле конфигурации: удалите блок "eds-mcp-server" из файла ~/.gemini/antigravity-ide/mcp_config.json.

5. Завершение фонового процесса: Если сервер был запущен в фоновом режиме или завис, найдите и завершите его процессы с помощью команды:

   pkill -f "node.*mcp-server/dist/index.js"