mendozagit · Oct 23, 2026 · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -1,12 +1,14 @@
 {
   "name": "fiscalapi",
   "description": "Plugins de FiscalAPI para agentes de código.",
-  "owner": { "name": "FiscalAPI" },
+  "owner": {
+    "name": "FiscalAPI"
+  },
   "plugins": [
     {
       "name": "fiscalapi",
       "source": "./",
-      "description": "Skills en español para integrar FiscalAPI (CFDI 4.0) en tu ERP, POS o SaaS."
+      "description": "Skills en español para integrar FiscalAPI (CFDI 4.0) en tu ERP, POS, SaaS o app."
     }
   ]
 }
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,10 +1,20 @@
 {
   "name": "fiscalapi",
-  "version": "0.1.0",
-  "description": "Skills en español para integrar FiscalAPI (CFDI 4.0) en tu ERP, POS o SaaS: primer timbre en pruebas, complementos, ciclo de vida de la factura y diagnóstico de errores del SAT.",
-  "author": { "name": "FiscalAPI" },
+  "version": "0.2.0",
+  "description": "Skills en español para integrar FiscalAPI (CFDI 4.0) en tu ERP, POS, SaaS o app: primer timbre en el ambiente de pruebas, CFDI/Factura con complementos, ciclo de vida del CFDI y diagnóstico de errores de validación, rechazos del PAC y errores del servidor.",
+  "author": {
+    "name": "FiscalAPI"
+  },
   "homepage": "https://docs.fiscalapi.com",
   "repository": "https://github.com/FiscalAPI/fiscalapi-ai",
   "license": "MPL-2.0",
-  "keywords": ["fiscalapi", "cfdi", "sat", "facturacion-electronica", "mexico"]
+  "keywords": [
+    "fiscalapi",
+    "cfdi",
+    "cfdi-4.0",
+    "factura",
+    "sat",
+    "facturacion-electronica",
+    "mexico"
+  ]
 }
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
@@ -1,10 +1,20 @@
 {
   "name": "fiscalapi",
-  "version": "0.1.0",
-  "description": "Skills en español para integrar FiscalAPI (CFDI 4.0) en tu ERP, POS o SaaS: primer timbre en pruebas, complementos, ciclo de vida de la factura y diagnóstico de errores del SAT.",
-  "author": { "name": "FiscalAPI" },
+  "version": "0.2.0",
+  "description": "Skills en español para integrar FiscalAPI (CFDI 4.0) en tu ERP, POS, SaaS o app: primer timbre en el ambiente de pruebas, CFDI/Factura con complementos, ciclo de vida del CFDI y diagnóstico de errores de validación, rechazos del PAC y errores del servidor.",
+  "author": {
+    "name": "FiscalAPI"
+  },
   "homepage": "https://docs.fiscalapi.com",
   "repository": "https://github.com/FiscalAPI/fiscalapi-ai",
   "license": "MPL-2.0",
-  "keywords": ["fiscalapi", "cfdi", "sat", "facturacion-electronica", "mexico"]
+  "keywords": [
+    "fiscalapi",
+    "cfdi",
+    "cfdi-4.0",
+    "factura",
+    "sat",
+    "facturacion-electronica",
+    "mexico"
+  ]
 }
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
@@ -1,8 +1,9 @@
 name: Check
 
-# En cada PR y cada lunes: las docs cambian aunque este repo no, y un enlace roto deja a una skill sin su fuente.
 on:
   pull_request:
+  push:
+    branches: [main]
   schedule:
     - cron: '0 14 * * 1'
   workflow_dispatch:
@@ -11,7 +12,8 @@ permissions:
   contents: read
 
 jobs:
-  check:
+  plugin:
+    name: Plugin (skills, commands and manifests)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -22,12 +24,46 @@ jobs:
         with:
           node-version: 24
 
-      - name: Frontmatter y enlaces de las skills
-        run: node scripts/check-skills.mjs
+      - name: Skill frontmatter and documentation links
+        run: node scripts/check-skills.mts
 
-      - name: Manifiestos de Claude Code, Codex y Copilot
+      - name: Claude Code, Codex and Copilot manifests
         run: npx -y @anthropic-ai/[email protected] plugin validate . --strict
 
