FEL

You run a local MCP server that validates FEL XML and renders branded PDFs for Guatemalan FEL invoices. It’s designed to work inside a Linux environment (WSL Ubuntu 22.04 or similar) and can be consumed by MCP hosts or client workflows to automate validation and PDF generation.

How to use

Use this local MCP server with an MCP client to validate FEL XML files and render branded PDFs. You will run the server in a Python-based environment, then send requests through the MCP channel your client supports. The server exposes tools to check required fields and totals, render PDFs, and process batches of XML files.

Typical usage patterns include validating a single FEL XML file, rendering a branded PDF from that file, and batch-processing a directory of FEL XML documents to produce PDFs and a manifest. Your MCP client can invoke the available tools and handle the resulting PDFs and manifests as part of your invoicing workflow.

How to install

# Prerequisites
# 1) Ensure Python 3.12 is installed on your system
# 2) Use a Linux environment (WSL Ubuntu 22.04 or native Linux)

# 3) Clone the repository (replace with the actual repo URL if needed)
git clone <REPO_URL>
cd <REPO_DIR>

# 4) Create and activate a virtual environment
python3.12 -m venv venv
source venv/bin/activate

# 5) Install dependencies
pip install -r requirements.txt

# 6) Prepare environment variables (see .env.example for placeholders)
cp .env.example .env

# 7) Customize environment vars in .env with absolute paths as needed

# Run server in STDIO mode (local MCP server)
source venv/bin/activate
python servers/fel_mcp_server/server_stdio.py

If you prefer to set up environment variables first, you can populate an .env file with your absolute paths (examples shown in the next snippet).

Configuration and environment variables

# I/O
FEL_XML_PATH=/ABSOLUTE/PATH/TO/REPO/data/xml/factura.xml
FEL_OUTPUT_PDF=/ABSOLUTE/PATH/TO/REPO/data/out/factura.pdf
FEL_BATCH_OUT_DIR=/ABSOLUTE/PATH/TO/REPO/data/out
# optional logo
FEL_LOGO_PATH=/ABSOLUTE/PATH/TO/REPO/data/logos/logo.jpg

# Fonts
FEL_ACTIVE_FONT=1
FEL_FONT_DIR_MONTSERRAT=/ABSOLUTE/PATH/TO/REPO/assets/fonts/Montserrat/static
FEL_FONT_DIR_ROBOTOMONO=/ABSOLUTE/PATH/TO/REPO/assets/fonts/Roboto_Mono/static

# Theme/Layout
FEL_THEME=light
FEL_QR_SIZE=150
FEL_TOP_BAR_HEIGHT=20

Create and edit the .env file to point to your absolute paths for XML input, output PDFs, and optional assets like logos and fonts. These settings are required for the server to locate input data and to place generated artifacts in the correct locations.

Tools and endpoints you can use

The local FEL MCP server exposes three core tools you can invoke via the MCP client: fel_validate, fel_render, and fel_batch. Each tool accepts specific path arguments and works with absolute WSL/Linux paths.

• fel_validate checks required fields and totals (subtotal, VAT 12%, total) for a single FEL XML file.
• fel_render renders a branded PDF from a FEL XML file.
• fel_batch processes all XML files in a directory, produces one PDF per XML in an output directory, and writes a manifest.json file.

Using with an MCP client or host

You can integrate this local FEL MCP server with an MCP host such as a chatbot client or an automation workflow. Start the server in your development environment, then connect your client to the STDIO interface to send initialize, tool call, and response messages. Ensure you provide the exact tool names and argument structures your client will pass to the server.

Notes and troubleshooting

Absolute paths are required for all inputs and outputs. If you encounter issues like missing arguments, ensure you start the server with the environment properly loaded (activate the virtual environment) and that your client sends the exact JSON-RPC payloads for tool calls with the proper parameters.

Available tools

fel_validate

Validates a FEL XML file, checking required fields and totals (subtotal, VAT at 12%, total).

fel_render

Renders a branded PDF from a FEL XML file, using configured fonts and logos if provided.

fel_batch

Processes all FEL XML files in a directory, generating one PDF per XML in the output directory and creating a manifest.json with batch results.