# DescargarMisFacturas — Servidor MCP Oficial (SAT CFDI 4.0)

> Conecta Claude, ChatGPT, Cursor, VS Code, Windsurf o Claude Code directamente a la bóveda fiscal SAT de tu empresa en México mediante Model Context Protocol (MCP) de solo lectura.

## Resumen y URLs Canónicas

- Sitio oficial: https://descargarmisfacturas.com
- Guía humana y para agentes: https://descargarmisfacturas.com/agentes
- Especificación Markdown (`llms.txt`): https://descargarmisfacturas.com/llms.txt
- Endpoint MCP (Streamable HTTP): https://descargarmisfacturas.com/mcp
- Seguridad y arquitectura: https://descargarmisfacturas.com/seguridad
- Registro gratuito (diagnóstico 90 días): https://descargarmisfacturas.com/registro
- Configuración de tokens en el panel: https://descargarmisfacturas.com/app/configuracion?tab=mcp

## Especificación Técnica del Servidor MCP

- Nombre del servidor: `DescargarMisFacturas SAT MCP`
- Versión: `1.0.0`
- Transporte: `Streamable HTTP` (`https://descargarmisfacturas.com/mcp`)
- Modelo de permisos: 100% solo lectura (`readOnlyHint=true`, `destructiveHint=false`, `idempotentHint=true`, `openWorldHint=false`)
- Disponibilidad por plan: Activo en **todos los planes**, incluido **Plan Gratuito** (respetando la ventana de comprobantes desbloqueados del plan activo) y sin restricciones en **PyME**, **Negocio** y **Corporativo**.

## Autenticación (2 Opciones Oficiales)

### Opción 1: OAuth 2.1 con PKCE (Recomendado para usuarios no técnicos en Claude Web/Desktop y ChatGPT)

- Protected Resource Metadata: `https://descargarmisfacturas.com/.well-known/oauth-protected-resource`
- Authorization Server Metadata: `https://descargarmisfacturas.com/.well-known/oauth-authorization-server`
- Dynamic Client Registration: `https://descargarmisfacturas.com/oauth/mcp/register`
- Authorization Endpoint: `https://descargarmisfacturas.com/oauth/mcp/authorize`
- Token Endpoint: `https://descargarmisfacturas.com/oauth/mcp/token`
- Pasos para el usuario:
  1. Agrega `https://descargarmisfacturas.com/mcp` como conector personalizado (Custom Connector) en Claude o ChatGPT.
  2. Inicia sesión con tu cuenta en `descargarmisfacturas.com` y autoriza el acceso de solo lectura.

### Opción 2: Token Bearer Personal (Recomendado para Claude Code, Cursor, VS Code, Windsurf y CLI)

- Header HTTP requerido: `Authorization: Bearer <TOKEN_MCP>`
- Control de acceso empresarial: Por seguridad, **solo el Propietario (Owner)** de la organización puede generar y revocar tokens MCP en `Panel -> Configuración -> Asistente AI (MCP)` (`https://descargarmisfacturas.com/app/configuracion?tab=mcp`).

## Snippets de Configuración Listos para Copiar

### Claude Code (CLI)

```bash
claude mcp add --transport http descargarmisfacturas https://descargarmisfacturas.com/mcp \
  --header "Authorization: Bearer TU_TOKEN_MCP"
```

### Cursor / VS Code / Windsurf (`mcp.json`)

```json
{
  "mcpServers": {
    "descargarmisfacturas": {
      "type": "http",
      "url": "https://descargarmisfacturas.com/mcp",
      "headers": {
        "Authorization": "Bearer TU_TOKEN_MCP"
      }
    }
  }
}
```

### Clientes sin terminal (Claude Web, Claude Desktop, ChatGPT)

- URL del servidor remoto: `https://descargarmisfacturas.com/mcp`
- Método de autenticación: OAuth 2.1 (el asistente abrirá la ventana de autorización de `descargarmisfacturas.com` automáticamente).

## Catálogo de Herramientas MCP (8 Tools de Solo Lectura)

1. `list_companies`
   - Descripción: Lista las razones sociales (RFCs) de tu organización activa, régimen fiscal, estado de e.firma (FIEL) y CSD, y última sincronización con el SAT.
   - Parámetros: ninguno (`{}`).

2. `search_cfdis`
   - Descripción: Busca y filtra CFDIs 4.0/3.3 emitidos o recibidos con paginación y sumatorias. Respeta los límites del plan Gratuito si aplica.
   - Parámetros opcionales:
     - `company_rfc` (string): RFC de la razón social; si se omite consulta todas tus empresas.
     - `direction` (`issued` | `received`): Emitidos o recibidos.
     - `tipo_comprobante` (`I` | `E` | `P` | `N` | `T`): Ingreso, Egreso, Pago/REP, Nómina, Traslado.
     - `metodo_pago` (`PUE` | `PPD`): Método de pago SAT.
     - `sat_status` (`Vigente` | `Cancelado`): Estatus ante el SAT.
     - `deductibility_status` (`ok` | `warning` | `risk`): Estado de auditoría de deducibilidad.
     - `efos_only` (boolean): `true` para filtrar alertas Art. 69-B (EFOS).
     - `counterparty_rfc` (string): RFC exacto o parcial de emisor/receptor.
     - `search` (string): Búsqueda libre por UUID, folio, RFC o razón social.
     - `date_from` (string `YYYY-MM-DD`) y `date_to` (string `YYYY-MM-DD`).
     - `min_total` y `max_total` (number): Rango de importe total.
     - `page` (integer >= 1, default `1`) y `per_page` (integer 1..50, default `20`).

