fintom8-mcp 0.1.0
MCP Server for Fintom8 E-Invoicing services (Conversion, Validation, Correction)
Requires Python: >=3.9

# Fintom8 E-Invoicing Agent (MCP)

[![MCP Certified](https://img.shields.io/badge/MCP-Certified-blue)](https://mcpmarket.com)
[![Peppol Ready](https://img.shields.io/badge/Peppol-3.0.20-green)](https://fintom8.com)

**The official Model Context Protocol (MCP) server for Fintom8.**

This server acts as an intelligent bridge to AI agentic Fintom8 E-Invoice Platform. It enables autonomous agents to validate, audit, and correct e-invoices against the latest European standards (EN16931) and Peppol regulations.

**General Functionalities Provided Over MCP:**
* **Convert Peppol UBL E-Invoice from PDF**
* **Validate Peppol UBL E-Invoice**
* **Correct Peppol UBL Invoice**

*Other formats and functionalities can be requested.*

## 🚀 Features

- **Autonomous Validation:** Agents can send XML content and receive detailed compliance reports.
- **Peppol 3.0.20 Support:** Checks against the newest rules, including EAS code updates and PDF attachment handling.
- **Smart Explanations:** The server returns structured error data that LLMs can easily parse to explain issues in human-readable language.

## 🛠️ Installation & Usage

### Option 1: Using `uvx` (Recommended)

You can run this server directly without installing it globally:

```bash
uvx fintom8-mcp-server
```

### Option 2: Clone and Run

1. Clone this repository:
   ```bash
   git clone https://github.com/Fintom8/fintom8-mcp-server.git
   cd fintom8-mcp-server
   ```

2. Install dependencies:
   ```bash
   pip install -e .
   ```

3. Run the server:
   ```bash
   mcp run server.py
   ```

## 🔑 Configuration

By default, the server connects to the public Fintom8 endpoints:
- **Validation endpoint**: `https://fintom8platform-dev.ey.r.appspot.com/backend/invoice-agent`
- **Converter endpoint**: `https://fintom8converter-prod.ey.r.appspot.com/backend/converter-workflowv2/`

To use a specific API environment or authenticated tier, set the environment variables:

```bash
export FINTOM_API_URL="https://api.fintom8.com/v1/validate"
export FINTOM_CONVERTER_URL="https://api.fintom8.com/v1/convert"
export FINTOM_API_KEY="your-api-key"
```

## 📦 Tools Included

### 1. **`convert_pdf_to_invoice`**: Convert PDF invoices to UBL format
Converts PDF invoice documents to structured UBL/Peppol XML format using AI-powered extraction.

**Input:**
- `pdf_path` (string, optional): Path to the PDF file to convert
- `pdf_base64` (string, optional): Base64-encoded PDF content
- `invoice_format` (string, default: "ubl"): Output format for the invoice
- `gemini_model` (string, default: "gemini-3-flash-preview"): The Gemini model to use
- `max_iterations` (int, default: 3): Maximum number of AI iterations for refinement
- `verbose_output` (bool, default: false): Include verbose processing details

**Output:** JSON containing the converted UBL invoice and conversion metadata

**Note:** Either `pdf_path` or `pdf_base64` must be provided.

### 2. **`validate_invoice`**: Validate UBL/Peppol XML invoices
Validates a UBL/Peppol XML invoice against EN16931 and Peppol compliance rules.

**Input:**
- `xml_content` (string): The raw XML string of the invoice to validate

**Output:** JSON compliance report (Valid/Invalid, Error List)

## � Usage Examples

### Example 1: Convert PDF to UBL Invoice
```python
# Using with Claude Desktop or other MCP-compatible client
convert_pdf_to_invoice(
    pdf_path="/path/to/invoice.pdf",
    invoice_format="ubl",
    gemini_model="gemini-3-flash-preview",
    max_iterations=3
)
```

### Example 2: Validate Converted Invoice
```python
# First convert PDF
result = convert_pdf_to_invoice(pdf_path="/path/to/invoice.pdf")

# Then validate the result
validate_invoice(xml_content=result["ubl_xml"])
```

### Example 3: Full Workflow
```python
# 1. Convert PDF to UBL
converted = convert_pdf_to_invoice(
    pdf_path="/invoices/supplier_invoice.pdf",
    verbose_output=True
)

# 2. Validate the converted invoice
validation_result = validate_invoice(xml_content=converted["ubl_xml"])

# 3. Check compliance
if validation_result["is_valid"]:
    print("✅ Invoice is Peppol-compliant!")
else:
    print("❌ Validation errors:", validation_result["errors"])
```


## �🛡️ Privacy & Security

This `fintom8-mcp-server` acts as a thin client proxy. 
- **No data processing** happens within this repository's code.
- All validation logic is handled secure servers at Fintom8.
- Your data is processed solely for the purpose of validation and is not used for AI model training.

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.