Connection check
verified live · 28h ago
onlyworlds-mcp
Read and write typed fictional worlds (22 linked element types) via the OnlyWorlds open standard.
Tools
11
GitHub stars
—
Installs / wk
—
Licence
—
Transport
streamable-http
Last checked
28h ago
Tools & capabilities
11 toolsRead from the running server on 28h ago.
bulk_apply
items*atomic
Create and/or update many elements across any of the 22 types in one call. Each entry in `items` is `{"type": <slug>, "element": <payload>}` with the same payload shape `create_el… Create and/or update many elements across any of the 22 types in one call. Each entry in `items` is `{"type": <slug>, "element": <payload>}` with the same payload shape `create_element` takes: an `element` with an `id` UPDATES that id (creating it if absent), an `element` without an `id` CREATES a new element. Items may reference each other by id, including a forward reference to a sibling later in the list. There is NO delete: bulk_apply never removes an element. When `atomic` is false (default), items succeed or fail independently and the response reports each outcome; when `atomic` is true, ANY item failure rolls the whole batch back and nothing is committed. Up to 1000 items. Requires a WRITE API-Key. Returns the batch response verbatim: `{errors, items: [{status, id, created_at, updated_at} | {status, id, error}, ...]}` — `errors` true means at least one item failed (and, under `atomic`, that nothing committed).
create_element
type*element*
Create one new element of `type` in the world named by your API-Key header. `type` is a slug from `list_element_types` (e.g. "character"). `element` is the field payload: `name` p… Create one new element of `type` in the world named by your API-Key header. `type` is a slug from `list_element_types` (e.g. "character"). `element` is the field payload: `name` plus any scalar, link, or extension fields for that type (call `get_element_schema(type)` for the field structure). Link fields are UUID arrays (multi) or a single UUID (single); every linked id must already exist in the world. Supply your own `id` (a UUID) to mint the element at that id, or omit `id` and the server mints a uuid7. Requires a WRITE API-Key. Returns the full created element in the v2 wire shape. Errors (naming the offending field) on an unknown field, a bad link target, or an id that already exists.
edit_links
id*addtype*field*remove
Add and/or remove links on ONE multi-link `field` of an element, leaving the rest of that field's array untouched. Use this for additive/subtractive link edits (unlike `update_ele… Add and/or remove links on ONE multi-link `field` of an element, leaving the rest of that field's array untouched. Use this for additive/subtractive link edits (unlike `update_element`, which REPLACES a link array). `type` is a slug from `list_element_types`; `id` is the element's UUID; `field` must be a multi-link field on that type (see `get_element_schema(type)`). `add` is a list of UUIDs to link (each must already exist in the world; adding an already-linked id is a no-op) and `remove` is a list of UUIDs to unlink (removing an absent id is tolerated). Requires a WRITE API-Key. Returns `{type, id, field, values}` where `values` is the field's full UUID array after the edit. Errors (naming `field`) if it is not a multi-link field of this type, if the element does not exist, or if an added target id is absent.
get_changes
limitsince_cursor
Return the delta feed for the world named by your API-Key header: every element created/updated (`op: "upsert"`, full body) or deleted (`op: "delete"`) since `since_cursor`, in app… Return the delta feed for the world named by your API-Key header: every element created/updated (`op: "upsert"`, full body) or deleted (`op: "delete"`) since `since_cursor`, in apply order, in pages of `limit` (default 25, max 1000). Entries carry FULL element bodies — a default page stays inside any client's token budget; measured worlds ran ~1.5-2k chars PER ENTRY, so raise `limit` only if you truly need bigger pages, and prefer paging with the cursor. Omit `since_cursor` (or pass "") to start from the beginning of the feed — for a big world that is a multi-page walk, not one response. Pass the returned `cursor` back as `since_cursor` to get the next page (or, later, only what changed since); treat the cursor as OPAQUE. `has_more` true means page again with the new cursor. Requires a READ or WRITE API-Key. This mirrors `GET /api/v2/changes`.
get_element
id*type*
Fetch one element by `type` and `id` (a UUID) from the world named by your API-Key header. `type` is a slug from `list_element_types`. Returns the full v2 wire shape (the same bod… Fetch one element by `type` and `id` (a UUID) from the world named by your API-Key header. `type` is a slug from `list_element_types`. Returns the full v2 wire shape (the same body as `GET /api/v2/{type}/{id}`): `type`, `id`, `name`, scalar fields, link fields as UUID arrays, and any extension fields inline. Requires a READ or WRITE API-Key. Errors if no element of that type with that id exists in the world.
get_element_schema
type*
Return the field structure of one OnlyWorlds element `type` (a slug from `list_element_types`, e.g. "character"). The result groups the type's writable fields by kind so a caller… Return the field structure of one OnlyWorlds element `type` (a slug from `list_element_types`, e.g. "character"). The result groups the type's writable fields by kind so a caller knows how to read and write them: `text` (strings), `integer`, `single_link` (one UUID), `multi_link` (an array of UUIDs), and `generic` (a type+id pair pointing at any element type). For every link field the target element type is given under `link_targets`. All link values are element UUIDs. Unauthenticated. Errors if `type` is not one of the 22 types.
list_elements
type*limitoffsetsupertypename_contains
List elements of one `type` in the world named by your API-Key header, newest-created first. `type` is a slug from `list_element_types` (e.g. "character"). Optional `name_contains… List elements of one `type` in the world named by your API-Key header, newest-created first. `type` is a slug from `list_element_types` (e.g. "character"). Optional `name_contains` filters by case-insensitive name substring; `supertype` filters exactly. `limit` (default 100, max 1000) and `offset` page the result. Requires a READ or WRITE API-Key. Returns `{data: [element, ...], limit, offset, has_more}` where each element is the full v2 wire shape and `id` is a UUID. Use `get_element(type, id)` for a single element.
list_element_types
List all 22 OnlyWorlds element types with a one-line shape summary of each. Every world is built from these types; each element has a stable UUID `id`, a `name`, and a `type`. Use… List all 22 OnlyWorlds element types with a one-line shape summary of each. Every world is built from these types; each element has a stable UUID `id`, a `name`, and a `type`. Use `get_element_schema(type)` for a type's full field list. Unauthenticated — schema is public reference. Returns a mapping of the 22 type slugs (the value you pass as `type` to the data tools) to a summary string.
search_elements
query*
Search elements by name across ALL 22 types in the world named by your API-Key header (case-insensitive substring match). Use this when you know part of a name but not the element… Search elements by name across ALL 22 types in the world named by your API-Key header (case-insensitive substring match). Use this when you know part of a name but not the element's type. Bounded to at most 50 matches per type. Returns `{query, results: [{type, id, name, supertype, subtype}, ...]}` — `id` is a UUID; call `get_element(type, id)` for the full body. Requires a READ or WRITE API-Key.
search_schema
query*
Search every element type's fields for `query` (case-insensitive substring), across all 22 types. Useful for "which types have a `location` field?" or finding where a concept lives… Search every element type's fields for `query` (case-insensitive substring), across all 22 types. Useful for "which types have a `location` field?" or finding where a concept lives in the schema. Returns a mapping of type slug -> the matching field names in that type (types with no match are omitted); a `query` that also matches a type slug lists that type with an empty field list so the type-name hit is not lost. Unauthenticated.
update_element
id*type*fields*