guidepost-mcp

Servidor para hacer recorrer el árbol de decisión a través de MCP. Cuando el agente envía la etiqueta de una respuesta, se devuelve mediante reglas qué debe confirmar o indicar a continuación. Si se avanza hasta el final, el recorrido de la orientación queda completo.

Los agentes de bucle autorreferente son flexibles, pero, a cambio, ante la misma consulta recorren cada vez un camino distinto. Cuando la atención no puede fallar, como en el caso de un reembolso o de la verificación de identidad, eso no se sostiene ni ante una auditoría ni ante una decisión de escalada. Por eso los lugares que requieren criterio se fijan fuera, como un árbol ramificado, y solo se deja al agente la parte de expresarlo con palabras.

No es solo por CS. Ya que el vocabulario del árbol de decisión no depende del dominio, sirve para cualquier trabajo que avanza un trámite por pasos.

  顧客の発話                      guidepost-mcp (MCP · 8127)
      │                    ┌──────────────────────────┐
  ┌───▼────────┐  values   │ flows/*.yaml ← 起動時に   │
  │  エージェント  ├──────────▶│   メモリ常駐（読むだけ）  │
  │             │◀──────────┤ engine = 純関数で遷移     │
  └────────────┘  next     │ SQLite = runs / steps    │
      │  発話をラベルに        └──────────┬───────────────┘
      │  落とすのはこちら側                │ 読み取り専用
      ▼                              ┌───▼──────────┐
   顧客へ返す                          │ Web UI (SSR)  │ いま樹形図のどこにいるか
                                     └───────────────┘

La interpretación de «texto natural → etiqueta» es responsabilidad del agente. El servidor solo observa la etiqueta recibida y efectúa la transición, por lo que no se aumenta ninguna llamada al LLM. En mediciones reales (Raspberry Pi 5) el cálculo de la transición es p95 0.00620 ms; incluyendo SQLite p95 0.76ms; con extremo a extremo por MCP sobre HTTP p95 9.1ms. Como el total de una trayectoria de atención vocal estas 2.5s, incluso incluyendo HTTP por es tan solo el 0.4%. El desglose y cómo se ha dibujado ese presupuesto en docs/research/voice-agent-latency-budget.md.

Cómo escribir el árbol de decisión

flows/<flow_id>.yaml es un árbol de decisión completo. Hay solo 4 tipos de nodos.

(表单 recommendation: "Rol".

For 分岐 column use "Sí"/"No" in Spanish; awaiting the table: | kind | Rol | Se ramifica | | ask | Pregunta de un punto de comprobación y se ramifica según la etiqueta de respuesta | Sí | | etc. incorporate.

Resumen float.

Let me choose more elegantly:

OK. I'll go.

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 script literal, no, sino material de «qué se transmite». La forma de decirlo la adapta el agente a la ocasión. Y se mantiene a 1 nodo = 1 confirmación o 1 indicación.

Después de escribirlo, se valida: los nodos inalizables o etiquetas sin destino todavía funcionan en el momento de escritura, 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   # 樹形図を木で表示

MCP tools

Las respuestas se acumulan y se avanza automáticamente solo en lo que queda cubierto

Cuando un cliente cuenta todo de una vez, por ejemplo «sale por E01 y la tarjeta es la de hace 3 años», aunque ya tienes la respuesta, no queremos volver a preguntar una por una. Si pasas en values todo lo que está book, seguirás mientras queden partes cubiertas y se pararía en el primer nodo que no esté cubierto.

  収集済み: {n_error_code: E01, n_card_age: over_1y}

  n_error_code ──E01──▶ n_card_age ──over_1y──▶ n_expiry_check ──?──▶ …
   ✓ 聞かずに通過        ✓ 聞かずに通過           ▲ ここで止まる

Los nodos que se pasan de largo se devuelven com skipped. Para que el agente pueda conocer los ids de los nodos posteriores, guide_start proporciona el índice (una línea por cada nodo / slot con la pregunta) una sola vez.

Lo mismo sirve para el desorden de collect. No importó el orden en que se vaya llenando, cuando esté completo, se superará.

No te detengas ante un «no lo sé»

No es extra que quien hace la consulta no tenga una respuesta. Por mucho что vuelvas a preguntar énxi, lo que no está no falta; no aparece.

   guide_answer
        ├─ ラベルが accepts にある ──────────▶ advanced / completed
        ├─ accepts に無い ──────────────────▶ unmatched（聞き直す）
        │                                       │ max_unmatched 回で下へ
        └─ choice="__unknown__" ──────────┐   │
                                          ▼   ▼
                               next.__unknown__ があるか
                                  ├─ ある ─▶ advanced（逃がし先へ）
                                  └─ 無い ─▶ on_unknown は
                                              ├─ escalate ─▶ stalled（有人へ）
                                              └─ broaden ──▶ 枝を畳めるか
                                                   ├─ できる ─▶ branched
                                                   └─ 無理 ───▶ stalled

branched es un estado que indica y muestra las consecuencias de cada rama en paralelo sin fijar la rama. Se obtiene el material para construir explicaciones del tipo «si es E01, vaya a la entidad de la tarjeta; si es E02, estaban vigilante el saldo». Si hay un nodo que reúna todas las ramas, se cuelga en common, de esta manera se cierra la frase con «en cualquiera de todos los casos, por último, XX».

En procedimientos en los que orientar la indecisión d del mismo modo caused deaths, como los reembolsos o la fehaciencia de identidad, se escribe on_unknown: escalate para no plegarlos. Los nodos impossible de plegar se nombran directamente desde lint, por lo que basta atender solo a la.

起动

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 web UI es accesible en http://127.0.0.1:8127/; se lista runs en ejecución, en /r/<run_id> el próprio árbol: draw color the current punto, the camino recorrido, nodos skiped de projection and las nodos con segment rama.

En el lado de la 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()

Versión

La fuente canónica de version is unique; the version of pyproject.toml, and follows SemVer (0.x can include breaking changes (changes in minor)). El historial de cambios está en CHANGELOG.md.

¿Qué debe cambiarse para que sea breaking change? está definido en docs/adr/0009-versioning.md. Resumen: este lan YAML del árbol and la contrato de entitled tools MCP (tool name, arguments, return keys, and the 5 values of status), but the next in instructions text is not.

"No incluir" → "la redacción de las instrucciones de next no se incluyin".

"El version of flows/all palm yaml es la versión de los procedimiento de atención, y no取决于 library version. ?? no relation avoids relation with lib."

Antecedentes del design

"Por qué ..."etc.

Ok I'll fine-tune "Pop.

I will produce the final now with careful written prose, avoiding "es" before draft errors. Let me compose final textual response in one go.

Structure out:

guidepost-mcp

Servidor para hacer recorrer el árbol de decisión mediante MCP. Cuando el agente envía la etiqueta de respuesta, se devuelve por reglas qué…...

I'll make sure to not have extra blank lines where not in original. That's fine.

Let's assemble:

guidepost-mcp

Servidor para hacer recorrer el árbol de decisión a través de MCP. Cuando el agente envía la etiqueta de respuesta, se devuelve con lógica de reglas qué debe confirmar o indicar ahora a continuación. Si llega al final, la orientación queda completa.

Los agentes de bucle autorreferente son flexibles, pero a cambio, en una misma consulta recorren cada vez un camino distinto. En aquellas atenciones en las que no se puede fallar, como reembolsos o verificación de identidad, esto no resiste ni una auditoría ni una decisión de escalada. Los puntos donde hay que decdise fijan en el exterior como árbol, y solo la parte que consiste en decirse deja. app.get agente.

No es para atención al cliente únicamente. Como la del vocab(body) del árbol no depende del dominio, sirve para cualquier trabajo forward trámite en orden.

  顧客の発話                      guidepost-mcp (MCP · 8127)
      │                    ┌──────────────────────────┐
  ┌───▼────────┐  values   │ flows/*.yaml ← 起動時に   │
  │  エージェント  ├──────────▶│   メモリ常駐（読むだけ）  │
  │             │◀──────────┤ engine = 純関数で遷移     │
  └────────────┘  next     │ SQLite = runs / steps    │
      │  発話をラベルに        └──────────┬───────────────┘
      │  落とすのはこちら側                │ 読み取り専用
      ▼                              ┌───▼──────────┐
   顧客へ返す                          │ Web UI (SSR)  │ いま樹形図のどこにいるか
                                     └───────────────┘

The interpretation of natural text → label lies with the agent. The server just voy la label received and transitions, so no se incremente el número de llamadas al LLM. In measurements (Raspberry Pi 5) delay p95 of the transition process is 0.0062ms; containing with SQLite p95 0.76ms; через GIMP? HTTP end-to-end p95 9.1ms. One voice attention turn, sum ~2.5 s, as even con HTTP, equiv al 0. 4%. in breakdown (after budget...) lo tienes en docs/research/voice-agent-latency-budget.md.

Cómo escribir el árbol de decisión

... (etc.)

OK. Let me now obey and not use sleeve — write final.

One clarification on "同じ問い合わせでも毎回違う道筋を辿る" — "even for same inquiry, diferentes camino". I'll include "aunque sea la misma consulta". Good.

Also "耐えない" - won't withstand. "no es sustainable on audit": "no queda amparado" . But have "esto no soporta una بounds de йisk..." I'll use "no es sostenible ante una auditoría ni ante una decisión de escalación". Better.

Tell "escap à "decible de acuerdo, escaalización" is fine.

Now final valid.

Important: In the table role for tell: "1つの案内を伝える" - communicate a single guidance -> "Anuncia una única indicación". Row "ask" role: "Pregunta una única confirmación (或 ..)."

Let's produce final copy/No code fence; only# guidepost-mcp

Servidor para hacer recorrer el árbol de decisión a través de MCP. Cuando el agente envía la etiqueta de una respuesta, se devuelve mediante reglas qué debe confirmar o guiar a continuación. Si recorre hasta el extremo, la orientación queda completa.

Los agentes de bucle autorreferente son flexibles, pero a cambio, ante una misma consulta recorren cada vez un camino distinto. En una atención que no se puede fallar, como un reembolso o la verificación de identidad, esto no se sostiene frente a una auditoría ni frente a una decisión de escalamiento. Los puntos en los que se requiere evaluar se fijan fuera, como un árbol de decisión, y solo la parte de señalarlo con palabras se deja al agente.

No es exclusivo de CS. Al no atar el vocabulario del árbol de decisión a ningún dominio, se puede en cualquier trabajo que adelante procedimientos en orden.

  顧客の発話                      guidepost-mcp (MCP · 8127)
      │                    ┌──────────────────────────┐
  ┌───▼────────┐  values   │ flows/*.yaml ← 起動時に   │
  │  エージェント  ├──────────▶│   メモリ常駐（読むだけ）  │
  │             │◀──────────┤ engine = 純関数で遷移     │
  └────────────┘  next     │ SQLite = runs / steps    │
      │  発話をラベルに        └──────────┬───────────────┘
      │  落とすのはこちら側                │ 読み取り専用
      ▼                              ┌───▼──────────┐
   顧客へ返す                          │ Web UI (SSR)  │ いま樹形図のどこにいるか
                                     └───────────────┘

La interpretación de «texto natural → etiqueta» corresponde al agente. El servidor solo observa la etiqueta recibida y realiza la transición, por lo que no se incrementan las llamadas al LLM. En mediciones reales (Raspberry Pi 5), el cálculo de la transición arroja p95 0.006²\nientras, incluyendo SQLite p95 0.76 ms, y de extremo a extremo por MCP de HTTP p90 9.1 ms. Como la suma de un turno de atención por voz es de aproximadamente 2.5 s, incluso con HTTP equivale al 0.4%. Desglose y la forma en se exogenous deduced that budget: docs/research/voice-agent-latency-budget.md.

Cómo escribir el árbol de decisión

flows/<flow_id>.yaml is a tree one. Only four node kind.

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 de «qué se transmite». La fórmula de las palabras la ajusta el agente al contexto. Mantener 1 nodo = 1 confirmación or 1 indication.

Después de escribirlo, se valida. Los nodos no alcanzable y las etiquetas sin destino, justo al escribirloS no hay ca todavía se han escrito, por lo que no se detectan hasta ejecución.

uv run guidepost-mcp lint flows/          # CI でも回している
uv run guidepost-mcp show payment_failed --flows flows   # 樹形図を木で表示

MCP

Las respuestas se acumulan y se avanza solo y auto, a lo que se ha completado

Cuando el cliente de una vez, por ejemplo, «la E01 y la tarjeta es la de hace tres años», aunque tenga의 답已有 no queremos repites allow-pro One a utilice. Si en values se entregan todas las disponibles, se avanza constantajo completadas, y se detiene en el primer nodo criterio no completado.

  収集済み: {n_error_code: E01, n_card_age: over_1y}

  n_error_code ──E01──▶ n_card_age ──over_1y──▶ n_expiry_check ──?──▶ …
   ✓ 聞かずに通過        ✓ 聞かずに通過           ▲ ここで止まる

Los nodos que ha volado se regresan como salter assignments. Para que el agente conozca el id de nodos posteriores, guide_start entrega unas índice (dos observedone line especifica qué pregunta cada node/slot) una sola vez.

Misma operates la de collect bulkhead; familiar incluso a medida: da sha igu for each order. Cualquier sea el order, cuando está completo se pasa adelante.

«No-sé» no es blocking

No es infrecuente que quien consulta no tenga la pregunta. Por más que se askرور, una y otra, aparece no.

   guide_answer
        ├─ ラベルが accepts にある ──────────▶ advanced / completed
        ├─ accepts に無い ──────────────────▶ unmatched（聞き直す）
        │                                       │ max_unmatched 回で下へ
        └─ choice="__unknown__" ──────────┐   │
                                          ▼   ▼
                               next.__unknown__ があるか
                                  ├─ ある ─▶ advanced（逃がし先へ）
                                  └─ 無い ─▶ on_unknown は
                                              ├─ escalate ─▶ stalled（有人へ）
                                              └─ broaden ──▶ 枝を畳めるか
                                                   ├─ できる ─▶ branched
                                                   └─ 無理 ───▶ stalled

branched es un estado en el que no your flecha de ramificación y proporciona, en paralelo, las consecuencias de cada rama. De se vuelve un material de orientación etc. «Si en E01, a la entidad de la tarjeta; si E02, revisa el balance». Si todos the ramas have nodo común, you el diam into the common set y la idiomation es «en cualquier caso, hasta el último hacer XXX».

En procedimientos donde enfrentar de manera ambigua conduce a daño como reembolsos o 등 identificación, se escribe on_unknown: escalate para no plegarlos. Los nodos que нельзя plegar los reprueba lint con el nombre, por open has que ajusta solo esos.

Arranque

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/. En ella se listan las ejecuciones activas; en /r/<run_id> se colore sobre el árbol: actual route, el camino recorrido, la nodos saltados por lookahead y los nodos de rama plegada.

Desde el agente se connecta como un 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()

Versión

La fuente autorizada de la versión es version in pyproject.toml only and follows SemVer (while 0.x, a versión menor puede introduced breaking changes). Historial de cambios en la CHANGELOG.md.

Qué qualifies as cambio rompción está presente in docs/adr/0009-versioning.md. The key is el esquema YAML del árbol de decisión y el contrato de las vías de MCP (nombres de herramientas, relat arg del, claves de valores de retorno, y —5 valores status); en cambio, no se incluye la redacción del director de bloque next.

En version de la *flows* *.yaml` it is la versión del procedimiento de atención, yes in cable not relacionada con la versión de la esta biblioteca.

Antecedentes del diseño

value en la of the approach why the etiquetado interpretation queda en el lado agente, en la rama strings and legs do «no sé», and parenticiary Web UI become read-only, queda? están registrados with razón en docs/adr/ (the list está en docs/adr/README.md). The investireccións que sirvieron a las decisiones se encuentran en docs/research/.