@chill-sharp/ui-core 1.1.12 → 1.1.15

package/doc/Mcp/README.md

@@ -1,799 +0,0 @@
-# ChillSharp MCP Module
-
-Versione italiana: [Italiano](../it/Mcp/README.md)
-
-
-This document describes the `ChillSharp.Mcp` module, how to register it in an ASP.NET Core host, and how to prepare a `DbContext` and model so AI agents can consume the exposed schema and query surface efficiently.
-
-`ChillSharp.Mcp` uses the official MCP C# SDK and exposes a Model Context Protocol server backed by your ChillSharp context.
-
-For a focused guide to connecting this MCP server from ChatGPT, see [HOW-TO: Connect ChillSharp MCP to ChatGPT](ChatGPT.md).
-
-## Goals
-
-After setup, an MCP client can:
-
-- discover the MCP-enabled schemas exposed by your host
-- inspect full entity and query schemas before sending requests
-- read schema-level and property-level MCP descriptions
-- execute only the queries that you explicitly expose through `EnableMCP`
-- run DTO operations such as lookup, find, create, update, delete, autocomplete, validate, and chunk
-- operate under bearer-authenticated user permissions and API-key limitations
-
-## Registered Tools
-
-The module registers these MCP tools:
-
-- `ChillSharp get-schema-list`
-- `ChillSharp get-schema`
-- `ChillSharp query`
-- `ChillSharp lookup`
-- `ChillSharp find`
-- `ChillSharp create`
-- `ChillSharp update`
-- `ChillSharp delete`
-- `ChillSharp autocomplete-entity`
-- `ChillSharp autocomplete-query`
-- `ChillSharp validate-entity`
-- `ChillSharp validate-query`
-- `ChillSharp chunk`
-
-### `ChillSharp get-schema-list`
-
-Returns only the schemas that are MCP-enabled.
-
-Use this as the discovery entry point. It tells the AI which entities and queries are intended to be consumed through MCP.
-
-### `ChillSharp get-schema`
-
-Returns the full `ChillDtoSchema` for one MCP-enabled entity or query type.
-
-This is the most important introspection tool. It includes:
-
-- schema metadata
-- query related type information
-- relation metadata inferred from collections annotated with `ChillRelationAttribute`
-- schema-level `MCPDescription`
-- all schema properties
-- property-level `MCPDescription` for each property
-- reference type information
-- `simplePropertyType`, an agent-friendly type string for payload construction
-
-In practice, this is how an AI learns:
-
-- what the object represents
-- what each property means
-- which query returns which entity type
-- which properties are references to other Chill types
-- which value shape each request property requires
-
-Agents should not invent request objects. Use `get-schema` as the contract, copy exact property names from the schema, and send values that match each property's `simplePropertyType`.
-
-For entity schemas, `Relations` describes child relation collections that the UI can wire automatically at runtime. Each relation entry includes:
-
-- `ChillType`, the child or relation-entity type exposed by the collection
-- `ChillQuery`, the query type to use for filtered child lookup when one can be resolved
-- `FixedValues`, default values to inject when creating a child entity
-- `FixedQueryValues`, default query filters to apply when browsing existing related entities
-- `RelationLabel`, the label GUID and default texts derived from the collection's `ChillRelationAttribute`
-
-When a relation can be tied back to the current parent through an annotated child reference, ChillSharp emits the magic value `@{mock}` inside `FixedValues` and `FixedQueryValues`. UI clients replace that token with the current parent entity for the matching FK/reference property name.
-
-Common `simplePropertyType` values are:
-
-| simplePropertyType | Payload value |
-| --- | --- |
-| `guid` | GUID string |
-| `int` | JSON number without decimals |
-| `decimal` | JSON number |
-| `date` | date string |
-| `time` | time string |
-| `datetime` | date-time string |
-| `duration` | duration string or numeric value accepted by the host |
-| `bool` | JSON boolean |
-| `string`, `text` | JSON string |
-| `json` | JSON object, array, or JSON string according to the field contract |
-| `chill-entity` | `ChillDtoEntity` reference with `ChillType` and `Guid` |
-| `chill-entity-collection` | array of `ChillDtoEntity` references |
-| `chill-query` | query DTO matching the referenced query schema |
-
-### `ChillSharp query`
-
-Executes a ChillSharp query only when its related returned entity is MCP-enabled.
-
-The recommended workflow is:
-
-1. call `ChillSharp get-schema-list`
-2. call `ChillSharp get-schema` on the selected query type
-3. read descriptions, properties, and returned type
-4. send a `ChillDtoQuery` payload to `ChillSharp query`
-
-The `Properties` object must contain only accepted input property names from the query schema. For each value, follow `simplePropertyType`; for example, send a string for `string`, a number for `int` or `decimal`, and a `ChillDtoEntity` reference for `chill-entity`.
-
-Read each query property's `MCPDescription` to infer how that input searches. Descriptions should tell the agent whether a property behaves as an exact value, contains-style text search, range boundary, lookup reference, status selector, or another custom query rule. If the description is missing or does not specify matching behavior, assume exact-match equals.
-
-Every Chill query also supports `Properties.FullTextSearch`. Use it for broad keyword search across the query target when the user is not asking for a specific structured filter.
-
-`FullTextSearch` searches against the entity `FullTextContent` generated by ChillSharp. Unquoted text without advanced selectors is normalized, split on whitespace, and AND-matched, so every token must be present. Brackets plus standalone `and`/`or` operators outside quotes enable grouped boolean search. Search the literal words `and` or `or` by wrapping them in matching quotes. Text enclosed by matching single or double quotes is searched as one normalized phrase with word boundaries:
-
-| Search text | Meaning |
-| --- | --- |
-| `la nazione` | Match records containing both `la` and `nazione` as tokens, in any position. |
-| `[la and nazione] or roma` | Match records containing both `la` and `nazione`, or records containing `roma`. |
-| `"and"` | Search the literal keyword `and` instead of the boolean operator. |
-| `"la nazione"` | Match the exact phrase as whole words, for example `bla bla la nazione bla bla`, but not `bla bla della nazione bla bla`. |
-| `"*la nazione"` or `"%la nazione"` | Relax the left boundary, so `della nazione` can match. |
-| `"la nazione*"` or `"la nazione%"` | Relax the right boundary, so a suffix can match. |
-| `"la*nazione"` or `"la%nazione"` | Treat the middle wildcard as a token separator and apply normal AND token matching. |
-
-### `ChillSharp lookup`
-
-Executes a generic full-text lookup against an MCP-enabled entity schema.
-
-Use a `ChillDtoQuery` payload with:
-
-- `ChillType` set to an entity type such as `Model.Blog`
-- `Properties.FullTextSearch` containing the search text
-- optional `ResultProperties`, `Pagination`, and `Ordering`
-
-`Properties.FullTextSearch` uses the same quoted phrase and wildcard rules described under `ChillSharp query`.
-
-### `ChillSharp find`
-
-Finds one MCP-enabled entity by `ChillType` and `Guid`.
-
-Use a `ChillDtoEntity` payload with:
-
-- `ChillType` set to an entity type such as `Model.Blog`
-- `Guid` set to the record identifier
-
-The tool returns `null` when no matching record exists.
-
-### `ChillSharp create`
-
-Creates a new MCP-enabled entity and returns the persisted `ChillDtoEntity`.
-
-Use `ChillSharp get-schema` first, then send a `ChillDtoEntity` payload with:
-
-- `ChillType` set to an entity type such as `Model.Blog`
-- optional `Guid` when the client chooses the identifier
-- `Properties` containing annotated field values
-
-### `ChillSharp update`
-
-Updates an existing MCP-enabled entity and returns the updated `ChillDtoEntity`.
-
-Use a `ChillDtoEntity` payload with:
-
-- `ChillType` set to an entity type such as `Model.Blog`
-- `Guid` set to an existing record
-- `Properties` containing the fields to update
-
-### `ChillSharp delete`
-
-Deletes an existing MCP-enabled entity identified by `ChillType` and `Guid`.
-
-This is a mutating operation. A client should normally call `ChillSharp find` first to confirm the exact record before deletion.
-
-### `ChillSharp autocomplete-entity`
-
-Applies ChillSharp entity autocomplete logic without persisting changes.
-
-Use this before `create` or `update` when the entity model calculates labels, URLs, references, or other derived values.
-
-### `ChillSharp autocomplete-query`
-
-Applies ChillSharp query autocomplete logic without executing the query.
-
-Use this when query inputs have dependent or calculated values.
-
-### `ChillSharp validate-entity`
-
-Validates an MCP-enabled entity DTO and returns ChillSharp validation errors without persisting changes.
-
-Use this before `create` or `update` when the host model exposes validation rules.
-
-### `ChillSharp validate-query`
-
-Validates an MCP-enabled query DTO and returns ChillSharp validation errors without executing the query.
-
-Use this before `query` when the query type exposes validation rules.
-
-### `ChillSharp chunk`
-
-Executes a list of `ChillOperation` items and returns the updated operation list.
-
-Supported verbs are:
-
-- `transaction`
-- `query`
-- `find`
-- `create`
-- `update`
-- `delete`
-- `autocomplete`
-- `validate`
-- `commit`
-
-Each operation is checked for MCP visibility before any operation executes. If one operation targets a non-MCP-enabled schema, the whole chunk is rejected.
-
-For `query`, `autocomplete`, and `validate` operations that use a query payload, set `Query`. For entity operations, set `Entity`.
-
-## Basic host setup
-
-```csharp
-using ChillSharp.Api;
-using Microsoft.EntityFrameworkCore;
-
-var builder = WebApplication.CreateBuilder(args);
-
-builder.Services.AddDbContext<AppDbContext>(options =>
-    options.UseSqlite("Data Source=app.db"));
-
-builder.Services.AddChillApi<AppDbContext>(options =>
-{
-    options.ProtectedApi = true;
-});
-
-var app = builder.Build();
-
-app.UseAuthentication();
-app.UseAuthorization();
-app.MapChillApi();
-app.Run();
-```
-
-When `EnableMcpApi` remains `true`, the MCP module is enabled by default as part of `AddChillApi<TContext>()`.
-
-## Agent connection URL
-
-Agents and MCP clients connect to the MCP HTTP transport endpoint, not to the normal ChillSharp REST endpoints.
-
-With the default configuration, use:
-
-```text
-{host}/api/chill-mcp
-```
-
-Local examples:
-
-```text
-http://localhost:5000/api/chill-mcp
-https://localhost:5001/api/chill-mcp
-```
-
-Do not configure agents to use `/api/chill`, `/api/chill/query`, or the Swagger URL. Those are regular REST API endpoints. The MCP SDK endpoint is `/api/chill-mcp` by default.
-
-The final URL is based on two settings:
-
-- `ChillApiOptions.ApiBasePath`, default `/api`
-- `ChillMcpOptions.RoutePattern`, default `/api/chill-mcp`
-
-The default MCP route is normalized to the current API base path. That means:
-
-| API base path | MCP route to use |
-| --- | --- |
-| `/api` | `/api/chill-mcp` |
-| `/backend` | `/backend/chill-mcp` |
-| empty base path | `/chill-mcp` |
-
-If you configure a custom MCP route:
-
-```csharp
-builder.Services.AddChillMcpApi<AppDbContext>(options =>
-{
-    options.RoutePattern = "mcp";
-});
-```
-
-then the route is relative to the ChillSharp API base path, so the default API base path produces:
-
-```text
-{host}/api/mcp
-```
-
-If you configure an absolute route:
-
-```csharp
-builder.Services.AddChillMcpApi<AppDbContext>(options =>
-{
-    options.RoutePattern = "/mcp";
-});
-```
-
-then agents should connect to:
-
-```text
-{host}/mcp
-```
-
-When `ProtectedApi = true`, the MCP endpoint requires authentication. Configure the agent or MCP client to send:
-
-```http
-Authorization: Bearer <access-token>
-```
-
-## Disable MCP globally
-
-```csharp
-builder.Services.AddChillApi<AppDbContext>(options =>
-{
-    options.EnableMcpApi = false;
-});
-```
-
-## Register the module directly
-
-If you need direct module registration:
-
-```csharp
-using ChillSharp.Mcp.Api;
-
-builder.Services.AddChillMcpApi<AppDbContext>(options =>
-{
-    options.Enabled = true;
-    options.RoutePattern = "/api/chill-mcp";
-});
-```
-
-## Context requirements
-
-Your host context must:
-
-- inherit from `DbContext`
-- implement `IChillContext`
-- implement `IChillSchemaDbContext`
-- include the Chill schema model in `OnModelCreating`
-
-Typical shape:
-
-```csharp
-using ChillSharp;
-using ChillSharp.Schema;
-using Microsoft.EntityFrameworkCore;
-
-public class AppDbContext : DbContext, IChillContext, IChillSchemaDbContext
-{
-    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }
-
-    public string GetChillTypePrefix()
-    {
-        return "MyCompany.MyProduct.Data";
-    }
-
-    public string GetPrimaryCultureName()
-    {
-        return "en-US";
-    }
-
-    public string GetSecondaryCultureName()
-    {
-        return "it-IT";
-    }
-
-    public string GetCurrentUserName()
-    {
-        return Environment.UserName;
-    }
-
-    protected override void OnModelCreating(ModelBuilder modelBuilder)
-    {
-        base.OnModelCreating(modelBuilder);
-        modelBuilder.AddChillSchemaModel();
-    }
-}
-```
-
-## Authentication
-
-The MCP endpoint is meant to run behind bearer authentication.
-
-If the host uses:
-
-```csharp
-builder.Services.AddChillApi<AppDbContext>(options =>
-{
-    options.ProtectedApi = true;
-});
-```
-
-then the mapped MCP endpoint also requires authentication.
-
-This is important because MCP exposure should usually be scoped to a user or API key, not to anonymous callers.
-
-## ChatGPT OAuth Connection
-
-When connecting ChatGPT to a protected remote MCP server, configure ChatGPT with the public HTTPS MCP endpoint:
-
-```text
-https://your-domain.example/api/chill-mcp
-```
-
-If you use the ASP.NET Core Identity-backed ChillSharp auth module, ChillSharp exposes a built-in OAuth authorization-code flow with PKCE for ChatGPT and other remote MCP clients.
-
-The default OAuth endpoints are:
-
-| Purpose | URL |
-| --- | --- |
-| OAuth authorization-server metadata | `https://your-domain.example/.well-known/oauth-authorization-server` |
-| MCP protected-resource metadata | `https://your-domain.example/.well-known/oauth-protected-resource` |
-| Dynamic client registration | `https://your-domain.example/api/chill-auth/oauth/register` |
-| User authorization and consent | `https://your-domain.example/api/chill-auth/oauth/authorize` |
-| Token exchange | `https://your-domain.example/api/chill-auth/oauth/token` |
-
-The flow is:
-
-1. ChatGPT discovers the protected-resource and authorization-server metadata.
-2. ChatGPT dynamically registers itself as a public OAuth client.
-3. The user is redirected to the ChillSharp authorization page.
-4. The user signs in with the ASP.NET Core Identity account.
-5. ChillSharp redirects ChatGPT back with an authorization code.
-6. ChatGPT exchanges the code and PKCE verifier for a ChillSharp bearer access token.
-7. ChatGPT calls the MCP endpoint with:
-
-```http
-Authorization: Bearer <access-token>
-```
-
-So OAuth is used for user consent and token acquisition. The MCP server itself still validates the resulting bearer token through the normal ChillSharp bearer authentication handler.
-
-Typical protected setup:
-
-```csharp
-builder.Services.AddIdentityCore<IdentityUser>()
-    .AddEntityFrameworkStores<AppDbContext>()
-    .AddSignInManager()
-    .AddDefaultTokenProviders();
-
-builder.Services.AddAuthentication(ChillAuthIdentityDefaults.AuthenticationScheme)
-    .AddChillAuthBearer();
-
-builder.Services.AddAuthorization();
-
-builder.Services.AddChillApi<AppDbContext, IdentityUser>(options =>
-{
-    options.ProtectedApi = true;
-});
-```
-
-The OAuth endpoints are enabled by default for the Identity-backed auth module. You can configure them through `ChillIdentityApiOptions`:
-
-```csharp
-builder.Services.AddChillApi<AppDbContext, IdentityUser>(options =>
-{
-    options.ProtectedApi = true;
-    options.OAuthBasePath = "/api/chill-auth/oauth";
-    options.OAuthProtectedResourcePath = "/api/chill-mcp";
-    options.OAuthAuthorizationCodeLifetime = TimeSpan.FromMinutes(5);
-});
-```
-
-If you disable or replace the built-in OAuth endpoints, you can still use ChillSharp as the MCP resource server as long as your authentication handler validates the final bearer token and ChatGPT can complete an OAuth authorization-code flow elsewhere.
-
-## How `EnableMCP` Works
-
-The MCP tools only expose schemas whose MCP visibility is enabled.
-
-A schema is considered MCP-enabled when either:
-
-- `schema.EnableMCP` is `true`
-- runtime entity options enable MCP for that Chill type
-
-For query schemas, MCP visibility is controlled by the related returned entity. A query that returns `Model.Invoice` is visible and executable through MCP only when `Model.Invoice` is MCP-enabled. Enabling only the query type does not publish a hidden entity.
-
-That means:
-
-- `get-schema-list` shows only enabled schemas
-- `get-schema` returns only enabled schemas
-- `query` executes only queries whose related returned entity is enabled
-- entity tools operate only on enabled entity schemas
-- `chunk` checks every targeted query or entity before executing the batch
-
-This gives you an explicit publish/unpublish mechanism for AI-facing database capabilities.
-
-## Preparing A DbContext For Efficient AI Consumption
-
-This is the most important part of the module.
-
-An AI does not understand your model the way a human teammate does. It depends heavily on metadata, naming, descriptions, and a constrained query surface. A database can be technically exposed through MCP and still be hard for an AI to use well.
-
-If you want an AI to consume a ChillSharp host efficiently, prepare the model intentionally.
-
-## 1. Use clear Chill type names
-
-Short type names like `Model.Blog`, `Model.Invoice`, and `Query.PostSearchQuery` are easier for an AI to reason about than opaque names.
-
-Prefer:
-
-- `Model.Customer`
-- `Model.Invoice`
-- `Query.InvoiceSearchQuery`
-- `Query.ActiveCustomerQuery`
-
-Avoid names that require internal team knowledge to decode.
-
-Less efficient:
-
-- `Model.TbAnag`
-- `Query.Q1`
-- `Query.RunDefault`
-
-## 2. Annotate every exposed property intentionally
-
-Use `[ChillProperty]` consistently on the properties you want in the AI-facing surface.
-
-This affects:
-
-- schema generation
-- query payload expectations
-- DTO mapping
-- the list of fields an AI sees when it inspects a schema
-
-If a property matters to queries, search, filtering, or results, it should usually be explicitly annotated.
-
-## 3. Write strong `MCPDescription` text on entities
-
-Entity and query descriptions are not decoration. They are how an AI learns business meaning.
-
-Good entity-level descriptions explain:
-
-- what the object is
-- when it should be queried
-- what it represents in business terms
-- whether it is a primary record, a lookup table, or a derived/query-only surface
-
-Example:
-
-```csharp
-[ChillEntity(
-    UniquePropertyKeyString: "4E16F6C0-6B95-4D67-98BC-9F4D0D63EAF1",
-    PrimaryLanguageLabel: "Invoice",
-    SecondaryLanguageLabel: "Fattura",
-    EnableMCP = true,
-    MCPDescription = "Customer invoice header. Use this schema to inspect invoice number, issue date, customer, total amount, and payment state.")]
-public class Invoice : ChillEntity
-{
-}
-```
-
-That is much more useful than:
-
-- `"Invoice entity"`
-- `"Main table"`
-
-## 4. Write strong `MCPDescription` text on properties
-
-Property descriptions matter even more.
-
-When an AI receives `get-schema`, each property can carry its own `MCPDescription`. This is often the difference between a correct query and a wrong one.
-
-Good property descriptions explain:
-
-- the business meaning
-- allowed or expected content
-- units or format
-- whether the field is a lookup, reference, status, code, or free text
-- whether the field is returned, filterable, computed, or informational
-- for query properties, whether matching is exact, contains-style, range-based, lookup-based, or custom
-
-When a query property's `MCPDescription` does not explain matching behavior, agents should assume exact-match equals. If you want contains, prefix, range, fuzzy, or domain-specific behavior, say so explicitly in the description.
-
-Example:
-
-```csharp
-[ChillProperty(
-    UniquePropertyKeyString: "50B1BB6C-D794-41E4-A85C-D4F9D7A6FA7E",
-    PrimaryLanguageLabel: "Invoice number",
-    SecondaryLanguageLabel: "Numero fattura",
-    MCPDescription = "Human-readable accounting document number shown to users and used in external communication.")]
-public string InvoiceNumber { get; set; } = string.Empty;
-```
-
-And:
-
-```csharp
-[ChillProperty(
-    UniquePropertyKeyString: "A18E7754-D8F7-45FE-B8A8-EA762A4EC9E6",
-    PrimaryLanguageLabel: "Payment status",
-    SecondaryLanguageLabel: "Stato pagamento",
-    MCPDescription = "Current payment lifecycle status. Expected values are Draft, Issued, PartiallyPaid, Paid, and Cancelled.")]
-public string PaymentStatus { get; set; } = string.Empty;
-```
-
-These descriptions are returned by `ChillSharp get-schema`.
-
-## 5. Prefer purpose-built query types over exposing everything
-
-AI works better when it has a small number of well-described queries instead of one giant ambiguous surface.
-
-Prefer several clear query types such as:
-
-- `Query.OpenInvoiceQuery`
-- `Query.InvoiceByCustomerQuery`
-- `Query.ActiveSubscriptionQuery`
-
-instead of forcing the AI to infer everything from one generic catch-all query.
-
-Each query should have:
-
-- a clear name
-- a clear purpose
-- well-described input properties
-- a predictable related entity type
-
-## 6. Keep query inputs narrow and meaningful
-
-A query with twenty optional inputs and vague meanings is hard for humans and harder for AI.
-
-Prefer a query surface where each input has a strong purpose.
-
-Good:
-
-- `Customer`
-- `FromIssueDate`
-- `ToIssueDate`
-- `PaymentStatus`
-
-Less good:
-
-- `Key1`
-- `Filter`
-- `Mode`
-- `ExtraData`
-
-## 7. Expose references intentionally
-
-References are useful because they tell an AI how tables and entities relate.
-
-If a property references another Chill type, make sure that:
-
-- the reference is represented through Chill metadata
-- the target type has a useful schema
-- the property description explains the relationship
-
-Example:
-
-- `"Customer that owns the invoice."`
-- `"Warehouse from which this shipment is fulfilled."`
-
-This helps an AI navigate the graph of your database instead of treating every object as isolated.
-
-## 8. Keep labels useful
-
-`Label`, `ShortLabel`, and schema display names help an AI choose the right object when many related types exist.
-
-A good label is:
-
-- stable
-- human-readable
-- derived from the business identity of the record
-
-Examples:
-
-- invoice number
-- customer name
-- product code and title
-
-This improves both UI behavior and AI comprehension.
-
-## 9. Separate internal-only objects from AI-facing objects
-
-Not every entity should be MCP-enabled.
-
-A good rule is:
-
-- enable MCP only for objects that are understandable and safe to expose to an AI workflow
-- keep low-level infrastructure entities, log tables, or sensitive internals disabled unless there is a real reason to publish them
-
-This reduces confusion, token waste, and accidental misuse.
-
-## 10. Design with permission boundaries in mind
-
-The authenticated API-key user can be restricted by permissions and other limitations.
-
-That means a good AI-facing host should align:
-
-- MCP-enabled schemas
-- query visibility
-- auth permissions
-- API key ownership
-
-If different clients need different visibility, use different identities or permission profiles rather than one global unrestricted MCP surface.
-
-## 11. Think in “AI reading order”
-
-A typical agent workflow is:
-
-1. list schemas
-2. choose one by name and description
-3. inspect schema and property descriptions
-4. infer related entity type
-5. build a query
-6. read results
-
-So the model should support that sequence cleanly.
-
-Ask yourself:
-
-- can the agent identify the right schema by reading the name and description?
-- can it understand the properties without hidden tribal knowledge?
-- can it tell which query returns which entity?
-- can it avoid irrelevant schemas?
-
-If not, enrich the metadata.
-
-## 12. Optimize for fewer round trips
-
-AI systems pay a price for each discovery step.
-
-To keep consumption efficient:
-
-- provide rich schema descriptions
-- describe properties well the first time
-- keep query surfaces focused
-- expose the result properties that are commonly needed
-- avoid forcing the agent to guess meanings and retry
-
-Good metadata lowers token usage, lowers retries, and produces more reliable results.
-
-## Practical AI-Ready Checklist
-
-Before exposing a model through `ChillSharp.Mcp`, check that:
-
-- entity names are clear
-- query names are clear
-- all AI-facing properties are annotated with `[ChillProperty]`
-- MCP-enabled schemas have useful `MCPDescription`
-- important properties have useful `MCPDescription`
-- queries are focused and purpose-built
-- references are described
-- labels are meaningful
-- sensitive or noisy schemas remain non-MCP
-- auth and permission boundaries match the intended AI use case
-
-## Example AI-Friendly Model Fragment
-
-```csharp
-using ChillSharp.Annotations;
-using ChillSharp.EF;
-
-[ChillEntity(
-    UniquePropertyKeyString: "4E16F6C0-6B95-4D67-98BC-9F4D0D63EAF1",
-    PrimaryLanguageLabel: "Invoice",
-    SecondaryLanguageLabel: "Fattura",
-    EnableMCP = true,
-    MCPDescription = "Customer invoice header. Use it to inspect invoice identity, customer, dates, totals, and payment state.")]
-public class Invoice : ChillEntity
-{
-    [ChillProperty(
-        UniquePropertyKeyString: "50B1BB6C-D794-41E4-A85C-D4F9D7A6FA7E",
-        PrimaryLanguageLabel: "Invoice number",
-        SecondaryLanguageLabel: "Numero fattura",
-        MCPDescription = "Human-readable invoice number used by accountants and customers.")]
-    public string InvoiceNumber { get; set; } = string.Empty;
-
-    [ChillProperty(
-        UniquePropertyKeyString: "A18E7754-D8F7-45FE-B8A8-EA762A4EC9E6",
-        PrimaryLanguageLabel: "Customer",
-        SecondaryLanguageLabel: "Cliente",
-        MCPDescription = "Customer that owns this invoice.",
-        ReferenceChillTypeQuery = "Query.CustomerQuery")]
-    public Customer? Customer { get; set; }
-
-    [ChillProperty(
-        UniquePropertyKeyString: "D6A6A0B6-3C22-4E18-B2AE-34D6EBE56EC8",
-        PrimaryLanguageLabel: "Payment status",
-        SecondaryLanguageLabel: "Stato pagamento",
-        MCPDescription = "Current payment lifecycle status such as Draft, Issued, Paid, or Cancelled.")]
-    public string PaymentStatus { get; set; } = string.Empty;
-}
-```
-
-## Related Documents
-
-- [ChatGPT connection how-to](ChatGPT.md)
-- [../README.md](../README.md)
-- [../RegisterContext.md](../RegisterContext.md)
-- [../ModelPreparation.md](../ModelPreparation.md)
-- [../AIAssistedDevelopment/README.md](../AIAssistedDevelopment/README.md)
-- [../../ChillSharp.Mcp/README.md](../../ChillSharp.Mcp/README.md)