Playbook

Procedimientos como JSON. Búscalos por intención, recorre los títulos, carga un do cada vez.

Playbook es un pequeño servidor CLI y MCP para que un agente (o tú) pueda escribir, encontrar y seguir procedimientos sin volcar todo el playbook en el contexto. Los verbos de la CLI permanecen separados. MCP comprime los verbos relacionados en menos herramientas. Todo es JSON.

Python 3.10+, solo stdlib en tiempo de ejecución.

Instalación

pip install -e .
playbook search

Aún no está publicado en PyPI.

Related MCP server: servicenow-platform-mcp

Dónde residen los archivos

Un archivo JSON por procedimiento, en el directorio de datos de la plataforma:

Respeta XDG_DATA_HOME / APPDATA / LOCALAPPDATA. Los comandos reciben un id de procedimiento, no una ruta.

Estructura

{
  "id": "follow-playbook",
  "title": "Follow a playbook procedure",
  "description": "When to pick this file. Can be verbose.",
  "tags": ["playbook", "follow"],
  "steps": [
    {
      "id": "a1b2c3…",
      "title": "Search by intent",
      "do": "Call playbook_search with a sentence for the job."
    }
  ]
}

• title — nombre corto en las tarjetas de búsqueda

• description — cuándo elegir este procedimiento

• steps — secuencial. Títulos únicos. IDs de paso aleatorios. do es el trabajo.

CLI

Cada comando imprime JSON (incluidos los errores).

playbook create demo --title "Demo" --description "when to pick this" --tags demo
playbook add-step demo --title "First" --do "Do the first thing."
playbook add-step demo --title "Middle" --do "Do the middle." --after "First"
playbook edit demo --title "Better title"
playbook search "I want to follow a procedure"
playbook load demo
playbook load demo --full
playbook start demo --title "First"
playbook validate demo
playbook mcp

search es BM25 más n-gramas de caracteres. Los resultados son solo id, title, description (por defecto 8, tope 50). Las coincidencias débiles se descartan.

load es solo títulos. --full incluye todos los do. start es un do más los títulos before / after.

MCP (Grok)

grok mcp add --scope user playbook -- playbook mcp

Usa una ruta absoluta a playbook si el proceso iniciado no va a tener tu PATH de shell. Luego /mcps y r, o una sesión nueva.

Pruebas

pip install -e .
python -m pytest tests/ -q

Licencia

MIT