CLAUDE.md

MCP FacturaScripts

Version 1.0.2 - TypeScript ESM project for a Model Context Protocol (MCP) server that integrates with FacturaScripts ERP system, providing comprehensive access to business, accounting, and administrative data.

Project Structure

The project follows a modular architecture that groups related functionality for better organization and maintainability:

• src/index.ts - Main MCP server entry point
• src/env.ts - Environment validation using Zod
• src/fs/client.ts - Axios-based FacturaScripts API client
• src/types/facturascripts.ts - TypeScript interfaces for all FacturaScripts entities
• src/utils/filterParser.ts - Dynamic filtering and sorting utilities

Modular Organization

src/modules/
├── core-business/          # Essential business entities
│   ├── clientes/           # Customer management
│   ├── productos/          # Product catalog
│   ├── proveedores/        # Supplier management
│   └── stocks/             # Inventory management
├── sales-orders/           # Sales and order processing
│   ├── pedidoclientes/     # Customer orders
│   ├── facturaclientes/    # Customer invoices
│   ├── presupuestoclientes/# Customer quotes
│   ├── albaranclientes/    # Customer delivery notes
│   └── line-items/         # All document line items
├── purchasing/             # Procurement and supplier operations
│   ├── facturaproveedores/ # Supplier invoices
│   ├── albaranproveedores/ # Supplier delivery notes
│   └── productoproveedores/# Products by supplier
├── accounting/             # General accounting
│   ├── asientos/           # Accounting entries
│   ├── cuentas/            # Chart of accounts
│   ├── diarios/            # Accounting journals
│   ├── ejercicios/         # Fiscal years
│   └── conceptopartidas/   # Entry concepts
├── finance/                # Financial management
│   ├── cuentabancos/       # Bank accounts
│   ├── cuentabancoclientes/# Customer bank accounts
│   ├── cuentabancoproveedores/# Supplier bank accounts
│   ├── cuentaespeciales/   # Special accounts
│   └── divisas/            # Currencies
├── configuration/          # System configuration
│   ├── almacenes/          # Warehouses
│   ├── agentes/            # Sales agents
│   ├── formapagos/         # Payment methods
│   ├── impuestos/          # Tax rates
│   ├── familias/           # Product families
│   ├── fabricantes/        # Manufacturers
│   └── [14 more modules]   # Complete configuration coverage
├── system/                 # System administration
│   ├── apiaccess/          # API access control
│   ├── apikeyes/           # API key management
│   ├── logmessages/        # System logs
│   └── [4 more modules]    # System management
├── communication/          # Communications
│   ├── emailnotifications/ # Email templates
│   ├── emailsentes/        # Email history
│   └── contactos/          # Contact management
└── geographic/             # Geographic data
    ├── ciudades/           # Cities
    ├── codigopostales/     # Postal codes
    └── empresas/           # Company locations

Module Structure

Each module follows a consistent pattern:

module-name/
├── resource.ts    # MCP resource implementation
├── tool.ts        # Claude Desktop tool definition
└── index.ts       # Module exports

This modular architecture provides:

• Better Organization: Related functionality grouped together
• Easier Maintenance: Changes isolated to specific modules
• Cleaner Code: Smaller, focused files instead of large monoliths
• Enhanced Testability: Individual modules can be tested in isolation
• Scalability: Easy to add new modules or modify existing ones

Configuration

Environment variables (see .env.example):

• FS_BASE_URL - Base URL of your FacturaScripts instance
• FS_API_VERSION - API version (default: 3)
• FS_API_TOKEN - API authentication token

Available Scripts

• npm run dev - Run development server (auto-builds, runs JavaScript)
• npm run build - Build TypeScript to dist/
• npm run start - Run built server (same as mcp)
• npm run mcp - Build and run MCP server (recommended for MCP Inspector)
• npm run dev:ts - Run TypeScript directly with tsx (development only, not for MCP Inspector)
• npm run test - Run tests with Vitest
• npm run test:watch - Run tests in watch mode
• npm run test:ui - Run tests with Vitest UI
• npm run test:run - Run tests once and exit

