BeeL MCP server

Сервер MCP (Model Context Protocol), который позволяет ИИ-агенту выставлять юридически корректные испанские электронные счета — регистрацию VeriFactu в AEAT, типы счетов F1/F2, корректировки R1–R5, проверку NIF по переписи и ключи режима, требуемые регламентом. Подключите его к Claude, ChatGPT, Cursor или VS Code — и ваш агент сможет обрабатывать испанские счета — facturación electrónica и factura electrónica VeriFactu — от начала до конца, без единого вызова API с вашей стороны.

Это не сгенерированная обёртка над API. Три вещи делают его пригодным для модели:

• Инструменты выводятся из публичного контракта OpenAPI, поэтому схема ввода каждого инструмента — это реальная схема операции — перечисления, позиции, ключи режима и всё остальное. Поверхность не может отклониться от API.

• Политика включения инструментов решает, что на самом деле следует дать агенту. Бинарные загрузки, многокомпонентные загрузки, вебхуки и устаревшие операции исключаются по правилу, а не вручную.

• Фискальные ограничения путешествуют вместе с инструментами: инварианты, которые упустила бы сгенерированная обёртка, — и как документация, которую читает модель, и как предварительные проверки, которые останавливают несоответствующий запрос до того, как он станет фискальным документом.

Одна кодовая база, два транспорта: размещённый удалённый сервер по адресу https://mcp.beel.es/mcp (Streamable HTTP + OAuth — один вход для пользователя, ничего устанавливать не нужно) и локальный сервер stdio, собранный из этого репозитория для безголового использования, где работает ключ API, а вход через браузер — нет.

Быстрый старт

Добавьте https://mcp.beel.es/mcp как коннектор в Claude, ChatGPT, Cursor или VS Code и войдите с помощью своей учётной записи BeeL. Ничего устанавливать не нужно, и никакой ключ API не требуется: сервер действует с вашими собственными учётными данными, а поток OAuth обнаруживается по URL.

# Claude Code
claude mcp add --transport http beel https://mcp.beel.es/mcp

Это вся настройка для интерактивного использования. Читайте дальше, только если вам нужен локальный сервер.

Related MCP server: chile-invoice-mcp

Запуск локально

Используйте локальный сервер, когда OAuth невозможен: запланированное задание, выставляющее счета, конвейер CI или любой безголовый процесс, где нет человека для завершения входа через браузер. Вместо этого он аутентифицируется с помощью ключа API.

Требуется Node ≥ 20.

// Claude Desktop / Claude Code MCP config
{
  "mcpServers": {
    "beel": {
      "command": "npx",
      "args": ["-y", "@beel_es/mcp"],
      "env": { "BEEL_API_KEY": "beel_sk_test_xxx" }
    }
  }
}

# Claude Code
claude mcp add beel --env BEEL_API_KEY=beel_sk_test_xxx -- npx -y @beel_es/mcp

Ключи с префиксом beel_sk_test_ безопасны для экспериментов; beel_sk_live_ создаёт реальные фискальные документы.

Релизы публикуются из CI через npm trusted publishing, поэтому они несут провенанс: npm записывает точный коммит и рабочий процесс, из которых была создана каждая сборка. Проверьте это с помощью npm audit signatures.

Каждый релиз также объявляется в MCP Registry как es.beel/mcp, с перечислением обоих транспортов, так что клиенты, просматривающие реестр, находят сервер без указания на него. Имя аутентифицируется DNS-записью на beel.es, поэтому оно говорит, что сервер исходит от нас, а не просто из какого-то репозитория.

Более ранний листинг под именем io.github.beel-es/beel-mcp (v0.2.2) был снят, когда имя переместилось. Имена в реестре — это идентичности, а не ярлыки, поэтому переименование — это новая запись, а не перенаправление; обе указывают на один и тот же npm-пакет и один и тот же размещённый сервер.

Что он предоставляет

• 118 инструментов API, полученных из openapi/public-api.yaml — счета, клиенты, товары, повторяющиеся счета, серии и налоговая конфигурация, проверка NIF, компании.

• 4 синтетических инструмента, для которых у API нет единой конечной точки: beel_docs_search, beel_docs_get, beel_docs_list по документации и beel_get_setup_status, который сообщает по каждому NIF, чего именно не хватает перед выставлением счёта, и единственное следующее действие.

• Ресурсы-ограничения по адресу beel://guardrails/* — фискальные инварианты, а также beel://guardrails/errors, каталог всех кодов ошибок с действием, которое они требуют. Их сводки вплетены в описание каждого инструмента, который они ограничивают.

• 7 подсказок рабочих процессов, кодирующих безопасный порядок операций для потоков, где порядок и делает их безопасными: issue-invoice (проверка NIF → выбор F1/F2 → проверка шлюзов VeriFactu → выпуск), fix-invoice (аннулирование против исправления), onboard-nif, setup-representation, invite-member, connect-payments и upgrade-integration.

• Встроенный просмотрщик PDF-счетов (MCP Apps): генерация PDF-счёта открывает его на боковой панели в хостах, которые это поддерживают.

Сгенерированный каталог всех инструментов с указанием требуемых областей находится на docs.beel.es/mcp/tools (npm run tools:catalog).

Что намеренно не является инструментом

Бинарные загрузки (предпросмотр PDF, массовый ZIP, экспорт Excel/CSV), многокомпонентные загрузки (импорт CSV/Holded, отправка подписанного PDF), инфраструктура вебхуков и каждая операция deprecated. Агент не может ими управлять, и каждая из них стоит контекста, который нужен полезному инструменту. Правила находятся в src/policy/tool-policy.ts.

Фискальные ограничения

Испанское электронное выставление счетов имеет инварианты, которые LLM получит неправильно из одной только схемы — аннулирование счёта, который следовало исправить, использование R1 для упрощённого счёта, редактирование счёта, который AEAT уже зарегистрировал. Сервер решает это на трёх уровнях, и разница между ними важна:

1. Консультативный — src/guardrails/rules/*.md, один файл Markdown на тему: жизненный цикл счёта, аннулирование против исправления, типы счетов, позиции счёта, ключи режима, нумерация серий, проверка NIF, шлюзы VeriFactu, мульти-NIF аккаунты. Каждый из них представлен как ресурс MCP по адресу beel://guardrails/*, а его однострочное резюме добавляется к описанию каждого инструмента, который он ограничивает, так что ограничение путешествует вместе с вызовом.

2. Принудительный — src/guardrails/validate.ts, проверяется перед отправкой запроса, так что плохой запрос даже не расходует ключ идемпотентности:

3. Объяснительный — BeeL API уже хорошо отвечает: его message написан для человека на языке вызывающего, error.details несёт конкретику, а поле type RFC 7807 ссылается на страницу документации для этого точного кода (их около 357). Сервер передаёт всё это без изменений и добавляет только две вещи, которые ответ не может нести: средство как вызов инструмента — документация обращается к человеку с открытой панелью управления («создайте серию в настройках»), агенту нужен beel_set_default_series — и может ли повторная попытка вообще помочь, что останавливает агента от зацикливания на 403, требующем администратора. src/guardrails/catalog.ts содержит только коды, к которым применимо одно из этих условий; всё остальное проходит насквозь, потому что пересказ был бы хуже оригинала и отклонился бы от него. Вложенные blockers[] из EMISSION_NOT_READY — самый ясный случай: они приходят как голые строки без сообщения и ссылки, и каждая возвращается с указанием инструмента, который её устраняет.

BeeL API — авторитет во всём этом. Каждое принудительное правило отражает отказ, который документирует контракт, так что предварительная проверка — строгое подмножество того, что API отклоняет: она может только ускорить и лучше объяснить сбой, но никогда не разрешить то, что API отклонил бы. Правила, зависящие от состояния на стороне сервера — соответствие переписи AEAT, потолок F2 в 3000 евро, существование серии — остаются консультативными намеренно, потому что локальные догадки отклоняли бы действительные счета. Установите BEEL_DISABLE_PREFLIGHT=1, чтобы полностью обойти локальные проверки.

Списки, составленные вручную, закреплены тестами: каждый каталогизированный код должен по-прежнему присутствовать в контракте, каждый проверяемый operationId должен по-прежнему разрешаться в реальный инструмент, и каждая ссылка на ограничение должна указывать на существующее ограничение. Переименование API приводит к сбою CI, а не к тихому отключению фискальной проверки.

Конфигурация

Только локальный сервер

Общие

Все значения по умолчанию находятся в src/shared/defaults.ts; ничто не захардкожено дважды. Переменные удалённого развёртывания описаны в DEPLOY.md.

Сервер запускается и перечисляет инструменты вообще без учётных данных — он выдаёт ошибку только при фактическом вызове инструмента API. POST-запросы несут стабильный Idempotency-Key, производный от самого запроса, поэтому агент, повторяющий «создать счёт», никогда не сможет создать второй счёт.

Самостоятельное размещение

Удалённый сервер работает на Cloudflare Workers. См. DEPLOY.md о пространстве имён KV, OAuth-клиенте, который BeeL должен зарегистрировать, и задействованных секретах.

Разработка

npm ci
npm run dev          # stdio server from source
npm test             # vitest
npm run typecheck    # both the Node and the Worker configs
npm run build        # single-file bundle to dist/index.js
npm run inspect      # MCP Inspector against the local build
npm run spec:verify  # the vendored contract still matches its lock

openapi/public-api.yaml — это сгенерированная копия контракта API, а openapi/spec.lock.json фиксирует его версию, количество операций и хэш. CI завершается ошибкой, если они расходятся, — именно это обеспечивает честность поставляемого контракта. См. CONTRIBUTING.md.

Остальная экосистема разработчика BeeL

Всё нижеперечисленное происходит из одного и того же контракта OpenAPI, поэтому словарь — типы счетов, ключи режимов, серии, состояния VeriFactu — идентичен, где бы вы с ним ни встретились.

Часто задаваемые вопросы

Что такое BeeL MCP сервер? Сервер MCP, который предоставляет испанский электронный документооборот VeriFactu в виде инструментов, которые может вызывать ИИ-агент, — так что Claude, ChatGPT, Cursor или VS Code могут создавать клиентов, выставлять счета F1/F2, регистрировать их в AEAT и отправлять корректировки R1–R5 от вашего имени.

Как подключить выставление счетов VeriFactu к Claude / ChatGPT / Cursor? Добавьте https://mcp.beel.es/mcp в качестве коннектора и войдите в свою учётную запись BeeL — см. Быстрый старт. Ничего устанавливать не нужно, и для интерактивного использования не нужно вставлять API-ключ.

Действительно ли он соответствует VeriFactu? Да. Счета регистрируются в AEAT в рамках VeriFactu, нумерация и серии соответствуют регламенту, а фискальные ограничения останавливают несоответствующие запросы до того, как они станут фискальным документом.

VeriFactu или TicketBAI? Этот сервер нацелен на VeriFactu, национальную систему AEAT. TicketBAI (режим Страны Басков) выходит за рамки.

Можно ли использовать его без ИИ-агента? Да — это стандартный MCP-сервер, поэтому работает любой клиент, поддерживающий MCP, а та же поверхность выставления счетов доступна в виде REST API, CLI и n8n node.

Вклад в проект

Приветствуются отчёты об ошибках и pull request'ы — см. CONTRIBUTING.md о том, как устроен проект и какие соглашения являются ключевыми. Проблемы безопасности отправляйте на security@beel.es, а не в публичный issue; см. SECURITY.md.

Лицензия

MIT © BeeL.