{
  "markdown": "# Guardian Engine — API & MCP Integration Guide\n\n> **A deterministic oracle inside your agent's generate→verify loop.** Your LLM authors the recipe; Guardian judges it. Guardian Engine catches hallucinated temperatures, missing techniques, wrong ingredients, and impossible cooking steps before they reach the pan — and returns machine-actionable patches so your agent can fix exactly what's wrong. Recipes are the first vertical — the same deterministic approach generalises to any procedural domain where correctness matters.\n\n**Why an oracle instead of another LLM critique?** An LLM critique is a *sample* — it misses differently on every run. Guardian's symbolic engine makes guarantees a generative model structurally cannot:\n\n- **Exhaustive checking** — every rule is evaluated on every call, not a sample of them.\n- **Certified negatives** — \"no EU Annex II allergen source detected\" is an absence claim an LLM cannot make.\n- **Replayable verdicts** — same input + same spec + same knowledge-base version → byte-identical output. Every response pins `kb_version_hash` and `master_hash` so any verdict is reproducible as an audit record.\n- **Machine-actionable repair** — findings come with structured `patches` (and `fix_recipe` can apply them deterministically); your agent authors the rest and re-verifies.\n- **Bring your own spec** — verify against *your* house recipe or SOP via `master_json`, not just the bundled catalog.\n\n[![Official MCP Registry](https://img.shields.io/badge/MCP%20Registry-Official-blue?logo=github)](https://registry.modelcontextprotocol.io/v0.1/servers/dev.kaimeilabs%2Fguardian-engine/versions/latest) [![Install with Smithery](https://smithery.ai/install-badge.svg)](https://smithery.ai/servers/kaimeilabs/guardian-engine) [![Glama.ai MCP Server](https://glama.ai/mcp/servers/badge)](https://glama.ai/mcp/servers/kaimeilabs/guardian-engine)\n\n**Endpoint**: `https://api.kaimeilabs.dev/mcp`  \n**Transport**: [Streamable HTTP (MCP)](https://modelcontextprotocol.io)  \n**Auth**: None — free during early access (fair use applies)\n\n---\n\n> ## ⚠️ Safety & Liability Notice\n>\n> Guardian Engine is an **automated, informational** recipe-verification tool. It is **not** a\n> food-safety, medical, nutritional, or regulatory-compliance authority, and its output is **not**\n> professional advice.\n>\n> - **Allergens are not guaranteed.** Allergen warnings (including `check_safety`,\n>   `check_allergens`, and the `allergens` field of every verification response) come from an\n>   automated knowledge base that may be incomplete or wrong. A `PASSED` verdict or an empty\n>   allergen list is **NOT** a guarantee that a recipe is free of any allergen or safe for any\n>   individual. **Never** rely on Guardian to decide whether a food is safe for someone with a\n>   food allergy or intolerance — always verify against the actual ingredient/product labelling\n>   and consult a qualified professional.\n> - **Dietary and religious claims are not certifications.** `verify_dietary_claim` results\n>   (vegan, vegetarian, gluten-free, dairy-free, nut-free, halal, kosher) are automated\n>   ingredient-level checks — they are **not** a substitute for certification by a recognised\n>   dietary or religious authority.\n> - **Repaired recipes are not certified safe.** `fix_recipe` output must be reviewed by a human\n>   before being cooked, served, or published; allergen findings are never auto-fixed and a\n>   repaired recipe may still fail verification.\n> - **Cooking-safety findings are informational** and must not replace certified guidance (e.g.\n>   USDA, EU FIC, or your local food-safety authority).\n> - **No warranty.** The Service is provided \"AS IS\", without warranty of any kind. To the maximum\n>   extent permitted by law, Kaimei Labs accepts no liability for any loss, injury, or damage\n>   arising from use of, or reliance on, Guardian output.\n>\n> Use of the API constitutes acceptance of the full [Terms of Service](https://kaimeilabs.dev/terms)\n> (warranty disclaimer, limitation of liability, indemnification).\n\n---\n\n## Connect Your Agent\n\nGuardian is a hosted MCP server. No install, no API key, no Docker. Pick your client and paste the config.\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"guardian\": {\n      \"url\": \"https://api.kaimeilabs.dev/mcp\",\n      \"transport\": \"streamable-http\"\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Ask: *\"List the available dishes in Guardian Engine\"* to confirm.\n\n### Cursor\n\nOpen **Settings → MCP Servers → Add new MCP server**, then paste:\n\n```json\n{\n  \"guardian\": {\n    \"url\": \"https://api.kaimeilabs.dev/mcp\",\n    \"transport\": \"streamable-http\"\n  }\n}\n```\n\n### VS Code (GitHub Copilot)\n\nAdd to your `.vscode/mcp.json` (or user `settings.json` under `\"mcp\"`):\n\n```json\n{\n  \"servers\": {\n    \"guardian\": {\n      \"type\": \"http\",\n      \"url\": \"https://api.kaimeilabs.dev/mcp\"\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to your Windsurf MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"guardian\": {\n      \"serverUrl\": \"https://api.kaimeilabs.dev/mcp\"\n    }\n  }\n}\n```\n\n### Smithery (One-Click)\n\n[![Install with Smithery](https://smithery.ai/install-badge.svg)](https://smithery.ai/servers/kaimeilabs/guardian-engine) — auto-configures Claude Desktop, Cursor, and more.\n\n> [!WARNING]\n> **Smithery Proxy Limitation:** The default Smithery proxy URL (`guardian-engine--kaimeilabs.run.tools`) **does not support Streaming HTTP** and will silently fail. You MUST edit your MCP config after installation to use the direct endpoint: `https://api.kaimeilabs.dev/mcp`.\n\n### Glama.ai\n\nGuardian Engine is also listed on **[Glama.ai](https://glama.ai/mcp/servers/kaimeilabs/guardian-engine)** — discover and connect to MCP servers from the Glama directory.\n\n### Any MCP Client (Python SDK)\n\n```python\nimport asyncio\nfrom mcp.client.session import ClientSession\nfrom mcp.client.streamable_http import streamable_http_client\nfrom httpx import AsyncClient\n\nasync def main():\n    async with AsyncClient(timeout=30.0) as http:\n        async with streamable_http_client(\"https://api.kaimeilabs.dev/mcp\", http_client=http) as streams:\n            read_stream, write_stream, _ = streams\n            async with ClientSession(read_stream, write_stream) as session:\n                await session.initialize()\n                result = await session.call_tool(\"list_dishes\", arguments={\"cuisine_filter\": \"french\"})\n                print(result)\n\nasyncio.run(main())\n```\n\n```bash\npip install mcp>=1.2.1 httpx>=0.27.0\n```\n\n---\n\n## Tools\n\nThe MCP server exposes seven tools. `verify_recipe` is the core loop; the rest support the compare → verify → repair cycle and master-independent safety checks.\n\n### `verify_recipe`\n\nVerify a candidate recipe against a Guardian master spec. Returns a structured report with a strict `PASSED`/`FAILED` verdict (no scores) and detailed findings, each citing the rule it violated. The verdict is policy-driven: any `CRITICAL` finding fails the recipe; more than 5 `WARNING`s also fail.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `dish_name` | string | Yes* | Name or alias of the dish (e.g. `\"carbonara\"`, `\"rendang\"`, `\"kung-pao\"`, `\"bourguignon\"`). `dish` is accepted as a backward-compatible alias. *Optional when `master_json` is supplied |\n| `candidate_json` | string \\| object | Yes | Full recipe as JSON — see [schema.md](schema.md). Max 500 KB |\n| `master_json` | string \\| object | No | **Bring your own master** — your house recipe/SOP to verify against, using the same schema as catalog masters. Bypasses the bundled catalog; the response pins your spec via `master_hash` (sha256) and `master_source: \"user\"` |\n| `original_prompt` | string | No | The user's original request that generated the recipe |\n| `response_format` | string | No | `\"text\"` (default) or `\"json\"`. Use `\"json\"` for machine-actionable patches in agentic self-correction loops |\n| `session_id` | string | No | Track an agent's improvement loop across multiple attempts |\n| `operator_id` | string | No | Audit identifier tagged into the verification log and compliance record (letters, digits, hyphens; max 64 chars) |\n\n**Tip — include the original prompt for personalised feedback:** When you include `original_prompt` (e.g. *\"Make a spicy vegan rendang\"*), Guardian matches findings to the user's stated dietary needs and flavour preferences, and activates audience-sensitive safety checks (e.g. flagging honey in recipes for infants, raw egg for pregnant users). Without it, Guardian still returns the full verdict and all findings.\n\n**Unknown dish?** If the dish isn't in the catalog, the `UNKNOWN_DISH` error carries a `safety_fallback` verdict — the master-independent safety layer (poultry temperature + allergen scan) still runs, so your agent always leaves with deterministic value.\n\n**Field audience:** `issue` is a machine-readable code for programmatic handling — don't show it to end users. Use `title` and `suggested_correction` as the user-facing fields.\n\n### `fix_recipe`\n\nDeterministically repair a candidate recipe against a master spec. Verifies, applies every machine-actionable patch the symbolic engine produced (missing ingredients, quantities, temperatures, durations, cooking media, substitutions), then re-verifies. **No LLM is involved** — the repair is a deterministic function of the candidate and the ruleset.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `dish_name` | string | Yes* | Dish to repair against (`dish` alias accepted). *Optional when `master_json` is supplied |\n| `candidate_json` | string \\| object | Yes | Same schema as `verify_recipe` |\n| `master_json` | string \\| object | No | BYO master to repair against; patches (including `suggested_step` templates) are built from *your* spec |\n| `original_prompt` | string | No | Used only for safety-context awareness during verification |\n| `response_format` | string | No | `\"text\"` (default) or `\"json\"` — use `\"json\"` to receive the full `fixed_recipe` object |\n\nThe response reports `verdict_before` → `verdict_after`, `fully_fixed`, `patches_applied`, `patches_skipped`, `unresolved_findings`, and the `fixed_recipe`. Changes that need recipe-authoring judgement (adding a whole cooking phase, rewriting instructions, ratio rebalancing) are **not** auto-applied — they're returned under `patches_skipped`, with `add_step` patches carrying a `suggested_step` template from the master for *your* agent to author in the recipe's own voice and re-verify. **Allergen findings are never auto-fixed.** Do not assume a fixed recipe will pass — check `verdict_after`.\n\n### `list_dishes`\n\nList all master recipes Guardian can verify against, with rich metadata (slug, title, cuisine, region, aliases, complexity).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `cuisine_filter` | string | No | Case-insensitive cuisine filter (e.g. `\"french\"`, `\"chinese\"`, `\"thai\"`) |\n\n### `get_master`\n\nReturn the canonical master recipe for a dish — a pure knowledge-base lookup, no LLM. Enables **compare-then-verify** loops: fetch the master, diff it against your recipe, then call `verify_recipe` instead of verifying blind. Master content is transparent by default: exact temperatures, timings, and EU FIC 1169/2011 allergen codes are returned verbatim. Also the live reference for the `master_json` schema when bringing your own master.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `dish_name` | string | Yes | Name or alias of the dish |\n| `response_format` | string | No | `\"json\"` (default) or `\"text\"` |\n\n### `check_safety`\n\nMaster-independent safety checks for **any** recipe — no dish resolution or master spec required. Checks poultry internal-temperature safety (≥ 74 °C) and scans all ingredients against the 14 EU FIC 1169/2011 Annex II allergen groups. Use it when `verify_recipe` has no matching master.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `candidate_json` | string | Yes | Full candidate recipe as a JSON string |\n\n### `check_allergens`\n\nCheck an ingredient list for EU FIC 1169/2011 allergen presence, with a detailed audit trace mapping each ingredient to its Annex II allergen group (entry numbers and labels included).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `ingredients` | list[string] | Yes | Ingredient names, freeform or canonical (e.g. `[\"butter\", \"wheat_flour\", \"peanut_butter\"]`) |\n| `restrictions` | list[string] | No | Allergen group IDs to check against user restrictions: `gluten`, `crustaceans`, `eggs`, `fish`, `peanuts`, `soy`, `dairy`, `tree_nuts`, `celery`, `mustard`, `sesame`, `sulphites`, `lupin`, `molluscs` |\n| `dish_name` | string | No | Reporting context |\n| `check_all_eu_allergens` | boolean | No | `true` scans for all 14 Annex II groups regardless of `restrictions` — use for labelling-style \"declare everything detected\" checks |\n| `response_format` | string | No | `\"text\"` (default) or `\"json\"` |\n\n### `verify_dietary_claim`\n\nVerify that a recipe satisfies a dietary claim, returning a structured verdict with the specific offending ingredients — never a vague paraphrase.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `candidate_json` | string | Yes | Recipe JSON (only the ingredient list is required) |\n| `claim` | string | Yes | One of: `vegan`, `vegetarian`, `gluten_free`, `dairy_free`, `nut_free`, `halal`, `kosher` |\n| `response_format` | string | No | `\"text\"` (default) or `\"json\"` |\n\n---\n\n## Bring Your Own Master (`master_json`)\n\nThe bundled catalog is a reference library — the primary production pattern is verifying against **your own spec**: a house recipe, a franchise SOP, a test kitchen's canonical version. Pass `master_json` to `verify_recipe` or `fix_recipe` (same schema as catalog masters — call `get_master` for a live example: `title`, `serves`, `ingredients[]`, `required_ingredients[]` with substitute tiers, `steps[]` with technique/temperature/duration/medium).\n\n- When `master_json` is supplied, `dish_name` may be omitted and the catalog is bypassed entirely — the candidate is checked against *your* spec.\n- The response pins the spec: `master_source: \"user\"` and `master_hash` (sha256 over the canonical master). Together with `kb_version_hash`, this makes every verdict **replayable**: anyone holding the same candidate, spec, and KB version reproduces the byte-identical result.\n- Malformed masters return a structured `INVALID_MASTER` error, not a server error. Max 500 KB.\n\n---\n\n## Available Recipes (161 dishes, 5 regions)\n\n| Region | Dishes |\n|--------|--------|\n| **Europe** | Basque Cheesecake · Beef Bourguignon · Beef Wellington · Butternut Squash Soup · Cacio e Pepe · Caprese Salad · Cassoulet · Cheese Soufflé · Chicken Cacciatore · Chicken Marsala · Chicken Piccata · Chocolate Soufflé · Confit de Canard · Coq au Riesling · Coq au Vin · Crème Brûlée · Crêpes · Fettuccine Alfredo · Fish & Chips · Florentine Biscuits · Focaccia Barese · French Omelette · French Onion Soup · Frittata · Gazpacho · Gnocchi di Patate · Goulash · Greek Salad · Köttbullar · Mille-Feuille · Minestrone · Niçoise Salad · Osso Buco · Pasta alla Norma · Pasta Carbonara · Pasta Pomodoro · Patatas Bravas · Penne alla Vodka · Pesto alla Genovese · Pierogi · Pissaladière · Potato-Leek Soup · Ratatouille · Risotto alla Milanese · Roast Chicken · Sauerbraten · Shepherd's Pie · Spanakopita · Spaghetti Aglio e Olio · Spaghetti all'Amatriciana · Spaghetti Bolognese · Spanish Paella · Steak Frites · Stollen · Tarte Tatin · Tiramisu · Tomato Soup · Tortilla Española |\n| **Asia & Southeast Asia** | Banh Mi · Beef Rendang · Biryani · Bulgogi · Butter Chicken · Cantonese Steamed Fish · Char Kway Teow · Chicken Tikka Masala · Chow Mein · Dan Dan Noodles · Jianbing · Khao Soi · Kimchi Fried Rice · Kung Pao Chicken · Laksa · Lo Mein · Massaman Curry · Nasi Goreng · Nasi Lemak · Okonomiyaki · Pad See Ew · Pad Thai · Palak Paneer · Rogan Josh · Som Tum · Sushi Rice · Sweet & Sour Chicken · Teriyaki Chicken · Thai Green Curry · Tonkatsu · Tonkotsu Ramen · Yakisoba |\n| **Middle East & North Africa** | Falafel · Hummus · Koshary · Lentil Soup · Moroccan Lamb Tagine · Mutabal · Pita Bread · Shakshuka · Shish Taouk · Tabbouleh |\n| **Americas** | Angel Food Cake · Baked Potato · Baked Salmon · Baked Ziti · Banana Bread · BBQ Ribs · Biscuits & Gravy · Buttermilk Pancakes · Caesar Salad · Carnitas · Ceviche · Cheese Quesadilla · Chicken Fajitas · Chicken Noodle Soup · Chicken Parmesan · Chili con Carne · Chocolate Chip Cookies · Classic Chocolate Cake · Cobb Salad · Crab Cakes · Creamed Spinach · Eggs Benedict · Fish Tacos · French Dip Sandwich · French Toast · Fudge Brownies · Garlic Butter Shrimp · Ground Beef Tacos · Italian-American Meatballs · Jerk Chicken · Key Lime Pie · Lobster Roll · Lomo Saltado · Macaroni & Cheese · Mashed Potatoes · Mole Poblano · Pan-Seared Pork Chops · Pan-Seared Scallops · Pão de Queijo · Pastel de Choclo · Pecan Pie · Philly Cheesesteak · Pot Roast · Pozole · Pulled Pork · Roasted Brussels Sprouts · Roasted Cauliflower · Sautéed Mushrooms · Shrimp Scampi · Southern Fried Chicken · Tamales · Texas Smoked Brisket · Turkey Meatballs · Vanilla Cupcakes · Vegetable Fried Rice · Waldorf Salad |\n| **Africa** | Bunny Chow · Efo Riro · Melktert · Muamba de Galinha · Suya |\n\nAll recipes accept multiple aliases (e.g. `\"rendang\"`, `\"tikka-masala\"`, `\"risotto\"`, `\"bourguignon\"`, `\"carbonara\"`). Use `list_dishes` for the full live catalog.\n\n### Missing a Dish?\nThe catalog is regularly expanding. If your agent requires verification for a dish not currently supported, please **[open an issue on GitHub](https://github.com/kaimeilabs/guardian-api-docs/issues)** to request it. We prioritize additions based on developer demand.\n\n---\n\n## Example Verification Output\n\nWhat does a Guardian verification report actually look like? Here's the (abridged) `response_format: \"json\"` structure when an agent submits a carbonara made with bacon, cream, and an overheated pan:\n\n```json\n{\n  \"api_version\": \"0.7.1\",\n  \"schema_version\": \"1.0\",\n  \"response_format_version\": \"v3\",\n  \"kb_version_hash\": \"7dda40a3b646\",\n  \"verdict\": \"FAILED\",\n  \"matched_against\": \"Pasta alla Carbonara (Master)\",\n  \"master_source\": \"catalog\",\n  \"master_hash\": \"3357e0929021c0003fea0b79015e2c53cf9ef50d70f0d507605788ad9741fd29\",\n  \"coverage_percentage\": 100.0,\n  \"summary\": {\"CRITICAL\": 4, \"WARNING\": 0, \"INFO\": 3},\n  \"findings\": [\n    {\n      \"step_index\": 2,\n      \"issue\": \"TEMPERATURE_MISMATCH\",\n      \"severity\": \"critical\",\n      \"justification\": \"Temperature is significantly outside the required range.\",\n      \"title\": \"rendering\",\n      \"details\": {\"expected\": \"100.0-130.0\", \"observed\": \"180\"},\n      \"dimension\": \"temperature\"\n    },\n    {\n      \"step_index\": null,\n      \"issue\": \"INGREDIENT_SUBSTITUTED\",\n      \"severity\": \"critical\",\n      \"justification\": \"'bacon' is in the same group ('cured_pork') as 'guanciale' but is not the canonical ingredient for this recipe.\",\n      \"title\": \"You used bacon, expected guanciale\",\n      \"details\": {\"expected\": \"guanciale\", \"observed\": \"bacon\"},\n      \"dimension\": \"ingredients\"\n    }\n  ],\n  \"allergens\": [\n    \"Allergen detected: Pork-derived ingredients (halal/kosher compliance)\",\n    \"Allergen detected: Milk and products thereof (including lactose)\",\n    \"Allergen detected: Cereals containing gluten (wheat, rye, barley, oats, spelt, kamut)\"\n  ],\n  \"patches\": [\n    {\"action\": \"set_temperature\", \"step_index\": 2, \"value\": \"100.0-130.0\"},\n    {\"action\": \"replace_ingredient\", \"remove\": \"bacon\", \"add\": \"guanciale\"}\n  ]\n}\n```\n\nEach finding carries a `severity`, a `justification` grounded in culinary science, and machine-readable `details` — and the `patches` array tells your agent *exactly* what change would resolve each fixable finding, so it repairs only what's wrong instead of regenerating and guessing. `kb_version_hash` + `master_hash` pin the exact knowledge-base and spec versions the verdict was computed against, making the result replayable as an audit record.\n\nPatch actions: `add_ingredient`, `replace_ingredient`, `set_quantity`, `adjust_quantity`, `set_temperature`, `set_duration`, `set_medium`, and `add_step` (which includes a `suggested_step` template for your agent to author, then re-verify).\n\n---\n\n## Files in This Repository\n\n| File | Purpose |\n|------|---------|\n| `schema.md` | Complete `candidate_json` structure required by `verify_recipe` |\n| `client.py` | Python example: submit a recipe for verification |\n| `test_integration.py` | Live connectivity test against the public API |\n| `smithery.yaml` | Smithery MCP registry configuration |\n| `glama.json` | Glama.ai MCP server claim configuration |\n\n---\n\n## Data & Privacy\n\n- **No PII collected** — we do not store user names, emails, or API keys. Underlying cloud infrastructure may temporarily process IP addresses for routing.\n- **Data for Compute Exchange** — the free service is provided in exchange for usage data. Submitted recipes are used to improve verification accuracy and create anonymized derived datasets. See our [Terms of Service](https://kaimeilabs.dev/terms).\n- **Do not include PII** in recipe payloads.\n- Fair use quotas enforced via compute limits.\n\n> [!CAUTION]\n> **Not a Substitute for Food Safety Knowledge**  \n> While Guardian Engine catches explicitly dangerous AI hallucinations (like serving poultry below safe temperatures), it cannot guarantee a recipe is 100% safe to consume. Pathogen destruction relies on variables (time, mass, equipment) that text-based AI models cannot perfectly control. Verification results are informational and must always be paired with human common sense and standard kitchen safety practices.\n\n---\n\n## Support & Contact\n\nBuilding an AI cooking assistant, smart kitchen platform, or agentic food-tech product? We'd love to hear from you.\n\n- **Email**: partners@kaimeilabs.dev\n- **Website**: [kaimeilabs.dev](https://kaimeilabs.dev)\n- **GitHub**: [github.com/kaimeilabs](https://github.com/kaimeilabs)\n\n## License\n\nClient code in this repository (`client.py`, `test_integration.py`) is released under the **MIT License**. The Guardian Engine verification logic and master recipe datasets are proprietary.\n",
  "bytes": 22417,
  "sha": "2a56a9b39a7c62e3eebe4ca6ef11d26174bf46630b8291e98840a5c497b500dd",
  "repo_slug": "kaimeilabs/guardian-api-docs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_dev_kaimeilabs_guardian_engine_5d87bc7b/readme"
}