MCP Inspector Usage

The server includes a robust entry point (mcp-server.js) that automatically builds the project and runs the JavaScript version for maximum compatibility.

✅ Recommended for MCP Inspector:

# Using MCP Inspector
npx @modelcontextprotocol/inspector npm run mcp

# Or directly with node
node mcp-server.js

# Or any of these npm scripts
npm start
npm run dev
npm run mcp

✅ All scripts now use the built JavaScript version - The project automatically builds and runs the compiled code to avoid ESM module resolution issues.

⚠️ Development only: TypeScript source execution

npm run dev:ts  # Only for development - may have import issues with MCP Inspector

The mcp-server.js entry point ensures consistent behavior across all environments including MCP Inspector, Claude Desktop, and other MCP clients.

MCP Resources

The server provides 59 comprehensive MCP resources covering all major FacturaScripts entities including business transactions, accounting data, contacts, inventory, and system administration.

Query Parameters

All resources support advanced filtering and sorting with a simple, dynamic parameter format:

Core Parameters:

• limit - Number of records to return (default: 50)
• offset - Number of records to skip (default: 0)
• filter - Dynamic filtering with field:value format
• order - Sorting with field:direction format

Filter Parameter Format: The filter parameter supports a flexible format that gets internally converted to FacturaScripts API format:

• Basic filtering: campo:valor (e.g., activo:1)
• Multiple filters: campo1:valor1,campo2:valor2 (e.g., activo:1,nombre:Juan)
• Advanced operators:
  • campo_gt:valor - Greater than
  • campo_gte:valor - Greater than or equal
  • campo_lt:valor - Less than
  • campo_lte:valor - Less than or equal
  • campo_neq:valor - Not equal
  • campo_like:texto - Text search (automatically normalized)

Order Parameter Format:

• Single field: campo:asc or campo:desc (e.g., nombre:asc)
• Multiple fields: campo1:asc,campo2:desc (e.g., nombre:asc,fechaalta:desc)

Important Notes:

• _like searches: Use lowercase text without accents, no wildcards needed
• Duplicate filters: Only the first occurrence is used if the same filter key appears multiple times
• Empty results: Non-existent column names return empty arrays
• Collection endpoints only: Filters/sorting only work on collection endpoints (not single resource endpoints like /productos/{id})

Usage Examples

Simple Filtering:

// Basic field filter
facturascripts://clientes?filter=activo:1

// Multiple filters
facturascripts://productos?filter=precio_gt:10.00,precio_lt:100.00

// Text search (automatically normalized to lowercase, no accents)
facturascripts://clientes?filter=nombre_like:acme

Advanced Filtering:

// Range queries with operators
facturascripts://facturaclientes?filter=fecha_gte:2024-01-01,total_gt:100.00

// Complex text searches
facturascripts://productos?filter=descripcion_like:laptop,familia:INFOR

// Using different operators
facturascripts://clientes?filter=fechaalta_neq:2024-01-01,activo:1

Sorting:

// Single field sorting
facturascripts://clientes?order=nombre:asc

// Multi-field sorting  
facturascripts://clientes?order=nombre:asc,fechaalta:desc

// Combined filtering and sorting
facturascripts://productos?filter=activo:1,precio_gt:10.00&order=nombre:asc&limit=25

Tool Usage (Claude Desktop):

// Using tools with dynamic filter parameter
get_clientes({
  filter: "activo:1,nombre_like:acme",
  order: "nombre:asc",
  limit: 25
})

// Advanced filtering with operators
get_productos({
  filter: "precio_gte:10.00,precio_lte:100.00,descripcion_like:laptop", 
  order: "precio:asc"
})

Available Resources

All resources support advanced filtering and sorting parameters as described above:

Core Business Resources:

• facturascripts://clientes - Client management and customer data
• facturascripts://productos - Product catalog and inventory items
• facturascripts://proveedores - Supplier and vendor management
• facturascripts://stocks - Inventory stock levels and warehouse data

Sales & Orders:

• facturascripts://pedidoclientes - Customer orders and order management
• facturascripts://facturaclientes - Customer invoices and billing
• facturascripts://presupuestoclientes - Customer quotes and estimates
• facturascripts://albaranclientes - Customer delivery notes
• facturascripts://lineapedidoclientes - Customer order line items
• facturascripts://lineafacturaclientes - Customer invoice line items
• facturascripts://lineapresupuestoclientes - Customer quote line items
• facturascripts://lineaalbaranclientes - Customer delivery note line items

Purchasing:

• facturascripts://facturaproveedores - Supplier invoices and payables
• facturascripts://albaranproveedores - Supplier delivery notes
• facturascripts://productoproveedores - Products by supplier relationships
• facturascripts://lineafacturaproveedores - Supplier invoice line items
• facturascripts://lineaalbaranproveedores - Supplier delivery note line items
• facturascripts://lineapedidoproveedores - Supplier order line items
• facturascripts://lineapresupuestoproveedores - Supplier quote line items

Accounting & Finance:

• facturascripts://asientos - Accounting journal entries
• facturascripts://cuentas - Chart of accounts
• facturascripts://diarios - Accounting journals
• facturascripts://ejercicios - Fiscal years and periods
• facturascripts://empresas - Company and organization data
• facturascripts://conceptopartidas - Accounting entry concepts
• facturascripts://cuentabancos - Bank account management
• facturascripts://cuentabancoclientes - Customer bank accounts
• facturascripts://cuentabancoproveedores - Supplier bank accounts
• facturascripts://cuentaespeciales - Special accounting accounts
• facturascripts://divisas - Currency and exchange rates

Configuration & Master Data:

• facturascripts://almacenes - Warehouse and location management
• facturascripts://agentes - Sales agents and representatives
• facturascripts://agenciatransportes - Shipping and transport agencies
• facturascripts://formapagos - Payment methods and terms
• facturascripts://impuestos - Tax rates and tax management
• facturascripts://impuestozonas - Tax zones and regional settings
• facturascripts://familias - Product families and categories
• facturascripts://fabricantes - Manufacturers and brands
• facturascripts://atributos - Product attributes and properties
• facturascripts://atributovalores - Product attribute values
• facturascripts://estadodocumentos - Document status definitions
• facturascripts://formatodocumentos - Document format templates
• facturascripts://grupoclientes - Customer groups and classifications
• facturascripts://identificadorfiscales - Tax ID types and formats

System & Administration:

• facturascripts://apiaccess - API access control and permissions
• facturascripts://apikeyes - API key management
• facturascripts://logmessages - System logs and audit trails
• facturascripts://cronjobes - Scheduled jobs and automation
• facturascripts://emailnotifications - Email notification templates
• facturascripts://emailsentes - Sent email history
• facturascripts://doctransformations - Document transformation logs
• facturascripts://attachedfiles - File attachments and uploads
• facturascripts://attachedfilerelations - File attachment relationships

Geographic & Contact Data:

• facturascripts://contactos - Contact information and details
• facturascripts://ciudades - Cities and urban areas
• facturascripts://codigopostales - Postal codes and ZIP codes

Returns JSON format:

{
  "meta": {
    "total": number,
    "limit": number,
    "offset": number,
    "hasMore": boolean
  },
  "data": [...]
}

Development Environment

This project runs a local FacturaScripts instance via Docker for development:

• Docker Compose setup includes FacturaScripts and MySQL
• Local directories: facturascripts/ (app files), mysql/ (database)
• Use .claudeignore to exclude large directories from Claude Code operations

MCP Inspector Compatibility

Entry Point: The project uses mcp-server.js as the main entry point for maximum compatibility:

// Auto-building entry point that ensures JavaScript execution
// Resolves ESM import issues with TypeScript source files

Usage with MCP Inspector:

# Recommended usage
npx @modelcontextprotocol/inspector npm run mcp

# Alternative commands
npm run start    # Same as mcp
npm run dev      # Same as mcp (JavaScript execution)

Important Notes:

• Always use npm run mcp or npm start for MCP Inspector
• Do NOT use npm run dev:ts with MCP Inspector (TypeScript runtime issues)
• The auto-building entry point ensures compiled JavaScript execution
• Resolves ESM module resolution conflicts between .ts source and .js imports

Claude Code Configuration

Important files for maintaining context:

• .claudeignore - Excludes node_modules/, dist/, mysql/, facturascripts/ from operations
• This CLAUDE.md file - Primary context for Claude Code sessions

Auto-Documentation Rules

IMPORTANT: When adding new MCP resources (modules in src/modules/):

1. Automatically update this CLAUDE.md file with the new resource endpoint
2. Update README.md "Available Resources" section if it exists
3. Follow the pattern: facturascripts://{resourceName} - Dynamic filtering and sorting support is automatic
4. All resources must support: limit, offset, filter (dynamic field:value format), and order (dynamic field:direction format)
5. Use consistent naming and documentation format
6. CRITICAL: Always add corresponding tools to src/index.ts for Claude Desktop integration:
   • Add tool definition in ListToolsRequestSchema handler with simple 4-parameter schema (limit, offset, filter, order)
   • Add tool implementation in CallToolRequestSchema handler
   • Use naming pattern: get_{resourceName} with dynamic filtering support
   • All tools support the same consistent parameter interface with advanced filtering via the filter parameter
   • Tools make resources interactive in Claude Desktop interface with full FacturaScripts API capability

Development Standards

Code Patterns

• Resource naming: Use plural names matching FacturaScripts API endpoints (e.g., clientes, productos)
• Error handling: Use try/catch with descriptive error messages
• TypeScript: Strict types, use interfaces for API responses
• Imports: Use .js extensions for ESM compatibility

Module Implementation Pattern

1. Resource Implementation (resource.ts):

// src/modules/{category}/{name}/resource.ts
import { Resource } from '@modelcontextprotocol/sdk/types.js';
import { FacturaScriptsClient } from '../../../fs/client.js';
import { Entity } from '../../../types/facturascripts.js';
import { parseUrlParameters } from '../../../utils/filterParser.js';

export class EntityResource {
  constructor(private client: FacturaScriptsClient) { }

  async getResource(uri: string): Promise<Resource> {
    const { limit, offset, additionalParams } = parseUrlParameters(uri);
    // Resource implementation...
  }

  matchesUri(uri: string): boolean {
    // URI matching logic...
  }
}

2. Tool Implementation (tool.ts):

// src/modules/{category}/{name}/tool.ts
export const toolDefinition = {
  name: 'get_{name}',
  description: 'Spanish description of the tool functionality',
  inputSchema: {
    type: 'object',
    properties: {
      limit: { type: 'number', description: '...', default: 50 },
      offset: { type: 'number', description: '...', default: 0 },
      filter: { type: 'string', description: 'Dynamic filtering...' },
      order: { type: 'string', description: 'Dynamic sorting...' },
    },
  },
};

export const toolImplementation = async (resource: any, buildUri: Function) => {
  const uri = buildUri('{name}');
  const result = await resource.getResource(uri);
  return { content: [{ type: 'text', text: result.contents[0].text }] };
};

3. Module Exports (index.ts):

// src/modules/{category}/{name}/index.ts
export { EntityResource } from './resource.js';
export { 
  toolDefinition as entityToolDefinition,
  toolImplementation as entityToolImplementation 
} from './tool.js';

Specialized Business Tools Pattern

When to Create Specialized Tools:

• Complex multi-step operations (e.g., search by tax ID → retrieve related data)
• Business-specific workflows that combine multiple API calls
• Enhanced error handling for common business scenarios
• Simplified interfaces for complex operations

Example Implementation Pattern:

// Specialized tool combining client search + invoice retrieval
export const toolByCifnifDefinition = {
  name: 'get_facturas_cliente_por_cifnif',
  description: 'Obtiene las facturas de un cliente específico mediante su CIF/NIF.',
  inputSchema: {
    type: 'object',
    properties: {
      cifnif: { type: 'string', description: 'CIF/NIF del cliente (requerido)' },
      limit: { type: 'number', default: 50, minimum: 1, maximum: 1000 },
      offset: { type: 'number', default: 0, minimum: 0 },
      order: { type: 'string', description: 'Ordenación (ej: fecha:desc)' }
    },
    required: ['cifnif']
  }
};

export async function toolByCifnifImplementation(args, client) {
  try {
    // Step 1: Find client by CIF/NIF
    const clientResult = await client.getWithPagination('/clientes', 1, 0, { 
      'filter[cifnif]': args.cifnif 
    });
    
    if (!clientResult.data.length) {
      return { 
        content: [{ type: 'text', text: JSON.stringify({
          error: 'Client not found',
          message: `No se encontró ningún cliente con CIF/NIF: ${args.cifnif}`
        }) }],
        isError: true 
      };
    }

    // Step 2: Get invoices for client
    const codcliente = clientResult.data[0].codcliente;
    const invoiceResult = await client.getWithPagination('/facturaclientes', 
      args.limit, args.offset, { 'filter[codcliente]': codcliente });

    // Step 3: Return combined response
    return {
      content: [{ type: 'text', text: JSON.stringify({
        clientInfo: { /* client details */ },
        invoices: invoiceResult
      }) }]
    };
  } catch (error) {
    // Comprehensive error handling
    return { /* error response */ };
  }
}

Key Principles:

• Multi-step Validation: Validate each step and provide clear error messages
• Parameter Sanitization: Enforce bounds and normalize inputs
• Consistent Response Format: Follow established patterns while adding business context
• Comprehensive Testing: Unit tests for all scenarios + integration tests with real APIs
• Proper Registration: Export from module index and register in main server

Quality Checks

Before completing any task, run:

• npm run build - Ensure TypeScript compiles (currently: ✅ passing)
• npm run test - Run all tests to ensure nothing is broken (currently: ✅ 358 tests passing)
• Test the resource manually if possible with live FacturaScripts API

TDD Workflow

Test-Driven Development Process:

1. Red: Write a failing test first

   npm run test:watch  # Keep tests running

2. Green: Write minimal code to make the test pass

   npm run test        # Verify tests pass

3. Refactor: Clean up code while keeping tests green

   npm run build       # Ensure TypeScript still compiles
   npm run test        # Ensure tests still pass

Test Structure: The test structure follows the same modular organization as src/modules/:

• tests/unit/modules/core-business/ - Tests for clients, products, suppliers, stock
• tests/unit/modules/sales-orders/ - Tests for customer orders, invoices, quotes, delivery notes and their line items
• tests/unit/modules/purchasing/ - Tests for supplier orders, invoices, delivery notes and their line items
• tests/unit/modules/accounting/ - Tests for accounting entries, accounts, journals, fiscal years
• tests/unit/modules/finance/ - Tests for bank accounts, currencies, special accounts
• tests/unit/modules/configuration/ - Tests for system configuration entities (taxes, payment methods, etc.)
• tests/unit/modules/system/ - Tests for system administration (API access, logs, transformations)
• tests/unit/modules/communication/ - Tests for contacts, emails, notifications
• tests/unit/modules/geographic/ - Tests for geographic data (cities, postal codes)
• tests/unit/fs/ - Tests for core client functionality
• tests/integration/modules/{category}/ - Integration tests with real APIs (require env setup)
• tests/setup.ts - Global test setup and teardown

Writing New Resources (TDD Approach):

1. Write unit tests in tests/unit/modules/{category}/{name}.test.ts
2. Write integration tests in tests/integration/modules/{category}/{name}.integration.test.ts
3. Implement the resource to pass the tests
4. Run quality checks before completion

API Response Format

All 28 resources return consistent pagination format:

{
  meta: { total, limit, offset, hasMore },
  data: T[]
}

Current Project Status (v1.0.2)

• ✅ 59 MCP Resources - Complete FacturaScripts API coverage including OpenAPI part16 implementation
• ✅ 66 Interactive Tools - Full Claude Desktop integration with advanced filtering including specialized business analytics and customer retention tools
• ✅ 567+ Tests Passing - Comprehensive unit & integration testing with modular organization including specialized business tools and customer retention analytics
• ✅ Live API Integration - Working with real FacturaScripts instances
• ✅ Advanced API Support - Full FacturaScripts filtering, sorting, and pagination
• ✅ TypeScript Strict Mode - Full type safety and IntelliSense
• ✅ Production Ready - Error handling, documentation, and monitoring
• ✅ Automated Changelog - Conventional commits and automated release management with Keep a Changelog format
• ✅ Enhanced Documentation - Comprehensive guides and best practices
• ✅ Specialized Business Tools - Advanced customer analytics including lost client recovery, invoice search by CIF/NIF, best-selling products, and customer retention analytics with comprehensive error handling
• ✅ MCP TypeScript SDK Examples - Comprehensive SDK documentation with business-focused examples
• ✅ OpenAPI Part16 Implementation - Product variants, work events, analytics models, and PDF export functionality
• ✅ Binary Data Support - PDF generation and download capabilities

Latest Implementation (Current Session)

OpenAPI Part16 Implementation - Complete ✅

Implementation Date: August 2025
New Resources Added: 3 resources + 1 specialized tool
New Tests Added: 145+ tests

New Resources Implemented:

1. variantes (Product Variants)

   • Location: src/modules/core-business/variantes/
   • Purpose: Comprehensive product variant management with attributes, pricing, and inventory
   • Key Features: Multi-attribute support, barcode tracking, cost/price management, margin calculation
   • Testing: 6 unit tests + 3 integration tests

2. workeventes (Work Events)

   • Location: src/modules/system/workeventes/
   • Purpose: System job/task tracking and process monitoring
   • Key Features: Process tracking, worker assignment, completion status, parameter storage
   • Testing: 7 unit tests + 4 integration tests

3. totalmodeles (Analytics Models)

   • Location: src/modules/system/totalmodeles/
   • Purpose: System analytics and data aggregation models for business intelligence
   • Key Features: Flexible data structure, aggregation support, business intelligence foundation
   • Testing: 5 unit tests + 2 integration tests

4. exportar_factura_cliente (PDF Export Tool)

   • Location: src/modules/sales-orders/facturaclientes/tool.ts
   • Purpose: Customer invoice PDF generation and download
   • Key Features: PDF generation, format options, language support, binary data handling
   • Enhancement: Added getRaw method to FacturaScriptsClient for binary data support

Technical Achievements:

• Enhanced TypeScript Interfaces: Added 3 new strongly-typed entities
• Binary Data Support: Implemented PDF download functionality
• Flexible Testing: Enhanced integration tests to handle API variations
• Error Resilience: Comprehensive error handling for new endpoints
• Total Test Count: Increased from 421 to 566 tests (100% pass rate)

Quality Assurance:

• ✅ TypeScript compilation successful
• ✅ All 566 tests passing
• ✅ Integration testing with real FacturaScripts API
• ✅ Error scenario coverage
• ✅ Binary data handling validated

Previous Implementation History

New Specialized Tool: get_productos_mas_vendidos

Implementation Details:

• Purpose: Generate rankings of best-selling products/services within specified date periods based on invoice line items
• Location: src/modules/sales-orders/line-items/lineafacturaclientes/tool.ts
• Registration: Properly exported from module index and registered in main src/index.ts
• Parameters:
  • fecha_desde, fecha_hasta (required): Date range for analysis (YYYY-MM-DD)
  • limit, offset (optional): Pagination (1-1000, default: 50)
  • order (optional): Sort by quantity or revenue (default: "cantidad_total:desc")
• Multi-step Process: Invoice lookup → Line item aggregation → Product grouping → Ranking generation
• Error Handling: No invoices found, invalid IDs, API failures, empty descriptions
• Response Structure: Period info + aggregated product rankings with totals

Advanced Features:

• Smart Product Grouping: Groups by referencia when available, otherwise by descripcion
• Data Aggregation: Sums quantities (cantidad_total) and revenue (total_facturado) per product
• Flexible Sorting: Supports sorting by units sold or total revenue (ascending/descending)
• Business Analytics: Handles both catalog products and custom services seamlessly

Testing Coverage:

• 16 New Tests: Comprehensive unit and integration testing
• Test Categories: Success scenarios, error handling, parameter validation, pagination, sorting
• Integration Testing: Real API validation with various date ranges and edge cases
• Total Test Count: Increased from 358 to 374 tests

Key Features:

• Date Range Validation: Robust handling of date periods and edge cases
• Parameter Validation: Limit bounds (1-1000), offset normalization, order validation
• Comprehensive Error Messages: User-friendly Spanish error responses for business scenarios
• Consistent API Pattern: Follows established filtering and pagination patterns
• Business Intelligence: Provides actionable insights for inventory, marketing, and sales analysis

SDK Documentation & Examples:

• Comprehensive Tool Usage Guide: Added detailed examples to docs/TOOL_USAGE_EXAMPLES.md
• TypeScript SDK Examples: Created examples/typescript-sdk/ with production-ready code samples
• Business Scenarios: Inventory management, revenue analysis, seasonal planning, performance monitoring
• Developer Experience: Quick-start examples, advanced patterns, error handling, best practices

Quality Assurance:

• ✅ TypeScript compilation success
• ✅ 100% test success rate (374/374 tests)
• ✅ Integration testing with real FacturaScripts API
• ✅ Comprehensive error scenario coverage
• ✅ Parameter validation and sanitization
• ✅ SDK documentation with business-focused examples

New Implementation: get_clientes_top_facturacion

Implementation Details:

• Purpose: Generate customer billing rankings by total invoiced amount within a specified date range
• Location: src/modules/sales-orders/facturaclientes/tool.ts
• Multi-step Process: Invoice filtering by date range → Client grouping and totals calculation → Client details lookup → Ranking generation
• Key Features:
  • Date range filtering (fecha_desde/fecha_hasta required)
  • Optional payment status filtering (solo_pagadas)
  • Comprehensive pagination (limit: 1-1000, default: 100)
  • Automatic sorting by total_facturado (descending)
  • Robust error handling for edge cases
• Testing: 11 comprehensive tests covering success scenarios, error handling, and parameter validation
• Integration Tests: 6 additional tests with real API validation
• Total New Tests: 17 tests added (increasing total from 374 to 421)
• Status: ✅ Complete and production-ready

Response Structure:

{
  "periodo": { "fecha_desde", "fecha_hasta", "solo_pagadas" },
  "meta": { "total", "limit", "offset", "hasMore" },
  "data": [
    {
      "codcliente": "string",
      "nombre": "string", 
      "cifnif": "string",
      "total_facturado": number,
      "numero_facturas": number
    }
  ]
}

Latest Implementation: get_clientes_perdidos

Implementation Details:

• Purpose: Identify customers who had previous purchase history but haven't bought since a specified date until now
• Location: src/modules/sales-orders/facturaclientes/tool.ts
• Multi-step Process: Historical invoice analysis → Client grouping and statistics calculation → Lost client filtering → Client details lookup → Chronological ranking
• Key Features:
  • Smart Date Handling: Automatic conversion between FacturaScripts DD-MM-YYYY and ISO YYYY-MM-DD formats
  • Historical Analysis: Only considers clients with previous purchase history (excludes never-purchased clients)
  • Comprehensive Data: Includes client contact info and historical statistics (total invoices, revenue, last purchase date)
  • Intelligent Sorting: Orders by fecha_ultima_factura descending (most recent lost clients first)
  • Robust Pagination: Full pagination support (limit: 1-1000, default: 100)
  • Business Intelligence: Provides actionable data for customer retention campaigns
• Testing: 14 comprehensive unit tests + 5 integration tests covering all scenarios
• Date Logic Fix: Corrected DD-MM-YYYY to YYYY-MM-DD conversion for accurate comparisons
• Status: ✅ Complete and production-ready with date format fix

