guidepost-mcp

A server that walks a guidance tree via MCP. When the agent throws in the label of an answer, what should be checked or guided next comes back rule-based. Traverse all the way to the end and the guidance is complete.

Self-looping agents are flexible, but the same inquiry takes a different route every time. For interactions that must not be missed — refunds, identity verification — that is not something audit or escalation decisions can stand. The spots that require judgment are fixed outside the model as a tree, and only the wording is left to the agent.

It is not CS-only. The tree's vocabulary is not domain-dependent, so the server works for any job that advances through steps in order.

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

Natural text → label interpretation lives on the agent side. The server only sees the label it receives and transitions, so no LLM calls are added. Measured on a Raspberry Pi 5, transition computation is p95 0.006ms, p95 0.76ms including SQLite, and p95 9.1ms end-to-end through the HTTP MCP. A single voice-response turn totals about 2.5 seconds, so this is 0.4% even with HTTP. The breakdown and how the budget was drawn are in docs/research/voice-agent-latency-budget.md.

Writing a tree

Each flows/<flow_id>.yaml is one tree. There are only four node kinds.

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 is not a verbatim script; it is the material for "what to convey". The agent adjusts the wording to the situation. Keep it at 1 node = 1 check item or 1 guidance.

Validate after you write. Unreachable nodes and labels without a destination still run at write time, so you cannot notice them until runtime.

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

MCP tools

Answers accumulate and the flow auto-advances as far as they are filled

When the customer says "I get E01 and the card is the one from 3 years ago" in one go, we do not want to ask again one question at a time when we already have the answers. If you pass all known values in values, the flow advances as long as they are filled and stops at the first node that is not filled.

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

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

Skipped nodes are returned as skipped. So that the agent can learn the IDs of upcoming nodes, guide_start passes the index (one line per node / slot describing what it asks for) only once.

collect unordered items run on the same mechanism; whichever order you fill them, the node passes at the moment they are complete.

It does not stop at "I don't know"

Callers often do not have the answer. Persisting will not bring it out either.

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

branched is a state that presents all branches and their endings without confirming one branch. The material to compose "if E01, contact the card company; if E02, check the balance" comes back. If there is a node where all branches converge, it goes into common, so you can close with "in either case, at the end, ◯◯".

For procedures where guiding while ambiguous does harm — refunds, identity verification — write on_unknown: escalate and do not collapse the branches. The nodes that cannot be collapsed are named by lint, so you only need to treat those.

Running

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 を交互に進める

The Web UI is at http://127.0.0.1:8127/. Running runs are listed; at /r/<run_id>, the current position, the route taken, the nodes skipped by lookahead, and the nodes where branches were collapsed are color-coded on the tree.

On the agent side, connect as an HTTP MCP.

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()

Versioning

The single source of truth is the version in pyproject.toml, and it follows SemVer (during 0.x, a minor version can contain breaking changes). The change history is in CHANGELOG.md.

What counts as a breaking change is defined in docs/adr/0009-versioning.md. The key point is the tree YAML schema and the MCP tool contract (tool names, arguments, return keys, the five status values); the wording of the next instruction is not included.

The version in flowaine/*.yaml is the version of the handling procedure and is unrelated to the version of that library.

Design background

Why label interpretation is on the agent side, why branches fold on "I don't know", and why the Web UI is read-only are recorded with reasons in docs/adr/ (index in docs/adr/README.md). The research that became the basis of the decision is in docs/research/.