Yichus / Reference / API MCP tools

api_scaffold

Generate a Yichus-first Bosatsu API module: structs, Yichus/Access rules, owner-scoped or public handlers, and a Yichus/Service routing table, plus a matching Yichus/Frontend::FrontendSpec (frontendSource) for api_frontend. The result compiles and verifies; edit it, then api_verify.

Kind: Scaffold. Core: MCP servers list it from the start. Origin: Yichus/Mcp::catalog.

CLI: none — the API scaffold (ApiScaffold) has no dedicated CLI subcommand; `service generate` plans CRUD endpoints for a service, a different generator.

Parameters

Example

Each response was produced by calling this tool with the displayed request when these docs were generated, on files committed to the repository. A violated or refuted verdict is a successful call: the check ran and found what its example shows.

A one-resource owner-scoped API

Request

{
  "package_name": "Demo/Service/TasksApi",
  "service_name": "tasks",
  "resources": [
    {
      "name": "task",
      "policy": "owner",
      "fields": [
        {
          "name": "title",
          "type": "String"
        }
      ]
    }
  ]
}

Response

{
  "ok": true,
  "tool": "api_scaffold",
  "fileName": "tasks_api.bosatsu",
  "source": "package Demo/Service/TasksApi\n\n# Generated by the Yichus API scaffolder. Edit freely: safety is\n# re-proven from the compiled IR by `api_verify`, not assumed from\n# this template.\n\nfrom Yichus/IO import IO, pure, flat_map\nfrom Yichus/Transaction import TxTable, Txn, stored_table, tx_bind, tx_pure, tx_read, tx_write, tx_delete, transaction, replied\nfrom Yichus/Access import Principal, AccessRule, AccessSpec, OwnerScoped\nfrom Yichus/Data import Db, Table, table, db_read\nfrom Yichus/Service import Reply, Done, Refused, TryAgain, handler, route, service_def, ReadPerm, WritePerm, DeletePerm\n\nexport (tasks_api, access_rules, Task())\nexposes (Yichus/Access, Yichus/Service)\n\nstruct Task(title: String)\n\n# The declared access surface. `api_verify` proves each rule against\n# the handlers below — and keeps proving it as this file is edited.\naccess_rules = AccessSpec([\n  AccessRule(\"tasks\", OwnerScoped),\n])\n\n# Why a change was refused; the error body's code is its name in\n# snake_case. maybe_saved: the commit was not confirmed, so sending\n# the change again could repeat it. not_saved: it was refused before\n# anything was saved (these transactions never refuse, but replied\n# needs an answer for it).\nenum ChangeRefused:\n  MaybeSaved\n  NotSaved\n\ndef unsaved[a](reason: ChangeRefused) -> Reply[ChangeRefused, a]:\n  Refused(\"the change was not saved; send it again\", reason)\n\n# Tasks are owner-scoped: one row per user, keyed by exactly\n# Principal.user_id, holding that user's list. The analyzer proves no\n# handler can reach another caller's row.\ndef tasks_table(db: Db) -> Table[List[Task]]:\n  table(db, \"tasks\")\n\n# The same table inside a transaction. Every change to a caller's row\n# goes through one, so changes made at the same moment, on one server\n# or several, never lose one another.\ntasks_rows: TxTable[s, List[Task]] = stored_table(\"tasks\")\n\ndef list_tasks(db: Db, p: Principal) -> IO[List[Task]]:\n  Principal(uid, _) = p\n  db_read(tasks_table(db), uid)\n\n# A change that may or may not have been saved (the commit was not\n# confirmed) is answered so the caller knows whether sending it again\n# is safe: replacing or clearing the row again is; adding again could\n# add the item twice.\ndef put_tasks(db: Db, p: Principal, items: List[Task]) -> IO[Reply[ChangeRefused, List[Task]]]:\n  Principal(uid, _) = p\n  outcome <- flat_map(transaction(db, _ -> tx_bind(tx_write(tasks_rows, uid, items), _ -> tx_pure(items))))\n  pure(replied(outcome, Done, unsaved, TryAgain(\"the tasks may not have been saved; send them again\")))\n\ndef add_task_plan[s](uid: String, item: Task) -> Txn[s, ChangeRefused, List[Task]]:\n  found <- tx_bind(tx_read(tasks_rows, uid))\n  items = match found:\n    case Some(saved): [item, *saved]\n    case None: [item]\n  _ <- tx_bind(tx_write(tasks_rows, uid, items))\n  tx_pure(items)\n\ndef add_task(db: Db, p: Principal, item: Task) -> IO[Reply[ChangeRefused, List[Task]]]:\n  Principal(uid, _) = p\n  outcome <- flat_map(transaction(db, _ -> add_task_plan(uid, item)))\n  pure(replied(outcome, Done, unsaved, Refused(\"the task may already be saved; list the tasks before adding it again\", MaybeSaved)))\n\ndef clear_tasks(db: Db, p: Principal) -> IO[Reply[ChangeRefused, Unit]]:\n  Principal(uid, _) = p\n  outcome <- flat_map(transaction(db, _ -> tx_delete(tasks_rows, uid)))\n  pure(replied(outcome, Done, unsaved, TryAgain(\"the tasks may not have been cleared; send the request again\")))\n\ntasks_api = service_def(\n  \"tasks\",\n  [\n    route(\"/tasks\", handler(\"list_tasks\", list_tasks), [ReadPerm(\"tasks\")]),\n    route(\"/tasks/put\", handler(\"put_tasks\", put_tasks), [WritePerm(\"tasks\")]),\n    route(\"/tasks/add\", handler(\"add_task\", add_task), [ReadPerm(\"tasks\"), WritePerm(\"tasks\")]),\n    route(\"/tasks/clear\", handler(\"clear_tasks\", clear_tasks), [DeletePerm(\"tasks\")]),\n  ]\n)\n",
  "frontendFileName": "tasks_app.bosatsu",
  "frontendSource": "package Demo/Service/TasksApi/Frontend\n\n# Generated by the Yichus API scaffolder: screens over the scaffolded\n# routes. Edit titles and drop views freely; `api_frontend` re-proves\n# every path against the route table. Compile together with\n# tasks_api.bosatsu.\n\nfrom Bosatsu/Predef import List\nfrom Yichus/Frontend import View, FrontendSpec, ListView, Form, Action\n\nexport (tasks_app)\nexposes Yichus/Frontend\n\ntasks_app = FrontendSpec(\n  \"Tasks\",\n  [\n    View(\"/tasks\", \"Your tasks\", ListView),\n    View(\"/tasks/put\", \"Replace tasks\", Form),\n    View(\"/tasks/add\", \"Add task\", Form),\n    View(\"/tasks/clear\", \"Clear tasks\", Action),\n  ]\n)\n",
  "note": "source is the API module; frontendSource is a matching Yichus/Frontend::FrontendSpec. Compile them together and pass both files to api_verify and api_frontend."
}

Run tools in the browser: api-mcp.html?webmcp=1.

Read the result according to this tool’s scope: static checks, bounded execution checks, and descriptive diagrams answer different questions. A successful call is not a general approval of the program. The safety and permissions guide compares the checks and provides editable ownership, guard, and role examples.