Agente Finnegans

Asistente unificado para que líderes consulten y modifiquen datos en Finnegans desde una IA (Claude Desktop), en lenguaje natural, con validación obligatoria antes de cualquier escritura.

Combina en un solo MCP:

• Descubrimiento de APIs (catálogo oficial Finnegans)

• Lectura (GET a cualquier endpoint)

• Escritura con validación (POST/PUT/DELETE solo tras confirmación del usuario)

Flujo para el líder

Líder: "¿Qué órdenes de compra pendientes tiene el proveedor Acme?"

IA:    [buscar_api → ver_api → consultar_finnegans]
       "El proveedor Acme tiene 3 órdenes pendientes: ..."

Líder: "Creá una OC al proveedor Beta por 50 unidades del producto X"

IA:    [buscar_api → ver_api → preparar_cambio]
       "Voy a crear esta OC: ... ¿Confirmás? (sí / no)"

Líder: "Sí, confirmá"

IA:    [ejecutar_cambio]
       "Listo. OC creada."

Related MCP server: sqlserver-mcp-colossal

Guía de instalación IT (paso a paso)

Esta sección está pensada para que alguien de IT configure una PC de líder sin conocimientos de programación avanzados. Seguí los pasos en orden. No saltees verificaciones: cada paso tiene un comando para confirmar que quedó bien.

Resumen de qué se instala

El líder no instala Python, no edita .env, no toca el MCP de docs de Cursor.

Paso 0 — Checklist previo

Antes de empezar, confirmá que tenés:

• Acceso administrativo a la PC del líder (Windows 10/11)

• Credenciales API de ejecución (client_id + client_secret)

  Finnegans → Configuración → General → Seguridad → Usuarios → [usuario API] → **Keys API**

• Credenciales del catálogo de APIs (x-client-id + x-secret-key)

  Las mismas que usa el MCP `finnegans-api-docs` en Cursor (archivo `mcp.json`)

• Instalador de Python 3.10+ (marcar "Add python.exe to PATH")

• Instalador de Claude Desktop

• Instalador de Git para Windows (dejá las opciones por defecto)

• Clave de lectura de la documentación (FINNEGANS_SWAGGER_KEY)

  Sin esta variable, buscar_api / ver_api / preparar_cambio no funcionan.

Paso 1 — Verificar Python

Abrí PowerShell (no hace falta admin) y ejecutá:

python --version

Resultado esperado: Python 3.10.x o superior (3.11, 3.12, 3.14, etc.).

Si dice "python no se reconoce":

1. Reinstalá Python marcando "Add python.exe to PATH".

2. Cerrá y volvé a abrir PowerShell.

3. Si sigue fallando, probá:

py --version

Anotá la ruta exacta del ejecutable (la vas a necesitar en el Paso 6):

(Get-Command python).Source

Ejemplo de salida: C:\Users\Juan\AppData\Local\Python\pythoncore-3.14-64\python.exe

Paso 2 — Clonar el proyecto en la PC

Clonalo con Git. No lo copies a mano ni lo bajes como ZIP: un clon deja la carpeta preparada para actualizarse después con un solo paso (scripts\actualizar.bat), sin volver a pasar por la PC del líder.

Recomendado: C:\FinnegansAgent (sin espacios en la ruta).

git clone https://github.com/JPSformas/finnegans-connector.git C:\FinnegansAgent
Set-Location C:\FinnegansAgent
Get-ChildItem

Resultado esperado: debés ver server.py, finnegans\, requirements.txt, .env.example, verify_setup.py, scripts\, etc.

Test-Path "C:\FinnegansAgent\server.py"
Test-Path "C:\FinnegansAgent\.git"

Ambos deben devolver True. El segundo es el que habilita la actualización en un paso.

Instalaciones viejas. Las hechas con el instructivo anterior (copiar un ZIP descomprimido) no tienen carpeta .git. Siguen funcionando, y scripts\actualizar.bat las actualiza igual bajando el ZIP del repo. No hace falta reinstalarlas.

