MCP tools

All inputs and outputs below are JSON objects. Entity parameters are exact, case-sensitive names. Results are structured content and are also represented as text by the SDK for compatible clients. Lists are deterministic. Every tool honors the startup entity allow-list.

`entity_list`

Lists visible entity names. It has no parameters and returns {"entities":[string]} sorted by name. An allow-list removes every unlisted entity. Repository reload failures produce repository_error.

{"entities":["Comment","Post","Tag","User"]}

`entity_show`

Shows the normalized schema/configuration for one visible entity.

Parameters: required string entity.
Result: entity plus schema, including entity metadata, identifier, fields, includes, inline data, source, inheritance, and write settings.
Authorization: an existing blocked name produces entity_not_allowed; allowing a parent does not allow descendants.
Errors: missing/wrong parameters, unknown_entity, entity_not_allowed, or repository_error.

Example request: {"entity":"User"}. The result begins with {"entity":"User","schema":{"Name":"User",...}}.

`object_list`

Lists record summaries declared as one exact entity; it does not expand descendant entities.

Parameters: required string entity.
Result: entity and objects. Each summary has type, id, and, when applicable, file, inline, and readOnly.
Authorization: the entity must be visible. All returned records belong exactly to it.
Errors: missing/wrong parameters, unknown_entity, entity_not_allowed, or repository_error.

{"entity":"User","objects":[{"type":"User","id":"user-alice","file":"<ROOT>/data/users/alice.yaml"},{"type":"User","id":"user-bob","file":"<ROOT>/data/users/bob.json"}]}

The file in this result is normally absolute. <ROOT> is the normalization used only in these captured docs.

`object_get`

Gets one record by exact entity and logical identifier.

Parameters: required strings entity and id. A $path identifier is passed in its workspace-relative form.
Result: object with type, id, fields, and optional file, inline, and readOnly. Derived read-only fields are included.
Authorization: only the exact visible entity is queried; a descendant record cannot be fetched through an allowed parent.
Errors: missing/wrong parameters, unknown_entity, entity_not_allowed, object_not_found, or repository_error.

Example request: {"entity":"User","id":"user-alice"} returns Alice’s full fields, including email and roles.

`repository_export`

Exports record fields for selected visible entities as one structured snapshot.

Parameters: optional string array entities. Omit it or pass an empty array for every visible entity.
Result: entities, a map from exact entity name to an identifier-sorted array of field maps.
Authorization: every explicitly requested entity must be visible; an omitted list exports only allow-listed entities. The call fails rather than partially exporting a blocked or unknown requested entity.
Errors: wrong parameters, unknown_entity, entity_not_allowed, or repository_error.

Example request: {"entities":["Post"]} returns {"entities":{"Post":[{"id":"post-001","title":"Launch Day",...}]}}.

`files_list`

Lists configured backing files that currently match entity includes.

Parameters: optional string entity. Omit it or pass an empty string for every visible entity.
Result: files, an array of {type,file} entries sorted by entity and workspace-relative path. Paths can begin with ../ for configured external roots.
Authorization: only visible entities contribute paths; a supplied entity must be visible. Inline records have no backing file entry.
Errors: wrong parameters, unknown_entity, entity_not_allowed, glob/filesystem failures as repository_error.

{"files":[{"type":"User","file":"data/users/alice.yaml"},{"type":"User","file":"data/users/bob.json"}]}

Captured session

This complete session is regenerated by the website check against examples/full. Machine-specific absolute roots are normalized to <ROOT>.