-      # Cursor no lee .claude-plugin: su manifiesto es una copia exacta del de Claude Code.
-      - name: Manifiesto de Cursor
+      - name: Cursor manifest matches the Claude Code manifest
         run: cmp .claude-plugin/plugin.json .cursor-plugin/plugin.json
+
+  docs-mcp:
+    name: Docs MCP server
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs-mcp
+    steps:
+      - name: Checkout
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Setup Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: docs-mcp/package-lock.json
+
+      - name: Install
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Generate data from the public sources
+        run: npm run build:data
+
+      - name: Package contents
+        run: npm pack --dry-run
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,57 @@
+# Contribuir
+
+Gracias por mejorar fiscalapi-ai. Este documento explica cómo está organizado el repositorio y cómo validar un cambio antes de abrir un pull request.
+
+## Estructura
+
+| Ruta | Contenido |
+| --- | --- |
+| `skills/` | Una carpeta por skill, con su `SKILL.md` y, si hace falta, `references/`. |
+| `commands/` | Comandos del plugin, uno por archivo. |
+| `.claude-plugin/`, `.cursor-plugin/` | Manifiestos del plugin y del marketplace. El de Cursor es una copia exacta del de Claude Code. |
+| `docs-mcp/` | Servidor MCP `@fiscalapi/docs-mcp`. |
+| `scripts/check-skills.mts` | Validación del frontmatter de las skills y de los enlaces a docs.fiscalapi.com. |
+
+## Requisitos
+
+Node.js 22.18 o posterior. Los scripts están escritos en TypeScript y Node.js los ejecuta sin compilarlos.
+
+## Skills y comandos
+
+- `name` es igual al nombre de la carpeta: minúsculas, dígitos y guiones.
+- `description` va en una sola línea, en tercera persona, y dice qué hace la skill, cuándo usarla y cuándo no.
+- `SKILL.md` tiene menos de 500 líneas.
+- Las skills enlazan la documentación en lugar de copiarla. Usa la URL `.md` de la sección (`https://docs.fiscalapi.com/<página>/<sección>.md`).
+- Las API keys siempre se leen de variables de entorno, y los ejemplos usan el ambiente de pruebas.
+
+Valida los cambios con:
+
+```
+node scripts/check-skills.mts
+```
+
+## Servidor MCP
+
+```
+cd docs-mcp
+npm ci
+npm run typecheck
+npm run build
+npm test
+```
+
+`npm run build:data` genera `data/` a partir de la especificación OpenAPI pública y de docs.fiscalapi.com. Las pruebas no usan la red: trabajan con los archivos de `test/fixtures/`. Para actualizar la copia de la documentación que usan las pruebas:
+
+```
+node scripts/snapshot-docs.ts https://docs.fiscalapi.com test/fixtures/docs-corpus.json.gz
+```
+
+Convenciones del código:
+
+- TypeScript estricto, sin `any`, sin aserciones de tipo y sin comentarios. Si un fragmento necesita explicarse, se reescribe con nombres más claros.
+- El código y los mensajes internos van en inglés. Los títulos, las descripciones y los resultados de las herramientas van en español, porque los lee el modelo.
+- Cada herramienta es una clase que implementa `McpTool` en `src/tools/` y recibe sus dependencias por interfaces.
+
+## Pull requests
+
+El workflow `Check` debe pasar: valida las skills, los manifiestos y el servidor MCP (typecheck, build, pruebas y contenido del paquete).
diff --git a/README.md b/README.md
@@ -1,15 +1,51 @@
 # fiscalapi-ai
 