Paso 3 — Crear y completar el archivo .env

El .env guarda las credenciales. Nunca lo compartas por mail, chat ni git.

Set-Location C:\FinnegansAgent
Copy-Item .env.example .env
notepad .env

Completá las 6 variables (sin comillas, sin espacios alrededor del =):

FINNEGANS_BASE_URL=https://api.finneg.com
FINNEGANS_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
FINNEGANS_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
FINNEGANS_WORKSPACE=SOUTEX

FINNEGANS_DOCS_MCP_URL=https://services.finneg.com/api/1/finnegans-developer-mcp/finnegans-api-docs/mcp
FINNEGANS_DOCS_CLIENT_ID=xxxxxxxx...
FINNEGANS_DOCS_SECRET_KEY=xxxxxxxx...

Errores comunes:

• Dejar valores tu_client_id / tu_docs_client_id → el script de verificación falla a propósito.

• Mezclar credenciales: las de ejecución y las de docs son distintas.

• Agregar comillas: FINNEGANS_CLIENT_ID="abc" → incorrecto. Debe ser FINNEGANS_CLIENT_ID=abc.

Verificá que .env no se suba a git (ya está en .gitignore):

git check-ignore .env

Debe imprimir .env.

Paso 4 — Instalar dependencias Python

Set-Location C:\FinnegansAgent
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Resultado esperado: instalación de mcp sin errores.

Verificá:

python -c "import mcp; print('mcp OK')"

Debe imprimir mcp OK.

Paso 5 — Verificación automática (obligatorio)

Este script prueba todo antes de configurar Claude:

Set-Location C:\FinnegansAgent
python verify_setup.py

Resultado esperado:

[OK] Python 3.x.x
[OK] FINNEGANS_CLIENT_ID configurado
[OK] Token obtenido
[OK] Búsqueda de prueba OK
[OK] Tools registradas: verificar_conexion, buscar_api, ...
RESULTADO: TODO OK (6/6 checks automáticos)

Si hay [ERROR], no continúes. Corregí el punto indicado y volvé a ejecutar:

python verify_setup.py

Al final del script verás el bloque JSON exacto para Claude Desktop con las rutas de esta PC.

Paso 6 — Configurar Claude Desktop

Nota sobre la ruta del config en Windows: Claude Desktop instalado desde Microsoft Store, WinGet o el instalador actual de claude.ai usa el formato MSIX. En ese caso el archivo real no está en %APPDATA%\Claude\, sino en una carpeta virtualizada bajo Packages\Claude_...\LocalCache\Roaming\Claude\. El botón Edit Config de Claude a veces abre el archivo equivocado; usá el script de abajo para abrir el que la app realmente lee.

6.1 Cerrar Claude Desktop por completo

Cerrá la app (incluido el ícono en la bandeja del sistema). La config solo se lee al iniciar.

6.2 Encontrar y editar el archivo de configuración MCP

Ejecutá este bloque en PowerShell. Detecta automáticamente si tenés instalación MSIX o clásica y abre el archivo correcto:

# Detectar la ruta real del config (MSIX o clasico)
$configFile = $null
$pkg = (Get-AppxPackage -Name "*Claude*" -ErrorAction SilentlyContinue).PackageFamilyName
if ($pkg) {
    $msixConfig = Join-Path $env:LOCALAPPDATA "Packages\$pkg\LocalCache\Roaming\Claude\claude_desktop_config.json"
    if (Test-Path (Split-Path $msixConfig -Parent)) {
        $configFile = $msixConfig
        Write-Host "Instalacion MSIX detectada."
        Write-Host "Config que lee Claude: $configFile"
    }
}
if (-not $configFile) {
    $configFile = "$env:APPDATA\Claude\claude_desktop_config.json"
    Write-Host "Instalacion clasica (no MSIX)."
    Write-Host "Config: $configFile"
}

# Crear el archivo si no existe
New-Item -ItemType Directory -Force -Path (Split-Path $configFile -Parent) | Out-Null
if (-not (Test-Path $configFile)) {
    '{}' | Set-Content -Path $configFile -Encoding UTF8
}

# Aviso si existen dos copias (bug conocido de MSIX)
$legacyConfig = "$env:APPDATA\Claude\claude_desktop_config.json"
if ($configFile -ne $legacyConfig -and (Test-Path $legacyConfig)) {
    Write-Host ""
    Write-Host "AVISO: Tambien existe $legacyConfig"
    Write-Host "       Edita SOLO el archivo MSIX de arriba. El otro lo ignora Claude."
}

notepad $configFile

El sufijo pzs8sxrjxfjjc suele ser fijo; si difiere en tu PC, el script de arriba lo resuelve solo con Get-AppxPackage.

6.3 Agregar el servidor MCP

Importante: usá la ruta de python que obtuviste en el Paso 1, y rutas absolutas a server.py.

Ejemplo (ajustá command si tu Python está en otro path):

{
  "mcpServers": {
    "finnegans-agent": {
      "command": "C:\\Users\\user\\AppData\\Local\\Microsoft\\WindowsApps\\python.exe",
      "args": ["C:\\FinnegansAgent\\server.py"],
      "cwd": "C:\\FinnegansAgent"
    }
  }
}

Reglas para no fallar:

Si ya tenés otros MCPs en el JSON, agregá finnegans-agent dentro de mcpServers sin borrar los demás.

Validá que el JSON sea válido (reutilizá la misma detección de ruta):

$pkg = (Get-AppxPackage -Name "*Claude*" -ErrorAction SilentlyContinue).PackageFamilyName
$configFile = if ($pkg -and (Test-Path (Join-Path $env:LOCALAPPDATA "Packages\$pkg\LocalCache\Roaming\Claude"))) {
    Join-Path $env:LOCALAPPDATA "Packages\$pkg\LocalCache\Roaming\Claude\claude_desktop_config.json"
} else {
    "$env:APPDATA\Claude\claude_desktop_config.json"
}
Get-Content $configFile | ConvertFrom-Json | Out-Null
if ($?) { Write-Host "JSON valido en $configFile" } else { Write-Host "JSON INVALIDO - corregir antes de abrir Claude" }

6.4 Reiniciar Claude Desktop

Abrí Claude Desktop. En la conversación, el ícono de herramientas (🔨) debería mostrar tools de finnegans-agent.

Paso 7 — Instrucciones del asistente para el líder

Para que el agente pida confirmación antes de escribir y hable en castellano claro:

1. En Claude Desktop, creá un Proyecto (ej. "Finnegans SOUTEX").

2. En Instrucciones del proyecto, pegá el contenido completo de ASSISTANT_INSTRUCTIONS.md.

3. El líder siempre usa ese proyecto para consultas de Finnegans.

notepad C:\FinnegansAgent\ASSISTANT_INSTRUCTIONS.md

Paso 8 — Prueba funcional en Claude (smoke test)

Con Claude Desktop abierto y el proyecto configurado, probá en este orden:

8.1 Conexión

Verificá la conexión con Finnegans.

Esperado: mensaje de API OK y catálogo OK.

8.2 Lectura (necesitás un código real de tu maestro)

Buscá la API de productos, mostrá cómo se consulta, y traeme el producto con código CODIGO_REAL.

Reemplazá CODIGO_REAL por un código existente en Finnegans.
Esperado: datos del producto o un 404 claro si el código no existe.

8.3 Escritura con validación (solo en ambiente de prueba)

Prepará la creación de [algo de bajo riesgo] y mostrámelo para confirmar. No ejecutes sin mi OK.

Esperado: resumen + pregunta de confirmación. No debe ejecutar solo.

Sí, confirmá.

Esperado: recién ahí ejecuta ejecutar_cambio.

Paso 9 — Pruebas manuales desde PowerShell (si Claude falla)

Si Claude no conecta el MCP pero verify_setup.py pasó, probá la API directo:

Set-Location C:\FinnegansAgent

# Token de autenticacion
python cli.py token

# Lectura de un producto (reemplazar CODIGO_REAL)
python cli.py get producto --id CODIGO_REAL

Si la CLI funciona pero Claude no, el problema está en claude_desktop_config.json (Paso 6).

Instalar en una PC nueva sin acceso a ella

Si IT no puede llegar a la máquina, scripts\instalar.bat hace la instalación completa. Requiere que el líder ya tenga Python 3.10+ y Claude Desktop instalados (el script corta con un mensaje claro si falta alguno).

Se corre dos veces, a propósito:

1. Primera pasada. Ubica Python y la config de Claude, descarga el código en %LOCALAPPDATA%\FinnegansAgent, instala las dependencias, y se detiene pidiendo el .env. Abre la carpeta donde hay que pegarlo.

2. Segunda pasada. Detecta el .env, completa lo que falte, registra el asistente en Claude, prueba la conexión real contra Finnegans y reinicia Claude.

El .env va por separado: tiene FINNEGANS_CLIENT_ID y FINNEGANS_CLIENT_SECRET, que son credenciales de producción y no pueden viajar dentro de un .bat. Se puede reusar el mismo .env de otra PC con una salvedad: FINNEGANS_OPERATOR identifica a quién la auditoría le atribuye cada cambio, así que no debe quedar con el nombre de otra persona ni con el valor de ejemplo. El instalador lo pregunta y lo escribe él mismo si detecta que falta o sigue en el ejemplo.

La entrada en claude_desktop_config.json se agrega sin pisar lo que ya haya: si la PC tiene otros MCP configurados, quedan intactos.

Actualizar una PC ya instalada

Pensado para cuando IT no tiene acceso a la máquina del líder.

Mandale scripts\actualizar.bat por mail o chat. El líder lo guarda en cualquier carpeta (Descargas sirve) y hace doble clic. El script:

1. Se ubica solo: lee la carpeta de instalación y el intérprete de Python desde claude_desktop_config.json, probando primero la ruta MSIX (Claude instalado desde la Store) y después la de %APPDATA%.

2. Trae la versión nueva: git pull si la carpeta es un clon, o bajando el ZIP del repo si se instaló copiando la carpeta. El ZIP no incluye .env, audit/ ni exports/ porque están en .gitignore, así que copiar encima no toca las credenciales ni el historial de auditoría.

3. Completa FINNEGANS_SWAGGER_KEY en el .env si falta.

4. Reinstala dependencias con el intérprete correcto.

5. Verifica contra swaggerGlobal que la versión nueva realmente busca.

6. Reinicia Claude Desktop. Cerrar la ventana no alcanza: el server MCP es un proceso hijo que sobrevive; hay que salir desde la bandeja del sistema, y eso es lo que el script hace por él.

Los detalles técnicos van a actualizacion-error.txt en la carpeta de instalación, no a la pantalla: cada mensaje de error le dice al líder qué archivo mandarle a IT.

Antes de enviarlo, si el .env del líder puede no tener la swagger key, completá la variable CLAVE_DOC en las primeras líneas del .bat. Si la dejás vacía y falta la clave, el script corta con un mensaje claro sin dejar nada a medias.

Entrega a usuarios

GATE OBLIGATORIO: Los 4 pasos siguientes son el criterio de aceptación por PC.

Antes de entregar la PC a un usuario (líder), un operador IT debe ejecutar en orden los 4 pasos de validación que figuran abajo. Solo cuando los 4 pasos pasen, la PC está lista.

Paso 1: Configurar .env con credenciales de servicio acotadas

Objetivo: verificar que las credenciales en .env son de un usuario API con rol acotado (NO administrador).

• En Finnegans, obtener un usuario de servicio con rol limitado (ej. "Solo lectura + escritura de tablas permitidas").

• Copiar su client_id y client_secret.

• Verificar en el archivo .env que está completado:

  FINNEGANS_CLIENT_ID=<id del usuario acotado>
  FINNEGANS_CLIENT_SECRET=<secret del usuario acotado>
  FINNEGANS_OPERATOR=<nombre de usuario de prueba para auditoría>

