ADR-045: Schema and resolution tools 

Status

Accepted

Date

2026-07-09

Deciders

nr_llm maintainers

Context 

The content and introspection tools (ADR-042) 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.
  2. 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).