caja de rompecabezas

Coordinación de agentes con máquinas de estados

Un servidor MCP que aloja máquinas de estados finitos como recursos dinámicos a los que los clientes pueden suscribirse y recibir actualizaciones cuando su estado cambia.

Related MCP server: A2AMCP

¿Qué problema aborda Puzzlebox?

Los equipos necesitan coordinación

Organizar a varios agentes para alcanzar un objetivo grande es más difícil que simplemente dividir una solicitud en tareas, asignarlas a los agentes disponibles y permitir la colaboración entre ellos.

Así como unos pocos agentes pueden colaborar para completar un proyecto pequeño, varios equipos de agentes conscientes de los procesos necesitan operar dentro de distintas fases del proyecto para abordar esfuerzos a largo plazo.

Consideremos los procesos de desarrollo de software a nivel empresarial:

• Un proyecto de software de gran envergadura generalmente sigue un camino de varios pasos, a veces con retrocesos, desde la concepción hasta el diseño, la construcción, las pruebas, la documentación, la comercialización y la producción.

• Diferentes equipos se concentran en distintos aspectos a lo largo del tiempo, informados por lo que sucedió antes y con la mirada puesta en un objetivo en constante cambio que se perfecciona de acuerdo con las lecciones aprendidas.

• Incluso dentro de una fase, los equipos pueden recorrer sus propias fases, como los sprints ágiles. Se define una cantidad de trabajo para el sprint, el equipo trabaja en sus partes y, al final del sprint, decide qué abordar a continuación. Se asume que cada sprint podría cambiar el curso del desarrollo futuro. Estos ciclos también pueden representarse como rompecabezas.

Con Puzzlebox, los miembros de equipos agentes pueden adquirir conciencia del proceso, pero el proceso en sí no está sujeto a alucinaciones.

Escenario: Equipos pasando la antorcha

Tres agentes están trabajando. El estado actual de su rompecabezas compartido es "Especificación".

• El agente 1 está especificando el idioma del dominio.

• El Agente 2 está definiendo el alcance del proyecto.

• El Agente 3 está produciendo el documento de especificaciones.

• Los agentes colaboran para llegar al documento de especificación final.

• Una vez realizada la especificación, el Agente 3 inicia una transición al estado "Diseño".

  • En primer lugar, un protector de salida (es decir, muestreo LLM) verifica que la especificación esté completa.

    • Si se encuentran problemas, se cancela la transición de estado y el equipo continúa.

    • Si es aceptable, el estado cambia a “Diseño”.

      • Los agentes de "Especificación" están monitoreando el rompecabezas y deberían finalizar su sesión ahora.

        • Sus largos (y costosos) contextos han sido destilados en la especificación.

        • El equipo de "Diseño" elige desde aquí, con la especificación como recurso y sus contextos nuevos y específicos para cada rol.

¿Qué es un rompecabezas?

Una cosa con estado sobre la que puedes actuar

Imagina el cubo de Rubik. Tiene 43 trillones de estados, y para cambiar entre ellos, actúas sobre él rotando los planos que se intersecan en el mecanismo.

Propiedades de un rompecabezas

• Un número finito de estados discretos, por ejemplo, "Concepto y tono de la serie", "Construcción del mundo", "Trazado de arco", "Planificación de episodios", "Fusión de líneas argumentales", "Esquema del episodio", "Redacción de guiones", etc.

• Cada estado puede tener cualquier número de acciones (incluida 0) que inician la transición a otro estado.

• Hay un estado inicial.

• Hay un estado actual que puede diferir después de que se hayan realizado acciones en el rompecabezas.

• Las transiciones pueden ser canceladas por los guardias de entrada y salida del estado, por ejemplo, consultar LLM a través de una solicitud de muestreo del cliente.

Un ejemplo sencillo

¿Qué es Puzzlebox?

Muchos clientes que comparten recursos dinámicos

Puzzlebox es una implementación de servidor MCP que:

• Admite múltiples conexiones de cliente que pueden crear y monitorear recursos dinámicos compartidos.

• Administra instancias de rompecabezas

• Expone herramientas para:

  • Añadiendo rompecabezas

  • Obtener una instantánea del estado y las acciones disponibles para un rompecabezas determinado en la caja

  • Realizar acciones en un rompecabezas determinado en la caja que activan transiciones de estado

• Expone rompecabezas registrados como recursos

  • Los clientes pueden usar la plantilla de recursos Puzzle Snapshot para obtener el recurso por ID

  • La URI del recurso es puzzlebox:/puzzle/{puzzleId}

  • Los clientes pueden suscribirse o cancelar la suscripción a URI de recursos individuales

Cómo funciona

1. Los clientes se conectan a un servidor SSE de Puzzlebox.

2. Los clientes registran los rompecabezas en el servidor.

3. Los clientes pueden suscribirse a un rompecabezas determinado para recibir actualizaciones cuando su estado cambia.

4. Los clientes realizan acciones en los rompecabezas que pueden cambiar su estado y las acciones disponibles.

5. El servidor de puzzlebox garantiza que cualquier acción intentada sea válida para el estado actual del rompecabezas dado.

6. Si una acción es válida, se inicia una transición al estado de destino.

7. Durante la transición, los guardias de entrada y salida opcionales pueden enviar solicitudes de muestreo al cliente, cuyos resultados podrían llevar a la cancelación de la transición (piense en pruebas de aceptación por parte de las partes interesadas).

8. Si los guardias pasan, la transición de estado se completa.

9. Cuando un cliente recibe una notificación de actualización de un recurso, puede leer el recurso o utilizar la herramienta get_puzzle_snapshot para obtener el estado actual y las acciones disponibles.

10. Los clientes actualizan su interfaz de usuario en función del nuevo estado.

Herramientas MCP

⚙️ add_puzzle

Agregar una nueva instancia de un rompecabezas (máquina de estados finitos).

• Entradas: Ninguna

• Devuelve: objeto JSON con success booleano y puzzleId

⚙️ get_puzzle_snapshot

Obtenga una instantánea de un rompecabezas (su estado actual y acciones disponibles).

• Entradas: puzzleId

• Devuelve: objeto JSON con currentState y matriz availableActions

• Nota: los clientes de MCP que no admiten suscripciones de recursos pueden sondear esta herramienta para observar los cambios de estado.

⚙️ perform_action_on_puzzle

Realizar una acción en un rompecabezas (intentar una transición de estado).

• Entradas: puzzleId y actionName

• Devuelve: objeto JSON con currentState y matriz availableActions

⚙️ count_puzzles

Obtenga el recuento de rompecabezas registrados

• Entradas: Ninguna

• Devuelve: objeto JSON con count actual de rompecabezas registrados

Configuración local

Instalar dependencias

• cd /path/to/puzzlebox/

• npm install

Construir

• npm run build

• Construye el entorno de ejecución del servidor MCP en /dist/index.js

Comenzar

• npm run start

• Inicia un servidor MCP/basado en SSE en el puerto :3001 con el punto final /sse

• DEBE INICIARSE ANTES DE EJECUTAR INSPECTOR

Inspector

• npm run inspector

• Ejecuta el Inspector de protocolo de contexto del modelo

• La interfaz de usuario del Inspector estará disponible en: http://localhost:5173

• En la interfaz de usuario del Inspector:

  • Asegúrese de que Transport Type esté configurado en SSE

  • Asegúrese de que URL esté configurada en http://localhost:3001/sse

  • Haga clic en el botón "Conectar" para conectarse al servidor de Puzzlebox.

    • Debería ver la luz verde 🟢 y el mensaje "Conectado" .

  • Haga clic en el botón Herramientas de lista

Formato

• npm run format

• Se ejecuta prettier en el código, ajustando el formato.

Comprobación de tipos

• npm run typecheck

• Ejecuta tsc con argumentos para verificar e informar problemas de tipo

Hilas

• npm run lint

• Ejecuta eslint para verificar e informar de forma no destructiva sobre problemas de sintaxis.

Corrección de pelusa

• npm run lint:fix

• Ejecuta eslint para verificar y corregir problemas de sintaxis

Prueba

• npm run test

• Ejecutar las pruebas unitarias

Capturas de pantalla

La prueba del servidor se realizó con el cliente de referencia oficial: MCP Inspector .

0 - Herramientas de lista

1 - Agregar rompecabezas

2 - Obtener una instantánea del rompecabezas (estado inicial)

3 - Realizar una acción en el rompecabezas

4 - Obtener instantánea del rompecabezas (nuevo estado)

5 - Realizar acción en el rompecabezas

6 - Obtener instantánea del rompecabezas (otro estado nuevo)

7 - Lista de recursos

8 - Plantilla de recursos

9 - Recurso no suscrito

10 - Recurso suscrito

11 - Notificación de actualización de recursos