# Documentación de Implementación: Servidor Pipefy MCP
Este documento detalla las decisiones técnicas, arquitectura y patrones de diseño utilizados en la implementación del servidor MCP para Pipefy.
## 1. Arquitectura del Sistema
El servidor está construido utilizando una arquitectura ligera y asíncrona optimizada para interacciones con LLMs.
### Componentes Principales
- **Framework**: `FastMCP` (Python SDK)
- **Por qué**: Proporciona una abstracción moderna y tipada para el Protocolo de Contexto de Modelos (MCP), simplificando la definición de herramientas y gestión del ciclo de vida del servidor. Soporta ejecución asíncrona nativa, esencial para operaciones de red I/O bound.
- **Validación de Datos**: `Pydantic`
- **Por qué**: Garantiza que las entradas del LLM cumplan estrictamente con los requisitos de la API antes de realizar cualquier solicitud. Esto es crucial en GraphQL donde los errores de sintaxis o tipos son costosos. Definimos modelos explícitos (`CreateCardInput`, `ListPipesInput`) que sirven como contrato de interfaz.
- **Cliente API**: `httpx` (Asíncrono)
- **Por qué**: Permite realizar solicitudes HTTP no bloqueantes, lo que mejora el rendimiento cuando se realizan múltiples operaciones o búsquedas.
## 2. Decisiones de Diseño Clave
### A. Abstracción de GraphQL
En lugar de exponer una herramienta genérica `execute_graphql` que requeriría que el LLM conociera la sintaxis exacta y esquema de Pipefy, hemos abstraído las operaciones en herramientas semánticas (`get_pipe`, `create_card`).
- **Ventaja**: Reduce drásticamente las alucinaciones de sintaxis GraphQL.
- **Ventaja**: Permite validar parámetros específicos (como IDs) antes de llamar a la API.
- **Ventaja**: Oculta la complejidad de la paginación y estructura de nodos/aristas (edges/nodes) típica de Relay/GraphQL.
### B. Flujo de Trabajo Orientado a Tareas
El conjunto de herramientas está diseñado para soportar un flujo de trabajo lógico completo para un agente autónomo:
1. **Descubrimiento**: `pipefy_list_pipes` permite al agente "ver" qué hay disponible sin conocer IDs a priori.
2. **Inspección**: `pipefy_get_pipe` permite leer el esquema (campos requeridos, fases) antes de actuar.
3. **Acción**: `pipefy_create_card` utiliza la información descubierta para realizar cambios.
### C. Formatos de Salida Duales (Markdown vs JSON)
Todas las herramientas aceptan un parámetro `response_format`.
- **Markdown (Default)**: Optimizado para consumo directo del LLM. Utiliza estructuras jerárquicas y listas para reducir el uso de tokens y mejorar la comprensión semántica.
- **JSON**: Disponible cuando el agente necesita procesar programáticamente la respuesta o extraer datos estructurados precisos.
### D. Manejo Centralizado de Errores
Se implementó un decorador/función `_handle_api_error` que captura excepciones de `httpx` y errores de GraphQL.
- **Objetivo**: Convertir stack traces técnicos o códigos de error HTTP (401, 403) en mensajes de lenguaje natural que informan al LLM sobre *qué* salió mal y *cómo* corregirlo (ej. "Token inválido", "Permiso denegado").
## 3. Justificación de Herramientas Implementadas
| Herramienta | Propósito | Justificación Técnica |
|-------------|-----------|-----------------------|
| **`pipefy_list_pipes`** | Descubrimiento | Los LLMs no conocen los IDs internos (`301234567`). Esta herramienta es el punto de entrada necesario para mapear Nombres -> IDs. |
| **`pipefy_get_pipe`** | Metadatos / Esquema | Esencial para operaciones de escritura. Revela los `field_id` requeridos para crear tarjetas, que son dinámicos y específicos de cada pipe. |
| **`pipefy_create_card`** | Escritura / Acción | Abstrae una mutación GraphQL compleja. Maneja la estructura de `fields_attributes` (array de clave-valor) que suele ser propensa a errores para los LLMs. |
| **`pipefy_list_cards`** | Contexto / Lectura | Permite obtener el estado actual del trabajo. Implementa paginación básica y búsqueda para manejar volúmenes grandes de datos. |
| **`pipefy_get_card`** | Detalle Profundo | Recupera información que no cabe en la vista de lista, como valores de todos los campos personalizados, comentarios y adjuntos. |
## 4. Referencias de Código (`main.py`)
- **Modelos de Entrada**: Ver clases que heredan de `BaseModel` (líneas ~95-216). Definen la estructura estricta de cada herramienta.
- **Cliente GraphQL**: Función `_make_graphql_request` (líneas ~45-67). Centraliza la autenticación Bearer y el manejo de respuestas `data`/`errors` estándar de GraphQL.
- **Definición de Herramientas**: Decoradores `@mcp.tool`. Cada herramienta incluye `annotations` detalladas (hints) para ayudar al orquestador MCP a entender si la operación es segura (`readOnlyHint`) o tiene efectos secundarios.