• Validar que NO están credenciales de administrador.

• Confirmar que .env está en .gitignore (no subido a git).

Criterio de aceptación: .env cargado con usuario acotado y FINNEGANS_OPERATOR definido.

Paso 2: Correr python verify_setup.py y confirmar checks 4, 5 y 6

Objetivo: validar que Python, credenciales, catálogo de APIs y servidor MCP funcionan.

• Abrir PowerShell en la carpeta del proyecto (ej. C:\FinnegansAgent).

• Ejecutar:

  python verify_setup.py

• Esperar a que finalice. Todos los checks deben estar [OK], especialmente:

  • Check 4: Autenticación y token (credenciales API válidas)

  • Check 5: Búsqueda en catálogo de APIs (conectividad a Finnegans)

  • Check 6: Servidor MCP registrado y funcionando

• Si hay un [ERROR], detente aquí:

  1. Lee el mensaje de error.

  2. Corrige el punto indicado (ej. actualizar .env, reiniciar, verificar conectividad).

  3. Vuelve a ejecutar python verify_setup.py.

  4. Repite hasta que todos los checks pasen.

Criterio de aceptación: Script finaliza con RESULTADO: TODO OK (6/6 checks automáticos).

Paso 3: Lectura real en Claude Desktop

Objetivo: verificar que el agente conecta a Finnegans y trae datos reales en modo lectura.

• Cerrar Claude Desktop por completo (incluido el ícono en la bandeja del sistema).

• Volver a abrir Claude Desktop.

• Entrar al Proyecto "Finnegans" (o el nombre que configuraste en el Paso 7).

• Escribir en la conversación un mensaje de lectura de solo lectura, ejemplo:

  Buscá la API de productos. Mostrá cómo se consulta. Ahora trae los datos del producto con código "PROD123".

  (Reemplazar PROD123 por un código que exista en tu base de datos de Finnegans.)

• Confirmar que:

  • El agente usa buscar_api para encontrar el endpoint.

  • El agente usa ver_api para ver los parámetros.

  • El agente usa consultar_finnegans para traer los datos.

  • Los datos se devuelven sin errores (no 401, 403, 500).

  • La respuesta es en castellano claro.

Criterio de aceptación: Claude Desktop ejecuta una consulta real contra Finnegans y devuelve datos correctos sin error de autenticación.

Paso 4: Escritura de prueba controlada con auditoría

Objetivo: validar que la escritura requiere confirmación, muestra preview, genera auditoría sin exponer tokens.

• En Claude, escribir un mensaje de escritura sobre un registro descartable (algo que no importe borrar después), ejemplo:

  Prepará la creación de una nota o comentario interno en un cliente de prueba. Mostrámelo para confirmar. No ejecutes sin mi OK.

• Confirmar que:

  • El agente NO ejecuta inmediatamente.

  • Muestra un PREVIEW con los campos exactos que va a cambiar.

  • Muestra el código que va a ejecutar.

  • Pregunta: "¿Confirmás? (sí / no)" esperando confirmación explícita.

• Escribir en la conversación:

  Sí, confirmá.

• Confirmar que:

  • Ahora SÍ ejecuta ejecutar_cambio.

  • Muestra "Listo" o mensaje de éxito.

  • No hay errores de permisos (401, 403) ni validación (400).

• Verificación posterior: escribir en Claude:

  Buscá el registro que acabo de crear/modificar. Tráeme sus datos actualizados para confirmar que el cambio está.

  Confirmar que el agente trae el registro con los cambios reflejados.

• Revisar auditoría — abrir PowerShell y ejecutar:

  Get-Content C:\FinnegansAgent\audit\finnegans-audit.jsonl | Select-Object -Last 10

  (O la ruta donde hayas configurado FINNEGANS_AUDIT_PATH.)

  Confirmar que aparecen al menos 2 líneas para tu cambio:

  1. Línea con "evento": "preparado" → debe tener "operador": "<tu_usuario_de_prueba>", SIN token.

  2. Línea con "evento": "ejecutado" → debe tener "operador": "<tu_usuario_de_prueba>", SIN token.