{
  "protocol_version": "2025-11-25",
  "tools": [
    "entity_list",
    "entity_show",
    "files_list",
    "object_get",
    "object_list",
    "repository_export"
  ],
  "examples": [
    {
      "tool": "entity_list",
      "request": {},
      "result": {
        "entities": [
          "Comment",
          "Post",
          "Tag",
          "User"
        ]
      }
    },
    {
      "tool": "entity_show",
      "request": {
        "entity": "User"
      },
      "result": {
        "entity": "User",
        "schema": {
          "Ancestors": null,
          "Descendants": null,
          "Description": "Directory of users who can author and moderate posts",
          "Extends": "",
          "FieldOrder": [
            "id",
            "name",
            "email",
            "roles"
          ],
          "Fields": {
            "email": {
              "Default": null,
              "Description": "Primary contact address for notifications",
              "Enum": null,
              "Format": "",
              "Name": "email",
              "Pattern": "",
              "Properties": {},
              "PropertyOrder": null,
              "ReferenceTypes": null,
              "Repeated": false,
              "Required": true,
              "Type": "string",
              "Unique": false
            },
            "id": {
              "Default": null,
              "Description": "Stable identifier shared across data files",
              "Enum": null,
              "Format": "",
              "Name": "id",
              "Pattern": "",
              "Properties": {},
              "PropertyOrder": null,
              "ReferenceTypes": null,
              "Repeated": false,
              "Required": true,
              "Type": "string",
              "Unique": false
            },
            "name": {
              "Default": null,
              "Description": "Display name rendered in UI surfaces",
              "Enum": null,
              "Format": "",
              "Name": "name",
              "Pattern": "",
              "Properties": {},
              "PropertyOrder": null,
              "ReferenceTypes": null,
              "Repeated": false,
              "Required": true,
              "Type": "string",
              "Unique": false
            },
            "roles": {
              "Default": null,
              "Description": "Role slugs that drive permission checks",
              "Enum": null,
              "Format": "",
              "Name": "roles",
              "Pattern": "",
              "Properties": {},
              "PropertyOrder": null,
              "ReferenceTypes": null,
              "Repeated": true,
              "Required": false,
              "Type": "string",
              "Unique": false
            }
          },
          "Identifier": {
            "Field": "id",
            "Generated": false,
            "Pattern": ""
          },
          "Include": [
            {
              "Path": "data/users/*.yaml",
              "Selector": ""
            },
            {
              "Path": "data/users/*.json",
              "Selector": ""
            }
          ],
          "InlineData": null,
          "JSONSchema": "",
          "Name": "User",
          "Source": "<ROOT>/entities/User.yaml",
          "Write": {
            "Format": "yaml",
            "Template": "{id}.yaml"
          }
        }
      }
    },
    {
      "tool": "object_list",
      "request": {
        "entity": "User"
      },
      "result": {
        "entity": "User",
        "objects": [
          {
            "file": "<ROOT>/data/users/alice.yaml",
            "id": "user-alice",
            "type": "User"
          },
          {
            "file": "<ROOT>/data/users/bob.json",
            "id": "user-bob",
            "type": "User"
          }
        ]
      }
    },
    {
      "tool": "object_get",
      "request": {
        "entity": "User",
        "id": "user-alice"
      },
      "result": {
        "object": {
          "fields": {
            "email": "alice@example.com",
            "id": "user-alice",
            "name": "Alice Example",
            "roles": [
              "admin",
              "author"
            ]
          },
          "file": "<ROOT>/data/users/alice.yaml",
          "id": "user-alice",
          "type": "User"
        }
      }
    },
    {
      "tool": "repository_export",
      "request": {
        "entities": [
          "Post"
        ]
      },
      "result": {
        "entities": {
          "Post": [
            {
              "author": "user-alice",
              "body": "We are excited to announce the product launch.\n",
              "id": "post-001",
              "status": "PUBLISHED",
              "tags": [
                "tag-product"
              ],
              "title": "Launch Day"
            }
          ]
        }
      }
    },
    {
      "tool": "files_list",
      "request": {
        "entity": "User"
      },
      "result": {
        "files": [
          {
            "file": "data/users/alice.yaml",
            "type": "User"
          },
          {
            "file": "data/users/bob.json",
            "type": "User"
          }
        ]
      }
    }
  ]
}

The six tools above are the complete released surface. See Restrict access to selected entities before exposing repository data to a client.