---
title: "ADR-045: Schema and resolution tools"
manual: "TYPO3 LLM Extension"
version: "0.35"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-llm:adr-045@0.35"
source: "Adr/Adr045SchemaAndResolutionTools.rst"
modified: "2026-09-16T22:09:16+00:00"
---

# ADR-045: Schema and resolution tools

-   *Status:* Accepted
-   *Date:* 2026-07-09
-   *Deciders:* nr_llm maintainers

## Context

The content and introspection tools ([ADR-042](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-042@0.35)) let an agent
read records, TypoScript and TSconfig. Debugging schema and templating
questions ("what does this table relate to?", "what fields does this FlexForm
have?", "which Fluid file actually wins?") still required guesswork.

Two shapes were considered for schema access:

1.  **Send the whole TCA and let the model reason.** Rejected: the resolved
    TCA is several megabytes — it neither fits an LLM context window nor is
    affordable per call.
1.  **Navigate: an index plus per-item detail.** Chosen. The model lists table
    names cheaply, then pulls the full definition only for the tables it cares
    about. Validation-style "find the error" tools remain a separate, later
    concern; these tools are retrieval, chunked to stay within budget.

The tools are **inspired by** `konradmichalik/typo3-ai-mate` (the Fluid
resolve and TCA introspection ideas) and `hn/typo3-mcp-server`
(`GetTableSchema` / `GetFlexFormSchema`) — both GPL-2.0-or-later, like this
extension. They are independent re-implementations; no code is copied and
neither extension is a dependency.

## Decision

Four read-only built-in tools:

-   **`get_full_tca` (group `structure`)**

    The TCA **index**: names + titles of every accessible table, each pointing
    at `get_table_schema`. This is the "navigate, don't dump" answer — the
    whole TCA is never serialised at once. Optional `filter` / `extension`.

-   **`get_table_schema` (group `structure`)**

    One table's readable schema: control highlights plus, per field, the type
    and — for relations — the **foreign table and relation kind**
    (group/select/inline/category). This relation view is the value over the
    raw `get_tca`.

-   **`get_flexform_schema` (group `structure`)**

    A FlexForm field's data structure rendered as sheets → fields, via
    `FlexFormTools`. When several structures are selectable by a pointer,
    the keys are listed for a precise follow-up call with `ds_pointer`.

-   **`fluid_resolve` (group `configuration`)**

    The candidate template/partial/layout file paths in override order with an
    exists flag and the winning path, to debug "wrong template wins" or "not
    found".

## Access model

`get_full_tca`, `get_table_schema` and `get_flexform_schema` reuse
`TableReadAccessService` (ADR-042): the sensitive-table denylist holds for
every user including admins; non-admins additionally pass `tables_select` and
the TCA `adminOnly` flag. Credential-like columns are shown by name and type
only. `fluid_resolve` exposes file paths (never contents), rejects path
traversal, and requires a valid extension key.

## Consequences

-   The agent can traverse the schema (index → detail) within token budget and
    reason about relations and FlexForm structures it previously could not see.
-   `fluid_resolve` resolves an extension's own `Resources/Private` paths.
    TypoScript-configured override root paths
    (`plugin.tx_*.view.*RootPaths`) require a live rendering context and are
    **not** reflected — documented as a known limitation, not a bug.
-   Write access remains out of scope; `hn/typo3-mcp-server`'s
    DataHandler-plus-workspace staging is the reference design if it is added
    later (see ADR-042).