Criterio de aceptación:

• El flujo es: preparación → preview → confirmación explícita → ejecución

• Los datos se actualicen realmente en Finnegans

• Verificación posterior confirma el cambio

• El log de auditoría registre ambos eventos (preparado y ejecutado) con el operador correcto

• Ningún token está expuesto en el log

Resumen: Checklist de aceptación por PC

Antes de entregar, confirma que:

• Paso 1: .env tiene credenciales acotadas y FINNEGANS_OPERATOR definido

• Paso 2: python verify_setup.py finaliza con TODO OK (6/6)

• Paso 3: Lectura real en Claude trae datos correctos desde Finnegans

• Paso 4: Escritura con validación, preview, confirmación y auditoría funcionan

Si algún paso falla:

1. Lee el error.

2. Investiga la causa (credenciales vencidas, conectividad, permisos).

3. Corrige el punto.

4. Repite el paso que falló.

5. No avances hasta que el paso anterior pase completamente.

Entrega al líder (usuario final)

Una vez que los 4 pasos pasen, entregá la PC con:

• Claude Desktop instalado y con sesión iniciada

• Proyecto "Finnegans" creado con instrucciones del archivo ASSISTANT_INSTRUCTIONS.md cargadas

• verify_setup.py ejecutado exitosamente con TODO OK

• Lectura real probada con un código real de Finnegans

• .env no compartido con el líder (IT lo guarda)

• Acceso rápido a Claude Desktop (opcional: acceso directo o pin a la barra de tareas)

Nota simple para el líder:
"Abrí Claude, entrá al proyecto Finnegans, y preguntá en castellano qué necesitás. Si te pide confirmar un cambio, leé el resumen y decí sí o no. ¿Preguntas? Llamá a IT."

Solución de problemas

python no se reconoce

• Reinstalá Python con Add to PATH.

• Usá la ruta completa en claude_desktop_config.json → command.

verify_setup.py — error en credenciales API

[ERROR] No se pudo autenticar: ...

• Verificá FINNEGANS_CLIENT_ID y FINNEGANS_CLIENT_SECRET en .env.

• Regenerá las keys en Finnegans si fueron rotadas.

• Comprobá que la PC tenga internet y acceso a https://api.finneg.com.

verify_setup.py — error en catálogo de APIs

[ERROR] No se pudo consultar el catalogo: ...

• Verificá FINNEGANS_DOCS_CLIENT_ID y FINNEGANS_DOCS_SECRET_KEY.

• Copiá los valores desde el mcp.json de Cursor (sección finnegans-api-docs → headers).

• Comprobá acceso a https://services.finneg.com.

Claude Desktop no muestra herramientas MCP

1. Cerrá Claude por completo (bandeja incluida).

2. Confirmá que editaste el config MSIX (si aplica), no solo el de %APPDATA%\Claude\ (Paso 6.2).

3. Validá JSON: ConvertFrom-Json en PowerShell (Paso 6.3).

4. Confirmá que command apunta al mismo python donde instalaste mcp.

5. Revisá logs de Claude (ruta según tipo de instalación):

 $pkg = (Get-AppxPackage -Name "*Claude*" -ErrorAction SilentlyContinue).PackageFamilyName
 $logDir = if ($pkg -and (Test-Path (Join-Path $env:LOCALAPPDATA "Packages\$pkg\LocalCache\Roaming\Claude\logs"))) {
     Join-Path $env:LOCALAPPDATA "Packages\$pkg\LocalCache\Roaming\Claude\logs"
 } else {
     "$env:APPDATA\Claude\logs"
 }
 Get-ChildItem $logDir -Recurse -Filter "*mcp*" | Sort-Object LastWriteTime -Descending | Select-Object -First 5

6. Ejecutá manualmente el servidor (debe quedar esperando, sin error):

 Set-Location C:\FinnegansAgent
 python server.py

