convez.ai
MCP ServerAutomaçãoIntermediário
msradam

Theodosia: Máquina de Estados Burr via MCP

msradam/theodosia

Máquina de estados controlada para agentes, com validação automática de transições

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que monta máquinas de estado Apache Burr, permitindo que agentes de IA naveguem apenas pelos próximos passos válidos com validação de reachability automática. Cada ação é registrada e reexecutável, garantindo fluxos de trabalho controlados e auditáveis.

Instalação

$npx convez-ai msradam/theodosia

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
16
Forks
1
Acompanhando
0
Saúde
100%
Último commit
há 2 semanas
Versão
v0.5.0
Issues abertas
5
Contribuidores
1

Casos de uso

  • Fluxos de trabalho multi-etapas com estados definidos (pedidos, aprovações, processamento)
  • Agentes que precisam seguir um caminho específico sem desvios
  • Auditoria e replay de sequências de ações de IA

Veredito

Excelente para criar agentes confiáveis em processos estruturados. Resolve o problema real de agentes tomarem ações inválidas ao combinar Burr com MCP, com suporte a observabilidade e replay automático.

README

A tradução para o português deste README ainda está na fila.

Theodosia

PyPI tests License Docs Built on Apache Burr Built on FastMCP

Theodosia mounts a Burr Application as an MCP server. Every Burr action is reachable through a single step(action, inputs) tool; the server checks reachability against the graph before each action runs, refuses out-of-order calls with the legal next moves, and records every attempt.

A coffee-order FSM driven over MCP, with a refusal and recovery

Install

Python 3.11, 3.12, or 3.13 (Burr does not yet support 3.14). On a fresh Python 3.14 install you will see "no version that satisfies the requirement theodosia"; create a 3.11–3.13 venv first.

uv venv --python 3.13       # or: python3.13 -m venv .venv
uv pip install theodosia    # or: pip install theodosia

Optional extras: theodosia[observability], theodosia[ui], theodosia[claude], theodosia[mellea], theodosia[all].

On a slim Docker image (python:3.13-slim, Alpine) the install pulls a psutil build that needs gcc and python3-dev. Either use the full python:3.13 image, or apt-get install -y gcc python3-dev before pip install.

Try it without an API key

theodosia primer

Walks the coffee-order FSM through Theodosia's step tool in-process and prints the timeline with state diffs and one structured refusal. No LLM, no network, same output every run.

Quickstart

from burr.core import ApplicationBuilder, State, action
from burr.core.action import Condition
from theodosia import mount


@action(reads=[], writes=["item", "stage"])
def take_order(state: State, item: str) -> State:
    return state.update(item=item, stage="ordered")


@action(reads=["stage"], writes=["stage"])
def pay(state: State, amount: float) -> State:
    return state.update(stage="paid")


def build_application():
    is_ordered = Condition.expr("stage == 'ordered'")
    return (
        ApplicationBuilder()
        .with_actions(take_order=take_order, pay=pay)
        .with_transitions(("take_order", "pay", is_ordered))
        .with_state(item=None, stage="empty")
        .with_entrypoint("take_order")
        .build()
    )


if __name__ == "__main__":
    mount(build_application, name="coffee").run()

Save as coffee.py and run python coffee.py to serve over stdio. Pass a factory (a callable returning a built Application) so each MCP session gets its own isolated state. Passing an already-built Application works too but shares state across sessions.

Exercise the server in-process with FastMCP's Client:

import asyncio
from fastmcp import Client
from coffee import build_application

async def main():
    async with Client(mount(build_application, name="coffee")) as client:
        r = await client.call_tool("step", {"action": "pay", "inputs": {"amount": 5.0}})
        print(r.structured_content)
        r = await client.call_tool("step", {"action": "take_order", "inputs": {"item": "mocha"}})
        r = await client.call_tool("step", {"action": "pay", "inputs": {"amount": 5.0}})
        print(r.structured_content)

asyncio.run(main())

A client that calls pay before take_order gets a structured refusal it can recover from:

{ "error": "invalid_transition", "valid_next_actions": ["take_order"] }

Primitives

  • mount(application, *, hooks=[...], middleware=[...], upstream=..., personas=...) wraps a Burr Application (or factory) as a FastMCP server. Returns the server; call .run() or pass to FastMCP's in-memory Client. Optional kwargs forward Burr LifecycleAdapter, FastMCP Middleware, upstream MCP clients, and PERSONA.md identity layers.
  • The four MCP tools every mounted server exposes: step(action, inputs), reset_session, fork_at(sequence_id), fork_from_past(app_id, sequence_id). The action namespace lives in step's argument schema; FSM complexity changes the schema, not the tool count. FastMCP's ResourcesAsTools transform adds list_resources and read_resource for clients that lack native resources/read.
  • Structured refusals from step: invalid_transition, unknown_action, validation_failed, action_timeout, action_error. Every refusal carries valid_next_actions. fork_at / fork_from_past return their own error codes on the same wire shape.
  • theodosia:// resources for inspection: graph, state, next, history, subruns, trace, session.
  • upstream lets a Burr action body call tools on other MCP servers through call_upstream(server, tool, args). The agent driving Theodosia never sees those servers; it only sees step.

Full reference (Persona, Assembly, hooks, middleware, tracker, drive_claude) lives in the docs.

Scope

Theodosia does not include an agent, a model, or a workflow engine. It mounts an existing Burr Application and gates an MCP client's access to it. The rails are only as tight as the graph you author.

Command line

theodosia serve module:app                       # mount as MCP server (stdio, default)
theodosia serve module:app --transport http --port 8000   # serve over HTTP
theodosia render module:app                      # draw the state machine in the terminal
theodosia doctor module:app                      # statically validate the graph; exits nonzero for CI
theodosia sessions show <id>                     # full timeline: per-step state diff + timing
theodosia sessions diff <a> <b>                  # cross-session: action-path divergence + final-state diff
theodosia watch                                  # live-tail a running session
theodosia logs --refusals                        # only the steps that were refused
theodosia status                                 # tracker storage + recent activity snapshot
theodosia verify                                 # recompute the ledger hash chain
theodosia primer                                 # offline first-touch, no API key
theodosia ui                                     # open the Burr UI

A downstream package can ship its own command (my-fsm serve, my-fsm doctor, ...) with build_cli.

Documentation

Full docs at msradam.github.io/theodosia.

PageCovers
IntroductionWhat Theodosia is and the primitives you reach for
Build your own agentEnd-to-end: write a Burr graph, serve it, drive it with an MCP client
Authoring a graphThe Burr building blocks: @action, Condition, with_transitions
Architecturemount(), the four-tool surface, the action-selection bridge
RefusalsThe five refusal shapes and how the agent recovers
SessionsPer-session isolation, fork_at, fork_from_past, partition keys
Security modelThe trust boundary, what the ledger does and does not prove
ObservabilityThe theodosia:// resources, CLI, Burr UI, OpenTelemetry
PersonasPERSONA.md identity layer mounted as MCP prompts
UpstreamCalling other MCP servers from action bodies
CompatibilityWhat works through mount() (typed state, persistence, hooks, parallelism, telemetry)
CLIserve / doctor / render / sessions / watch / logs / status / report / primer, and build_cli
Deployment recipesCopy-pasteable configs: Claude Code, Cursor, mcphost, fast-agent, HTTP, SSE, Lambda, Kubernetes
Case studyKimi K2.6 on Grafana o11y-bench: free-ranging vs gated
Research foundationThe published evidence the design rests on

Examples and tests

examples/ ships self-contained FSMs covering pure-FSM, typed state, hooks, persistence, real shellouts, LLM-in-the-graph, SKILL-to-FSM, upstream, and multi-graph. Each runs with uv run python examples/<file>.py. The test suite runs with uv run pytest.

Compose with Philip

Philip lifts declarative artifacts (Ansible YAML, Mermaid stateDiagram-v2, Excalidraw) into Burr Application instances that theodosia.mount() serves directly.

Acknowledgements

Theodosia is glue between two libraries that do the hard parts: Apache Burr provides the state-machine Application, the transition graph, and the tracking UI; FastMCP provides the MCP server, the transforms, and the client behind upstream. The SKILL demos under examples/skills/ are reproduced verbatim from Anthropic and Trail of Bits with attribution.

Theodosia is an independent project, not affiliated with or endorsed by the Apache Software Foundation, DAGWorks, the Apache Burr project, or FastMCP.

License

Apache 2.0. Theodosia is independent open-source work by Adam Munawar Rahman and does not represent the views of IBM Corporation or any other employer. See NOTICE.md.

Ver o original no GitHub

Bom para

Relacionados