Skip to main content
Glama
xca-mcp

xca-mcp

by bardimnik
README.md
# xca-mcp

[![CI](https://github.com/bardimnik/xca-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/bardimnik/xca-mcp/actions/workflows/ci.yml)

MCP-сервер для [XCA](https://github.com/chris2511/xca) (X Certificate and
Key management) — позволяет ИИ-агенту смотреть в базу ключей/сертификатов
XCA и управлять ею: генерировать ключи, импортировать объекты, создавать CRL.

Сервер не лезет во внутренности XCA — он оборачивает её **консольный режим**
(`xca --no-gui ...`, поддерживается с версии 2.4) через `subprocess`.
Пароль базы данных никогда не передаётся в аргументах командной строки
(чтобы не светился в `ps`) — он идёт через переменную окружения (`env:`).

## Возможности (MCP-инструменты)

**Чтение (аудит):**

| Инструмент | Что делает |
|---|---|
| `xca_list_items` | Все объекты БД: id, тип (Key/Cert/Req/CRL/Temp), имя |
| `xca_get_item` | Просмотр объекта по id: `text` (openssl-dump), `pem`, `print` |
| `xca_list_issuers` | Сертификаты, пригодные как issuer (CA с приватным ключом) |
| `xca_list_curves` | Поддерживаемые эллиптические кривые |
| `xca_version` | Версия XCA |

**Управление:**

| Инструмент | Что делает |
|---|---|
| `xca_keygen` | Генерация ключа: `RSA:4096`, `EC:prime256v1`, `Ed25519`, … |
| `xca_import_files` | Импорт PEM/DER, PKCS#10, PKCS#12, CRL в БД |
| `xca_crlgen` | Генерация CRL для CA (по имени или id) |
| `xca_revoke` | Отзыв сертификата (с причиной) ⚠ требует патч |
| `xca_unrevoke` | Отмена отзыва ⚠ требует патч |
| `xca_sign_request` | Подписание CSR с указанным CA ⚠ требует патч |

## Какой XCA нужен

| Вариант | Что работает |
|---|---|
| **Стоковый XCA ≥ 2.9.0** | всё, кроме `xca_revoke` / `xca_unrevoke` / `xca_sign_request` (они вернут понятную ошибку) |
| **Сборка из master апстрима** ([chris2511/xca](https://github.com/chris2511/xca)) | всё: revoke/sign-req слиты в master (PR [#745](https://github.com/chris2511/xca/pull/745)), войдут в следующий релиз |
| **Ветка `bundled` форка** ([bardimnik/xca](https://github.com/bardimnik/xca/tree/bundled)) | всё + Ed25519-подпись на PKCS#11-токенах под OpenSSL 4.x (in-process провайдер, PR [#747](https://github.com/chris2511/xca/pull/747)); CI собирает бинарь-артефакт против OpenSSL 3.x и 4.x |

Укажите выбранный бинарник через `XCA_MCP_BINARY` (по умолчанию — `xca` из PATH).

Про выбор алгоритмов ключей (важно для веб-сервисов): браузеры и публичные
CA работают только с RSA/ECDSA — Ed25519-сертификаты для HTTPS не годятся.
Ed25519 идеален для VPN/WireGuard, SSH, подписи артефактов и mTLS между
доверенными сервисами (не-браузерные клиенты).

## Известные ограничения

Ed25519-токенная подпись требует сборки с провайдером (см. таблицу выше) —
на стоковом XCA 2.9.0 и в сборках из master до мержа #747 такие ключи
загружаются только как публичные.

Параллельная запись в одну БД из GUI-сессии XCA и от агента может
конфликтовать — либо закрывайте GUI на время работы агента, либо
используйте агента только на read-only операциях.

Также: параллельная запись в одну БД из GUI-сессии XCA и от агента может
конфликтовать — либо закрывайте GUI на время работы агента, либо
используйте агента только на read-only операциях.

## Установка и запуск

Нужен установленный XCA ≥ 2.4 (`xca` в PATH) и Python ≥ 3.10.

```sh
pip install -e .        # или: uv pip install -e .
xca-mcp                 # stdio-транспорт
```

## Подключение агента

Пример конфигурации (`mcpServers`):

```json
{
  "mcpServers": {
    "xca": {
      "command": "xca-mcp",
      "env": {
        "XCA_MCP_DATABASE": "/path/to/database.xdb",
        "XCA_MCP_PASSWORD": "пароль-базы"
      }
    }
  }
}
```

Переменные окружения:

- `XCA_MCP_BINARY` — путь к бинарнику (по умолчанию `xca`)
- `XCA_MCP_DATABASE` — путь к `.xdb`; без неё XCA возьмёт БД по умолчанию
- `XCA_MCP_PASSWORD` — пароль БД (опционально; без него XCA не сможет
  неинтерактивно открыть зашифрованную БД)

Не передавайте пароль в аргументах `xca-mcp` и не закладывайте его в
конфиг агента без необходимости — для продакшена лучше `env:`, файл
(`XFile`) или незапускаемая сессия с экспортом переменной.

## Разработка

```sh
PYTHONPATH=src python3 -m pytest
```

Живой смоук-тест против настоящей базы (выполняет keygen — только на
одноразовой тестовой БД):

```sh
xca --no-gui --database /tmp/opencode/test.xdb \
    --password pass:testpw --keygen RSA:1024 --name smoke-rsa
PYTHONPATH=src python3 scripts/smoke.py
```

Тесты не требуют установленного XCA — вызовы `subprocess` подменяются.
Smoke-тест против реального бинарника: операции без БД (`version`,
`list-curves`) проверены на XCA 2.9.0.

## Структура

```
src/xca_mcp/cli.py     — обёртка над CLI XCA (пароль через env, срез ANSI)
src/xca_mcp/server.py  — MCPServer + регистрация инструментов
tests/                 — pytest (unit + тесты сервера)
```