Ctrl+C para salir. Si imprime error acá, corregilo antes de abrir Claude.

Bad Request: id missing al consultar

• El router de Finnegans exige un segmento tras la entidad. Rutas válidas:

  • GET /api/{entidad}/{codigo} → un registro.

  • GET /api/{entidad}/list → listado completo.

  • GET /api/reports/{Nombre} → reportes.

• Si querés listar, usá api_id='{entidad}/list'. Si querés un registro, pasá id.

404 Not Found al consultar

• La petición está bien formada; el código no existe en Finnegans.

• Probá con otro código que sepas que existe.

El agente escribe sin pedir confirmación

• Revisá que las instrucciones del proyecto incluyan ASSISTANT_INSTRUCTIONS.md.

• El flujo correcto es: preparar_cambio → usuario confirma → ejecutar_cambio.

• ejecutar_cambio con usuario_confirmo=false nunca ejecuta (está bloqueado en código).

Actualizar el agente en una PC ya configurada

# Detener Claude Desktop primero
$Destino = "C:\FinnegansAgent"
Copy-Item -Path "\\servidor\compartido\finnegans-connector\*" -Destination $Destino -Recurse -Force
# NO sobrescribir .env si ya tiene credenciales
Set-Location $Destino
python -m pip install -r requirements.txt
python verify_setup.py
# Reiniciar Claude Desktop

Herramientas MCP expuestas

Fuente de verdad de APIs: el conector resuelve endpoints contra el spec OpenAPI completo de Finnegans (FINNEGANS_SWAGGER_URL + FINNEGANS_SWAGGER_KEY, el Swagger de oneteam). El MCP finnegans-api-docs queda como apoyo secundario.

Seguridad

• Credenciales en .env (nunca en git, nunca en el chat).

• Escrituras siempre en dos pasos: preparar → confirmar → ejecutar.

• ejecutar_cambio rechaza si usuario_confirmo no es true.

• Confirmaciones expiran a los 10 minutos.

• No se usan contraseñas personales; solo credenciales de aplicación.

• Si el client_secret o el FINNEGANS_SWAGGER_KEY se exponen (chat, mail), rotarlos en Finnegans y actualizar el .env.

Estructura del proyecto

finnegans-connector/
├── server.py                  # Agente MCP unificado (punto de entrada)
├── verify_setup.py            # Script de verificación para IT
├── finnegans/
│   ├── client.py              # HTTP client (auth + GET/POST/PUT/DELETE)
│   ├── discovery.py           # Catálogo de APIs (MCP remoto Finnegans)
│   ├── validator.py           # Cola de cambios con confirmación
│   └── config.py              # Carga de .env
├── cli.py                     # CLI para pruebas manuales
├── ASSISTANT_INSTRUCTIONS.md  # Prompt para Claude Desktop
├── .env.example
└── requirements.txt

Diferencia con el MCP de docs de Cursor

Los líderes solo necesitan este agente + Claude Desktop. El MCP de docs en Cursor queda para desarrollo.

Referencia rápida de comandos IT

# Ir al proyecto
Set-Location C:\FinnegansAgent

# Verificación completa
python verify_setup.py

# Probar token API
python cli.py token

# Probar lectura
python cli.py get producto --id CODIGO_REAL

# Abrir config MCP de Claude (detecta MSIX o clasico)
$pkg = (Get-AppxPackage -Name "*Claude*" -ErrorAction SilentlyContinue).PackageFamilyName
$configFile = if ($pkg -and (Test-Path (Join-Path $env:LOCALAPPDATA "Packages\$pkg\LocalCache\Roaming\Claude"))) {
    Join-Path $env:LOCALAPPDATA "Packages\$pkg\LocalCache\Roaming\Claude\claude_desktop_config.json"
} else { "$env:APPDATA\Claude\claude_desktop_config.json" }
notepad $configFile

# Validar JSON de Claude
Get-Content $configFile | ConvertFrom-Json

# Ver ruta de Python para la config
(Get-Command python).Source