3. `get_cfdi_detail`
   - Descripción: Devuelve el desglose completo de un CFDI por UUID (emisor, receptor, impuestos, hasta 50 conceptos del XML, CFDIs relacionados, seguimiento PPD y REPs aplicados).
   - Parámetros:
     - `uuid` (string, requerido): Folio fiscal UUID del CFDI.
     - `company_rfc` (string, opcional).

4. `get_accounts_receivable_ppd`
   - Descripción: Consulta cuentas por cobrar PPD emitidas, antigüedad de saldos (0-30, 31-60, 61-90 y >90 días), Complementos de Pago (REP) pendientes o vencidos al día 5 del mes siguiente y discrepancias.
   - Parámetros opcionales:
     - `company_rfc` (string)
     - `filter` (`all` | `pending_collection` | `collected_pending_rep` | `overdue_rep` | `discrepancy` | `reconciled`, default `all`)
     - `client_rfc` (string)
     - `page` (integer >= 1, default `1`), `per_page` (integer 1..50, default `25`)

5. `get_accounts_payable_ppd`
   - Descripción: Consulta cuentas por pagar PPD de proveedores, REPs pendientes por recibir o vencidos y discrepancias.
   - Parámetros opcionales:
     - `company_rfc` (string)
     - `filter` (`all` | `unpaid` | `awaiting_rep` | `overdue_rep` | `discrepancy` | `reconciled`, default `all`)
     - `supplier_rfc` (string)
     - `page` (integer >= 1, default `1`), `per_page` (integer 1..50, default `25`)

6. `get_monthly_tax_closing`
   - Descripción: Calcula el pre-cierre fiscal mensual bajo flujo de efectivo: IVA trasladado cobrado vs IVA acreditable pagado, retenciones IVA/ISR, alertas de CFDIs PUE con forma de pago `99` y desglose de proveedores DIOT.
   - Parámetros:
     - `year` (integer `2014..2035`, requerido)
     - `month` (integer `1..12`, requerido)
     - `company_rfc` (string, requerido si la organización tiene más de una razón social).

7. `get_compliance_and_efos_audit`
   - Descripción: Audita riesgos fiscales SAT: contrapartes en listas negras EFOS Art. 69-B, observaciones de deducibilidad, PUE con forma `99`, cancelados recientes, XMLs faltantes vs metadata SAT y vigencia FIEL/CSD.
   - Parámetros opcionales:
     - `company_rfc` (string)
     - `year` (integer `2014..2035`)
     - `limit` (integer `1..50`, default `20`)

8. `get_payroll_and_retenciones_summary`
   - Descripción: Resumen de auditoría de Nómina CFDI tipo N (percepciones gravadas/exentas, ISR retenido, IMSS, subsidio) y Constancias de Retenciones. Enmascara automáticamente CURP y NSS.
   - Parámetros:
     - `year` (integer `2014..2035`, requerido)
     - `month` (integer `1..12`, opcional; si se omite consolida el ejercicio completo)
     - `company_rfc` (string, requerido si la organización tiene más de una razón social).

## Recursos MCP (3 Resources)

- `organization_overview` (`todosat://organization/overview`, `application/json`): Panorama de la organización activa, plan, uso mensual y RFCs configurados.
- `company_fiscal_snapshot` (`todosat://companies/{rfc}/fiscal-snapshot`): Resumen fiscal puntual de un RFC específico.
- `sat_fiscal_rules_glossary` (`todosat://glossary/sat-cfdi-rules`, `text/markdown`): Reglas SAT CFDI 4.0 de flujo de efectivo IVA/DIOT, PUE vs PPD, regla del día 5 para REP (RMF 2.7.1.32) y Art. 69-B EFOS.

## Prompts Preconstruidos (3 Prompts)

- `diagnosticar-cierre-mensual` (`year` req, `month` req, `company_rfc` opt): Flujo completo para revisar IVA/ISR en flujo de efectivo, DIOT y alertas PUE+99.
- `auditar-riesgos-fiscales` (`company_rfc` opt, `year` opt): Auditoría preventiva EFOS Art. 69-B, deducibilidad, metadata SAT y certificados FIEL/CSD.
- `estado-cartera-y-reps` (`company_rfc` opt): Revisión de cuentas por cobrar/pagar PPD y Complementos de Pago pendientes o vencidos.

## Flujo Recomendado para un Agente Autónomo

1. Ejecuta `list_companies` o lee `todosat://organization/overview` para conocer los RFCs disponibles y el plan activo.
2. Si necesitas reglas de negocio SAT locales en México, lee `todosat://glossary/sat-cfdi-rules`.
3. Invoca la herramienta específica (`get_monthly_tax_closing`, `get_accounts_receivable_ppd`, `get_accounts_payable_ppd`, `get_compliance_and_efos_audit`, `get_payroll_and_retenciones_summary` o `search_cfdis`) y verifica si `paywall` indica límites del Plan Gratuito.
4. No puedes ni debes modificar CFDIs, timbrar o acceder a llaves privadas FIEL/CSD (`.cer` / `.key`): el servidor es estrictamente de solo lectura, registra bitácora por llamada y protege datos personales sensibles (CURP/NSS enmascarados).