Skills MX

Plugins de Claude Code, skills y MCP servers para operar una PyME o profesión en México: CFDI 4.0, SAT, nómina e IMSS, pagos, marketplaces, trámites estatales y municipales, y 40 verticales por industria.

Contenido

1. Estado de los MCPs
2. Inicio rápido
3. Cómo está organizado
4. Plugins verticales
5. MCP servers
6. Configuración y credenciales
7. Solver de CAPTCHA (opt-in)
8. Calidad y pruebas
9. Seguridad y cumplimiento
10. Pendientes
11. Documentación
12. Licencia

Estado de los MCPs

Cada MCP declara en su README una sección "Estado real" con lo que se validó en vivo, cuándo y contra qué URL. La tabla de abajo se genera de esas secciones; no se edita a mano.

Estado a 2026-10-14 (oleada 1: mock → real)

Generado por scripts/generar-estado-mcps.py desde la sección "Estado real" de cada README. 83 MCPs, 417 tools.

Qué significa cada categoría:

El detalle por MCP (estado, nota y tools) está en mcp-servers/CATALOGO.md.

Regla común: ningún MCP devuelve datos simulados haciéndolos pasar por reales. Sin credenciales responde datos de ejemplo marcados simulated: true; con credenciales, cualquier error del proveedor se propaga como error tipado (AuthError, UpstreamError, NotFoundError…). PLUGINS_MX_MOCK=1 fuerza el modo de ejemplo.

Inicio rápido

Instalar plugins en Claude Code

/plugin marketplace add elimorals/Skills_MX
/plugin install core-mexico --marketplace elimorals/Skills_MX      # base de todos los verticales
/plugin install freelancers-mx --marketplace elimorals/Skills_MX   # o cualquier vertical de la lista

core-mexico (CFDI, IVA y retenciones, RFC, MXN, LFPDPPP, WhatsApp) es la dependencia de todos los verticales. Los MCPs que trae cada plugin se descargan solos la primera vez con uv, que es el único requisito además de Claude Code.

Usar un MCP suelto

Cada MCP trae un example.mcp.json listo para copiar; no depende de dónde esté el repo. Por ejemplo, para el portal del SAT:

{
  "mcpServers": {
    "sat_portal": {
      "command": "uv",
      "args": ["run", "--no-project", "--quiet", "--with",
               "plugins-mx-mcp-servers[sat-ws,sat-portal] @ git+https://github.com/elimorals/Skills_MX@main#subdirectory=mcp-servers",
               "python", "-m", "mp_sat_portal.server"],
      "env": {
        "SAT_RFC": "${SAT_RFC:-}",
        "SAT_EFIRMA_CERT": "${SAT_EFIRMA_CERT:-}",
        "SAT_EFIRMA_KEY": "${SAT_EFIRMA_KEY:-}",
        "SAT_EFIRMA_PASSWORD": "${SAT_EFIRMA_PASSWORD:-}"
      }
    }
  }
}

Desarrollo

git clone https://github.com/elimorals/Skills_MX && cd Skills_MX/mcp-servers
uv venv .venv --python 3.12
uv pip install -e ".[dev]"            # agrega extras según lo que toques (ver abajo)
.venv/bin/pytest -q                   # 1,900 tests, sin red

Cómo está organizado

Skills_MX/
├── .claude-plugin/           marketplace.json con los 40 plugins (scripts/generar-marketplace.py)
├── _shared/                  6 skills base (fuente de verdad), se copian a cada plugin
├── core-mexico/              Plugin base: CFDI, IVA, RFC, MXN, LFPDPPP, WhatsApp + 8 workflows
├── <vertical>-mx/            39 plugins por industria
│   ├── .claude-plugin/       plugin.json
│   ├── skills/               SKILL.md + references/
│   ├── commands/             comandos /<plugin>:<comando>
│   ├── agents/               agentes y workflows en markdown
│   ├── workflows/            *.workflow.js ejecutables
│   └── .mcp.json             MCPs que usa el vertical
├── mcp-servers/              83 MCPs (mp_*) + shared/ (cache, bitácora, errores, handoff, solver)
├── webhooks/                 Receptor FastAPI (HMAC, Bearer, allowlist, idempotencia, audit JSONL)
├── evals/                    Triggering por skill, golden deterministas y promptfoo
├── tests/fixtures/           Casos de regresión por skill
├── schemas/                  JSON Schemas de salida
├── scripts/                  Sync de _shared, lint, generador de estado, crons, hooks
├── website/                  Sitio público (Vercel), generado en parte por scripts/
└── docs/                     Arquitectura, guías, integraciones, ADRs, historial

Cómo se conectan las piezas: una skill sabe qué hacer (reglas fiscales, plantillas, flujos). Un MCP hace la consulta real (SAT, Banxico, municipios, pasarelas). Un workflow orquesta varias skills y MCPs para un proceso completo (p. ej. emitir CFDI tras un pago). Los hooks validan antes de acciones sensibles, como timbrar o enviar WhatsApp masivo.

Plugins verticales

Workflows ejecutables

MCP servers

Están en mcp-servers/mp_*. Por fuente:

Utilidades compartidas en mcp-servers/shared/: portal_handoff.py (entrega a humano con formato único), captcha_solver.py, errors.py (errores tipados), bitacora.py (JSONL con hash de datos sensibles), cache.py, mock.py.

Configuración y credenciales

Las credenciales van en variables de entorno, nunca en el repo. .env.example lista todas.

El .gitignore bloquea .env*, *.cer, *.key, *.pem, *.p12, *.pfx, *password*.txt y *contraseña*.

Solver de CAPTCHA (opt-in)

mcp-servers/shared/captcha_solver.py resuelve CAPTCHA con 2captcha. Si falla un captcha de imagen y hay ANTHROPIC_API_KEY, usa visión como respaldo. Está apagado por defecto: sin la configuración, cada portal devuelve la entrega a humano.

export PLUGINS_MX_CAPTCHA_SOLVER=2captcha
export TWOCAPTCHA_API_KEY=...          # tu llave

• No evade anti-bots de red. CURP (Akamai), INE (Cloudflare) y Mérida (Radware) bloquean antes del CAPTCHA. Ahí el tool detecta el bloqueo y entrega la consulta a humano sin gastar CAPTCHA.
• Excluidos por diseño: citas_monitor (apartar citas automáticamente le quita lugar a otras personas) y REPEP (anti-bot deliberado).
• Sin validar en vivo todavía: los portales con solver necesitan una llave para la primera prueba real.

Calidad y pruebas

cd mcp-servers && .venv/bin/pytest -q                       # unitarios, sin red
PLUGINS_MX_LIVE=1 .venv/bin/pytest -q -m live <ruta>       # contra el portal real
python3 scripts/eval-golden.py                              # cálculos fiscales deterministas
bash scripts/lint-skills.sh                                 # frontmatter y reglas de SKILL.md
python3 scripts/generar-estado-mcps.py --check              # el sitio y este README están al día
python3 scripts/generar-marketplace.py --check              # marketplace al día con los plugin.json
python3 scripts/mcp-config-portable.py --check              # configs MCP sin rutas locales ni mock forzado
claude plugin validate .                                    # valida marketplace y plugins
npx [email protected] eval -c evals/promptfoo/promptfooconfig.yaml   # evals LLM (requiere API key)

En cada PR, el CI corre los tests de los MCPs, las evals golden, el lint de skills, la verificación de copias de _shared, SkillSpector (análisis estático), la validación de JSON y el escaneo de secretos.

Los tests que necesitan e.firma generan una autofirmada al vuelo. Las comparaciones byte a byte contra phpcfdi usan la e.firma de prueba del SAT desde SAT_EFIRMA_PRUEBA_DIR, que vive fuera del repo.

Seguridad y cumplimiento

• Validación experta antes de producción. Las skills fiscales las debe revisar un contador; los contratos, un abogado; las plantillas de WhatsApp, Meta.
• Tasas estatales. Varias tasas (ISN, ISH, tenencia) vienen de fuentes secundarias de 2026 y están marcadas con su nivel de confianza en cada README.
• Datos personales. La bitácora guarda solo hashes de RFC, CURP y correo. CURP e INE no cachean resultados e incluyen un aviso LFPDPPP.
• Buró de crédito. mp_buro_credito_personal exige el token de autorización del titular: consultar sin ella es delito.
• Escrituras ante el SAT (actualizar obligaciones, citas): no se automatizan.
• Repo público. No se commitean credenciales ni capturas de navegador. Detalles en docs/architecture/seguridad.md.

Pendientes

Documentación

Licencia

Apache-2.0 · Elías Rashid Morales Mendoza · github.com/elimorals/Skills_MX