Multi-Tenant Invoice Autofill MCP Server

Un servicio backend en Python que permite a los LLM con capacidad de llamada a funciones o compatibles con MCP (Claude, Gemini, GPT, etc.) autocompletar y guardar facturas en Digital Invoicing Software en nombre de los inquilinos.

Características

• Soporte de doble transporte: Expuesto mediante el protocolo MCP estándar (stdio / Streamable HTTP) y API REST (FastAPI) con esquema OpenAPI.

• Multitenencia y autenticación: Cifrado de credenciales por inquilino, claves de API MCP personalizadas y gestión de sesiones aislada.

• Adaptador resiliente: Adaptador HTTP encapsulado que replica las cabeceras del navegador, con renovación reactiva de la sesión y análisis dinámico de la caducidad de las cookies.

• Idempotencia y concurrencia: Desduplicación mediante hash de documento y bloqueo distribuido Redis por inquilino (lock:tenant:{id}).

• Privacidad ante todo: Capa obligatoria de depuración de registros estructurados que elimina contraseñas, cookies, claves y tokens.

• Cero valores codificados: Sin credenciales ni identidades de negocio incrustadas en código, comentarios o pruebas; generación completa de datos de prueba sintéticos.

Related MCP server: Invoice MCP Server

Requisitos previos locales

• Python 3.12+

• Docker y Docker Compose (para Postgres y Redis locales)

Primeros pasos

1. Configuración del entorno

Copia .env.example a .env y establece las variables locales:

cp .env.example .env

2. Inicia la base de datos local y Redis

docker-compose up -d

3. Instala las dependencias

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

4. Ejecuta las migraciones

.\.venv\Scripts\alembic upgrade head

5. Inicia el servidor

# 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

Seguridad

[!CAUTION] Gestión de la clave de cifrado: La variable de entorno ENCRYPTION_KEY debe establecerse con una clave Fernet segura de 32 bytes codificada en base64. El inicio de la aplicación fallará inmediatamente si no se proporciona ENCRYPTION_KEY. Si una clave de cifrado se utilizó alguna vez para cifrar datos reales de inquilinos y se sospecha que ha quedado expuesta, esos datos deben volver a cifrarse con una clave recién generada, ya que la clave anterior debe considerarse comprometida.

Flujos de trabajo

Incorporación de inquilinos (connect_account)

1. Llama a connect_account con el correo de inicio de sesión, la contraseña y el nombre comercial del inquilino en Digital Invoicing Software.

2. El servidor cifra las credenciales, las valida mediante un inicio de sesión inicial y devuelve una mcp_api_key única.

3. Proporciona esta mcp_api_key al LLM (como token Bearer o cabecera) para las invocaciones posteriores de herramientas.

Autocompletado de facturas (fill_invoice)

El LLM invoca fill_invoice con la carga útil JSON de la factura extraída (buyer, items, meta). El servicio valida los campos obligatorios, aplica la secuenciación de un único documento, comprueba la idempotencia, resuelve la sesión del inquilino, mapea la carga útil al formato del sistema de destino y crea el borrador de la factura.

Ejecución de pruebas

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