Multi-Tenant Invoice Autofill MCP Server

Бэкенд-сервис на Python, позволяющий LLM с поддержкой вызова функций или MCP (Claude, Gemini, GPT и др.) автоматически заполнять и сохранять счета в Digital Invoicing Software от имени тенантов.

Возможности

• Поддержка двух транспортов: доступ через стандартный протокол MCP (stdio / Streamable HTTP) и REST API (FastAPI) со схемой OpenAPI.

• Мультитенантность и аутентификация: шифрование учетных данных для каждого тенанта, индивидуальные MCP API-ключи и изолированное управление сессиями.

• Отказоустойчивый адаптер: инкапсулированный HTTP-адаптер, воспроизводящий заголовки браузера, с реактивным обновлением сессии и динамическим разбором срока действия cookie.

• Идемпотентность и конкурентность: дедупликация на основе хеша документа и распределенная блокировка Redis для каждого тенанта (lock:tenant:{id}).

• Конфиденциальность прежде всего: обязательный слой маскирования структурированных логов, вычищающий пароли, cookie, ключи и токены.

• Ноль жестко прописанных значений: никаких учетных данных или бизнес-идентификаторов, зашитых в код, комментарии или тесты; полная генерация синтетических тестовых данных.

Related MCP server: Invoice MCP Server

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

• Python 3.12+

• Docker и Docker Compose (для локальных Postgres и Redis)

Начало работы

1. Настройка окружения

Скопируйте .env.example в .env и задайте локальные переменные:

cp .env.example .env

2. Запуск локальной базы данных и Redis

docker-compose up -d

3. Установка зависимостей

python -m venv .venv
# Windows:
.\.venv\Scripts\pip install -r requirements.txt
# Linux/macOS:
source .venv/bin/activate
pip install -r requirements.txt

4. Запуск миграций

.\.venv\Scripts\alembic upgrade head

5. Запуск сервера

# Start FastAPI REST server:
.\.venv\Scripts\uvicorn mcp_digitalinvoice.main:app --reload --port 8000

# Run MCP stdio server:
.\.venv\Scripts\python -m mcp_digitalinvoice.mcp_server.server

Безопасность

[!CAUTION] Управление ключом шифрования: переменная окружения ENCRYPTION_KEY должна быть задана как безопасный 32-байтовый ключ Fernet в кодировке base64. Запуск приложения немедленно завершится ошибкой, если ENCRYPTION_KEY не задана. Если ключ шифрования когда-либо использовался для шифрования реальных данных тенантов и есть подозрение на его утечку, эти данные должны быть повторно зашифрованы с помощью заново сгенерированного ключа, поскольку старый ключ следует считать скомпрометированным.

Рабочие процессы

Онбординг тенанта (connect_account)

1. Вызовите connect_account, передав email тенанта для входа в Digital Invoicing Software, пароль и название бизнеса.

2. Сервер шифрует учетные данные, проверяет их с помощью первичного входа и возвращает уникальный mcp_api_key.

3. Передайте этот mcp_api_key LLM (как Bearer-токен или заголовок) для последующих вызовов инструментов.

Автозаполнение счетов (fill_invoice)

LLM вызывает fill_invoice с извлеченной JSON-полезной нагрузкой счета (buyer, items, meta). Сервис проверяет обязательные поля, обеспечивает последовательную обработку документов по одному, проверяет идемпотентность, восстанавливает сессию тенанта, преобразует полезную нагрузку в формат, требуемый нижестоящей системой, и создает черновик счета.

Запуск тестов

.\.venv\Scripts\pytest -v tests/