{"id":51429720,"url":"https://github.com/msradam/coffee-agent","last_synced_at":"2026-07-05T03:02:34.392Z","repository":{"id":360132826,"uuid":"1248739199","full_name":"msradam/coffee-agent","owner":"msradam","description":"A toy MCP agent built with Theodosia: a coffee-order state machine an LLM drives one enforced step at a time.","archived":false,"fork":false,"pushed_at":"2026-05-25T05:16:09.000Z","size":1955,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T07:14:46.177Z","etag":null,"topics":["apache-burr","example","llm-agents","mcp","model-context-protocol","state-machine","theodosia"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/msradam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-25T02:20:11.000Z","updated_at":"2026-05-25T05:16:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/msradam/coffee-agent","commit_stats":null,"previous_names":["msradam/coffee-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/msradam/coffee-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msradam%2Fcoffee-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msradam%2Fcoffee-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msradam%2Fcoffee-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msradam%2Fcoffee-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msradam","download_url":"https://codeload.github.com/msradam/coffee-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msradam%2Fcoffee-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35141967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apache-burr","example","llm-agents","mcp","model-context-protocol","state-machine","theodosia"],"created_at":"2026-07-05T03:02:30.947Z","updated_at":"2026-07-05T03:02:34.341Z","avatar_url":"https://github.com/msradam.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# coffee-agent\n\nA toy agent built with [Theodosia](https://github.com/msradam/theodosia): a coffee\nordering workflow defined as a [Burr](https://burr.dagworks.io/) state machine\nand served as an [MCP](https://modelcontextprotocol.io/) server. An LLM drives\nit one transition at a time, and the server enforces the order of operations.\n\n```mermaid\nstateDiagram-v2\n    [*] --\u003e take_order\n    take_order --\u003e add_modifier\n    take_order --\u003e pay\n    take_order --\u003e cancel\n    add_modifier --\u003e add_modifier\n    add_modifier --\u003e pay\n    add_modifier --\u003e cancel\n    pay --\u003e fulfill\n    fulfill --\u003e [*]\n    cancel --\u003e [*]\n```\n\nThis diagram is the contract. The agent can only move along these edges; the\nserver refuses any step that is not a reachable transition. The workflow lives\nin the state machine, not in a prompt the model has to remember. Pay before\nordering, or fulfill before paying, and the response is a structured refusal\nlisting the actions that are actually reachable.\n\nAn LLM drives it over MCP. Here fast-agent connects a Llama-3.3-70B model\n(on Together) and the model calls the `step` tool to walk the order:\n\n![coffee-agent driven by an LLM](demos/coffee-agent-agent.gif)\n\nThe same workflow is observable from the terminal. `coffee-agent render` prints\nthe graph; `coffee-agent sessions show` replays a recorded run, refusals in red:\n\n![coffee-agent observability](demos/coffee-agent.gif)\n\n## Build it yourself\n\nThis whole repo is about 90 lines. The shape:\n\n1. `src/coffee_agent/app.py` defines the Burr graph (five `@action`s and the\n   transitions between them).\n2. `src/coffee_agent/cli.py` wraps it in Theodosia's `build_cli` so the package\n   ships a `coffee-agent` command with the graph baked in.\n3. `pyproject.toml` depends on `theodosia` and registers the console script.\n\n## Install\n\n```bash\ngit clone https://github.com/msradam/coffee-agent.git\ncd coffee-agent\nuv venv --python 3.13\nuv pip install -e .\n```\n\n`coffee-agent serve` now runs the MCP server over stdio. You usually do not run\nit directly; an MCP client launches it for you (below).\n\n## Run it as an agent\n\nThe repo ships an `.mcp.json` pointing a client at `coffee-agent serve`. Pick a\nclient:\n\n### Claude Code (zero extra install if you have it)\n\n```bash\nclaude mcp add --transport stdio coffee-agent -- uv run coffee-agent serve\nclaude\n```\n\nThen ask: \"Order a latte with an extra shot and pay for it.\" Claude calls the\n`step` tool to walk the graph.\n\n### fast-agent (a terminal REPL, Python)\n\nThe repo ships a `fastagent.config.yaml` defining this server, so:\n\n```bash\nuvx fast-agent-mcp go --servers coffee-agent -m \"Order a latte and pay for it, then fulfill the order.\"\n```\n\nIt uses Gemini by default (set `GOOGLE_API_KEY`). To drive it with a Together\nmodel instead, set `GENERIC_API_KEY` and add\n`--model generic.meta-llama/Llama-3.3-70B-Instruct-Turbo`. For a fully local\nrun, point the config's `generic.base_url` at Ollama.\n\n### MCPJam (one npx command, free hosted models, browser playground)\n\n```bash\nnpx @mcpjam/inspector\n```\n\nAdd the server with command `uv` and args `run coffee-agent serve`, then chat in\nthe playground.\n\n## Watch what it did\n\nEvery step is recorded to Burr's tracker. From the repo:\n\n```bash\nuv run coffee-agent sessions ls\nuv run coffee-agent sessions show         # per-step timeline, refusals in red\nuv run coffee-agent watch                 # live-tail a running session\nuv run coffee-agent verify                # check the session's hash-chained ledger\n```\n\n`coffee-agent` inherits these observability commands from Theodosia. Every step\nand refusal is also hash-chained into a tamper-evident `ledger.jsonl`; `verify`\nrecomputes the chain and names any line that was edited or reordered after the\nfact.\n\n## License\n\nApache 2.0. Built on [Theodosia](https://github.com/msradam/theodosia),\n[Apache Burr](https://github.com/apache/burr), and\n[FastMCP](https://github.com/jlowin/fastmcp).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsradam%2Fcoffee-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsradam%2Fcoffee-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsradam%2Fcoffee-agent/lists"}