Financial Credit Committee MCP v4

Repositorio: github.com/sebaml-rgb/factoring_MCP

This package adds an auditable PDF-to-JSON extraction layer for credit committee financial analysis, with a factoring-oriented debtor ranking module.

Guía rápida para el equipo

1. Clonar e instalar

git clone https://github.com/sebaml-rgb/factoring_MCP.git
cd factoring_MCP

python3.11 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install --upgrade pip
pip install pdfplumber reportlab "mcp>=1.0,<2" pytest

macOS — OCR (recomendado para PDFs escaneados):

brew install poppler tesseract

Ubuntu/Debian:

sudo apt-get install poppler-utils tesseract-ocr

2. Probar que funciona

PYTHONPATH=. pytest tests/test_factoring_ranking.py -q

PYTHONPATH=. python -m financial_credit_mcp.cli fixtures/source_pdfs/flesan.pdf \
  --out /tmp/flesan_extraction.json \
  --factoring-out /tmp/flesan_factoring_report.json \
  --factoring-pdf-out /tmp/flesan_factoring_report.pdf

3. Conectar con Claude Desktop (MCP)

Edita el archivo de configuración de Claude:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Agrega (ajusta la ruta donde clonaste el repo):

{
  "mcpServers": {
    "financial-credit-committee-v4": {
      "command": "/RUTA/AL/REPO/factoring_MCP/.venv/bin/python",
      "args": ["-m", "financial_credit_mcp.server"],
      "cwd": "/RUTA/AL/REPO/factoring_MCP",
      "env": {
        "PYTHONPATH": "/RUTA/AL/REPO/factoring_MCP"
      }
    }
  }
}

Reinicia Claude Desktop por completo (Cmd+Q / cerrar app).

Importante: el MCP local solo funciona en Claude Desktop, no en claude.ai en el navegador. Si usas la web, prueba ChatGPT (sección siguiente) o sube el PDF con upload_pdf_* / pdf_base64 — nunca uses pdf_path desde un cliente remoto.

Si “no funciona” en Claude Desktop pero el conector aparece:

1. Revisa logs: ~/Library/Logs/Claude/mcp-server-financial-credit-committee-v4.log

2. Para PDFs adjuntos en chat, usa subida por chunks (upload_pdf_start_tool → chunks → finish → analyze_factoring_case_tool con file_id)

3. Instala OCR: brew install poppler tesseract

3b. Conectar con ChatGPT (Developer Mode)

ChatGPT no puede lanzar un MCP local por stdio. Necesitas exponer el servidor por HTTPS con un túnel.

Requisitos: plan ChatGPT Plus/Pro/Business + Developer Mode activado en Settings → Apps → Advanced.

Paso 1 — instalar túnel (una vez):

brew install cloudflared

Paso 2 — levantar MCP + túnel:

cd factoring_MCP
chmod +x scripts/*.sh
./scripts/start_for_chatgpt.sh

Copia la URL https://....trycloudflare.com que imprime cloudflared.

Paso 3 — crear conector en ChatGPT:

1. chatgpt.com → Settings → Connectors

2. Advanced → activar Developer Mode

3. Create connector:

   • Name: Factoring MCP

   • MCP Server URL: https://TU-TUNEL.trycloudflare.com/mcp

   • Authentication: None

Paso 4 — usar en un chat: habilita el conector y pide analizar un PDF. Para archivos grandes usa las tools upload_pdf_start_tool / upload_pdf_chunk_tool / upload_pdf_finish_tool, luego analyze_factoring_case_tool con el file_id.

Solo HTTP (sin túnel), para probar localmente:

./scripts/run_mcp_http.sh
# endpoint: http://127.0.0.1:8000/mcp

4. Uso desde Claude

Ejemplos de prompts:

• Analiza el caso de factoring del PDF /ruta/completa/informe.pdf

• Extrae los estados financieros y ordéname los deudores por exposición y riesgo

• Genera el reporte de factoring en PDF para este informe de comité

Herramientas clave del MCP:

Clientes MCP remotos (sin filesystem compartido): envía el PDF como pdf_base64 (y opcionalmente filename) en lugar de pdf_path. Las tools de PDF devuelven siempre pdf_base64 en la respuesta, con output_path opcional solo para uso local.

PDFs grandes (recomendado para informes reales): usa la subida por chunks:

1. upload_pdf_start_tool → obtienes file_id

2. upload_pdf_chunk_tool → envía trozos de ~200 KB en base64, en orden

3. upload_pdf_finish_tool → valida el PDF y deja listo el file_id

4. analyze_factoring_case_tool o extract_financial_statements_tool con file_id

Tamaño máximo por upload: 64 MB. Variable opcional FCC_MCP_UPLOAD_DIR para persistir uploads en despliegues con volumen dedicado.

5. Veredictos de factoring

6. Colaboración en GitHub

git pull origin main          # traer cambios
git checkout -b mi-feature    # nueva rama
# ... editar ...
git add -A && git commit -m "Descripcion del cambio"
git push -u origin mi-feature # abrir Pull Request en GitHub

El workflow de CI corre automáticamente en cada push y PR a main.

What v4 Includes

• Automatic PDF page classification for Balance, Estado de Resultados, Fuentes y Usos / Flujo de Caja, resumen financiero, credit request, and debtor/client tables.

• Normalized JSON schema with FY/YTD/LTM-aware period metadata.

• Field-level evidence map: field, value, page, extraction method, and source text.

• Ownership map from antecedent shareholder tables, with owners, percentages, direct/indirect debt, related entities, and source traceability.

• Conservative missing-data behavior: unknown values stay null.

• Deterministic validation before analysis:

  • accounting equation;

  • required field coverage;

  • FY/YTD comparability warnings.

• Ratio engine and integrated three-statement analysis.

• Main debtor/client extraction with deduplication and OCR noise filtering.

• Dual debtor ranking for factoring:

  • exposure ranking by accounts receivable / sales;

  • composite risk score (exposure + payment behavior + data quality).

• Factoring credit report and PDF with portfolio concentration metrics.

• Optional MCP server wrapper.

Local Usage

python -m financial_credit_mcp.cli fixtures/source_pdfs/flesan.pdf \
  --out examples/flesan_extraction.json \
  --report-out examples/flesan_report.json \
  --pdf-out examples/flesan_committee_report.pdf \
  --factoring-out examples/flesan_factoring_report.json \
  --factoring-pdf-out examples/flesan_factoring_report.pdf

OCR requires Poppler (pdftoppm) and Tesseract. If they are unavailable, extraction still runs using embedded PDF text and marks scanned pages as incomplete.

Factoring Flow

1. Extract the PDF into normalized JSON.

2. Rank debtors by exposure and by composite risk score.

3. Generate a factoring verdict:

   • APROBAR_FACTORING

   • APROBAR_CON_CONDICIONES

   • REQUIERE_REVISION

   • NO_OPERAR

4. Export JSON and/or a factoring PDF with ranked debtor tables and concentration metrics.

MCP Usage

Install the optional MCP dependency:

pip install pdfplumber reportlab "mcp>=1.0,<2"
PYTHONPATH=. python -m financial_credit_mcp.server

The server exposes:

• extract_financial_statements_tool

• validate_extracted_financials_tool

• validate_period_comparability_tool

• calculate_financial_ratios_tool

• analyze_three_financial_statements_tool

• get_main_debtors_tool

• get_ownership_map_tool

• generate_credit_committee_report_tool

• generate_credit_committee_pdf_tool

• rank_debtors_tool

• generate_factoring_credit_report_tool

• analyze_factoring_case_tool

• generate_factoring_credit_pdf_tool

• upload_pdf_start_tool

• upload_pdf_chunk_tool

• upload_pdf_finish_tool

PDF Reports

The committee PDF is designed as a compact presentation for credit committees.

The factoring PDF adds:

• factoring verdict on the cover page;

• portfolio concentration metrics (top 1/3/5, HHI);

• ranked debtor tables by exposure and by risk score;

• factoring-specific follow-up questions.

Test Fixtures

The ZIP includes the two PDFs supplied for this prototype under fixtures/source_pdfs/ plus derived JSON outputs under examples/.