# Financial Credit Committee MCP v4

[![CI](https://github.com/sebaml-rgb/factoring_MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/sebaml-rgb/factoring_MCP/actions/workflows/ci.yml)

Repositorio: [github.com/sebaml-rgb/factoring_MCP](https://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

```bash
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):**

```bash
brew install poppler tesseract
```

**Ubuntu/Debian:**

```bash
sudo apt-get install poppler-utils tesseract-ocr
```

### 2. Probar que funciona

```bash
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):

```json
{
  "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](https://designrevision.com/blog/add-mcp-server-to-chatgpt) activado en Settings → Apps → Advanced.

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

```bash
brew install cloudflared
```

**Paso 2 — levantar MCP + túnel:**

```bash
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](https://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:**

```bash
./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:

| Tool | Para qué sirve |
|---|---|
| `analyze_factoring_case_tool` | Flujo completo: PDF → extracción → ranking → reporte |
| `rank_debtors_tool` | Ordenamiento dual por exposición y score de riesgo |
| `generate_factoring_credit_report_tool` | Informe JSON con veredicto de factoring |
| `generate_factoring_credit_pdf_tool` | PDF de presentación para comité |

**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

| Veredicto | Significado |
|---|---|
| `APROBAR_FACTORING` | Caso sólido con validación contable aceptable |
| `APROBAR_CON_CONDICIONES` | Operar con condiciones (concentración, mora, datos parciales) |
| `REQUIERE_REVISION` | Revisión humana obligatoria antes de operar |
| `NO_OPERAR` | Señales críticas; no usar sin revisión profunda |

### 6. Colaboración en GitHub

```bash
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

```bash
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:

```bash
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/`.