Skip to main content
Glama
fatturafacile-mcp-server

fatturafacile-mcp-server

Official

fatturafacile-mcp-server

Official Model Context Protocol (MCP) AI Gateway for the Fattura Facile ERP ecosystem.

License: MIT Node.js TypeScript Package Manager Build & Tests


Overview

fatturafacile-mcp-server is an enterprise-grade AI Gateway enabling LLMs, Autonomous Agents, and Copilots to safely, reliably, and auditably interact with the Fattura Facile ERP backend via the standard Model Context Protocol (MCP).

It exposes comprehensive ERP operations across invoicing, CRM, quotation, catalog management, payments, and analytics, backed by strict multi-tenancy isolation, role-based access control (RBAC), OpenTelemetry distributed tracing, Redis caching, and transactional multi-step workflows.


Related MCP server: HiveDesk

Architectural Highlights

  • OpenAPI Single Source of Truth: All ERP communication is performed strictly via SDK client interfaces with no duplicate DTOs or handwritten HTTP models.

  • Multi-Tenancy & Zero Leakage: Every execution is scoped by explicit TenantContext, UserContext, CompanyContext, and PermissionContext. Cache keys and audit trails are completely partitioned.

  • Unified Tool Framework: Centralized lifecycle incorporating Zod schema validation, RBAC checks, OpenTelemetry spans, exponential backoff retries, structured error handling, and multi-tenant Redis caching.

  • Pluggable MCP Transports: Native support for stdio, streamable-http, and legacy sse transports.

  • Agentic Workflow Engine: Multi-step business workflows with automated compensation actions and transaction rollback support.

  • Vendor-Neutral Semantic Search: Abstracted vector storage and retrieval layer for future RAG and knowledge graph capabilities.


Capabilities Overview

1. 39 MCP Tools (Actions)

Category

Available Tools

Customers

search_customer, get_customer, create_customer, update_customer, delete_customer, list_customers

Invoices

search_invoice, get_invoice, create_invoice, update_invoice, delete_invoice, list_invoices, send_invoice, cancel_invoice, duplicate_invoice

Quotes

search_quote, get_quote, create_quote, update_quote, delete_quote, list_quotes, convert_quote_to_invoice

Payments

search_payment, register_payment, refund_payment, list_payments

Products & Services

search_product, get_product, create_product, update_product, list_products, search_service, get_service, create_service, update_service, list_services

Companies & Contacts

search_company, get_company, create_company, update_company, list_companies, search_contact, get_contact, create_contact, update_contact, list_contacts

Projects & Tasks

search_project, get_project, create_project, update_project, list_projects, search_task, get_task, create_task, update_task, complete_task, list_tasks

Files & Documents

search_file, get_file, upload_file, download_file, list_files

2. 22 Dynamic MCP Resources (Context)

  • Company: company://profile, company://settings, company://statistics, company://subscriptions

  • Customers: customer://recent, customer://top, customer://inactive, customer://vip

  • Products: product://catalog, product://top-selling, product://low-stock

  • Quotes: quote://recent, quote://drafts, quote://expiring

  • Invoices: invoice://latest, invoice://drafts, invoice://paid, invoice://overdue, invoice://unpaid

  • Payments: payment://recent, payment://reconciliation

  • Projects: project://recent, project://active

  • Dashboards: dashboard://summary, dashboard://sales, dashboard://customers, dashboard://cashflow, dashboard://invoices

3. 20 Pre-Engineered Prompts (Guided Interactions)

  • Sales: CreateQuotePrompt, CreateInvoicePrompt, SendInvoicePrompt, InvoiceReminderPrompt, SalesSummaryPrompt, SalesForecastPrompt, RevenueAnalysisPrompt

  • Customers: CustomerLookupPrompt, CustomerAnalysisPrompt, CustomerRiskPrompt, CustomerHealthPrompt

  • Finance: FinancialOverviewPrompt, CashFlowPrompt, ProfitabilityPrompt, OverdueInvoicesPrompt, RevenueForecastPrompt

  • Productivity: DailySummaryPrompt, WeeklySummaryPrompt, ManagementReportPrompt, ExecutiveReportPrompt

4. Agentic Workflows

  • Customer Onboarding & Quote Generation: Multi-step client onboarding with automatic commercial quotation and compensation on failure.

  • Quote-to-Invoice Conversion & Dispatch: Converts accepted customer quotes to official invoices and automatically transmits them.

  • Overdue Invoice Recovery: Scans outstanding balances, calculates dunning terms, and dispatches compliant reminders.

  • Monthly Executive Reporting: Aggregates P&L metrics, cashflow projections, and customer health for board briefings.


Getting Started

Prerequisites

  • Node.js >= 22.x LTS

  • pnpm >= 9.x (v12 supported)

  • Redis (optional, in-memory cache fallback is active by default)

Installation

# Clone the repository
git clone https://github.com/FatturaFacile/fatturafacile-mcp-server.git
cd fatturafacile-mcp-server

# Install dependencies
pnpm install --frozen-lockfile

# Configure environment
cp .env.example .env

Running the Server

# Development mode with hot-reload
pnpm run dev

# Compile TypeScript to dist/
pnpm run build

# Start production server (stdio by default)
pnpm start

# Start with Streamable HTTP / SSE transport on port 3000
MCP_TRANSPORT=streamable-http PORT=3000 pnpm start

Client Integration Examples

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "fattura-facile": {
      "command": "node",
      "args": ["C:/dev/fattura-facile/mcp-server/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "FATTURA_FACILE_API_URL": "https://api.fatturafacile.eu",
        "FATTURA_FACILE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor & Windsurf

In .cursor/mcp.json or Windsurf's mcp_config.json:

{
  "mcpServers": {
    "fattura-facile": {
      "command": "node",
      "args": ["C:/dev/fattura-facile/mcp-server/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Testing & Quality Assurance

# Run unit and integration tests (Vitest)
pnpm test

# Run tests with code coverage
pnpm run test:coverage

# Typecheck with TypeScript strict mode
pnpm run typecheck

# Code linting
pnpm run lint

# Code style check
pnpm run format:check

Docker Deployment

# Build and run containerized server with Redis
docker-compose up --build -d

# Check service health
curl http://localhost:3000/health

Documentation


License

This project is open-source software licensed under the MIT License.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Governed MCP bridge that lets AI clients query live ERP data via SuiteQL, saved searches, and records, with role-based permissions and full audit logging.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that exposes an in-browser AI ERP (CRM, stock, invoices, HR) with role-aware agents, enabling natural language chat and confirm-before-write actions.
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants like Claude, ChatGPT, and Copilot to access SAP Business One, S/4HANA Cloud, and Concur data through MCP tools for partners, orders, invoices, expense reports, and more.
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents such as ChatGPT, Claude, and local LLMs to operate an enterprise digital-operations platform through MCP, exposing 19 model tools and 3 app-only tools for identity, data, workflow, files, and PII-controlled operations with role-based permissions and two-phase confirmations.
      Apache 2.0