Response Structure:

{
  "fecha_corte": "2025-08-01",
  "meta": { "total": 25, "limit": 100, "offset": 0, "hasMore": false },
  "data": [
    {
      "codcliente": "CLI001",
      "nombre": "Cliente Perdido S.L.",
      "email": "contacto@clienteperdido.com",
      "telefono1": "600123456",
      "fecha_ultima_factura": "15-12-2024",
      "total_facturas_historicas": 8,
      "total_facturado_historico": 15750.50
    }
  ]
}

Usage Examples:

// Basic usage - find clients lost since August 1st, 2025
get_clientes_perdidos({
  fecha_desde: "2025-08-01"
})

// With pagination for large datasets
get_clientes_perdidos({
  fecha_desde: "2024-06-01",
  limit: 50,
  offset: 0
})

// Find clients lost in the last 6 months
get_clientes_perdidos({
  fecha_desde: "2024-08-01",
  limit: 25
})

Business Use Cases:

• Customer Retention Campaigns: Target clients who haven't purchased recently but have historical value
• Sales Recovery: Prioritize follow-up based on total_facturado_historico and fecha_ultima_factura
• Performance Analysis: Identify patterns in customer attrition by analyzing lost client timelines
• Marketing Segmentation: Create targeted campaigns for different customer segments based on purchase history

Date Format Handling: The tool automatically handles FacturaScripts' DD-MM-YYYY date format:

• Invoice date "17-08-2025" with fecha_desde: "2025-08-01" → Client NOT lost (recent purchase)
• Invoice date "10-07-2025" with fecha_desde: "2025-08-01" → Client IS lost (old purchase)
• Sorting works correctly with mixed date formats in the database

Previous Implementation: get_facturas_cliente_por_cifnif

Implementation Details:

• Purpose: Search customer invoices by CIF/NIF tax identification number
• Location: src/modules/sales-orders/facturaclientes/tool.ts
• Two-step Process: Client lookup → Invoice retrieval
• Testing: 11 comprehensive tests for business scenarios
• Status: ✅ Complete and production-ready

Changelog Management

Automated Tools - Complete Setup ✅

• conventional-changelog-cli: Generate changelogs from conventional commits
• auto-changelog: Auto-generate changelogs from git history
• GitHub Actions: Automated release creation on tag pushes
• Keep a Changelog Format: Standardized changelog format compliance
• Semantic Versioning: Automated version management integration

Available Scripts

# Conventional commits changelog (recommended)
npm run changelog

# Generate for unreleased changes only  
npm run changelog:unreleased

# Auto-generate from git history
npm run changelog:auto

# Complete changelog with keepachangelog template
npm run changelog:all

# Version management with changelog
npm run version           # Patch version
npm run version:minor     # Minor version
npm run version:major     # Major version

# Full release process
npm run release           # Patch release
npm run release:minor     # Minor release  
npm run release:major     # Major release

Configuration Files

• .auto-changelog: Complete configuration for automated changelog generation
• docs/CHANGELOG_GUIDE.md: Enhanced guide with latest automation examples
• Conventional commit mapping: Automatic categorization (feat → Added, fix → Fixed, etc.)

Conventional Commits Format

feat: add new feature
feat(openapi): implement product variants management tool
feat(export): add PDF export functionality for customer invoices  
fix: bug fix
fix(client): handle API timeout errors
fix(tests): resolve integration test parameter passing
docs: documentation changes
test: add tests
chore: maintenance tasks

Release Process

1. Use conventional commits during development
2. Run npm run release for automated versioning
3. GitHub Actions creates releases automatically on tag push
4. Changelog automatically updates with proper categorization
5. See docs/CHANGELOG_GUIDE.md for detailed guidelines and examples

Latest Changelog Features ✅

• Keep a Changelog format compliance: Standardized format with proper sections
• Conventional commit support: Automatic categorization and release notes generation
• GitHub integration: Automated release creation with proper linking
• Version management: Semantic versioning with automated changelog updates
• Comprehensive documentation: Detailed guides with practical examples