@segmentstream-cloud/ontology 0.9.0 → 0.11.0

package/dist/service/mcp/server.js

@@ -0,0 +1,370 @@
+import { Cause, Data, Effect, Layer, Option, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { encodeManifest } from "../../manifest.js";
+import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
+import { renderCatalog } from "../../render.js";
+import { CurrentPrincipal, withPrincipal } from "../authentication.js";
+import { catalogFor } from "../catalog.js";
+import { RequestId, errorBodyForWire, expectedFailure, internalError, schemaIssues, } from "../errors.js";
+import { publicOrigin } from "../oauth/protocol.js";
+import { mcpChallenge, mcpResource } from "../oauth/server.js";
+import { identityToken, makeOperations, toQuery } from "../operations.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { ActionResponse, HistoryPage, HistoryParams, IdParam, Me, } from "../schemas.js";
+import { mcpTools, visibleTools } from "./tools.js";
+/** The URL path of the ontology's MCP server, outside `/api/ontology`: one per app. */
+export const MCP_PATH = "/mcp";
+/** The MCP revisions the server speaks, newest first. */
+export const MCP_PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18"];
+const PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
+/** JSON-RPC and MCP error codes. */
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const RESOURCE_NOT_FOUND = -32002;
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function rpcResult(id, result) {
+    return HttpServerResponse.jsonUnsafe({ jsonrpc: "2.0", id, result });
+}
+function rpcError(id, code, message, status = 200) {
+    return HttpServerResponse.jsonUnsafe({ jsonrpc: "2.0", id, error: { code, message } }, { status });
+}
+/** A message that is not a request: a notification, or a response to a request of the server's. */
+const ACCEPTED = HttpServerResponse.empty({ status: 202 });
+const METHOD_NOT_ALLOWED = HttpServerResponse.empty({ status: 405, headers: { allow: "POST" } });
+function classify(body) {
+    if (!isObject(body) || body.jsonrpc !== "2.0") {
+        return { kind: "invalid", id: null };
+    }
+    const { id, method, params } = body;
+    const validId = typeof id === "string" || typeof id === "number";
+    if (typeof method !== "string") {
+        // A response to a request the server sent; this server sends none, so there is nothing to do.
+        return "result" in body || "error" in body ? { kind: "other" } : { kind: "invalid", id: null };
+    }
+    if (id === undefined) {
+        return { kind: "other" };
+    }
+    if (!validId || (params !== undefined && !isObject(params))) {
+        return { kind: "invalid", id: validId ? id : null };
+    }
+    return { kind: "request", id, method, params: params ?? {} };
+}
+/** Arguments a tool could not decode. Unlike a protocol error, the model reads it and corrects itself. */
+class InvalidArguments extends Data.TaggedError("InvalidArguments") {
+}
+/** Decodes a tool's arguments; the service's schemas need no services. */
+function decodeArguments(schema, args) {
+    return Schema.decodeUnknownEffect(schema)(args, {
+        errors: "all",
+        onExcessProperty: "error",
+    }).pipe(Effect.mapError((error) => new InvalidArguments({ issues: schemaIssues(error.issue) })));
+}
+/** What the service sends: a value encoded with the schema of the matching HTTP route. */
+function encoded(schema, value) {
+    return Schema.encodeUnknownEffect(schema)(value).pipe(Effect.orDie);
+}
+const GetArguments = Schema.Struct({ id: IdParam });
+const HistoryArguments = Schema.Struct({ id: IdParam, ...HistoryParams });
+function structured(value) {
+    return { text: JSON.stringify(value), structured: value };
+}
+function errorText(body) {
+    const issues = Array.isArray(body.issues)
+        ? body.issues.map(({ path, message }) => `\n- ${path.length > 0 ? `${path.join(".")}: ` : ""}${message}`)
+        : [];
+    return `${body.detail} (${body.error}, request ${body.requestId})${issues.join("")}`;
+}
+/**
+ * A failed tool call as the model reads it: `isError`, the REST route's error body as structured
+ * content, and the same in a sentence. Unexpected failures are logged with their cause and answered
+ * with the request id only.
+ */
+function toolFailure(cause, requestId) {
+    if (Cause.hasInterruptsOnly(cause)) {
+        return Effect.failCause(cause);
+    }
+    const error = Option.getOrUndefined(Cause.findErrorOption(cause));
+    const expected = error instanceof InvalidArguments
+        ? {
+            error: "invalid_request",
+            detail: "The tool's arguments are invalid.",
+            requestId,
+            issues: error.issues,
+        }
+        : error === undefined
+            ? undefined
+            : expectedFailure(error, requestId)?.body;
+    const failure = expected === undefined
+        ? Effect.logError("ontology.mcp.tool_failed", cause).pipe(Effect.annotateLogs({ requestId }), Effect.as(internalError(requestId).body))
+        : Effect.succeed(expected);
+    return Effect.map(failure, (body) => ({
+        content: [{ type: "text", text: errorText(body) }],
+        structuredContent: errorBodyForWire(body),
+        isError: true,
+    }));
+}
+function runTool({ built, operations }, tool, args, request) {
+    return Effect.gen(function* () {
+        const { target } = tool;
+        switch (target.kind) {
+            case "describe": {
+                const principal = yield* CurrentPrincipal;
+                return {
+                    text: renderCatalog(built.plan.ontology.manifest, { as: principal.permissions }),
+                };
+            }
+            case "me":
+                return structured(yield* encoded(Me, yield* operations.caller));
+            case "find": {
+                const schemas = built.schemas.get(target.planned.name);
+                const query = (yield* decodeArguments(schemas.query, args));
+                const page = yield* operations.find(target.planned, toQuery(query));
+                return structured(yield* encoded(schemas.findResult, page));
+            }
+            case "get": {
+                const schemas = built.schemas.get(target.planned.name);
+                const { id } = yield* decodeArguments(GetArguments, args);
+                return structured(yield* encoded(schemas.record, yield* operations.get(target.planned, id)));
+            }
+            case "history": {
+                const { id, ...params } = yield* decodeArguments(HistoryArguments, args);
+                return structured(yield* encoded(HistoryPage, yield* operations.history(target.planned, id, params)));
+            }
+            case "action": {
+                const answer = yield* operations.runAction(target.planned, target.action, {
+                    input: args,
+                    validateOnly: false,
+                    identityToken: identityToken(request),
+                });
+                return structured(yield* encoded(ActionResponse, answer));
+            }
+        }
+    });
+}
+function callTool(server, params, request) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const tool = server.tools.find((candidate) => candidate.name === params.name);
+        if (tool === undefined) {
+            return { kind: "invalid", message: `Unknown tool: ${String(params.name)}.` };
+        }
+        const args = params.arguments ?? {};
+        if (!isObject(args)) {
+            return { kind: "invalid", message: "The tool's arguments must be an object." };
+        }
+        const result = yield* runTool(server, tool, args, request).pipe(Effect.map(({ text, structured: content }) => ({
+            content: [{ type: "text", text }],
+            ...(content === undefined ? {} : { structuredContent: content }),
+        })), Effect.catchCause((cause) => toolFailure(cause, requestId)));
+        return { kind: "called", result };
+    });
+}
+const CATALOG_URI = "ontology://catalog";
+const DESCRIBE_URI = "ontology://describe";
+const RESOURCES = [
+    {
+        uri: CATALOG_URI,
+        name: "catalog",
+        title: "The ontology's catalog",
+        description: "The manifest: entities, properties, relationships, actions and roles with their " +
+            "permissions, with only the actions you may run.",
+        mimeType: "application/json",
+    },
+    {
+        uri: DESCRIBE_URI,
+        name: "describe",
+        title: "The ontology as prose",
+        description: "What the describe tool returns: the entities you may read and the actions you may run.",
+        mimeType: "text/plain",
+    },
+];
+function readResource({ built }, uri) {
+    return Effect.gen(function* () {
+        const principal = yield* CurrentPrincipal;
+        const { manifest } = built.plan.ontology;
+        switch (uri) {
+            case CATALOG_URI:
+                return [
+                    {
+                        uri,
+                        mimeType: "application/json",
+                        text: JSON.stringify(encodeManifest(catalogFor(manifest, principal.permissions))),
+                    },
+                ];
+            case DESCRIBE_URI:
+                return [
+                    {
+                        uri,
+                        mimeType: "text/plain",
+                        text: renderCatalog(manifest, { as: principal.permissions }),
+                    },
+                ];
+            default:
+                return undefined;
+        }
+    });
+}
+/**
+ * What an agent learns when it connects: what the server is, the entities the caller may read and
+ * where to find the rest.
+ */
+function instructions({ built }, permissions) {
+    const readable = built.plan.entities
+        .filter(({ name, resolved }) => {
+        const definition = resolved.entity.definition;
+        return (definition.source === undefined && isAllowed(permissionOf(name, READ_VERB), { permissions }));
+    })
+        .map(({ name, resolved }) => `- ${name}: ${resolved.entity.definition.description}`);
+    return [
+        "This server is the app's ontology: the records the company works with and the actions " +
+            "that change them. Every change goes through an action, is checked against your " +
+            "permissions and is kept in history; nothing else writes.",
+        readable.length > 0
+            ? `Entities you may read, each with <entity>_find, <entity>_get and <entity>_history:\n${readable.join("\n")}`
+            : "You may read no entities.",
+        "Call describe for the full catalog: properties, relationships and the actions you may run.",
+    ].join("\n\n");
+}
+function negotiate(requested) {
+    return MCP_PROTOCOL_VERSIONS.includes(requested)
+        ? requested
+        : MCP_PROTOCOL_VERSIONS[0];
+}
+/** Answers one JSON-RPC request as the authenticated caller. */
+function dispatch(server, message, request) {
+    return Effect.gen(function* () {
+        const { id, method, params } = message;
+        const principal = yield* CurrentPrincipal;
+        switch (method) {
+            case "initialize":
+                return rpcResult(id, {
+                    protocolVersion: negotiate(params.protocolVersion),
+                    capabilities: { tools: {}, resources: {} },
+                    serverInfo: {
+                        name: "segmentstream-ontology",
+                        title: "Ontology",
+                        version: server.built.plan.ontology.manifest.hash,
+                    },
+                    instructions: instructions(server, principal.permissions),
+                });
+            case "ping":
+                return rpcResult(id, {});
+            case "tools/list":
+                return rpcResult(id, {
+                    tools: visibleTools(server.tools, principal).map((tool) => ({
+                        name: tool.name,
+                        title: tool.title,
+                        description: tool.description,
+                        inputSchema: tool.inputSchema,
+                        ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
+                        annotations: tool.annotations,
+                    })),
+                });
+            case "tools/call": {
+                const called = yield* callTool(server, params, request);
+                return called.kind === "invalid"
+                    ? rpcError(id, INVALID_PARAMS, called.message)
+                    : rpcResult(id, called.result);
+            }
+            case "resources/list":
+                return rpcResult(id, { resources: RESOURCES });
+            case "resources/templates/list":
+                return rpcResult(id, { resourceTemplates: [] });
+            case "resources/read": {
+                const contents = yield* readResource(server, params.uri);
+                return contents === undefined
+                    ? rpcError(id, RESOURCE_NOT_FOUND, `Unknown resource: ${String(params.uri)}.`)
+                    : rpcResult(id, { contents });
+            }
+            default:
+                return rpcError(id, METHOD_NOT_FOUND, `Method not found: ${method}.`);
+        }
+    });
+}
+/** A request from a page on another origin, which a browser sent: refused, as MCP asks. */
+function crossOrigin(request) {
+    const origin = request.headers.origin;
+    if (origin === undefined) {
+        return false;
+    }
+    return !URL.canParse(origin) || new URL(origin).host !== new URL(publicOrigin(request)).host;
+}
+/** `POST /mcp`: one JSON-RPC message in, one JSON response out, nothing kept between requests. */
+function handlePost(server, verifyToken, backend) {
+    const credential = HttpApiBuilder.securityDecode(HttpApiSecurity.bearer);
+    return (request) => Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        if (crossOrigin(request)) {
+            return HttpServerResponse.jsonUnsafe(errorBodyForWire({
+                error: "forbidden",
+                detail: "Requests from another origin are refused.",
+                requestId,
+            }), { status: 403 });
+        }
+        const answer = Effect.gen(function* () {
+            const text = yield* Effect.orDie(request.text);
+            let body;
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                return rpcError(null, PARSE_ERROR, "The body is not valid JSON.", 400);
+            }
+            if (Array.isArray(body)) {
+                return rpcError(null, INVALID_REQUEST, "Batches are not supported.", 400);
+            }
+            const message = classify(body);
+            const version = request.headers[PROTOCOL_VERSION_HEADER];
+            // `initialize` negotiates the revision, so its header is not checked: a 400 there would make
+            // a client fall back to the legacy HTTP+SSE transport.
+            if (version !== undefined &&
+                !MCP_PROTOCOL_VERSIONS.includes(version) &&
+                !(message.kind === "request" && message.method === "initialize")) {
+                return rpcError(null, INVALID_REQUEST, `Unsupported MCP-Protocol-Version ${version}; this server speaks ` +
+                    `${MCP_PROTOCOL_VERSIONS.join(" and ")}.`, 400);
+            }
+            switch (message.kind) {
+                case "invalid":
+                    return rpcError(message.id, INVALID_REQUEST, "Invalid JSON-RPC request.", 400);
+                case "other":
+                    return ACCEPTED;
+                case "request":
+                    return yield* dispatch(server, message, request);
+            }
+        });
+        const origin = publicOrigin(request);
+        // With the OAuth tables, members' access tokens work here, and a 401 tells the client where
+        // the member authorizes it.
+        return yield* withPrincipal(yield* Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request), verifyToken, backend, answer, backend.oauth === undefined
+            ? {}
+            : {
+                oauthResource: mcpResource(origin),
+                challenge: (missing) => mcpChallenge(origin, missing),
+            });
+    });
+}
+/**
+ * The ontology's MCP server at `POST /mcp`: Streamable HTTP without sessions, so any instance can
+ * answer any request. Its tools run the same operations as the HTTP routes, behind the same
+ * authentication. `GET` and `DELETE`, which open a server stream and end a session, answer 405.
+ */
+export function mcpLayer(options) {
+    const tools = mcpTools(options.built);
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const server = {
+            built: options.built,
+            tools,
+            operations: makeOperations(backend, options.built.plan, options.hooks, options.connections),
+        };
+        yield* router.add("POST", MCP_PATH, handlePost(server, options.verifyToken, backend));
+        yield* router.add("GET", MCP_PATH, METHOD_NOT_ALLOWED);
+        yield* router.add("DELETE", MCP_PATH, METHOD_NOT_ALLOWED);
+    }));
+}

