Oboe MCP

Flujos de trabajo estructurados uno a uno (one-by-one) para agentes de codificación.

Servidor MCP para flujos de trabajo de revisión duraderos uno a uno, con estado de sesión priorizado para agentes de codificación.

Proporciona 16 herramientas para crear, navegar y resolver elementos en archivos de sesión con puntuación de prioridad, incluyendo el manejo de elementos bloqueados, actualizaciones de aprobación de primer nivel y sesiones secundarias anidadas, para que los flujos de trabajo /obo puedan usar operaciones MCP en lugar de ediciones JSON manuales.

Licenciado bajo AGPL-3.0-or-later con licencia comercial disponible. Consulta LICENSE para conocer los términos completos.

Paquete PyPI

Instala o ejecuta Oboe MCP directamente desde PyPI usando cualquiera de estas alternativas:

• Ejecútalo sin instalar: uvx oboe-mcp

• Instálalo en tu entorno actual: pip install oboe-mcp

Instalar oboe-mcp también instala el comando oboe-cli:

# After pip install oboe-mcp
oboe-cli --help

# From PyPI 
uvx --from oboe-mcp oboe-cli --help

# From a local checkout (no install needed)
uvx --from /path/to/oboe-mcp oboe-cli --help

Referencia de CLI (oboe-cli)

Instalar oboe-mcp también instala oboe-cli, un compañero de línea de comandos amigable para el usuario para los mismos archivos de sesión en los que operan las herramientas MCP.

oboe-cli [--session SESSION] [--base-dir DIR] COMMAND [ARGS...]

Opciones globales:

Autodetección de base-dir: cuando se omite --base-dir, oboe-cli utiliza el directorio de trabajo actual si contiene una carpeta .github/obo_sessions/, de lo contrario, vuelve al directorio de trabajo tal cual.

Comandos

Inicio rápido

# Create a session from a JSON items file
oboe-cli --base-dir /path/to/project create \
    --title "Code review findings" \
    --input-file findings.json

# List sessions
oboe-cli --base-dir /path/to/project sessions

# Work through items
oboe-cli --base-dir /path/to/project --session session_20260411_120000.json next
oboe-cli --base-dir /path/to/project --session session_20260411_120000.json \
    in-progress 1
oboe-cli --base-dir /path/to/project --session session_20260411_120000.json \
    complete 1 "Fixed the validation bug"

Nota: el script obo_helper.py enviado en versiones anteriores es ahora un delgado adaptador de obsolescencia que delega en oboe-cli.

Por qué las sesiones OBO

Las sesiones One-by-One no son solo notas de chat guardadas. Son un modelo de flujo de trabajo para manejar el trabajo de múltiples elementos como una sesión de interacción duradera y ordenada.

En comparación con el chat simple o las preguntas de seguimiento integradas de un agente, OBO añade capacidades que esos modos de interacción más ligeros no suelen proporcionar:

• un flujo de trabajo centrado en la visión general, donde el agente puede comenzar con el alcance, el recuento de elementos, las categorías principales y el orden de ejecución propuesto

• repriorización explícita basada en urgencia, importancia, esfuerzo y presión de dependencia en lugar de cualquier orden que haya aparecido en el chat

• estados de ciclo de vida duraderos a través de pending, in_progress, deferred, blocked, completed y skipped

• metadatos de aprobación separados a través de approval_status, approval_mode, approved_at y approval_note

• metadatos de bloqueador almacenados para que el trabajo bloqueado siga siendo visible y explicable en lugar de desaparecer silenciosamente de la cola activa

• sesiones secundarias anidadas que pausan una sesión principal, manejan un subproblema y luego reanudan la sesión principal limpiamente

• gestión del ciclo de vida de la sesión de primer nivel: listar, crear, inspeccionar, fusionar, pausar, reanudar y cerrar sesiones como objetos de flujo de trabajo con nombre

• recuperación determinista después de reinicios del modelo, recargas del editor o traspaso de agentes

• un registro de auditoría legible por máquina en archivos de sesión en lugar de depender de la memoria conversacional

Esto es más importante cuando el trabajo abarca muchos hallazgos, requiere aprobaciones explícitas del usuario, depende de subinvestigaciones intermedias o debe sobrevivir a varios turnos del agente. El chat es bueno para la conversación. Una herramienta de preguntas estructurada es buena para obtener una respuesta limpia en el turno actual. OBO es para la orquestación de flujos de trabajo duraderos.

Usa OBO cuando necesites un manejo secuencial controlado, estado de cola duradero o subtrabajo anidado. Usa el chat simple cuando la tarea sea lo suficientemente pequeña como para que un objeto de flujo de trabajo completo añada más carga que valor.

Modelo de estado

OBO rastrea cada elemento en dos ejes independientes.

Eje de ciclo de vida

• pending: el trabajo está en cola pero aún no ha comenzado

• in_progress: el trabajo se está realizando activamente ahora

• deferred: el trabajo está aprobado para una ejecución posterior y debe permanecer fuera de la cola de revisión inmediata hasta que se agote la pasada de revisión activa o el usuario solicite explícitamente el trabajo diferido

• blocked: el trabajo no puede continuar hasta que se resuelva una dependencia externa o un subproblema

• completed: el trabajo está terminado y cerrado

• skipped: el trabajo no se está ejecutando intencionalmente

Eje de aprobación

• unreviewed: aún no se ha registrado ninguna decisión explícita del usuario

• approved: el usuario ha autorizado el trabajo

• denied: el usuario ha rechazado explícitamente el trabajo

