Tutorial del pipeline de tres etapas del servidor MCP de DevSpeak dentro de un IDE con IA: optimize_text para la limpieza léxica de Etapa 1, translate_text para generar un API Design en Etapa 2 con audience, context, format y tone, y refine_translation para la revisión iterativa de Etapa 3 con previousOutput y feedback. Explica por qué la Etapa 1 actúa sobre el texto original y la Etapa 3 sobre la salida generada, y cómo summarize_input maneja texto sobre el límite de 10.000 caracteres.
Traduce Requisitos a un Diseño de API sin Salir de tu Editor
Un product manager deja un mensaje en Slack. Es lo bastante claro para una persona e inútil para quien debe implementarlo. Este tutorial lleva ese mensaje por las tres etapas de DevSpeak usando herramientas MCP, hasta obtener un diseño de API que realmente pondrías en un pull request.
Lo que Aprenderás
optimize_text (Etapa 1)translate_text (Etapa 2)refine_translation (Etapa 3)Requisitos Previos
refine_translation necesita además el refinamiento iterativo (VIBECODER y superiores)Tiempo Estimado
~12 minutos
La Entrada
Este es el mensaje, sin editar:
`` oye necesitamos que los usuarios puedan como guardar sus cosas y volver a ellas después, también debería funcionar si están en el celular. ah y marketing quiere saber cuánta gente lo usa realmente. urgente porfatext
`
Hay cuatro requisitos enterrados ahí: persistencia, reanudación de sesión, soporte móvil y analítica de uso. Ninguno está especificado.
Etapa 1 — Optimiza la Entrada
optimize_text es una pasada de edición monolingüe. Corrige gramática, tono y claridad sin agregar significado. Acepta audience y context, pero solo los usa para calibrar el tono. Nunca genera un documento, así que rechaza deliberadamente los parámetros que dan forma a la salida: format y tone.
Pídele a tu asistente:
> Usa optimize_text en este mensaje de Slack con audience "Tech Lead" y context "Backend".
`json
{
"input": "oye necesitamos que los usuarios puedan como guardar sus cosas...",
"audience": "Tech Lead",
"context": "Backend"
}
`
El resultado se lee con claridad pero dice exactamente lo mismo:
`text
Necesitamos que los usuarios puedan guardar su trabajo y retomarlo más
tarde. Esto también debe funcionar en dispositivos móviles. Además,
marketing requiere visibilidad sobre las métricas de uso. Es prioritario.
`
optimize_text acepta únicamente input, audience, context y managedModel. El esquema es estricto, así que pasar format o tone devuelve un error de validación en lugar de ignorarlos en silencio. Es intencional — descartarlos calladamente te haría creer que un parámetro se aplicó cuando nunca ocurrió.
Cuándo omitir esta etapa: si tu entrada ya está bien redactada, ve directo a la Etapa 2. La Etapa 1 es un pulido, no un requisito.
Etapa 2 — Genera el Diseño de API
Ahora el trabajo real. translate_text recibe los cuatro parámetros que dan forma a toda la salida:
| Parámetro | Valor | Efecto |
| ---------- | ------------ | ----------------------------------------------- |
| audience | Senior Dev | Asume fluidez; omite explicaciones básicas |
| context | Backend | Enmarca la salida en servicios y datos |
| format | API Design | Produce endpoints, esquemas y códigos de estado |
| tone | 70 | Detallado — cruza el umbral de 50 |
> Usa translate_text con el texto optimizado, audience "Senior Dev", context "Backend", format "API Design" y tone 70.
`json
{
"input": "Necesitamos que los usuarios puedan guardar su trabajo...",
"audience": "Senior Dev",
"context": "Backend",
"format": "API Design",
"tone": 70
}
`
El valor de tone es un binario duro, no un gradiente. Por debajo de 50 produce una reescritura concisa; en 50 o más produce un documento técnico completo. Un tone de 49 y uno de 51 dan documentos estructuralmente distintos, mientras que 51 y 90 solo difieren en profundidad. Si tu salida se siente pobre, lo primero que debes revisar es si el tone cayó por debajo de 50.
La salida es un diseño de API estructurado — endpoints de recursos, esquemas de petición y respuesta, códigos de estado y un modelo de autenticación. Lo bastante concreto como para revisarse.
Punto de Control
En este punto deberías tener:
Ese último punto importa. Una especificación tan vaga que nadie puede objetarla no cumplió su función.
Etapa 3 — Refina la Salida
Al revisar el diseño faltan dos cosas: paginación, y el requisito de analítica se perdió.
refine_translation resuelve esto. La distinción crítica:
> La Etapa 1 actúa sobre el texto original. La Etapa 3 actúa sobre la salida generada. No son intercambiables.
Pasar tu mensaje original de Slack a refine_translation no funcionará como esperas — la herramienta espera el documento generado en previousOutput.
> Usa refine_translation con ese diseño de API como previousOutput y este feedback: "Agrega paginación basada en cursor al endpoint de listado, y agrega un endpoint que exponga métricas de uso para el equipo de marketing."
` { "previousOutput": "## Diseño de API: Persistencia de Workspace\n\n### POST /api/workspaces...", "feedback": "Agrega paginación basada en cursor al listado, y un endpoint que exponga métricas de uso.", "audience": "Senior Dev", "context": "Backend", "format": "API Design", "tone": 70 }json
`
Cada refinamiento devuelve un documento completo e independiente, no un diff. Alimenta la versión más reciente en el siguiente previousOutput — encadenar refinamientos contra una copia desactualizada descarta silenciosamente el trabajo intermedio.
Los refinamientos tienen cuota. Por MCP la asignación es la misma que en la app web: 25 al mes en VIBECODER, 100 en DEVELOPER e ilimitada en ENTERPRISE. Verifica con get_account_info antes de una sesión larga de revisión.Manejo de Entradas Muy Largas
translate_text limita la entrada a 10.000 caracteres. Para un documento de requisitos extenso, condénsalo primero:
> Usa summarize_input en este documento y luego traduce el resumen.
`json
{
"input": "<hasta 15.000 caracteres>"
}
`
Devuelve el resumen seguido de la longitud antes y después:
`text
La plataforma requiere workspaces de usuario persistentes...
(14820 → 9480 chars)
`
El endpoint REST detrás de la herramienta, POST /api/v1/optimize/summarize, también devuelve reductionRatio — la fracción eliminada, (originalLength − summaryLength) / originalLength, así que 14.820 → 9.480 es 0.36.
Pasa el resumen a translate_text, pero revisa antes el segundo número. El resumidor condensa el texto en lugar de recortarlo a un tamaño fijo, así que una entrada de 15.000 caracteres aún puede quedar por encima del límite de 10.000 de traducción. Si ocurre, resume el resultado otra vez o divide el documento. Ten presente el otro techo: summarize_input acepta 15.000 caracteres, así que un documento realmente grande debe dividirse antes de llegar a esta herramienta.Solución de Problemas
Input must be at least 10 characters
Toda herramienta que recibe texto exige un mínimo de 10 caracteres. Casi siempre significa que una variable quedó vacía.
La salida es mucho más corta de lo esperado
El tone quedó por debajo de 50. Valores menores a 50 piden una reescritura concisa, no un documento. Súbelo a 60–75.
refine_translation ignoró mi feedback
Revisa qué pasaste en previousOutput. Enviar la entrada original en lugar del documento generado es la causa más común — la herramienta se queda sin documento que revisar.
HTTP 403 en refine_translation
El refinamiento necesita refinamiento iterativo (VIBECODER y superiores). Confirma con get_account_info que iterativeRefinement aparezca en features.
DevSpeak API request to <url> timed out
El cliente MCP dejó de esperar la respuesta; no es un error devuelto por el servidor. Una entrada extensa con tone alto puede tardar lo suficiente como para provocarlo. Acorta la entrada o baja el tone.
Resumen
Aprendiste a:
sin alterar su significado sobre la salida generada