Skip to content

Add the entity tools #2534

Closed
Closed

Description

@pournasserian

Part of #2417 (F-ENT). The entity tools (MCP-01, P1): agents read facts, relations, unsourced facts and the blast radius, and propose a fact with its source or a relation, in the write-tool conventions of #2514. Entities are entries of entity types, so create_entry and update_entry (#2523) already write whole entities. These tools add the fact-level writes S1's pipeline agent needs and the reads of the earlier F-ENT slices (#2526, #2529, #2532). Listing stale facts comes with the stale slice (ENT-03), which waits for the job queue (#2531).

Scope

  • Core (FluentCMS.Core.Builtin.Tools): EntityTools, a tool provider with
    • get_entity_facts: an entity's facts with their source, owner, validity and unsourced flag, for its latest draft or a named version (ENT-02).
    • get_entity_relations: the entities it relates to and the entities that relate to it (ENT-01).
    • list_unsourced_facts: the unsourced facts of the site, or of one entity type (ENT-02).
    • get_blast_radius: the published entries a change set's entity changes affect, each with the old and new value at each path (ENT-04).
    • set_entity_fact: proposes one fact of an entity, with its value, source, owner and validity, keeping the other facts. Every fact property it leaves out is stored as null, so a fact without a source is flagged.
    • relate_entities: proposes a relation. It sets a single reference field, or adds to a list of references, and keeps the fact's metadata.
    • The two writes take base_version and a change set target, like update_entry, and propose an update, or a create while the entity was never published.
  • The propose flow EntryTools uses moves into a shared helper, so entry and entity writes commit a version and its operation the same way.
  • ToolArgumentsReader.RequiredValue reads an argument that can be any JSON value but null, such as a fact's value.
  • The ENT rows of McpCoverageTests list the tools; stale facts stay open on F-ENT: Entity registry with sources, validity and blast radius #2417.

Out of scope

  • Listing stale facts: with ENT-03.
  • Removing a relation: update_entry writes the whole entity.
  • Opening a set from the blast radius on its own: the set holds the entity operations, and the blast radius is read from it.

Acceptance

  • S1 over MCP: an agent sets the prices of two products with the export file as source, in one session's set, then reads the blast radius. It shows the published product page of each product with the old and new price. The page of an untouched product is not in it.
  • A fact set without a source reads back flagged unsourced, and list_unsourced_facts lists it.
  • relate_entities adds a spec to a product's specs and sets its category, and get_entity_relations shows both directions.
  • A stale base version, a field the type does not have and a related id of the wrong type are refused with hints, and store nothing. Fact writes on a plain entry are refused.
  • Every tool passes ToolProviderConformanceTests and the MCP-01 coverage test.
  • Everything above passes on SQLite and PostgreSQL, with no new package.

Activity

  1. added a commit that references this issue on Oct 19, 2026
    b2247e7
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:entitiesEntities and facts (ENT)type:featureNew capabilityv2FluentCMS v2 (v2 branch)

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions