Skip to content

Add Protocol Builder screen for designing session-type interaction protocols #1280

@chrisbartoloburlo

Description

@chrisbartoloburlo

Summary

Add a Protocol Builder screen to the v2 Inspector that lets users visually design session-type protocols for the tools exposed by the connected MCP server, then export the result as a runtime-checkable protocol DSL plus a Python integration snippet.

Motivation

When an MCP server exposes a set of tools, an LLM client typically follows an implicit interaction protocol — "first call `search`, then `book` with the chosen result". Today that protocol lives in prompts and prose; nothing checks it at runtime.

Session types give a precise way to write down such interaction protocols (`!search.?searchResult.!book.?bookConfirmation.end`) and verify them with a finite-state monitor. The Protocol Builder makes that practical from inside the Inspector: discover tools, drag them into a sequence, branch with internal/external choice, loop with recursion, and copy out a DSL string the client can monitor against.

This is closely related to issue #1034 (MCP Server Interface Diff Tool) and #516 (validate tool invocation): all three are about making MCP server contracts more explicit. The Protocol Builder targets the interaction shape rather than the type schema of a single call.

The same component shipped on v1 in PR #1224 — this issue tracks porting it to v2's architecture (Mantine, dumb-component split, ≥90% coverage).

Proposal

A new screen at `clients/web/src/components/screens/ProtocolBuilderScreen/` with the supporting groups in `clients/web/src/components/groups/`. Layout follows existing screens (3-column `Flex` with sidebar palette + middle sequence + right output panel).

Features (parity with v1 PR #1224):

  • Tool palette built from the connected server's `tools` list (clicking a tool appends a paired `!Tool.?ToolResult` to the sequence)
  • Protocol-construct palette: send/receive pair, internal choice `!{}`, external choice `?{}`, recursion `rec X`, loop-back references
  • Editable sequence with paired `!?` cards, branch cards, recursion scopes, and a "convert pair → choice" shortcut
  • "Insert target" indicator so palette clicks add into a specific branch
  • Live-rendered outputs: syntax-highlighted DSL, FSM state-machine preview, copy-pasteable Python integration snippet, downloadable `.py` file
  • Smart label suggestions (sender labels feed receiver dropdowns, sibling labels are excluded from branch label dropdowns)

v2 conformance:

  • Mantine components only (`Box`/`Group`/`Stack`/`Flex` for layout, no raw `div`)
  • No inline styles, no raw hex/rgba — uses `--inspector-*` tokens (may need to add a few for "send" green / "receive" blue / "recursion" amber surfaces)
  • Strict types, no `any`
  • Dumb component: takes `tools` and an `onRefreshTools` callback as props, owns local sequence state internally
  • Tests via `renderWithMantine` + `@testing-library/user-event`, ≥90% line coverage per file
  • Storybook stories with fixtures
  • Wired into `InspectorView` as a new tab ("Protocol Builder") in `ALL_TABS`

Acceptance criteria

  • `ProtocolBuilderScreen` renders with a tool palette, an editable sequence, and an output panel showing the DSL, an FSM preview, and a Python snippet
  • Clicking a tool, a construct, or a rec-var loop-back updates the sequence and the rendered DSL stays in sync
  • Choices nest correctly; converting a paired `!?` to a choice preserves the sibling
  • Wired into `InspectorView`'s tab list, available once a server is connected
  • `npm run validate` passes (format, lint, build, test:coverage with the per-file 90/85/80/50 gate)
  • Stories cover empty / populated / with-choice / with-recursion states

Reference

The v1 implementation lives in PR #1224 (`client/src/components/ProtocolBuilderTab.tsx`, ~1.8k LOC). The v2 port will split it into a screen + ~3 group components and rewrite the UI in Mantine.

Background on session-type runtime monitoring: Bartolo Burlò, Francalanza, Scalas — On the Monitorability of Session Types, in Theory and in Practice (ECOOP 2021). Reference implementation of the runtime: `llmsessioncontract` on PyPI / llmcontract.dev.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions