remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Integrations

The server uses ESLint for syntax checking and fixing as part of its development workflow, as shown in the Local Setup section.
Used for package management and running scripts in the server's development environment.
Used for code formatting in the development workflow, as mentioned in the Format section.

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.

¿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

{
  "initialState": "LOBBY",
  "states": {
    "LOBBY": {
      "name": "LOBBY",
      "actions": {
        "START_GAME": { "name": "START_GAME", "targetState": "PLAYING" }
      }
    },
    "PLAYING":  {
      "name": "PLAYING",
      "actions": {
        "END_GAME": { "name": "END_GAME", "targetState": "GAME_OVER" }
      }
    },
    "GAME_OVER": {
      "name": "GAME_OVER",
      "actions": {
        "RESTART": { "name": "RESTART", "targetState": "PLAYING" }
      }
    }
  }
}

¿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

Los clientes se conectan a un servidor SSE de Puzzlebox.
Los clientes registran los rompecabezas en el servidor.
Los clientes pueden suscribirse a un rompecabezas determinado para recibir actualizaciones cuando su estado cambia.
Los clientes realizan acciones en los rompecabezas que pueden cambiar su estado y las acciones disponibles.
El servidor de puzzlebox garantiza que cualquier acción intentada sea válida para el estado actual del rompecabezas dado.
Si una acción es válida, se inicia una transición al estado de destino.
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).
Si los guardias pasan, la transición de estado se completa.
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.
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

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

Un servidor MCP que permite la coordinación de agentes a través de máquinas de estados finitos compartidas (rompecabezas) donde los clientes pueden crear, monitorear y activar transiciones de estado de recursos con estado.