package/dist/service/mcp/tools.d.ts

@@ -0,0 +1,47 @@
+import type { JsonSchemaObject } from "../../analyze.js";
+import { type PermissionHolder } from "../../permissions.js";
+import type { BuiltApi } from "../api.js";
+import type { PlannedAction, PlannedEntity } from "../plan.js";
+/** How a tool behaves, as MCP's tool annotations say it. */
+export interface McpToolAnnotations {
+    readonly readOnlyHint: boolean;
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    /** Whether the tool reaches beyond the ontology: true for actions that call connections. */
+    readonly openWorldHint: boolean;
+}
+/** What a tool runs: a read or an action of an entity, or one of the global tools. */
+export type McpToolTarget = {
+    readonly kind: "find" | "get" | "history";
+    readonly planned: PlannedEntity;
+} | {
+    readonly kind: "action";
+    readonly planned: PlannedEntity;
+    readonly action: PlannedAction;
+} | {
+    readonly kind: "describe";
+} | {
+    readonly kind: "me";
+};
+/** A tool of the ontology's MCP server, derived from the same plan as the HTTP routes. */
+export interface McpTool {
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchemaObject;
+    /** The JSON Schema of the tool's `structuredContent`, for the tools that return a known shape. */
+    readonly outputSchema?: JsonSchemaObject;
+    readonly annotations: McpToolAnnotations;
+    /** Every permission a caller needs to see and run the tool; none for the global tools. */
+    readonly permissions: ReadonlyArray<string>;
+    readonly target: McpToolTarget;
+}
+/**
+ * The MCP tools of an ontology: `describe` and `me`, then for every stored entity `find`, `get`,
+ * `history` and a tool per generated and authored action. Entities with a warehouse source have none,
+ * as they have no record routes. Throws {@link InvalidOntology} when two tools share a name, which
+ * `check` already refuses.
+ */
+export declare function mcpTools(built: BuiltApi): ReadonlyArray<McpTool>;
+/** The tools a caller may see: those whose every permission the caller's roles grant. */
+export declare function visibleTools(tools: ReadonlyArray<McpTool>, caller: PermissionHolder): ReadonlyArray<McpTool>;