Campos de metadatos de aprobación:

• approval_status: decisión de aprobación para el elemento

• approval_mode: immediate o delayed cuando se registró una decisión de tiempo de aprobación

• approved_at: marca de tiempo de cuándo se registró la aprobación

• approval_note: nota de texto libre opcional sobre la decisión de aprobación

Emparejamientos comunes:

• Aprobar inmediato: llama a obo_set_approval(..., approval_status="approved", approval_mode="immediate"); el elemento normalmente permanece pending hasta que comienza el trabajo o se mueve a in_progress

• Aprobar diferido: llama a obo_set_approval(..., approval_status="approved", approval_mode="delayed"); esto registra la aprobación diferida y mueve el elemento a deferred

• Denegar: establece approval_status=denied; si el elemento se está cerrando fuera de la cola, empareja con status=skipped

Modos de interacción

Los tres patrones de interacción comunes son el chat simple, una herramienta de preguntas estructurada y una sesión OBO completa. Resuelven problemas diferentes.

Ejemplo de progresión:

• Chat estándar: un agente enumera varios hallazgos en prosa y la conversación misma se convierte en el único registro de lo que se manejó.

• askQuestions: el agente puede pedir una elección de menú limpia, pero aún no tiene una cola de elementos persistente a menos que la almacene en otro lugar.

• Sesión OBO: el agente comienza con una visión general, almacena la lista completa de elementos, la ordena intencionalmente, registra aprobaciones, omisiones y bloqueadores, y puede reanudar más tarde sin reconstruir la sesión a partir del historial de chat.

Ejemplo de juguete: Cinco elementos de revisión

Supongamos que un agente revisa una pequeña aplicación de tareas de juguete y encuentra cinco elementos en este orden de descubrimiento original:

1. Mejorar una etiqueta de configuración ambigua en la interfaz de usuario.

2. Resolver una condición de carrera en el trabajo de sincronización en segundo plano.

3. Añadir una prueba de regresión para IDs de tarea duplicados.

4. Añadir validación de entrada faltante en el endpoint de creación de tareas.

5. Corregir el registro de contraseñas en el manejador de inicio de sesión.

Chat estándar

Agente:

Encontré cinco problemas en la aplicación de juguete: Problema 1: Mejorar una etiqueta de configuración ambigua en la interfaz de usuario. Problema 2: Resolver una condición de carrera en el trabajo de sincronización en segundo plano. Problema 3: Añadir una prueba de regresión para IDs de tarea duplicados. Problema 4: Añadir validación de entrada faltante en el endpoint de creación de tareas. Problema 5: Corregir el registro de contraseñas en el manejador de inicio de sesión.

¿Qué quieres hacer a continuación?

Usuario:

Haz 4 y 2 primero.

Comentario:

• Esto es rápido, pero el chat mismo se convierte en el único registro de la secuencia, la dependencia entre los elementos 4 y 3 es implícita.

• El estado de los otros problemas no se captura, y el usuario deberá solicitar explícitamente que el agente muestre o trabaje en los otros problemas.

• Si la sesión se interrumpe, otro agente tendría que reconstruir el estado a partir de la transcripción.

Chat estilo askQuestions

Agente:

Encontré cinco problemas. ¿Cuál deberíamos hacer primero?

Opciones: • 4. Añadir validación de entrada faltante en el endpoint de creación de tareas • 2. Resolver una condición de carrera en el trabajo de sincronización en segundo plano • 5. Corregir el registro de contraseñas en el manejador de inicio de sesión • 3. Añadir una prueba de regresión para IDs de tarea duplicados • 1. Mejorar una etiqueta de configuración ambigua en la interfaz de usuario

Usuario:

4

Agente:

¿Siguiente acción?

Opciones: • Continuar con 2 • Reordenar la lista restante • Detener

Comentario:

• Esto da opciones de usuario más limpias que el chat simple, pero la herramienta aún no crea un objeto de flujo de trabajo duradero y consciente de las dependencias por sí misma.

• El estado de los otros problemas aún no se captura, y el usuario deberá solicitar explícitamente que el agente muestre o trabaje en los otros problemas.

• Del mismo modo, si la sesión se interrumpe, otro agente tendría que reconstruir el estado a partir de la transcripción.

Sesión One-by-One

Siguiendo las instrucciones del prompt del agente OBO, el agente asigna esta lógica de ordenamiento:

• El elemento 4 va primero porque el comportamiento del endpoint de creación de tareas debe estabilizarse antes de que se escriba la prueba de regresión de seguimiento.

• El elemento 2 viene después porque la condición de carrera puede afectar la corrección a través del flujo de sincronización y puede requerir una sesión de investigación anidada.

• El elemento 5 sigue porque es una corrección de seguridad importante, pero no bloquea el trabajo de validación y concurrencia.

• El elemento 3 se queda detrás del elemento 4 porque la prueba de regresión debería fijar el comportamiento de validación final en lugar de precederlo.

• El elemento 1 sigue siendo útil, pero tiene poco impacto en comparación con los otros cuatro elementos, por lo que va al final.

Agente:

Creé una sesión OBO para 5 hallazgos.

Resumen ejecutivo: • Total de elementos: 5 • Categorías: 1 corrección de API, 1 concurrencia, 1 seguridad, 1 pruebas, 1 UX • Orden de prioridad: 4, 2, 5, 3, 1 • Esfuerzo estimado: 11 • Elementos críticos: 3 • Nota de dependencia: el elemento 3 sigue al elemento 4 para que la prueba de regresión