@simtlix/simfinity-js 2.6.4 → 3.2.0

package/README.md

@@ -1,11 +1,27 @@
+![Simfinity.js — Define once. Build beyond. GraphQL, MongoDB, PostgreSQL, and optional MCP.](.github/assets/readme-cover.png)
+
 # Simfinity.js
 
-A powerful Node.js framework that automatically generates GraphQL schemas from your data models, bringing all the power and flexibility of MongoDB query language to GraphQL interfaces.
+A Node.js framework that turns GraphQL object types into generated queries, mutations, relationships, and database storage. Use the established MongoDB/Mongoose facade or the PostgreSQL 15+ facade with real tables and foreign keys.
+
+Read the [documentation website](https://simtlix.github.io/simfinity.js/): start with the [quick start](https://simtlix.github.io/simfinity.js/guide/getting-started.html), explore the [guides](https://simtlix.github.io/simfinity.js/guide/schema.html), or consult the [API reference](https://simtlix.github.io/simfinity.js/reference/api.html). The website source is in [`docs/`](docs/).
+
+Run the documentation website locally with Node.js 22+:
+
+```sh
+npm run docs:install
+npm run docs:dev
+```
+
+For builds and hosting, see the [website maintainer guide](docs/.vitepress/README.md). The website documents the current source; some older examples later in this README retain historical conventions.
+
+> **Documentation for both databases:** The [public website](https://simtlix.github.io/simfinity.js/guide/databases.html) now covers MongoDB and PostgreSQL, including shared APIs, relationships, generated FKs, scopes, and MCP. Both adapters are available in **v3.2.0** on npm. Follow the quick starts for installation, or download the runnable starters and verified release archives.
 
 ## 📑 Table of Contents
 
 - [Features](#-features)
 - [Installation](#-installation)
+- [PostgreSQL support](#postgresql-support)
 - [Quick Start](#-quick-start)
 - [Core Concepts](#-core-concepts)
   - [Connecting Models](#connecting-models)
@@ -53,6 +69,18 @@ A powerful Node.js framework that automatically generates GraphQL schemas from y
   - [Custom Mutations](#custom-mutations)
   - [Working with Existing Mongoose Models](#working-with-existing-mongoose-models)
   - [Programmatic Data Access](#programmatic-data-access)
+- [MCP Generation](#-mcp-generation)
+  - [Generating tool definitions](#generating-tool-definitions)
+  - [Standalone MCP server (stdio)](#standalone-mcp-server-stdio)
+  - [HTTP MCP endpoint (alongside GraphQL)](#http-mcp-endpoint-alongside-graphql)
+  - [Options](#options)
+  - [Selecting and naming tools](#selecting-and-naming-tools)
+  - [Customizing tools](#customizing-tools)
+  - [Limits](#limits)
+  - [Tool middleware](#tool-middleware)
+  - [Remote execution](#remote-execution)
+  - [Tool results and errors](#tool-results-and-errors)
+  - [Authentication](#authentication)
 - [Aggregation Queries](#-aggregation-queries)
 - [Complete Example](#-complete-example)
 - [Resources](#-resources)
@@ -62,8 +90,8 @@ A powerful Node.js framework that automatically generates GraphQL schemas from y
 ## ✨ Features
 
 - **Automatic Schema Generation**: Define your object model, and Simfinity.js generates all queries and mutations
-- **MongoDB Integration**: Seamless translation between GraphQL and MongoDB
-- **Powerful Querying**: Any query that can be executed in MongoDB can be executed in GraphQL
+- **MongoDB or PostgreSQL**: Choose the database facade once during application startup
+- **Powerful Querying**: Typed filters, nested paths, pagination, sorting, and aggregations across the supported contract
 - **Aggregation Queries**: Built-in support for GROUP BY queries with aggregation operations (SUM, COUNT, AVG, MIN, MAX)
 - **Auto-Generated Resolvers**: Automatically generates resolve methods for relationship fields
 - **Automatic Index Creation**: Automatically creates MongoDB indexes for all ObjectId fields, including nested embedded objects and relationship fields
@@ -77,101 +105,86 @@ A powerful Node.js framework that automatically generates GraphQL schemas from y
 ## 📦 Installation
 
 ```bash
-npm install mongoose graphql @simtlix/simfinity-js
+npm install mongoose@^8.16.2 graphql@^16.11.0 @simtlix/simfinity-js@3.2.0
 ```
 
 **Prerequisites**: Simfinity.js requires `mongoose` and `graphql` as peer dependencies.
 
-## 🚀 Quick Start
-
-### 1. Basic Setup
+## PostgreSQL support
 
-```javascript
-const express = require('express');
-const { graphqlHTTP } = require('express-graphql');
-const mongoose = require('mongoose');
-const simfinity = require('@simtlix/simfinity-js');
+Version 3.2.0 releases `@simtlix/simfinity-core`, `@simtlix/simfinity-mcp`, `@simtlix/simfinity-postgres`, and the root MongoDB facade in lockstep. Install the selected adapter from npm; shared dependencies resolve automatically. PostgreSQL runs the shared GraphQL query/mutation engine, including scopes, controllers, validators, state transitions and nested writes. It generates and validates tables, indexes, and **real foreign keys**, including inverse relations, explicit many-to-many linking entities, and references inside embedded objects. PostgreSQL installation does not pull Mongoose, MongoDB, or MCP dependencies.
 
-// Connect to MongoDB
-mongoose.connect('mongodb://localhost:27017/bookstore', {
-  useNewUrlParser: true,
-  useUnifiedTopology: true,
-});
+Enum filters resolve member names first, then declared internal values by strict equality, on both backends. For example, with `ONE: { value: 'TWO' }` and `TWO: { value: 'two' }`, filter `"TWO"` selects member `TWO`. Numeric internal values require numbers, not numeric strings. This applies to scalar lists, embedded/reference leaves and state filters across EQ, NE, LT, LTE, GT, GTE, BTW, IN and NIN. LIKE accepts string fields only. PostgreSQL writes and state guards continue to use internal enum values.
 
-const app = express();
-```
+The shared runtime preserves the v3.1 contract: generated relationships run target middleware/scopes with protected identity and parent filters; nested mutations enforce child middleware and persisted ownership; standalone `saveObject()` wraps the complete workflow in a transaction. Accepted empty strings are preserved. Both facades expose `configureQueryLimits()` for bounded pagination.
 
-### 2. Define Your GraphQL Type
+Choose the backend at application setup. The existing package continues to use MongoDB; PostgreSQL uses `createPostgres({ pool, schema })`, the same `connect(null, Type, ...)`/`createSchema()` signatures, and an awaited `initializeDatabase()` before serving requests. See the canonical [PostgreSQL quick start](docs/guide/postgresql.md), detailed [storage reference](docs/postgresql.md), and [compatibility contract](docs/compatibility.md) before adopting this version.
 
-```javascript
-const { GraphQLObjectType, GraphQLString, GraphQLNonNull, GraphQLID } = require('graphql');
+Both database facades expose the same `auth`, `validators`, `scalars`, and `plugins` helper objects. PostgreSQL keeps MCP optional; install the database-independent integration and its transport SDK only when needed:
 
-const BookType = new GraphQLObjectType({
-  name: 'Book',
-  fields: () => ({
-    id: { type: new GraphQLNonNull(GraphQLID) },
-    title: { type: new GraphQLNonNull(GraphQLString) },
-    author: { type: GraphQLString },
-  }),
-});
+```sh
+npm install @simtlix/simfinity-mcp@3.2.0 @modelcontextprotocol/sdk@^1.13.0
 ```
 
-### 3. Connect to Simfinity
+Import `generateMCPTools`, `createMCPServer`, or the transport helpers from `@simtlix/simfinity-mcp` and pass the schema returned by `createPostgres().createSchema()`.
 
-```javascript
-// Connect the type to Simfinity
-simfinity.connect(null, BookType, 'book', 'books');
+Compatibility tests run the same GraphQL schemas and query corpus against both databases. IDs use UUIDs on PostgreSQL, native model/session APIs differ, and some mappings remain explicitly unsupported, including whole embedded-object uniqueness and whole-object sorting/grouping. Nested embedded scalar-list filters/sorts, ragged array group keys and array aggregate facts now match the supported Mongo query contract. Native embedded writes retain explicit nulls, apply descendant list defaults and minimize empty inline objects; historical Date parameters use UTC. PostgreSQL enforces scalar/list multikey uniqueness within embedded trees through typed owner-key tables, validates JSONB embedded shapes, and checks owned marker/row consistency with deferred database triggers. MongoDB fixes also cover list nullability wrappers, scalar-ID inverse relations, inverse aggregation paths, embedded array replacement after clearing, and isolation of mutation input across transaction retries. Existing API signatures remain unchanged.
 
-// Create the GraphQL schema
-const schema = simfinity.createSchema();
+## 🚀 Quick Start
+
+The [complete quick start](docs/guide/getting-started.md) includes MongoDB setup, installation, and working create, read, update, and delete operations. Simfinity uses ES modules and named exports.
+
+```sh
+npm install @simtlix/simfinity-js graphql@^16.11.0 mongoose@^8.16.2 graphql-yoga@^5
 ```
 
-### 4. Setup GraphQL Endpoint
+Set `"type": "module"` in your application's `package.json`, then create `server.js`:
 
 ```javascript
-app.use('/graphql', graphqlHTTP({
-  schema,
-  graphiql: true,
-  formatError: simfinity.buildErrorFormatter((err) => {
-    console.log(err);
-  })
-}));
+import { createServer } from 'node:http';
+import { GraphQLID, GraphQLNonNull, GraphQLObjectType, GraphQLString } from 'graphql';
+import { createYoga } from 'graphql-yoga';
+import mongoose from 'mongoose';
+import * as simfinity from '@simtlix/simfinity-js';
+
+const SerieType = new GraphQLObjectType({
+  name: 'Serie',
+  fields: {
+    id: { type: GraphQLID },
+    name: { type: new GraphQLNonNull(GraphQLString) },
+  },
+});
 
-app.listen(4000, () => {
-  console.log('Server is running on port 4000');
+await mongoose.connect(process.env.MONGODB_URI || 'mongodb://127.0.0.1:27017/series?replicaSet=rs0&directConnection=true');
+simfinity.connect(null, SerieType, 'serie', 'series');
+const schema = simfinity.createSchema();
+const yoga = createYoga({ schema });
+createServer(yoga).listen(4000, '127.0.0.1', () => {
+  console.log('GraphQL ready at http://127.0.0.1:4000/graphql');
 });
 ```
 
-### 5. Try It Out
+Generated mutations require a MongoDB replica set or sharded cluster. Follow the [local MongoDB setup](docs/guide/getting-started.md#2-start-mongodb), then run `node server.js` and open `http://127.0.0.1:4000/graphql`:
 
-Open [http://localhost:4000/graphql](http://localhost:4000/graphql) and try these queries:
-
-**Create a book:**
 ```graphql
 mutation {
-  addBook(input: {
-    title: "The Hitchhiker's Guide to the Galaxy"
-    author: "Douglas Adams"
-  }) {
+  addserie(input: { name: "The Expanse" }) {
     id
-    title
-    author
+    name
   }
 }
 ```
 
-**List all books:**
 ```graphql
 query {
-  books {
+  series {
     id
-    title
-    author
+    name
   }
 }
 ```
 
-> For a full working application, see the [Series Sample Project](https://github.com/simtlix/series-sample) -- a complete TV series microservice with types, relationships, state machines, controllers, and authorization.
+For a full working application, see the [Series Sample Project](https://github.com/simtlix/series-sample), with relationships, state machines, controllers, and authorization.
 
 ## 🔧 Core Concepts
 
@@ -203,6 +216,12 @@ const schema = simfinity.createSchema(
 );
 ```
 
+Importing Simfinity initializes its global `__Field.extensions` introspection field safely whether GraphQL's fields have already been materialized or a schema already exists. Repeated module evaluation with the same GraphQL peer reuses the existing extension field and metadata types. Application field metadata is preserved.
+
+The extension remains shared by every schema using that GraphQL peer; Simfinity's type and middleware registries belong to each runtime instance. Schemas constructed after import include `FieldExtensionsType` and `RelationType` in their type maps. Earlier schemas keep their original type maps: ordinary operations and direct metadata selections work, but named fragments on the new metadata types require a schema constructed after import.
+
+Schema-cloning tools remain unsupported. In a process that has imported Simfinity, `buildClientSchema()` on a post-import schema's introspection result can also fail with duplicate metadata type names. Use Envelop plugins and in-place resolver wrapping; see the [introspection metadata reference](docs/reference/extensions.md).
+
 ### Global Configuration
 
 ```javascript
@@ -233,8 +252,25 @@ Simfinity automatically generates mutations for each connected type:
 // - deleteBook(id: ID): Book
 ```
 
+Creation inputs retain required scalar, enum, embedded-object, and list fields. Update inputs remove the outer non-null wrapper so fields can be omitted; the entity `id` remains required for `GraphQLID` and `GraphQLID!`. Other ID fields remain optional on update. List item nullability is preserved:
+
+| Output field | Create input | Update input |
+| --- | --- | --- |
+| `[String]` | `[String]` | `[String]` |
+| `[String]!` | `[String]!` | `[String]` |
+| `[String!]` | `[String!]` | `[String!]` |
+| `[String!]!` | `[String!]!` | `[String!]` |
+
+The same wrapper handling applies to enum lists, supported custom scalar lists, and embedded lists (using their nested input types). Referenced collections keep the `added` / `updated` / `deleted` input object: a required collection requires that object on create, and non-null object items make `added` and `updated` items non-null. Nullable collection-operation items are ignored. Use `deleted` to delete children.
+
+Empty strings, `false`, `0`, and empty arrays are persisted after validators accept them. Omitting an update field leaves its value unchanged. Explicit `null` clears a nullable scalar, embedded field, or single-object reference; references clear the actual stored `connectionField`, or the GraphQL field name when no override is configured. Multiple nullable fields can be cleared in one update. An explicit `null` for an originally non-null field leaves its stored value unchanged; use an update validator to reject that input if needed.
+
 ### Filtering and Querying
 
+Every relationship or embedded `terms` entry is combined with AND, including repeated paths such as `age GTE 18` and `age LTE 30`. These conditions remain ANDed with top-level logical groups and scope filters. Filter and list-sort paths must resolve to declared scalar or enum fields. `id` paths refer to the stored `_id`; comparisons use the connected Mongoose model's schema, so supplied string or numeric ID models retain their identifier representation.
+
+Filter values must use the field's JSON scalar type. `IN` and `NIN` require flat lists, `BTW` requires exactly two non-null bounds, and `LIKE` requires a string search fragment. Literal objects, nested lists, null list elements, invalid operators, unknown paths, and malformed groups are rejected with a structured 400 error instead of being ignored. Explicit `null` remains supported by `EQ` and `NE`. Enum names or declared internal enum values are converted to the stored representation; state-machine `state` filters preserve stored state names. Date filters convert valid date values without mutating the query input. Validated string scalars support partial `LIKE` searches, and range filters use their base scalar type rather than the field's create/update validation constraints.
+
 Query with powerful filtering options:
 
 ```graphql
@@ -648,7 +684,7 @@ const BookType = new GraphQLObjectType({
 
 ### Relationship Configuration
 
-- `connectionField`: **(Required for collections)** The field storing the related object's ID - only needed for one-to-many relationships (GraphQLList). For single object relationships, the field name is automatically inferred from the GraphQL field name.
+- `connectionField`: **(Required for referenced collections)** The child field linking back to the parent. For a single-object reference, this optionally overrides the stored ObjectId field; when omitted, model generation, writes, clears, and resolvers use the GraphQL field name.
 - `displayField`: **(Optional)** Field to use for display in UI components
 - `embedded`: **(Optional)** Whether the relation is embedded (default: false)
 
@@ -969,6 +1005,8 @@ mutation {
 }
 ```
 
+For non-embedded collections, each `added`, `updated`, or `deleted` child runs the target type's global middleware with the request context. The operation and argument shapes match root mutations: `save`/`update` receive `{ input }`, and `delete` receives `{ id }`. Updated and deleted children must already belong to the current parent in the transaction; a missing child raises `NOT_VALID_ID`, and a different parent raises `FORBIDDEN`. Nested updates cannot move a child between parents. A rejection aborts the parent mutation and its child changes.
+
 ## ✅ Validations
 
 ### Declarative Validation Helpers
@@ -1431,7 +1469,7 @@ const bookController = {
   onSaved: async (doc, args, session, context) => {
     // After saving - doc is a plain object
     console.log(`Book saved: ${doc._id}`);
-    // Can access context.user for post-save operations like notifications
+    // Use context.user for transactional audit/outbox records on this session
   },
 
   onUpdating: async (id, doc, session, context) => {
@@ -1483,7 +1521,7 @@ simfinity.connect(null, BookType, 'book', 'books', bookController);
 - `context`: GraphQL context object (includes request info, user data, etc.)
 
 **`onUpdated(doc, session, context)`**:
-- `doc`: Full updated Mongoose document
+- `doc`: Full updated Mongoose document, after the parent update and nested collection writes have completed
 - `session`: Mongoose session for transaction
 - `context`: GraphQL context object (includes request info, user data, etc.)
 
@@ -1492,6 +1530,10 @@ simfinity.connect(null, BookType, 'book', 'books', bookController);
 - `session`: Mongoose session for transaction
 - `context`: GraphQL context object (includes request info, user data, etc.)
 
+The parent update executes before nested child operations. An update with no matching parent throws `NOT_VALID_ID` (404), without running child operations or `onUpdated`.
+
+Lifecycle hooks, including `onSaved` and `onUpdated`, run before the transaction commits. They can run again after a transient transaction failure, with up to five retries after the first attempt. Keep additional database writes on the supplied session. For email or webhooks, write an outbox record in that transaction and deliver it after commit; external calls inside hooks cannot be rolled back. An uncertain commit result retries only the commit, up to five times, without repeating hooks. If the result remains uncertain, the error is returned and the database may already have committed; reconcile the outcome before repeating the operation.
+
 ### Using Context in Controllers
 
 The `context` parameter provides access to the GraphQL request context, which typically includes user information, request metadata, and other application-specific data. This is particularly useful for:
@@ -1834,6 +1876,8 @@ const EpisodeType = new GraphQLObjectType({
 - **Modify Args In Place**: Scope functions should modify the `args` object directly
 - **Filter Structure**: Use the correct filter structure (`QLFilter` for scalars, `QLTypeFilterExpression` for relations)
 - **All Query Operations**: Scope applies to `find`, `aggregate`, and `get_by_id` operations
+- **Generated Relationships**: Non-embedded single relations run the target type's `get_by_id` middleware and scope; collection relations run its `find` middleware and scope with the same request context. A separate database predicate preserves the referenced ID or parent connection even when filters are changed, including by scope functions. A scoped-out single relation returns `null`; a collection omits scoped-out children.
+- **Custom Resolvers and Writes**: Existing relationship resolvers remain unchanged. Query scope does not authorize mutations; use global middleware or controller checks for write permissions, including permissions on nested children.
 - **Automatic Merging**: For `get_by_id`, the id filter is automatically combined with scope filters
 - **Context Access**: Use `context.user`, `context.ip`, or other context properties to determine scope
 
@@ -1904,14 +1948,20 @@ const permissions = {
 
 **Rule Types:**
 - **Function**: `(parent, args, ctx, info) => boolean | void | Promise<boolean | void>`
-- **Array of functions**: All rules must pass (AND logic)
-- **Policy expression**: JSON AST object (see below)
+- **Nonempty array of rules**: All rules must pass (AND logic); functions, expressions, and nested nonempty arrays can be mixed
+- **Policy expression**: JSON AST object or boolean literal (see below)
+
+Permission maps must be plain objects (including objects with a null prototype). Only their own type and field entries are used. The default policy applies only when an exact field entry and wildcard are both absent. `defaultPolicy` must be exactly `'ALLOW'` or `'DENY'`; omitting it defaults to `'DENY'`.
+
+`createAuthPlugin`, `createAuthMiddleware`, and `createFieldMiddleware` throw `TypeError` when configured with an invalid rule, empty rule array, malformed policy expression, permission map, or default policy. A configured `null`, `undefined`, or unknown object never falls back to `ALLOW`. Use `allow()` or `true` to grant access explicitly, or omit the entry to use the default policy.
 
 **Rule Semantics:**
 - `return true` or `return void` → allow
 - `return false` → deny
 - `throw Error` → deny with error
 
+Only `true` and `undefined` allow access. Other results, including `null`, `0`, an empty string, objects, and other truthy values, deny access. This contract is identical for direct rules, `composeRules`, `anyRule`, and `createRule`, including async results. `composeRules`, `anyRule`, and `createRule` require function arguments. `anyRule` may continue after a denial or error to a different granting rule.
+
 ### Rule Helpers
 
 Simfinity.js provides reusable rule builders:
@@ -1956,6 +2006,8 @@ const permissions = {
 
 Requires the user to have a specific role. Supports custom paths:
 
+The required role must be a nonempty string or nonempty array of nonempty strings; invalid configuration throws `TypeError`. The user's single role value must match an allowed string exactly.
+
 ```javascript
 const permissions = {
   Query: {
@@ -1976,6 +2028,8 @@ const permissions = {
 
 Requires the user to have specific permission(s). Supports custom paths:
 
+The required permission must be a nonempty string or nonempty array of nonempty strings; invalid configuration throws `TypeError`. The user's claim must be an array of nonempty strings. Entries match exactly; only a standalone `'*'` entry grants every permission. A claim such as `'posts:read'` must be supplied as `['posts:read']`. String claims, substrings, and embedded wildcard characters do not grant access.
+
 ```javascript
 const permissions = {
   Mutation: {
@@ -2027,6 +2081,8 @@ const permissions = {
 
 Checks if the authenticated user owns the resource:
 
+IDs must be nonempty strings, finite numbers (including zero), or Mongoose `ObjectId` instances. Numbers compare by their string representation, and ObjectIds compare by hexadecimal value. Missing/null IDs, empty strings, arrays, booleans, and arbitrary objects deny access. Use the path or extractor arguments to obtain a supported ID from a custom identity object.
+
 ```javascript
 const permissions = {
   Post: {
@@ -2074,7 +2130,13 @@ Use `{ ref: 'path' }` to reference values:
 
 **Security:**
 - Only `parent`, `args`, and `ctx` roots are allowed
-- Unknown operators fail closed (deny)
+- Reference paths support root values, dotted fields, document getters, and numeric array indices. Empty path segments and `__proto__`, `prototype`, or `constructor` segments are invalid
+- `eq` and `in` require exactly two operands; `in` requires an array or a reference resolving to an array. `allOf` and `anyOf` require arrays of valid expressions; `not` requires a valid expression
+- Unknown operators or malformed nested expressions invalidate the entire configured policy, even inside an otherwise granting `anyOf`
+- Factories reject malformed expressions with `TypeError`; `isPolicyExpression` validates the complete AST, and direct `evaluateExpression` calls return `false` for malformed ASTs
+- Missing references and invalid runtime membership operands cannot grant access, including under `not` or repeated negation. They propagate through `allOf` and implicit AND. A separate valid `anyOf` branch can still grant access, such as a published post without an authenticated user
+- Explicit `null`, `false`, `0`, and empty-string comparison values remain valid; equality is strict. Use `requireAuth()` or `isOwner()` for identity checks rather than treating two explicit null IDs as ownership
+- Boolean expressions and logical identities remain valid: `{ allOf: [] }` is true, `{ anyOf: [] }` is false, and `{ not: false }` is true. Multiple operator keys form an implicit AND
 - No `eval()` or `Function()` - pure object traversal
 
 ### Integration with GraphQL Yoga / Envelop
@@ -2234,6 +2296,8 @@ simfinity.use((params, next) => {
 
 Each middleware receives a `params` object containing:
 
+Generated non-embedded relationship reads and nested collection mutations also invoke middleware for the related type. Middleware and scope callbacks are awaited. Nested child operations use the same argument shapes and request context as their root equivalents; review middleware that previously assumed it ran only once per root operation.
+
 ```javascript
 simfinity.use((params, next) => {
   // params object contains:
@@ -2560,6 +2624,289 @@ console.log(UserType.getFields()); // Access GraphQL fields
 const BookInput = simfinity.getInputType(BookType);
 ```
 
+## 🤖 MCP Generation
+
+Simfinity can automatically expose every generated GraphQL operation as a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) tool. For each connected type you get one MCP tool per generated query and mutation — exactly mirroring the GraphQL surface:
+
+| GraphQL operation | MCP tool name |
+| --- | --- |
+| Single-entity query | `book` |
+| List query | `books` |
+| Aggregate query | `books_aggregate` |
+| Add mutation | `addbook` |
+| Update mutation | `updatebook` |
+| Delete mutation | `deletebook` |
+| State-machine action | `publish_book` |
+| Custom mutation | _the registered name_ |
+
+Each generated tool follows MCP best practices so an agent can use it without extra context:
+
+- **`description`**: reuses the GraphQL type/field descriptions and adds an actionable summary. List and aggregate tools spell out the available filter operators (`EQ, NE, LT, LTE, GT, GTE, IN, NIN, BTW, LIKE`), `AND`/`OR` groups, pagination and sorting; aggregate tools additionally document the `SUM/COUNT/AVG/MIN/MAX` operations and the `aggregation` argument.
+- **`title`**: a human-readable label (e.g. `List Book`, `Create Book`, `Aggregate Book`).
+- **`inputSchema`**: JSON Schema derived from the GraphQL arguments (scalars, enums, input objects, lists, non-null wrappers, and recursive filter types such as `QLFilterGroup` via `$defs`/`$ref`). Nullable arguments, input fields and list items accept explicit `null`; non-null positions reject it. Nullable references use `anyOf` with a null alternative. GraphQL type and field descriptions are propagated, with curated descriptions for synthetic types. `Date`/`DateTime`/`Time` scalars use the matching JSON Schema `format`. Defaulted arguments are optional; representable defaults appear in the schema and generated GraphQL variables, with enum member names rather than internal values. Omitted opaque scalar defaults that have no GraphQL literal representation use the field's original default.
+- **`outputSchema`**: JSON Schema describing the returned data (mirroring the auto-generated selection set), with type/field descriptions. Every nullable GraphQL position also accepts `null` (e.g. `type: ['string', 'null']`; enums get `null` appended), so validating MCP clients accept the `null`s GraphQL legitimately returns in `structuredContent` (get-by-id misses, unset optional fields).
+- **`annotations`**: behavioral hints — queries are `readOnlyHint: true`, `delete*` is `destructiveHint: true`, `update*` is `idempotentHint: true`. Generated CRUD mutations are recognized by the placeholder descriptions Simfinity stamps on them, so a custom mutation that happens to be named `updateReport` (and carries its own description) keeps that description and gets no inferred hints.
+
+On execution, each tool returns both a serialized JSON `text` content block and a machine-readable `structuredContent` (the GraphQL `data`) that conforms to the `outputSchema`. When the caller requests `pagination: { count: true }` on a **list** tool, the total record count is delivered in the tool result `_meta.count` (aggregate tools ignore the flag — their resolver never computes a total).
+
+> The MCP transports require the optional `@modelcontextprotocol/sdk` dependency (`^1.13.0` or newer). Install it with `npm install @modelcontextprotocol/sdk@^1.13.0`. `generateMCPTools` works without it. SDK load problems raise distinct error codes: `MCP_SDK_NOT_INSTALLED` (not installed), `MCP_SDK_INCOMPATIBLE` (installed but too old to provide the requested transport — upgrade it), `MCP_SDK_LOAD_FAILED` (any other import failure).
+
+### Installation
+
+```bash
+npm install @modelcontextprotocol/sdk@^1.13.0
+```
+
+### Generating tool definitions
+
+`generateMCPTools(schema, options)` returns the tool list, a `callTool` executor and a `getOperation` inspector. It does not require the SDK and is handy for inspection or custom wiring:
+
+```javascript
+import * as simfinity from '@simtlix/simfinity-js';
+
+const schema = simfinity.createSchema();
+const { tools, callTool, getOperation } = simfinity.generateMCPTools(schema);
+
+// tools: [{ name, title, description, inputSchema, outputSchema, annotations, kind }, ...]
+const result = await callTool('addbook', { input: { title: 'Dune' } });
+// result: { content: [{ type: 'text', text: '...JSON...' }],
+//           structuredContent: { addbook: { ... } }, isError: false }
+
+// getOperation returns the prebuilt GraphQL document a tool executes
+console.log(getOperation('books'));
+// query booksOperation($id: QLFilter, $pagination: QLPagination, ...) {
+//   books(id: $id, pagination: $pagination, ...) { id title ... }
+// }
+```
+
+Both `callTool` and `getOperation` throw a `SimfinityError` with code `MCP_TOOL_NOT_FOUND` for unknown tool names.
+
+### Standalone MCP server (stdio)
+
+Use stdio for a standalone executable consumed by clients like Cursor or Claude Desktop:
+
+```javascript
+import * as simfinity from '@simtlix/simfinity-js';
+
+const schema = simfinity.createSchema();
+await simfinity.startStdioMCPServer(schema, {
+  serverName: 'my-api-mcp',
+  context: { user: { id: 'system' } },
+});
+```
+
+### HTTP MCP endpoint (alongside GraphQL)
+
+Mount an MCP endpoint (Streamable HTTP) next to your existing GraphQL server:
+
+```javascript
+import express from 'express';
+import * as simfinity from '@simtlix/simfinity-js';
+
+const schema = simfinity.createSchema();
+const app = express();
+app.use(express.json());
+
+const mcpHandler = await simfinity.createHTTPMCPHandler(schema, {
+  // In HTTP mode the context factory receives the Express `req`,
+  // so you can authenticate per request (e.g. from the Authorization header).
+  context: (req) => ({ user: resolveUserFrom(req.headers.authorization) }),
+});
+app.post('/mcp', mcpHandler);
+```
+
+For deployments reachable from a browser (especially localhost), enable the SDK's DNS-rebinding protection via `transportOptions`, and observe failures with `onError`:
+
+```javascript
+const mcpHandler = await simfinity.createHTTPMCPHandler(schema, {
+  context: (req) => ({ user: resolveUserFrom(req.headers.authorization) }),
+  // Spread into the SDK's StreamableHTTPServerTransport options
+  transportOptions: {
+    enableDnsRebindingProtection: true,
+    allowedHosts: ['127.0.0.1:3000', 'localhost:3000'],
+    allowedOrigins: ['http://localhost:3000'],
+  },
+  onError: (err, req, res) => console.error('MCP request failed', err),
+});
+```
+
+The handler catches all errors itself: `onError` is for logging/metrics, and a JSON-RPC internal error (HTTP 500) is sent automatically when response headers were not already written.
+
+### Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `execution` | `{ mode: 'in-process' }` | `in-process` runs against the in-memory `schema`. `remote` issues HTTP GraphQL requests: `{ mode: 'remote', endpoint, headers, timeoutMs, retry: { attempts, backoffMs } }`. See [Remote execution](#remote-execution). |
+| `context` | `{}` | GraphQL context value, or a factory. For in-process/stdio it is called as `(extra) => context`; for the HTTP handler it is called as `(req, extra) => context` so you can authenticate per request. Passed through to execution so `scope` functions and auth rules work (they read `context.user`). |
+| `include` / `exclude` | — | String or array: raw GraphQL field names, prefixed tool names, or the categories `'query'` / `'mutation'`. `exclude` wins over `include`. |
+| `includeTypes` / `excludeTypes` | — | String or array of entity (return) type names — one entry covers every tool for that entity (`'Book'` matches `book`, `books`, `books_aggregate`, `addbook`, ...). `excludeTypes` wins. |
+| `selectionDepth` | `1` | Nesting depth for the auto-generated output selection set (and the mirrored `outputSchema`). |
+| `includeId` | `true` | Select a scalar or enum `id` as a fallback when nothing else is selectable; otherwise use `__typename`. |
+| `toolNamePrefix` | — | Prefix prepended to every published tool name (e.g. `'catalog_'`). Must match `/^[a-zA-Z0-9_-]+$/`; the resulting names must match `/^[a-zA-Z0-9_-]{1,128}$/` (`MCP_INVALID_TOOL_NAME` otherwise). |
+| `toolOverrides` | `{}` | Per-tool overrides keyed by tool (or unprefixed field) name: `{ description, title, annotations, selectionDepth, includeId, selection }`. See [Customizing tools](#customizing-tools). |
+| `toolMiddleware` | — | Array of koa-style `async (call, next)` functions run around every tool call. See [Tool middleware](#tool-middleware). |
+| `limits` | — | Guardrails: `{ maxPageSize, defaultPagination, maxResultBytes }`. See [Limits](#limits). |
+| `schemaPlugins` | — | Envelop-style plugins whose `onSchemaChange` hook is applied once before serving (in-process execution only). See [Authentication](#authentication). |
+| `serverName` / `serverVersion` | `'simfinity-mcp'` / `'1.0.0'` | Identity reported by the MCP server. |
+| `transportOptions` | — | `createHTTPMCPHandler` only: stateless SDK transport options (e.g. `enableDnsRebindingProtection`, `allowedHosts`, `allowedOrigins`). Setting `sessionIdGenerator`, `onsessioninitialized`, `onsessionclosed` or `eventStore` raises `MCP_INVALID_TRANSPORT_OPTIONS` at setup. |
+| `onError` | — | `createHTTPMCPHandler` only: `(err, req, res)` callback invoked when a request fails; the handler still responds with a JSON-RPC internal error (HTTP 500) if headers were not sent. |
+
+Selection sets always fall back to `id` and then `__typename` when nothing else is selectable (interface/union return types select `__typename`), so the generated documents are always statically valid — and the output schemas mirror the same fallbacks.
+
+### Selecting and naming tools
+
+Trim and namespace the published surface with `include`/`exclude`, `includeTypes`/`excludeTypes` and `toolNamePrefix`:
+
+```javascript
+const { tools, callTool, getOperation } = simfinity.generateMCPTools(schema, {
+  exclude: 'mutation',          // read-only server
+  excludeTypes: 'AuditLog',     // hide every tool whose entity type is AuditLog
+  toolNamePrefix: 'catalog_',   // books -> catalog_books
+});
+
+// callTool/getOperation use the published (prefixed) name;
+// the underlying GraphQL document still uses the raw field name.
+console.log(getOperation('catalog_books'));
+// query booksOperation(...) { books(...) { ... } }
+```
+
+- `include`/`exclude` entries match the raw GraphQL field name, the prefixed tool name, or the categories `'query'` / `'mutation'`. `exclude` always wins over `include`.
+- `includeTypes`/`excludeTypes` match the entity (return) type. Aggregate queries resolve their entity through the sibling list field (`books_aggregate` → `books`), so `excludeTypes: 'Book'` also hides the aggregate tool. With an `includeTypes` allowlist, tools without an object return type are dropped too.
+- Duplicate tool names (e.g. a Query field and a Mutation field sharing a name) are not allowed by MCP: the first tool wins and the later one is skipped with a `console.warn` — rename one of the GraphQL fields or use `include`/`exclude`.
+
+### Customizing tools
+
+`toolOverrides` tunes individual tools without touching the schema. Keys accept either the published tool name or the unprefixed field name:
+
+```javascript
+const { tools } = simfinity.generateMCPTools(schema, {
+  toolOverrides: {
+    books: {
+      title: 'Search books',
+      description: 'Search the book catalog. Filter by title, author or publication year.',
+      selectionDepth: 2,                        // deeper selection set for this tool only
+    },
+    publish_book: {
+      annotations: { idempotentHint: true },    // merged over the generated annotations
+    },
+    book: {
+      selection: 'id title author { name }',    // explicit selection set
+    },
+  },
+});
+```
+
+`selection` accepts `'id title'` or `'{ id title }'` and replaces the auto-generated selection set. When it is set, the `outputSchema` is **omitted** for that tool — it can no longer be guaranteed to match the returned data, and publishing a wrong schema would make validating clients reject valid results.
+
+### Limits
+
+`limits` protects agents (and your database) from oversized requests and responses. Violations come back as regular `isError` tool results, not exceptions:
+
+```javascript
+const { callTool } = simfinity.generateMCPTools(schema, {
+  limits: {
+    maxPageSize: 100,                          // MCP_PAGE_SIZE_EXCEEDED above this
+    defaultPagination: { page: 1, size: 20 },  // injected when the caller sends none
+    maxResultBytes: 262144,                    // MCP_RESULT_TOO_LARGE above this
+  },
+});
+```
+
+- `maxPageSize`: rejects calls whose `pagination.size` exceeds the cap.
+- `defaultPagination`: injected only for tools that have a `pagination` argument, and only when the caller did not send one. `page` and `size` are both required (QLPagination declares them non-null), and `size` must not exceed `maxPageSize` — that misconfiguration throws `MCP_INVALID_LIMITS` at setup.
+- `maxResultBytes`: caps the UTF-8 byte length of the pretty-printed logical payload: `data` on success, or `{ errors, data? }` on failure. Oversized errors and partial data are replaced by `MCP_RESULT_TOO_LARGE`. This diagnostic and pagination-limit diagnostics are exempt from the cap, so even a tiny cap can return an actionable error. The cap excludes MCP envelope overhead, the duplicate `structuredContent`, and middleware-created results; it runs after execution and does not limit database work or remote download size.
+
+### Tool middleware
+
+`toolMiddleware` wraps every tool execution with koa-style `(call, next)` functions — for logging, metrics, argument rewriting or policy checks. `call` is `{ name, args, extra, kind, operation }`:
+
+```javascript
+const { callTool } = simfinity.generateMCPTools(schema, {
+  toolMiddleware: [
+    async (call, next) => {
+      const started = Date.now();
+      const result = await next();
+      console.log(`[mcp] ${call.name} (${call.kind}) took ${Date.now() - started}ms`);
+      return result;
+    },
+    async (call, next) => {
+      if (call.kind === 'mutation' && process.env.MCP_READ_ONLY === 'true') {
+        // Short-circuit: return a result without calling next()
+        return {
+          content: [{ type: 'text', text: 'Mutations are disabled on this server.' }],
+          isError: true,
+        };
+      }
+      return next();
+    },
+  ],
+});
+```
+
+Middleware can mutate `call.args` before calling `next()`, short-circuit by returning a result, or throw. Calling `next()` twice rejects with `MCP_MIDDLEWARE_ERROR`.
+
+### Remote execution
+
+`execution.mode: 'remote'` turns the MCP server into a thin proxy that POSTs each operation to an existing GraphQL endpoint. Harden it with `timeoutMs` and `retry`:
+
+```javascript
+const { callTool } = simfinity.generateMCPTools(schema, {
+  execution: {
+    mode: 'remote',
+    endpoint: 'https://api.example.com/graphql',
+    headers: { Authorization: `Bearer ${token}` },
+    timeoutMs: 10000,                        // abort requests slower than 10s
+    retry: { attempts: 2, backoffMs: 250 },  // up to 2 extra attempts, linear backoff
+  },
+});
+```
+
+- `timeoutMs` aborts slow attempts, including reading the response body (`AbortSignal.timeout`); the timeout signal is combined with the MCP client's cancellation signal. Client cancellation rejects during either fetch or body reading and is never retried.
+- `retry` re-issues failed **queries only — never mutations** — after network errors/timeouts, HTTP 5xx and 429 responses. Backoff is linear: the first retry waits `backoffMs`, the second `2 × backoffMs`, and so on (default `backoffMs`: 250).
+- Transport failures surface as `isError` tool results carrying GraphQL-shaped errors with the codes `MCP_REMOTE_HTTP_ERROR` (non-2xx response without a valid GraphQL body, includes `extensions.status`), `MCP_REMOTE_REQUEST_FAILED` (network error/timeout, including body-read failures) and `MCP_REMOTE_INVALID_RESPONSE` (non-JSON body or invalid GraphQL response shape). A valid body has object `data` or a nonempty `errors` array with string messages; `data: null` requires errors. Invalid successful HTTP responses are not retried. Client cancellation rejects instead of returning an error tool result.
+- If the remote response carries a numeric `extensions.count` (e.g. exposed via `simfinity.plugins.envelopCountPlugin()`), it is surfaced as `_meta.count` on the tool result.
+
+`schemaPlugins` is not applied in remote mode — the remote GraphQL server enforces its own plugins.
+
+### Tool results and errors
+
+Successful calls return `{ content: [textJSON], structuredContent: data, isError: false }`. Failures and edge cases behave as follows:
+
+- **Total count**: with `pagination: { count: true }` on a **list** tool, the count lands in `_meta.count` on the tool result — in-process it is read back from a per-call context layer (Simfinity's find resolver writes it there; counts never leak across calls), in remote mode from the response `extensions.count`. Aggregate tools never deliver a count.
+- **Execution errors**: `isError: true` with a `text` payload of `{ errors, data? }` — partial data is preserved alongside errors when it fits `maxResultBytes`. `structuredContent` is omitted on errors.
+- **Remote transport failures** and **limit violations** are also `isError` results (see [Remote execution](#remote-execution) and [Limits](#limits) for the codes).
+- **Unknown tool names** are the exception: `callTool` and `getOperation` throw `MCP_TOOL_NOT_FOUND`. An aborted `extra.signal` throws `MCP_CALL_CANCELLED` before execution, including cancellation while awaiting an asynchronous context factory. This prevents starting the GraphQL operation after cancellation; it does not undo or cancel database work already started.
+
+### Authentication
+
+The MCP tools execute the same resolvers as GraphQL, so the GraphQL `context` flows through unchanged: pass credentials via `options.context` (a value or a factory). [Query scope](#-query-scope) functions read the context on every execution and need no extra wiring.
+
+Field-level rules from [`createAuthPlugin`](#-authorization) are different. The auth plugin is an Envelop plugin that wraps resolvers from its `onSchemaChange` hook — a hook that only fires when an Envelop/Yoga server boots. A standalone MCP server executes operations with bare `graphql()`, so without help the hook never fires and the field-level rules are silently skipped. Pass the plugin via `schemaPlugins` to get auth parity: every plugin's `onSchemaChange` is invoked once before serving (in-process execution only):
+
+```javascript
+import * as simfinity from '@simtlix/simfinity-js';
+
+const { createAuthPlugin, requireAuth, requireRole } = simfinity.auth;
+
+// Permissions are keyed by the schema's type names. Simfinity names its
+// roots `RootQueryType` and `Mutation`.
+const permissions = {
+  RootQueryType: { books: requireAuth() },
+  Mutation: { deletebook: requireRole('admin') },
+};
+
+const schema = simfinity.createSchema();
+await simfinity.startStdioMCPServer(schema, {
+  // requireRole reads `user.role` by default (see rolePath to customize).
+  context: { user: { id: 'agent', role: 'admin' } },
+  schemaPlugins: [createAuthPlugin(permissions, { defaultPolicy: 'ALLOW' })],
+});
+```
+
+Mounting the MCP handler next to a running Envelop/Yoga server that shares the same `schema` object also works: Yoga fires `onSchemaChange` at startup and `createAuthPlugin` wraps the resolvers in place, so the MCP tools execute the already-wrapped schema.
+
+For per-request HTTP auth, use a function `context`: the HTTP handler invokes it as `(req, extra) => context`, so you can read the `Authorization` header from the Express `req` and map it to `context.user` exactly like your GraphQL server does.
+
 ## 📊 Aggregation Queries
 
 Simfinity.js now supports powerful GraphQL aggregation queries with GROUP BY functionality, allowing you to perform aggregate operations (SUM, COUNT, AVG, MIN, MAX) on your data.
@@ -2761,9 +3108,10 @@ The `groupId` and `path` parameters support:
 
 ### Pagination Notes
 
-- The `page` and `size` parameters work as expected
+- Explicit `page` and `size` must be positive safe integers, and `size` must fit the configured maximum (1000 by default). Invalid input produces `INVALID_PAGINATION` with status 400.
 - The `count` parameter is **ignored** for aggregation queries
 - Pagination is applied **after** grouping and sorting
+- Aggregation queries remain unbounded when pagination is omitted; they do not inherit the list default limit.
 
 ### MongoDB Translation
 
@@ -3206,6 +3554,16 @@ query {
 
 Simfinity.js supports built-in pagination with optional total count:
 
+Configure the process-wide maximum once during application startup:
+
+```javascript
+import * as simfinity from '@simtlix/simfinity-js';
+
+simfinity.configureQueryLimits({ maxPageSize: 500 });
+```
+
+The default maximum is **1000**. Explicit `page` and `size` must be positive safe integers, `size` must not exceed the maximum, and the computed skip must remain a safe integer. Invalid pagination throws `INVALID_PAGINATION` (400); invalid configuration throws `INVALID_QUERY_LIMITS` (400). With no pagination, a list returns at most `Math.min(100, maxPageSize)` records. Any positive safe-integer maximum is allowed, including values below 100. Call `configureQueryLimits()` to restore the default maximum. This deliberately tightens previously unbounded explicit page sizes; applications needing larger pages can configure an appropriate maximum. Unpaginated aggregate queries retain their existing behavior.
+
 ```graphql
 query {
   series(
@@ -3293,6 +3651,8 @@ See the [Plugins for Count in Extensions](#-plugins-for-count-in-extensions) sec
 
 ### 11. Sorting
 
+List sort fields must resolve to declared scalar or enum paths, and every term requires `ASC` or `DESC`. Root `id` and related `author.id` sort by their stored `_id` paths. Embedded paths remain dotted, and repeated sort terms through one relationship reuse the same lookup. Supply at least one term; invalid sort input is rejected before executing the list query.
+
 Simfinity.js supports sorting with multiple fields and sort orders:
 
 ```graphql
@@ -3910,17 +4270,21 @@ console.log(BookInput.getFields()); // Input fields for mutations
 
 ### `saveObject(typeName, args, session?, context?)`
 
-Programmatically save an object outside of GraphQL mutations.
+Programmatically save an object through the creation pipeline, including validation, controllers, and nested writes.
 
 **Parameters:**
 - `typeName` (string): The name of the GraphQL type
 - `args` (object): The data to save
-- `session` (MongooseSession, optional): Database session for transactions
+- `session` (MongooseSession, optional): Caller-owned session with an active transaction, from the same MongoDB client as the registered model
 - `context` (object, optional): GraphQL context object (includes request info, user data, etc.)
 
 **Returns:**
 - `Promise<object>`: The saved object
 
+Without a session, `saveObject()` starts a transaction on the registered model's connection, commits the parent and nested writes together, and awaits session cleanup. The same bounded transaction and commit retries described above apply. This requires a transaction-capable MongoDB deployment, such as a replica set.
+
+With a session, it participates in the caller's active transaction. It never starts, commits, aborts, retries, or ends that caller-owned transaction/session; the caller must handle failures and finish the transaction. An inactive supplied session is rejected with `ACTIVE_TRANSACTION_REQUIRED` (400) before writes. Pass the provided session when calling from a controller or custom mutation so the writes share its transaction. Direct calls bypass GraphQL input coercion, field authorization, and global middleware.
+
 **Example:**
 
 ```javascript
@@ -3957,5 +4321,3 @@ const schema = simfinity.createSchema();
 ```
 
 *Built with ❤️ by [Simtlix](https://github.com/simtlix)*
-
-