README.md•4.69 kB
# FEL MCP Server (Local)
Local **Model Context Protocol (MCP)** server for **Guatemalan FEL** invoices.
Exposes tools to **validate FEL XML** and **render branded PDFs**. Designed for **WSL (Ubuntu)** or Linux and can be consumed by MCP hosts (e.g., Claude Desktop).
> This repository focuses on the **FEL MCP server**. It’s often used alongside a chatbot client; see “Related repositories”.
## 🔗 Related repositories
- [Chatbot (CLI / UI)](https://github.com/JosueSay/ChatBotMCP) — client that can drive this MCP server.
- [Reference: OpenAI Chat API Example](https://github.com/JosueSay/Selectivo_IA/blob/main/docs_assistant/README.md) — reference only (patterns for API connectivity and instruction context).
## ✨ Tools (MCP)
- `fel_validate`
**required**: `xml_path` (absolute WSL path)
Checks required fields and totals (subtotal, VAT 12%, total).
- `fel_render`
**required**: `xml_path`, `out_path` (absolute WSL paths)
Renders a branded PDF from the FEL XML.
- `fel_batch`
**required**: `dir_xml`, `out_dir` (absolute WSL paths)
Processes all `*.xml` in `dir_xml`, produces one PDF per XML in `out_dir`, and writes `manifest.json`.
> Use **absolute WSL paths** like `/mnt/d/...` in all arguments and environment variables.
## ⚙️ Requirements
- Python **3.12**
- **WSL Ubuntu 22.04** (or Linux)
- Virtual environment (recommended)
## 🔧 Installation
```bash
git clone <REPO_URL>
cd <REPO_DIR>
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
Create your environment file (use **absolute WSL paths**):
```bash
cp .env.example .env
```
Key variables used by the server (placeholders shown):
```env
# 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
```
## ▶️ Run the server (STDIO)
```bash
source venv/bin/activate
python servers/fel_mcp_server/server_stdio.py
```
## 🧪 Quick CLI tests (JSON-RPC over stdin)
**List tools:**
```bash
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| python servers/fel_mcp_server/server_stdio.py
```
**Validate one XML:**
```bash
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"fel_validate","arguments":{"xml_path":"/ABSOLUTE/PATH/TO/REPO/data/xml/factura.xml"}}}' \
| python servers/fel_mcp_server/server_stdio.py
```
**Render one PDF (no logo):**
```bash
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"fel_render","arguments":{"xml_path":"/ABSOLUTE/PATH/TO/REPO/data/xml/factura.xml","out_path":"/ABSOLUTE/PATH/TO/REPO/data/out/testing.pdf"}}}' \
| python servers/fel_mcp_server/server_stdio.py
```
**Batch:**
```bash
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"fel_batch","arguments":{"dir_xml":"/ABSOLUTE/PATH/TO/REPO/data/xml","out_dir":"/ABSOLUTE/PATH/TO/REPO/data/out/batch"}}}' \
| python servers/fel_mcp_server/server_stdio.py
```
## 🖥️ Use with Claude Desktop (MCP)
1. Install Claude Desktop: [https://claude.ai/download](https://claude.ai/download)
2. Open **Settings -> Developer -> Edit Config**, then edit `claude_desktop_config.json`:
```json
{
"mcpServers": {
"FEL": {
"command": "wsl.exe",
"args": [
"-e",
"/ABSOLUTE/PATH/TO/REPO/venv/bin/python",
"/ABSOLUTE/PATH/TO/REPO/servers/fel_mcp_server/server_stdio.py"
]
}
}
}
```
- Use **absolute WSL paths** in `args`.
- If the host logs show errors like `"'xml_path'"`, it means the call was sent **without arguments**; re-run with a prompt that includes the **exact JSON arguments** block.
3. Restart Claude Desktop (PowerShell):
```powershell
Stop-Process -Name "Claude" -Force; Start-Process "<ABSOLUTE_WINDOWS_PATH_TO_Claude.exe>"
```
## 📚 References
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Anthropic API](https://docs.anthropic.com/en/api)
- [JSON-RPC 2.0](https://www.jsonrpc.org/)