# Локальный 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-диалоги) для безопасного ввода пароля.

---

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

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

1. Установите зависимости:
   ```bash
   npm install
   ```

2. Соберите Java-компонент (Signer) и TypeScript-пакеты:
   ```bash
   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`:
```json
{
  "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
Запустите следующую команду в консоли:
```bash
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`:
  ```json
  {
    "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`

### Пример конфигурации:
```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` (путь к оригинальным данным, если подпись отсоединенная).

---

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

Для отладки сервера или просмотра выводимых ошибок вы можете запустить его напрямую в терминале:
```bash
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 с помощью команды:
   ```bash
   claude mcp remove eds-mcp-server
   ```
4. **В Antigravity IDE**:
   - В интерфейсе: перейдите на вкладку **Integrations** в панели агента и удалите или отключите `eds-mcp-server`.
   - В файле конфигурации: удалите блок `"eds-mcp-server"` из файла `~/.gemini/antigravity-ide/mcp_config.json`.

5. **Завершение фонового процесса**:
   Если сервер был запущен в фоновом режиме или завис, найдите и завершите его процессы с помощью команды:
   ```bash
   pkill -f "node.*mcp-server/dist/index.js"
   ```