-Skills en español para integrar [FiscalAPI](https://docs.fiscalapi.com) (CFDI 4.0) en tu ERP, POS o SaaS desde tu agente de código: Claude Code, Codex, Cursor o GitHub Copilot.
+Skills y comandos en español para integrar [FiscalAPI](https://docs.fiscalapi.com) (CFDI 4.0) en tu ERP, POS, SaaS o app desde tu agente de código: Claude Code, Codex, Cursor o GitHub Copilot.
 
-Las skills no copian la documentación: te llevan a la sección exacta de [docs.fiscalapi.com](https://docs.fiscalapi.com) y te ayudan a decidir qué endpoint, complemento o catálogo usar.
+Las skills no copian la documentación. Llevan al agente a la sección exacta de [docs.fiscalapi.com](https://docs.fiscalapi.com) y le ayudan a decidir qué operación, complemento o catálogo SAT usar.
+
+## Qué incluye
+
+### Skills
+
+El agente carga cada skill cuando la tarea lo requiere.
+
+| Skill | Úsala para |
+| --- | --- |
+| `fiscalapi-integracion` | Empezar: ambiente de pruebas, API key y tenant, SDK según el lenguaje y modo por valores o por referencias. |
+| `fiscalapi-ingreso-egreso` | CFDI/Factura de ingreso, CFDI/Factura de egreso (nota de crédito) y CFDI/Factura global. |
+| `fiscalapi-pagos` | CFDI/Factura de pago (complemento de recepción de pagos 2.0) de facturas PPD. |
+| `fiscalapi-nomina` | CFDI/Factura de nómina (complemento de nómina 1.2). |
+| `fiscalapi-carta-porte` | CFDI/Factura de carta porte (complemento Carta Porte 3.1, autotransporte). |
+| `fiscalapi-comercio-exterior` | CFDI/Factura de comercio exterior (complemento Comercio Exterior 2.0). |
+| `fiscalapi-ciclo-de-vida` | Cancelación, estatus ante el SAT, XML, PDF, envío por correo y webhooks. |
+| `fiscalapi-diagnostico` | Interpretar errores de validación, rechazos del PAC y errores del servidor. |
+
+### Comandos
+
+| Comando | Qué hace |
+| --- | --- |
+| `primer-timbre` | Timbra tu primera factura de ingreso en el ambiente de pruebas con el SDK de tu proyecto y devuelve su UUID. |
+| `explicar-error` | Explica un error de la API (un código como `CFDI40147` o la respuesta JSON completa) y propone la corrección. |
+| `revisar-integracion` | Revisa una integración existente y reporta los defectos que causan problemas en producción, con la línea y la corrección de cada uno. |
+
+### Servidor MCP de documentación
+
+[`@fiscalapi/docs-mcp`](docs-mcp/README.md) es opcional y complementa a las skills: le da al agente la especificación pública de la API y una búsqueda en la documentación, sin llamar a la API ni requerir API key. Se instala por separado.
+
+## Requisitos
+
+Para timbrar en el ambiente de pruebas necesitas una cuenta, una API key y el tenant. Sigue [Pasos para comenzar](https://docs.fiscalapi.com/quickstart/pasos-para-comenzar.md).
 
 ## Instalación
 
 ### Claude Code
 
+En una sesión:
+
 ```
-/plugin install fiscalapi --marketplace FiscalAPI/fiscalapi-ai
+/plugin marketplace add FiscalAPI/fiscalapi-ai
+/plugin install fiscalapi@fiscalapi
 ```
 
 O desde la terminal:
@@ -21,21 +57,22 @@ claude plugin install fiscalapi@fiscalapi
 
 ### Codex
 
+Agrega el marketplace y después instala `fiscalapi` desde `/plugins` en una sesión de Codex:
+
 ```
 codex plugin marketplace add FiscalAPI/fiscalapi-ai
-codex plugin add fiscalapi@fiscalapi
 ```
 
-### GitHub Copilot
-
-En Copilot CLI:
+### GitHub Copilot CLI
 
 ```
 copilot plugin marketplace add FiscalAPI/fiscalapi-ai
 copilot plugin install fiscalapi@fiscalapi
 ```
 
-En VS Code, agrega el marketplace a tu configuración:
+### VS Code
+
+Agrega el marketplace en tu `settings.json` (función experimental de VS Code) e instala `fiscalapi` desde la vista de plugins del chat:
 
 ```json
 {
@@ -46,12 +83,21 @@ En VS Code, agrega el marketplace a tu configuración:
 
 ### Cursor
 
-Clona el repo en la carpeta de plugins locales y recarga la ventana (**Developer: Reload Window**):
+Clona el repositorio en la carpeta de plugins locales y recarga la ventana con **Developer: Reload Window**:
 
 ```
 git clone https://github.com/FiscalAPI/fiscalapi-ai ~/.cursor/plugins/local/fiscalapi
 ```
 
+## Seguridad
+
+- Las skills leen la API key y el tenant de variables de entorno (`FISCALAPI_API_URL`, `FISCALAPI_API_KEY`, `FISCALAPI_TENANT`). No los escribas en el código ni en archivos versionados.
+- Trabaja en el ambiente de pruebas (`https://test.fiscalapi.com`). Timbrar en producción es un acto fiscal irreversible.
+
+## Soporte
+
+Consulta la [documentación](https://docs.fiscalapi.com) o abre un [issue](https://github.com/FiscalAPI/fiscalapi-ai/issues).
+
 ## Licencia
 
 [MPL-2.0](LICENSE)
diff --git a/commands/primer-timbre.md b/commands/primer-timbre.md
@@ -3,15 +3,15 @@ description: Timbra tu primera factura de ingreso en el ambiente de pruebas de F
 argument-hint: "[lenguaje, si el proyecto todavía no tiene uno]"
 ---
 
-Timbra una factura de ingreso de prueba en este proyecto siguiendo la skill `fiscalapi-integracion` (lee su sección de SDK y `references/sdks.md` antes de escribir código).
+Timbra una factura de ingreso de prueba en este proyecto siguiendo la skill `fiscalapi-integracion` (antes de escribir código, lee su sección de SDK y su referencia de SDK).
 
 $ARGUMENTS
 
-1. **Llaves.** Lee `FISCALAPI_API_KEY` y `FISCALAPI_TENANT` de las variables de entorno, y `FISCALAPI_API_URL` (si no existe, usa `https://test.fiscalapi.com`). Si falta la llave o el tenant, detente y explica cómo obtenerlas con el paso 1 de la skill. Nunca escribas las llaves en el código ni en un archivo, y nunca uses `https://live.fiscalapi.com`.
-2. **Lenguaje y SDK.** Detecta el lenguaje con la tabla de la skill (o usa el que te indiquen arriba; si el proyecto está vacío y no te indican uno, pregunta cuál usar). Instala el SDK oficial con el comando de `references/sdks.md`.
-3. **Certificados de prueba.** Descarga el zip de [Certificados de prueba](https://docs.fiscalapi.com/testing-data/certificados-de-prueba.md) en una carpeta que no se versione (agrégala al `.gitignore`). Del emisor `FUNK671228PH6`, toma el `.cer` y el `.key` de la subcarpeta `CSD_*` (no los de la FIEL) y conviértelos a base64 al ejecutar; la contraseña es `12345678a`.
-4. **Factura.** Arma una factura de ingreso por valores con el cuerpo de ejemplo de [Crear factura ingreso](https://docs.fiscalapi.com/invoices-by-value/crear-factura-ingreso.md): emisor `FUNK671228PH6` (régimen 621), receptor `EKU9003173C9` (régimen 601, uso G01, CP 42501), un concepto con IVA 16 % que conserve todos los campos del concepto del ejemplo (por valores, `itemSku` es obligatorio), y la fecha actual como texto `yyyy-MM-ddTHH:mm:ss`. Usa los nombres del SDK, no los del README si `references/sdks.md` dice que el README falla.
-5. **Timbra una sola vez.** Si `succeeded` es verdadero, imprime el `id` y el `uuid` de `data`. Si no, interpreta la respuesta con la skill `fiscalapi-diagnostico`, corrige y vuelve a intentar. Ante un 5xx o un timeout, no reintentes: sigue la regla de la skill.
+1. **API key y tenant.** Lee `FISCALAPI_API_KEY` y `FISCALAPI_TENANT` de las variables de entorno, y `FISCALAPI_API_URL` (si no existe, usa `https://test.fiscalapi.com`). Si falta la API key o el tenant, detente y explica cómo obtenerlos con la sección 1 de la skill `fiscalapi-integracion`. Nunca escribas la API key ni el tenant en el código ni en un archivo, y nunca uses `https://live.fiscalapi.com`.
+2. **Lenguaje y SDK.** Detecta el lenguaje con la tabla de la skill (o usa el que te indiquen arriba; si el proyecto está vacío y no te indican uno, pregunta cuál usar). Instala el SDK oficial con el comando de la referencia de SDK de la skill `fiscalapi-integracion`.
+3. **Certificados de prueba.** Descarga el zip de [Certificados de prueba](https://docs.fiscalapi.com/testing-data/certificados-de-prueba.md) en una carpeta que no se versione (agrégala al `.gitignore`). Del emisor `FUNK671228PH6`, toma el Certificado CSD (.cer) y la Llave privada CSD (.key) de la subcarpeta `CSD_*` (no el Certificado FIEL (.cer) ni la Llave privada FIEL (.key)) y conviértelos a base64 al ejecutar; la contraseña es `12345678a`.
+4. **Factura.** Arma una factura de ingreso por valores con el cuerpo de ejemplo de [Crear factura ingreso](https://docs.fiscalapi.com/invoices-by-value/crear-factura-ingreso.md): emisor `FUNK671228PH6` (régimen 621), receptor `EKU9003173C9` (régimen 601, uso G01, CP 42501), un concepto con IVA 16 % que conserve todos los campos del concepto del ejemplo (por valores, `itemSku` es obligatorio), y la fecha actual como texto `yyyy-MM-ddTHH:mm:ss`. Usa los nombres de clases y campos de la referencia de SDK de la skill `fiscalapi-integracion`.
+5. **Timbra y revisa la respuesta.** Si `succeeded` es verdadero, imprime el `id` y el `uuid` de `data`. Si es un 400 con fallas de validación o un rechazo del PAC, interprétalo con la skill `fiscalapi-diagnostico`, corrige el dato y vuelve a timbrar: no consume timbre. Ante un 5xx o un timeout, no reintentes: el CFDI pudo quedar timbrado; sigue las reglas clave de la skill `fiscalapi-integracion`.
 6. **Comprueba.** Consulta la factura por su `id` con el SDK ([Obtener factura por ID](https://docs.fiscalapi.com/invoices-by-value/obtener-factura-por-id.md)) y confirma que trae el mismo `uuid`.
 
 Responde con el `uuid`, el `id`, los archivos que creaste y el comando para volver a correr el programa.
diff --git a/commands/revisar-integracion.md b/commands/revisar-integracion.md
@@ -9,10 +9,10 @@ $ARGUMENTS
 
 Busca en el código (excluye `node_modules`, `bin`, `obj`, `vendor` y dependencias) estos defectos, en este orden:
 
-1. **Llaves en el código o en archivos versionados.** Valores con forma de API key de FiscalAPI (`sk_live_`, `sk_test_` o `sk_development_` seguidos de un GUID con guiones bajos), secretos de webhook (`whsec_`), o una API key o tenant escritos como texto en lugar de leerse del entorno o de un gestor de secretos. Revisa también `.env` versionados y archivos de configuración. Una llave `sk_live_` es crítica: indica rotarla en el dashboard.
+1. **API keys en el código o en archivos versionados.** Valores que empiecen con `sk_test_` o `sk_live_`, secretos de webhook (`whsec_`), o una API key o tenant escritos como texto en lugar de leerse del entorno o de un gestor de secretos. Revisa también `.env` versionados y archivos de configuración. Una API key `sk_live_` es crítica: indica rotarla en el dashboard.
 2. **Peticiones sin `X-TIME-ZONE`.** Llamadas HTTP directas a FiscalAPI que mandan `X-API-KEY` pero no `X-TIME-ZONE`, o un cliente del SDK sin zona horaria cuando el sistema no trabaja en hora de México.
 3. **Reintentos a ciegas tras un 5xx o un timeout al timbrar.** Un ciclo de reintento, una librería de retry o un `catch` que vuelve a llamar `POST /api/v4/invoices` (o `invoices.create`) sin consultar antes si la factura quedó timbrada. Un 5xx o un timeout al timbrar no se reintenta.
-4. **Webhooks sin verificar la firma.** Un endpoint que recibe eventos de FiscalAPI y procesa el cuerpo sin verificar `webhook-signature` con el secreto, o que verifica sobre el JSON ya parseado en lugar del cuerpo crudo.
+4. **Webhooks sin verificar la firma.** Código de la URL del webhook que recibe eventos de FiscalAPI y procesa el cuerpo sin verificar `webhook-signature` con el secreto, o que verifica sobre el JSON ya parseado en lugar del cuerpo crudo.
 
 Además, si los ves, repórtalos: la URL de producción (`live.fiscalapi.com`) en código de pruebas, `succeeded` sin revisar en la respuesta, y una cancelación marcada como definitiva con la sola respuesta del DELETE.
 

diff --git a/docs-mcp/.gitignore b/docs-mcp/.gitignore
@@ -0,0 +1,3 @@
+node_modules/
+dist/
+data/
diff --git a/mcp/LICENSE → docs-mcp/LICENSE b/mcp/LICENSE → docs-mcp/LICENSE