package/dist/service/mcp/tools.js

@@ -0,0 +1,218 @@
+import { Schema } from "effect";
+import { InvalidOntology } from "../../diagnostics.js";
+import { GENERATED_UPSERT_PREFIX, humanize, mcpToolName } from "../../names.js";
+import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
+import { queryJsonSchema } from "../../query.js";
+import { actionInputJsonSchema } from "../../runtime/generated-actions.js";
+import { actionDescription, requires } from "../descriptions.js";
+import { HistoryPage, Me } from "../schemas.js";
+const DEFS = "#/$defs/";
+/**
+ * A JSON Schema whose root is an object schema, as MCP requires of tool inputs and outputs: a root
+ * `$ref` into `$defs` is replaced by the definition it names.
+ */
+function rootObject(schema) {
+    const reference = schema.$ref;
+    const definitions = schema.$defs;
+    if (typeof reference !== "string" || !reference.startsWith(DEFS) || definitions === undefined) {
+        return schema;
+    }
+    const referenced = definitions[reference.slice(DEFS.length)];
+    if (referenced === undefined) {
+        return schema;
+    }
+    const rest = Object.fromEntries(Object.entries(schema).filter(([key]) => key !== "$ref"));
+    return { ...rest, ...referenced };
+}
+/** The JSON Schema of what a schema encodes to: the shape the service sends. */
+function encodedJsonSchema(schema) {
+    const document = Schema.toJsonSchemaDocument(schema);
+    const root = document.schema;
+    return rootObject(Object.keys(document.definitions).length === 0
+        ? root
+        : { ...root, $defs: document.definitions });
+}
+const NO_INPUT = { type: "object", properties: {}, additionalProperties: false };
+function idInput(label) {
+    return {
+        type: "object",
+        properties: { id: { type: "string", format: "uuid", description: `The ${label}'s id.` } },
+        required: ["id"],
+        additionalProperties: false,
+    };
+}
+function historyInput(label) {
+    return {
+        type: "object",
+        properties: {
+            id: { type: "string", format: "uuid", description: `The ${label}'s id.` },
+            after: { type: "string", description: "The next_cursor of the previous page." },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                maximum: 200,
+                description: "The page size, at most 200.",
+            },
+        },
+        required: ["id"],
+        additionalProperties: false,
+    };
+}
+const READ = { readOnlyHint: true, openWorldHint: false };
+/** The hints of generated actions, which only their name tells apart. */
+const GENERATED_HINTS = {
+    create: { destructive: false, idempotent: false },
+    update: { destructive: true, idempotent: true },
+    delete: { destructive: true, idempotent: true },
+    link: { destructive: false, idempotent: true },
+    unlink: { destructive: true, idempotent: true },
+};
+/** MCP's defaults for a tool that writes: it may destroy, and repeating it may change more. */
+const AUTHORED_DEFAULT = { destructive: true, idempotent: false };
+function hintsOf(planned, { name, generated }) {
+    if (generated) {
+        return name.startsWith(GENERATED_UPSERT_PREFIX)
+            ? { destructive: true, idempotent: true }
+            : (GENERATED_HINTS[name] ?? AUTHORED_DEFAULT);
+    }
+    const declared = planned.resolved.actions.find((candidate) => candidate.name === name)?.hints;
+    return { ...AUTHORED_DEFAULT, ...declared };
+}
+/** How an agent reaches the records a relationship leads to, with the tools it has. */
+function relatedHint(planned, traversal) {
+    const id = `<${planned.resolved.entity.definition.label.toLowerCase()} id>`;
+    const find = mcpToolName(traversal.target, "find");
+    switch (traversal.kind) {
+        case "one":
+            return (`${traversal.name}: include {"${traversal.name}": true}, or ` +
+                `${mcpToolName(traversal.target, "get")} with ${traversal.name}_id.`);
+        case "inverseOfOne":
+            return `${traversal.name}: ${find} with where {"${traversal.opposite}": {"id": {"eq": "${id}"}}}.`;
+        case "many":
+        case "inverseOfMany":
+            return (`${traversal.name}: ${find} with where ` +
+                `{"${traversal.opposite}": {"some": {"id": {"eq": "${id}"}}}}.`);
+    }
+}
+function readTools(planned, schemas, built) {
+    const { manifest } = built.plan.ontology;
+    const { definition } = planned.resolved.entity;
+    const label = definition.label.toLowerCase();
+    const read = permissionOf(planned.name, READ_VERB);
+    const related = planned.traversals.map((traversal) => `- ${relatedHint(planned, traversal)}`);
+    return [
+        {
+            name: mcpToolName(planned.name, "find"),
+            title: `Find ${definition.plural.toLowerCase()}`,
+            description: `Filter, sort and page through ${definition.plural.toLowerCase()}, at most 200 at a ` +
+                `time; pass next_cursor as after to read the next page. ${definition.description}\n\n` +
+                `${requires([read])} Including a relationship, or filtering through one, requires ` +
+                "reading its entity too." +
+                (related.length > 0 ? `\n\nRelated records:\n${related.join("\n")}` : ""),
+            // The query of POST /<entity>/query, closed: an unknown field or operator is an error.
+            inputSchema: queryJsonSchema(manifest, planned.name),
+            outputSchema: encodedJsonSchema(schemas.findResult),
+            annotations: READ,
+            permissions: [read],
+            target: { kind: "find", planned },
+        },
+        {
+            name: mcpToolName(planned.name, "get"),
+            title: `Get a ${label}`,
+            description: `One ${label} by its id. ${definition.description}\n\n${requires([read])}`,
+            inputSchema: idInput(label),
+            outputSchema: encodedJsonSchema(schemas.record),
+            annotations: READ,
+            permissions: [read],
+            target: { kind: "get", planned },
+        },
+        {
+            name: mcpToolName(planned.name, "history"),
+            title: `History of a ${label}`,
+            description: `What each action changed on a ${label}, newest first, with who ran it and the values ` +
+                `before and after. ${requires([read])}`,
+            inputSchema: historyInput(label),
+            outputSchema: encodedJsonSchema(HistoryPage),
+            annotations: READ,
+            permissions: [read],
+            target: { kind: "history", planned },
+        },
+    ];
+}
+function actionTool(planned, plannedAction) {
+    const { name, action, permissions } = plannedAction;
+    const hints = hintsOf(planned, plannedAction);
+    return {
+        name: mcpToolName(planned.name, name),
+        title: `${planned.resolved.entity.definition.label}: ${humanize(name).toLowerCase()}`,
+        description: actionDescription(plannedAction),
+        inputSchema: rootObject(actionInputJsonSchema(action.input)),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: hints.destructive,
+            idempotentHint: hints.idempotent,
+            openWorldHint: action.connections.length > 0,
+        },
+        permissions,
+        target: { kind: "action", planned, action: plannedAction },
+    };
+}
+const GLOBAL_TOOLS = [
+    {
+        name: "describe",
+        title: "Describe the ontology",
+        description: "The ontology as prose: the entities you may read, their properties and relationships, " +
+            "and the actions you may run, each with what it requires. Read it before working with " +
+            "records.",
+        inputSchema: NO_INPUT,
+        annotations: READ,
+        permissions: [],
+        target: { kind: "describe" },
+    },
+    {
+        name: "me",
+        title: "Who am I",
+        description: "Who you are in this app: your user, your roles and the permissions they grant. History " +
+            "names you by the user id.",
+        inputSchema: NO_INPUT,
+        outputSchema: encodedJsonSchema(Me),
+        annotations: READ,
+        permissions: [],
+        target: { kind: "me" },
+    },
+];
+/**
+ * The MCP tools of an ontology: `describe` and `me`, then for every stored entity `find`, `get`,
+ * `history` and a tool per generated and authored action. Entities with a warehouse source have none,
+ * as they have no record routes. Throws {@link InvalidOntology} when two tools share a name, which
+ * `check` already refuses.
+ */
+export function mcpTools(built) {
+    const tools = [...GLOBAL_TOOLS];
+    for (const planned of built.plan.entities) {
+        if (planned.resolved.entity.definition.source !== undefined) {
+            continue;
+        }
+        const schemas = built.schemas.get(planned.name);
+        tools.push(...readTools(planned, schemas, built));
+        tools.push(...planned.actions.map((action) => actionTool(planned, action)));
+    }
+    const seen = new Set();
+    const duplicates = tools.filter(({ name }) => seen.size === seen.add(name).size);
+    if (duplicates.length > 0) {
+        throw new InvalidOntology({
+            message: `The ontology's MCP tools collide: ${duplicates.map(({ name }) => name).join(", ")}.`,
+            diagnostics: duplicates.map(({ name }) => ({
+                severity: "error",
+                code: "invalid-tool-name",
+                path: name,
+                message: `${name} is the name of two MCP tools.`,
+            })),
+        });
+    }
+    return tools;
+}
+/** The tools a caller may see: those whose every permission the caller's roles grant. */
+export function visibleTools(tools, caller) {
+    return tools.filter((tool) => tool.permissions.every((required) => isAllowed(required, caller)));
+}