@chill-sharp/ui-core 1.1.12

package/doc/Mcp/README.md

@@ -0,0 +1,799 @@
+# 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)