Servidor que permite recorrer un árbol de guía a través de MCP. Cuando el agente envía la etiqueta de una respuesta, se devuelve qué comprobar o guiar a continuación basado en reglas. Al llegar al final, la guía se completa.
Los agentes de bucle automático son flexibles, pero ante la misma consulta toman caminos diferentes cada vez. En atenciones que no se pueden omitir, como reembolsos o verificación de identidad, esto no resiste ni la auditoría ni las decisiones de escalado. Fija los puntos que requieren decisión en un árbol de guía externo y deja solo la parte de redacción al agente.
No es exclusivo para atención al cliente. Como el vocabulario del árbol de guía no depende del dominio, se puede usar en cualquier trabajo que requiera avanzar por procedimientos en orden.
顧客の発話 guidepost-mcp (MCP · 8127)
│ ┌──────────────────────────┐
┌───▼────────┐ values │ flows/*.yaml ← 起動時に │
│ エージェント ├──────────▶│ メモリ常駐（読むだけ） │
│ │◀──────────┤ engine = 純関数で遷移 │
└────────────┘ next │ SQLite = runs / steps │
│ 発話をラベルに └──────────┬───────────────┘
│ 落とすのはこちら側 │ 読み取り専用
▼ ┌───▼──────────┐
顧客へ返す │ Web UI (SSR) │ いま樹形図のどこにいるか
└───────────────┘La interpretación de texto natural a etiquetas la tiene el agente. El servidor solo ve la etiqueta recibida y hace la transición, por lo que no aumenta las llamadas al LLM. En mediciones reales (Raspberry Pi 5), el cálculo de transición es p95 0.006 ms, con SQLite p95 0.76 ms, y de extremo a extremo a través de MCP por HTTP p95 9.1 ms. Como el total de un turno de atención por voz es de unos 2,5 segundos, incluso con HTTP supone un 0,4%. El desglose y cómo se calculó ese presupuesto están en docs/research/voice-agent-latency-budget.md.
flows/<flow_id>.yaml es un árbol de guía. Solo hay 4 tipos de nodos.
kind | Función | Ramificación |
| Escucha un punto de confirmación y ramifica según la etiqueta de la respuesta | Sí |
| Comunica una guía | No |
| Recoge varios elementos independientes en cualquier orden | No |
| Terminal. Tiene | No |
id: payment_failed
title: 支払いが失敗した
entry: n_error_code
max_unmatched: 3 # 聞き直しの上限
max_branch_fanout: 3 # これより枝が多いと畳まない
branch_depth: 2 # 枝を辿って結末を探す深さ
on_unknown: broaden # 分からないと言われたとき。broaden / escalate
on_stuck: 原因が絞れないため、決済窓口の担当者に引き継ぐ
nodes:
- id: n_error_code
kind: ask
say: 決済画面に出ているエラーコードを確認する # 逐語原稿ではなく「何を伝えるか」
accepts: # ラベル → そのラベルに落とす条件
E01: カードが拒否された
E02: 残高不足・限度額超過
next:
E01: n_card_age
E02: n_balance
__other__: n_symptom # 想定外のラベルの逃がし先（任意）
__unknown__: n_generic # 分からないときの逃がし先（任意）
- id: n_identity
kind: collect
say: 本人確認に必要な情報を集める
on_unknown: escalate # 重要な手続きなので畳ませない
slots:
order_id:
ask: 注文番号を聞く
required: true # 埋まらないと進めない
phone: 登録の電話番号を聞く # 短い書き方（任意扱い）
next: n_verify
- id: n_resolved
kind: end
outcome: resolved
say: 解消したことを確認し、対応を締めるsay no es un guion literal, sino material sobre "qué comunicar". El agente adapta la redacción al contexto. Mantén 1 nodo = 1 punto de confirmación o 1 guía.
Al escribirlo, verifícalo. Los nodos inalcanzables o las etiquetas sin destino funcionan en el momento de escribirlos, por lo que no se detectan hasta la ejecución.
uv run guidepost-mcp lint flows/ # CI でも回している
uv run guidepost-mcp show payment_failed --flows flows # 樹形図を木で表示
uv run guidepost-mcp drafts # 預かっている草案の一覧
uv run guidepost-mcp approve refund_request # 草案を検査し直して flows/ へ移す
uv run guidepost-mcp discard refund_request # 草案を捨てるRelated MCP server: sop-mcp
Herramienta | Función |
| Sin argumentos devuelve la lista de categorías y el número de cada una; con |
| Inicia una ejecución. Devuelve |
| Envía una respuesta. Devuelve uno de los 5 estados siguientes |
| Posición actual, ruta y valores recopilados. Para reanudar y transferir |
| Retrocede. Descarta los valores corregidos |
| Cierra sin llegar al final |
| Deposita el árbol de guía como borrador. Devuelve las observaciones del lint. No aparece en la atención |
Como al aumentar los árboles de guía ya no se pueden devolver todos, guide_flows() primero devuelve las categorías (definidas en flows/categories.yaml) y el número de cada una, y con guide_flows(category=...) devuelve la lista de los que están dentro. Si no encaja en ninguna categoría, no lo fuerces y atiende sin usar el árbol de guía.
guide_draft solo guarda el árbol de guía; no aparece en flows/ ni en guide_flows(). Solo se convierte en versión oficial cuando una persona lo aprueba con guidepost-mcp approve. La generación del árbol de guía es trabajo fuera de este servidor y no se contempla generarlo durante la atención (la razón de esta decisión está en docs/adr/0011-draft-intake.md).
Si el cliente dice de una vez "tengo el E01 y la tarjeta es la de hace 3 años", queremos evitar volver a preguntar una por una aunque ya tengamos las respuestas. Si pasas todo lo que sabes en values, avanza mientras esté completo y se detiene en el primer nodo que no esté completo.
収集済み: {n_error_code: E01, n_card_age: over_1y}
n_error_code ──E01──▶ n_card_age ──over_1y──▶ n_expiry_check ──?──▶ …
✓ 聞かずに通過 ✓ 聞かずに通過 ▲ ここで止まるLos nodos omitidos se devuelven como skipped. Para que el agente pueda conocer los ids de los nodos posteriores, guide_start entrega una índice (una línea por nodo/slot sobre qué pregunta) solo una vez.
El orden arbitrario de collect usa el mismo mecanismo. Se puede completar en cualquier orden y se pasa cuando esté completo.
Es normal que quien consulta no tenga la respuesta. Por mucho que insistas, no va a aparecer.
guide_answer
├─ ラベルが accepts にある ──────────▶ advanced / completed
├─ accepts に無い ──────────────────▶ unmatched（聞き直す）
│ │ max_unmatched 回で下へ
└─ choice="__unknown__" ──────────┐ │
▼ ▼
next.__unknown__ があるか
├─ ある ─▶ advanced（逃がし先へ）
└─ 無い ─▶ on_unknown は
├─ escalate ─▶ stalled（有人へ）
└─ broaden ──▶ 枝を畳めるか
├─ できる ─▶ branched
└─ 無理 ───▶ stalledbranched es un estado en el que sin fijar la rama, se presentan los desenlaces de cada rama para guiar. Devuelve el material para armar "si es E01, contacte con la compañía de tarjeta; si es E02, verifique el saldo". Si hay un nodo donde todas las ramas convergen, entra en common, de modo que se puede cerrar con "en cualquier caso, al final haga ○○".
Para procedimientos donde guiar con ambigüedad causa daño, como reembolsos o verificación de identidad, escribe on_unknown: escalate para no plegarlos. El lint señala los nodos que no se pueden plegar, así que solo hay que tratar esos.
uv sync
uv run uvicorn guidepost_mcp.web:app --host 127.0.0.1 --port 8127
uv run python scripts/mcp_smoke.py # 実プロトコルで 1 周辿る
uv run python scripts/mcp_smoke.py --parallel # 2 本の run を交互に進めるLa interfaz web está en http://127.0.0.1:8127/. Se listan las ejecuciones en curso y en /r/<run_id> se muestran sobre el árbol de guía, con colores, la posición actual, la ruta recorrida, los nodos omitidos por adelantado y los nodos con ramas plegadas.
Desde el lado del agente se conecta como MCP por HTTP.
from langchain_mcp_adapters.client import MultiServerMCPClient
client = MultiServerMCPClient(
{
"guidepost-mcp": {"url": "http://127.0.0.1:8127/mcp/", "transport": "streamable_http"},
}
)
tools = await client.get_tools()La versión oficial es la única version en pyproject.toml y sigue SemVer (durante 0.x, los cambios menores pueden ser destructivos). El historial de cambios está en CHANGELOG.md.
Qué cambios se consideran destructivos está definido en docs/adr/0009-versioning.md. El punto clave es el esquema YAML del árbol de guía y el contrato de las herramientas MCP (nombres de herramientas, argumentos, claves de valores de retorno y los 5 valores de status); no se incluye el texto de las instrucciones de next.
La version de flows/*.yaml es la versión del procedimiento de atención y no tiene relación con la versión de esta librería.
Por qué se deja la interpretación de etiquetas al agente, por qué se pliegan las ramas ante "no lo sé" y por qué la interfaz web es de solo lectura está documentado con razones en docs/adr/ (la lista está en docs/adr/README.md). Las investigaciones que sirvieron de base para las decisiones están en docs/research/.
This server cannot be deployed
Deterministic decision layer for autonomous agents: reproducible PROCEED/REVIEW/SKIP verdicts.
Deterministic reasoning stack for AI agents: simulate, decide & compute, plus cross-domain tools.
The system of record for AI agent authority: playbooks, routed policy questions, reusable rules.
Deterministic contextual decision arbitration and action routing for autonomous software. Takes current state, context, or intent plus caller-supplied candidate actions, state transitions, routes, refusals, escalations, tools, or models and returns a deterministic ordered candidate field. Also provides persistent machine representations for memory, retrieval, indexing, and downstream coherence measurement.
