@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/mcp/server.js

@@ -0,0 +1,861 @@
+import { Cause, Data, Effect, Layer, Option, Redacted, Schema, SchemaTransformation } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { ActionRejected } from "../../errors.js";
+import { DeploymentAdmissionError } from "../../deployment.js";
+import { effectivePermissions } from "../../permissions.js";
+import { encodeManifest } from "../../manifest.js";
+import { describeError, SCOPE_MISMATCH } from "../metric-query-platform.js";
+import { gatewayCredential, gatewayDecisions } from "../decisions.js";
+import { CurrentPrincipal, withPrincipal } from "../authentication.js";
+import { currentCaller } from "../caller-context.js";
+import { requireRuntimeOperation, runtimeManifest } from "./runtime-policy.js";
+import { CONFIRMATION_PREVIEW_METHOD, previewLocale, withoutConfirmation } from "./confirmation.js";
+import { consumeChatEnvelope, CurrentChatCall } from "../chat/envelope.js";
+import { ChatList, ChatHistory, ChatPostWire, RuntimeChatPostWire } from "../chat/schemas.js";
+import { ChatPostResult } from "../../chat.js";
+import { chatReads } from "../chat/reads.js";
+import { withChatMembership } from "../chat/resolve.js";
+import { catalogFor } from "../catalog.js";
+import { createDiscovery, DiscoveryError } from "../discovery.js";
+import { suggestNames, suggestionDetail } from "../name-suggestions.js";
+import { DiscoverInput } from "../discovery-schemas.js";
+import { NavigationInput } from "../navigation-schemas.js";
+import { createNavigation, NavigationError } from "../navigation.js";
+import { ConversationSearch } from "../agent/conversations.js";
+import { GetDimensionsInput, GetDimensionValuesInput, ListMetricsInput, listMetrics, metricDimensions, planDimensionValues, VALUES_DEFAULT, } from "./metric-tools.js";
+import { RequestId, errorBodyForWire, expectedFailure, internalError, isStorageFailure, schemaIssues, storageUnavailable, } 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 { WarehouseQueries } from "../warehouse-platform.js";
+import { runtimeCredential } from "../runtime-identity.js";
+import { ActionResponse, HistoryPage, HistoryParams, IdParam, WarehouseIdParam, Me, } from "../schemas.js";
+import { uploadFields } from "../../storage/attachments.js";
+import { RECORDS_OR_METRIC_QUERIES } from "../../render.js";
+import { memberFileOperations } from "../member-files.js";
+import { ACTION_OPTIONS_ARGUMENT, mcpTools, RUNTIME_SOURCE_META, visibleTools, } from "./tools.js";
+import { listTools, toolDefinition } from "./listing.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, data) {
+    return HttpServerResponse.jsonUnsafe({ jsonrpc: "2.0", id, error: { code, message, ...(data === undefined ? {} : { data }) } }, { 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.setHeader(rpcError(null, INVALID_REQUEST, "Use GET with Accept: text/event-stream, or POST.", 405), "allow", "GET, POST");
+/** Bearer clients may call from any origin; cookies never authorize this transport. */
+const CORS = {
+    "access-control-allow-origin": "*",
+    "access-control-allow-methods": "GET, POST",
+    "access-control-allow-headers": "authorization, content-type, mcp-protocol-version, mcp-session-id, last-event-id",
+    "access-control-expose-headers": "www-authenticate, mcp-protocol-version, mcp-session-id, x-request-id",
+};
+const PREFLIGHT = HttpServerResponse.empty({
+    status: 204,
+    headers: { ...CORS, allow: "GET, POST" },
+});
+// The generated Vercel service enables Fluid without a maxDuration override. Stay below even
+// a 60s function limit, leaving time for cold starts and authentication before the stream opens.
+export const MCP_STREAM_MAX_DURATION_MS = 45_000;
+const HEARTBEAT_MS = 15_000;
+/** A stateless keepalive stream: comments and a reconnect hint, never JSON-RPC messages or IDs. */
+function eventStream(signal, maxDurationMs) {
+    let cleanup = () => { };
+    const stream = new ReadableStream({
+        start(controller) {
+            const encoder = new TextEncoder();
+            let closed = false;
+            const finish = (closeStream) => {
+                if (closed) {
+                    return;
+                }
+                closed = true;
+                clearInterval(heartbeat);
+                clearTimeout(deadline);
+                signal.removeEventListener("abort", close);
+                if (closeStream) {
+                    controller.close();
+                }
+            };
+            const close = () => finish(true);
+            cleanup = () => finish(false);
+            controller.enqueue(encoder.encode(": connected\nretry: 1000\n\n"));
+            const heartbeat = setInterval(() => {
+                // A slow reader needs no queued keepalives; bound memory until it reads or disconnects.
+                if ((controller.desiredSize ?? 0) > 0) {
+                    controller.enqueue(encoder.encode(": heartbeat\n\n"));
+                }
+            }, HEARTBEAT_MS);
+            const deadline = setTimeout(close, maxDurationMs);
+            signal.addEventListener("abort", close, { once: true });
+            if (signal.aborted) {
+                close();
+            }
+        },
+        cancel() {
+            cleanup();
+        },
+    });
+    return HttpServerResponse.raw(stream, {
+        contentType: "text/event-stream",
+        headers: { "cache-control": "no-cache, no-transform", "x-accel-buffering": "no" },
+    });
+}
+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) })));
+}
+/** The `_options` argument of an action tool that consumes or stages an upload. */
+const McpActionOptions = Schema.Struct({
+    idempotency_key: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(128))),
+    create_intent: Schema.optionalKey(Schema.String.check(Schema.isUUID())),
+}).pipe(Schema.decodeTo(Schema.Struct({
+    idempotencyKey: Schema.optionalKey(Schema.String),
+    createIntent: Schema.optionalKey(Schema.String),
+}), SchemaTransformation.transform({
+    decode: (value) => ({
+        ...(value.idempotency_key === undefined ? {} : { idempotencyKey: value.idempotency_key }),
+        ...(value.create_intent === undefined ? {} : { createIntent: value.create_intent }),
+    }),
+    encode: (value) => ({
+        ...(value.idempotencyKey === undefined ? {} : { idempotency_key: value.idempotencyKey }),
+        ...(value.createIntent === undefined ? {} : { create_intent: value.createIntent }),
+    }),
+})));
+/** 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("")}`;
+}
+/** SegmentStream's refusal when its deployed manifest is not the one the service checked against. */
+const VERSION_MISMATCH = "ontology_version_mismatch";
+/** What the agent reads instead of SegmentStream's detail, for refusals it must act on itself. */
+const AGENT_DETAILS = {
+    [VERSION_MISMATCH]: "The ontology changed; call list_metrics for the current metric names, then call " +
+        "query_metrics with them.",
+    [SCOPE_MISMATCH]: "SegmentStream would read entities this app's ontology service did not check, so it refused. " +
+        "Retrying will not help: ask the app's operator to update @segmentstream/ontology and " +
+        "redeploy.",
+};
+/**
+ * SegmentStream's answer to a metric query as the model reads it: the body as structured content, its
+ * warnings first in the text so they are not missed, and an error status as a tool error.
+ */
+function metricQueryOutput(answer) {
+    const { body } = answer;
+    if (answer.status >= 400) {
+        const code = typeof body.error === "string" ? body.error : `HTTP ${answer.status}`;
+        const reference = typeof body.requestId === "string" ? `, request ${body.requestId}` : "";
+        const detail = AGENT_DETAILS[code] ??
+            (typeof body.detail === "string" ? body.detail : "The metric query failed.");
+        return { text: `${detail} (${code}${reference})`, structured: body, isError: true };
+    }
+    return withWarnings(body, warningsOf(body));
+}
+/** The warnings of SegmentStream's answer to a metric query, such as a filter some entity missed. */
+function warningsOf(body) {
+    const execution = body.execution;
+    return Array.isArray(execution?.warnings)
+        ? execution.warnings.filter((warning) => typeof warning === "string")
+        : [];
+}
+/** Structured content as the model reads it, with the warnings first in the text. */
+function withWarnings(value, warnings) {
+    const json = JSON.stringify(value);
+    return {
+        text: warnings.length === 0
+            ? json
+            : `Warnings:\n${warnings.map((warning) => `- ${warning}`).join("\n")}\n\n${json}`,
+        structured: value,
+    };
+}
+/**
+ * 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 typedFailure = Option.getOrUndefined(Cause.findErrorOption(cause));
+    const defect = typedFailure === undefined ? Cause.squash(cause) : undefined;
+    const error = typedFailure ?? (defect instanceof DeploymentAdmissionError ? defect : undefined);
+    const expected = error instanceof NavigationError
+        ? {
+            error: error.error,
+            detail: error.detail,
+            requestId,
+            ...(error.revision === undefined ? {} : { revision: error.revision }),
+        }
+        : error instanceof DiscoveryError
+            ? {
+                error: error.error,
+                detail: error.detail,
+                requestId,
+                ...(error.hash === undefined ? {} : { hash: error.hash }),
+                ...(error.suggestions === undefined ? {} : { suggestions: error.suggestions }),
+            }
+            : 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.succeed(expected)
+        : isStorageFailure(error)
+            ? Effect.logError("ontology.storage.failed", cause).pipe(Effect.annotateLogs({ requestId }), Effect.as(storageUnavailable(requestId).body))
+            : Effect.logError("ontology.mcp.tool_failed", cause).pipe(Effect.annotateLogs({ requestId }), Effect.as(internalError(requestId).body));
+    const reported = error instanceof NavigationError && error.error === "page_catalog_unavailable"
+        ? Effect.logError("ontology.navigation.unavailable", error.cause).pipe(Effect.annotateLogs({ requestId }), Effect.andThen(failure))
+        : failure;
+    return Effect.map(reported, (body) => ({
+        content: [{ type: "text", text: errorText(body) }],
+        structuredContent: errorBodyForWire(body),
+        isError: true,
+    }));
+}
+function runTool(server, tool, args, request, preview) {
+    const { built, operations, queryMetrics, conversations, discovery, memberFiles, chats } = server;
+    return Effect.gen(function* () {
+        const { target } = tool;
+        const caller = yield* currentCaller;
+        switch (target.kind) {
+            case "navigation": {
+                const principal = yield* CurrentPrincipal;
+                const input = yield* decodeArguments(NavigationInput, args);
+                const result = yield* Effect.try({
+                    try: () => {
+                        if (server.navigation === undefined) {
+                            throw new Error("Navigation tool has no deployment catalog binding.");
+                        }
+                        return server.navigation(input, principal, caller, publicOrigin(request));
+                    },
+                    catch: (error) => error,
+                });
+                return structured(result);
+            }
+            case "discover": {
+                const principal = yield* CurrentPrincipal;
+                const input = yield* decodeArguments(DiscoverInput, args);
+                const model = built.plan.ontology.config.discovery?.model;
+                // Meaning ranks entities on one page; actions, metrics and later pages match words.
+                if (model !== undefined &&
+                    input.after === undefined &&
+                    (input.kind ?? "entity") === "entity") {
+                    const credential = gatewayCredential(identityToken(request));
+                    const decide = server.decide ?? gatewayDecisions({ credential: () => credential });
+                    const ranked = yield* Effect.tryPromise({
+                        try: () => discovery.discoverByMeaning(input, principal, caller, { decide, model }),
+                        catch: (error) => error,
+                    }).pipe(Effect.exit);
+                    if (ranked._tag === "Success") {
+                        return structured(ranked.value);
+                    }
+                    const failure = Cause.squash(ranked.cause);
+                    if (failure instanceof DiscoveryError) {
+                        return yield* Effect.fail(failure);
+                    }
+                    // A search never fails because of the model: word matching answers, and operators
+                    // see why, without the gateway credential.
+                    yield* Effect.logWarning("ontology.discover.ranking_failed").pipe(Effect.annotateLogs({
+                        model,
+                        error: describeError(failure, (text) => credential === undefined ? text : text.split(credential.token).join("[redacted]")),
+                    }));
+                    return structured({ ...discovery.discover(input, principal, caller), ranking: "words" });
+                }
+                const result = yield* Effect.try({
+                    try: () => discovery.discover(input, principal, caller),
+                    catch: (error) => error,
+                });
+                return structured(model === undefined ? result : { ...result, ranking: "words" });
+            }
+            case "query-metrics": {
+                // The route's facade, as the caller: the arguments are the request body.
+                const answer = yield* queryMetrics(args).pipe(Effect.catchTag("InvalidRequestBody", (error) => Effect.fail(new InvalidArguments({ issues: error.issues }))));
+                return metricQueryOutput(answer);
+            }
+            case "list-metrics": {
+                const { search } = yield* decodeArguments(ListMetricsInput, args);
+                const permissions = effectivePermissions(yield* CurrentPrincipal);
+                return structured({
+                    metrics: listMetrics(built.plan.ontology.manifest, permissions, search),
+                });
+            }
+            case "get-dimensions": {
+                const { metrics, search } = yield* decodeArguments(GetDimensionsInput, args);
+                const permissions = effectivePermissions(yield* CurrentPrincipal);
+                const answer = metricDimensions(built.plan.ontology.manifest, permissions, metrics, search);
+                if ("reason" in answer) {
+                    return yield* new InvalidArguments({
+                        issues: [{ path: ["metrics"], message: answer.reason }],
+                    });
+                }
+                return structured(answer);
+            }
+            case "get-dimension-values": {
+                const input = yield* decodeArguments(GetDimensionValuesInput, args);
+                const permissions = effectivePermissions(yield* CurrentPrincipal);
+                const { dimension } = input;
+                const plan = planDimensionValues(built.plan.ontology.manifest, permissions, dimension, input.metrics);
+                switch (plan.kind) {
+                    case "refused":
+                        return yield* new InvalidArguments({
+                            issues: [{ path: ["dimension"], message: plan.reason }],
+                        });
+                    case "boolean":
+                        return structured({ dimension, values: [true, false], truncated: false });
+                    case "options": {
+                        const options = plan.property.options ?? [];
+                        return structured({
+                            dimension,
+                            values: options.map((option) => option.value),
+                            options: options.map(({ value, label, description }) => ({
+                                value,
+                                label,
+                                ...(description === "" ? {} : { description }),
+                            })),
+                            truncated: false,
+                        });
+                    }
+                }
+                const answer = yield* queryMetrics({
+                    metrics: plan.metrics,
+                    dimensions: [dimension],
+                    filters: [
+                        ...(input.filters ?? []),
+                        ...(input.search === undefined
+                            ? []
+                            : [{ dimension, operator: "contains", value: input.search }]),
+                    ],
+                    orderBy: [{ dimension, direction: "asc" }],
+                    limit: input.limit ?? VALUES_DEFAULT,
+                }).pipe(Effect.catchTag("InvalidRequestBody", (error) => Effect.fail(new InvalidArguments({ issues: error.issues }))));
+                if (answer.status >= 400) {
+                    return metricQueryOutput(answer);
+                }
+                const { body } = answer;
+                const requested = new Set(plan.metrics);
+                const fields = Array.isArray(body.fields) ? body.fields : [];
+                // A scoped dimension's parent comes first, marked implicit: the values are the requested
+                // dimension's, under its own name when the platform answers with it.
+                const grouped = fields.filter((candidate) => typeof candidate.name === "string" &&
+                    !requested.has(candidate.name) &&
+                    candidate.implicit !== true);
+                const field = (grouped.find((candidate) => candidate.name === dimension) ?? grouped[0])
+                    ?.name;
+                const rows = Array.isArray(body.rows) ? body.rows : [];
+                const values = [
+                    ...new Set(rows.map((row) => row[typeof field === "string" ? field : dimension] ?? null)),
+                ];
+                // A filter that missed some metric's entity leaves its rows unfiltered: the warnings say so.
+                const warnings = warningsOf(body);
+                return withWarnings({
+                    dimension,
+                    values: values,
+                    metrics: [...plan.metrics],
+                    truncated: body.truncated === true,
+                    ...(warnings.length === 0 ? {} : { warnings: [...warnings] }),
+                }, warnings);
+            }
+            case "me":
+                return structured(yield* encoded(Me, yield* operations.caller));
+            case "chat-list":
+                return structured(yield* chats.list(yield* decodeArguments(ChatList, args)));
+            case "chat-history":
+                return structured(yield* chats.history(yield* decodeArguments(ChatHistory, args), identityToken(request)));
+            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(target.planned.resolved.entity.definition.source === undefined
+                    ? GetArguments
+                    : Schema.Struct({ id: WarehouseIdParam }), args);
+                return structured(yield* encoded(schemas.record, yield* operations.get(target.planned, id)));
+            }
+            case "member-file":
+                return structured(yield* memberFiles(target.operation, args, identityToken(request)));
+            case "conversation-search": {
+                if (!conversations) {
+                    return yield* new ActionRejected({
+                        message: "The conversation archive is not configured.",
+                    });
+                }
+                const search = yield* decodeArguments(ConversationSearch, args);
+                const principal = yield* CurrentPrincipal;
+                return structured(yield* conversations({ search, principal, identityToken: identityToken(request) }));
+            }
+            case "history": {
+                const { id, ...params } = yield* decodeArguments(HistoryArguments, args);
+                return structured(yield* encoded(HistoryPage, yield* operations.history(target.planned, id, params)));
+            }
+            case "action": {
+                if (target.planned.name === "agent_chat" && target.action.name === "post_message") {
+                    yield* decodeArguments(caller.kind === "runtime" ? RuntimeChatPostWire : ChatPostWire, args);
+                    const answer = yield* operations.runAction(target.planned, target.action, {
+                        input: args,
+                        validateOnly: false,
+                        identityToken: identityToken(request),
+                    });
+                    return structured(yield* encoded(ChatPostResult, answer.result));
+                }
+                const { [ACTION_OPTIONS_ARGUMENT]: rawOptions, ...input } = args;
+                // What the person confirms is described from the business input alone, and nothing runs.
+                if (preview !== undefined) {
+                    const answer = yield* operations.runAction(target.planned, target.action, {
+                        input,
+                        validateOnly: false,
+                        confirm: preview,
+                        identityToken: identityToken(request),
+                    });
+                    return structured({
+                        confirmation: (answer.result ?? null),
+                    });
+                }
+                const options = rawOptions === undefined ||
+                    (uploadFields(target.action.action.input).length === 0 &&
+                        (target.action.action.files?.length ?? 0) === 0)
+                    ? undefined
+                    : yield* decodeArguments(McpActionOptions, rawOptions);
+                const answer = yield* operations.runAction(target.planned, target.action, {
+                    input: options === undefined ? args : input,
+                    validateOnly: false,
+                    ...(options === undefined ? {} : { options }),
+                    identityToken: identityToken(request),
+                });
+                return structured(yield* encoded(ActionResponse, answer));
+            }
+        }
+    });
+}
+/**
+ * Calls a tool, or with `preview`, asks a confirmable action what its person confirms: a tool that
+ * describes no confirmation of its own is then refused, so a stale or mistaken preview runs nothing.
+ */
+function callTool(server, params, request, preview) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const caller = yield* currentCaller;
+        const principal = yield* CurrentPrincipal;
+        const call = params;
+        const tool = server.tools.find((candidate) => candidate.name === call.name);
+        const allowed = yield* requireRuntimeOperation({
+            ...(typeof call.name === "string" ? { name: call.name } : {}),
+            ...(tool === undefined ? {} : { target: tool.target }),
+        }).pipe(Effect.exit);
+        if (allowed._tag === "Failure") {
+            return { kind: "called", result: yield* toolFailure(allowed.cause, requestId) };
+        }
+        if (tool === undefined) {
+            const candidates = visibleTools(server.tools, principal, caller)
+                .filter((candidate) => candidate.target.kind === "action")
+                .map((candidate) => candidate.name);
+            const suggestions = typeof call.name === "string" ? suggestNames(call.name, candidates) : [];
+            return {
+                kind: "invalid",
+                message: suggestionDetail(`Unknown tool: ${String(call.name)}.`, suggestions),
+                data: suggestions.length === 0 ? undefined : { suggestions },
+            };
+        }
+        const args = call.arguments ?? {};
+        if (!isObject(args)) {
+            return {
+                kind: "invalid",
+                message: "The tool's arguments must be an object.",
+                data: undefined,
+            };
+        }
+        if (preview !== undefined && tool.confirmation?.preview !== true) {
+            return {
+                kind: "invalid",
+                message: `${tool.name} describes no confirmation of its own; nothing was run.`,
+                data: undefined,
+            };
+        }
+        const execute = Effect.gen(function* () {
+            const consumed = yield* consumeChatEnvelope(args, yield* currentCaller);
+            const run = runTool(server, tool, withoutConfirmation(consumed.input), request, preview);
+            return yield* consumed.envelope === undefined
+                ? run
+                : run.pipe(Effect.provideService(CurrentChatCall, consumed.envelope));
+        });
+        const result = yield* execute.pipe(Effect.map(({ text, structured: content, isError }) => ({
+            content: [{ type: "text", text }],
+            ...(content === undefined ? {} : { structuredContent: content }),
+            ...(isError === true ? { isError } : {}),
+        })), Effect.catchCause((cause) => toolFailure(cause, requestId)));
+        return { kind: "called", result };
+    });
+}
+const CATALOG_URI = "ontology://catalog";
+const TOOL_URI = "ontology://tools/";
+/**
+ * One tool as this caller's `tools/list` lists it, for a client that holds only its name, such as
+ * an agent runtime confirming a call that another of its tools makes on the member's behalf.
+ */
+const RESOURCE_TEMPLATES = [
+    {
+        uriTemplate: `${TOOL_URI}{name}`,
+        name: "tool",
+        title: "One listed tool",
+        description: "The tool named name exactly as tools/list lists it to the caller, or not found when it does " +
+            "not list it.",
+        mimeType: "application/json",
+    },
+];
+const RESOURCES = [
+    {
+        uri: CATALOG_URI,
+        name: "catalog",
+        title: "The ontology's catalog",
+        description: "Explicit full manifest export, with current permission filtering. Can be large; the " +
+            "tools themselves describe what an agent needs.",
+        mimeType: "application/json",
+    },
+];
+function readResource({ built, tools }, uri) {
+    return Effect.gen(function* () {
+        const principal = yield* CurrentPrincipal;
+        const caller = yield* currentCaller;
+        const { manifest } = built.plan.ontology;
+        switch (uri) {
+            case CATALOG_URI:
+                return [
+                    {
+                        uri,
+                        mimeType: "application/json",
+                        text: JSON.stringify(encodeManifest(catalogFor(runtimeManifest(manifest, caller), effectivePermissions(principal)))),
+                    },
+                ];
+            default: {
+                const name = typeof uri === "string" && uri.startsWith(TOOL_URI) ? uri.slice(TOOL_URI.length) : "";
+                const tool = visibleTools(tools, principal, caller).find((candidate) => candidate.name === name);
+                return tool === undefined
+                    ? undefined
+                    : [{ uri, mimeType: "application/json", text: JSON.stringify(toolDefinition(tool)) }];
+            }
+        }
+    });
+}
+/**
+ * When to offer feedback, for a caller who may send it. Platform guidance for the agent; the agent
+ * words the offer itself, in the conversation's language.
+ */
+export const FEEDBACK_INSTRUCTIONS = "Feedback: this app accepts feedback for its builders. Offer to send it when the user wants " +
+    "something no permitted tool, field or data provides, an operation is refused for lack of " +
+    "permission, an operation fails unexpectedly or a retryable failure persists, or the user says " +
+    "something works badly or asks for something new. Do not offer what you can do yourself; offer " +
+    "once per problem. Before submitting, look for the user's open app_feedback with the same " +
+    "subject. Submit with app_feedback_submit only after the user agrees to the title and summary you " +
+    "show in their language. At the " +
+    "start of a conversation, find the user's app_feedback with responded_at set and seen_at empty, " +
+    "tell them the builders' response, then call app_feedback_acknowledge with its responded_at.";
+export const AUTOMATIC_FAILURE_REPORT_INSTRUCTIONS = "Feedback: During requested work, this workspace preauthorizes minimal technical failure reports. " +
+    "Automatically record unexpected or persistent tool/connection failures through app_feedback_submit; " +
+    "first reuse the caller's open report with the same subject. Include only the operation, safe technical " +
+    "reason and request_id/error code, never business contents, credentials or files. Explain the actual " +
+    "reason and that the report was recorded in one or two sentences; do not merely offer to report it, " +
+    "and never claim it was recorded before a successful submission or existing-item read. " +
+    "Feature/change requests and sharing task contents or files still require the member's agreement " +
+    "to the title and summary. At conversation start, read the caller's unseen builder responses and " +
+    "acknowledge only the response you have relayed.";
+/**
+ * Fixed guidance keeps initialization independent of ontology size: the feedback paragraph depends
+ * only on whether the caller may run `app_feedback_submit`.
+ */
+function instructions(feedback, files, automaticFailureReports, byMeaning, metrics) {
+    return [
+        "This server is the app's ontology. Every change goes through an action, is checked " +
+            "against your current permissions, and is kept in history.",
+        "Each <entity>_find describes its entity: what its fields and their values mean, its " +
+            "related records and its metrics. Each action's tool says what it does and when it is " +
+            "refused." +
+            (metrics
+                ? " list_metrics lists every metric you may compute, get_dimensions what they can be " +
+                    "grouped by, get_dimension_values a dimension's values, and query_metrics computes them."
+                : "") +
+            (byMeaning
+                ? " To learn which entities a request concerns, call discover with the request."
+                : ""),
+        "Call me for the caller and permissions. Metadata visibility does not grant record access. " +
+            "Stored entities use <entity>_find, <entity>_get, <entity>_history and permitted action tools.",
+        `For analytics, ${RECORDS_OR_METRIC_QUERIES}. Warehouse observations also support find/get and relationship reads.`,
+        "Use the authenticated tool annotations for confirmation: permitted actions classified as " +
+            "non-destructive and reversible need no extra approval. Destructive, irreversible or " +
+            "external actions (openWorldHint) require confirmation before preparation; idempotence " +
+            "alone does not waive it. Present confirmations in the conversation's language using " +
+            "action, entity, field and option labels and readable record titles, never tool names, ids or JSON.",
+        ...(feedback
+            ? [
+                (automaticFailureReports
+                    ? AUTOMATIC_FAILURE_REPORT_INSTRUCTIONS
+                    : FEEDBACK_INSTRUCTIONS) +
+                    (files ? " Add each screenshot or file with app_feedback_file_attach." : ""),
+            ]
+            : []),
+    ].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;
+        const caller = yield* currentCaller;
+        switch (method) {
+            case "initialize":
+                return rpcResult(id, {
+                    protocolVersion: negotiate(params.protocolVersion),
+                    capabilities: {
+                        tools: {},
+                        resources: {},
+                        // The agent runtime learns that tool calls accept its chat source without listing
+                        // the catalog. The `me` tool keeps its `_meta` marker for older agents.
+                        experimental: { [RUNTIME_SOURCE_META]: {} },
+                    },
+                    serverInfo: {
+                        name: "segmentstream-ontology",
+                        title: "Ontology",
+                        version: server.built.plan.ontology.manifest.hash,
+                    },
+                    instructions: instructions(visibleTools(server.tools, principal, caller).some((tool) => tool.name === "app_feedback_submit"), visibleTools(server.tools, principal, caller).some((tool) => tool.name === "app_feedback_file_attach"), server.built.plan.ontology.manifest.feedback?.automaticFailureReports === true, server.built.plan.ontology.config.discovery !== undefined, visibleTools(server.tools, principal, caller).some((tool) => tool.name === "query_metrics")),
+                });
+            case "ping":
+                return rpcResult(id, {});
+            case "tools/list": {
+                return yield* Effect.try({
+                    try: () => listTools(server.tools, principal, caller, server.built.plan.ontology.manifest.hash, params.cursor),
+                    catch: (error) => error,
+                }).pipe(Effect.map((result) => rpcResult(id, result)), Effect.catchIf((error) => error instanceof DiscoveryError, (error) => Effect.succeed(rpcError(id, INVALID_PARAMS, error.detail))));
+            }
+            case "tools/call":
+            case CONFIRMATION_PREVIEW_METHOD: {
+                const called = yield* callTool(server, params, request, method === CONFIRMATION_PREVIEW_METHOD
+                    ? { locale: previewLocale(params.locale) }
+                    : undefined);
+                return called.kind === "invalid"
+                    ? rpcError(id, INVALID_PARAMS, called.message, 200, called.data)
+                    : rpcResult(id, called.result);
+            }
+            case "resources/list":
+                return rpcResult(id, { resources: RESOURCES });
+            case "resources/templates/list":
+                return rpcResult(id, { resourceTemplates: RESOURCE_TEMPLATES });
+            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}.`);
+        }
+    });
+}
+/** Whether the supplied Origin differs from this service's public host. */
+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;
+}
+/** GET and POST deliberately share bearer-only authentication and Origin policy. */
+function withMcpPrincipal(request, verifyToken, verifyRuntime, backend, answer, workspaceId) {
+    const credential = HttpApiBuilder.securityDecode(HttpApiSecurity.bearer);
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const bearer = yield* Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request);
+        // Explicit bearer credentials still pass through authentication below, even if invalid.
+        if (Redacted.value(bearer).trim().length === 0 && crossOrigin(request)) {
+            return HttpServerResponse.jsonUnsafe(errorBodyForWire({
+                error: "forbidden",
+                detail: "Requests from another origin are refused.",
+                requestId,
+            }), { status: 403 });
+        }
+        const origin = publicOrigin(request);
+        const runtime = runtimeCredential(verifyRuntime, request);
+        // With the OAuth tables, members' access tokens work here, and a 401 tells the client where
+        // the member authorizes it. The app's agent calls as the member it names, or, running a task a
+        // workflow handed it, as the workflow's user.
+        return yield* withPrincipal(bearer, verifyToken, backend, answer, {
+            ...(runtime === undefined ? {} : { runtime }),
+            ...(workspaceId === undefined ? {} : { agentTasks: { workspaceId } }),
+            ...(backend.oauth === undefined
+                ? {}
+                : {
+                    oauthResource: mcpResource(origin),
+                    challenge: (missing) => mcpChallenge(origin, missing),
+                }),
+        });
+    });
+}
+/** `POST /mcp`: one JSON-RPC message in, one JSON response out, nothing kept between requests. */
+function handlePost(server, verifyToken, verifyRuntime, backend, workspaceId) {
+    return (request) => {
+        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);
+            }
+        });
+        return withMcpPrincipal(request, verifyToken, verifyRuntime, backend, answer, workspaceId);
+    };
+}
+/** An optional, authenticated server stream; stateless instances have no messages to send. */
+function handleGet(request, options, backend) {
+    const acceptsStream = request.headers.accept?.split(",").some((range) => {
+        const [type, ...parameters] = range.trim().toLowerCase().split(";");
+        return (type?.trim() === "text/event-stream" &&
+            !parameters.some((parameter) => /^q\s*=\s*0(?:\.0*)?$/.test(parameter.trim())));
+    });
+    if (!acceptsStream) {
+        return Effect.succeed(METHOD_NOT_ALLOWED);
+    }
+    return withMcpPrincipal(request, options.verifyToken, options.verifyRuntime, backend, Effect.gen(function* () {
+        const version = request.headers[PROTOCOL_VERSION_HEADER];
+        if (version !== undefined &&
+            !MCP_PROTOCOL_VERSIONS.includes(version)) {
+            return rpcError(null, INVALID_REQUEST, `Unsupported MCP-Protocol-Version ${version}.`, 400);
+        }
+        const webRequest = yield* HttpServerRequest.toWeb(request);
+        return eventStream(webRequest.signal, options.streamMaxDurationMs ?? MCP_STREAM_MAX_DURATION_MS);
+    }), options.workspaceId);
+}
+/**
+ * Streamable HTTP without sessions: POST answers JSON-RPC, GET keeps an idle SSE stream alive,
+ * and DELETE answers 405. Every instance can answer any authenticated request independently.
+ */
+export function mcpLayer(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const warehouseQueries = yield* Effect.serviceOption(WarehouseQueries);
+        const tools = mcpTools(options.built, options.conversations !== undefined, {
+            attachments: backend.attachments !== undefined,
+            files: backend.blobs !== undefined,
+        }, options.navigation !== undefined);
+        const operations = makeOperations(backend, options.built.plan, options.hooks, options.connections, options.replicate, options.chatDelivery);
+        const conversations = options.conversations && withChatMembership(options.conversations, backend);
+        const server = {
+            chats: chatReads(backend, conversations, options.built.plan.ontology.config.chat?.attribution),
+            built: options.built,
+            tools,
+            discovery: createDiscovery(options.built, tools),
+            ...(options.navigation === undefined
+                ? {}
+                : {
+                    navigation: createNavigation(options.navigation, options.built.plan.ontology.manifest, options.appOrigins ?? []),
+                }),
+            operations,
+            memberFiles: memberFileOperations(backend, options.built.plan, operations),
+            queryMetrics: options.metricQueries.model,
+            conversations,
+            decide: options.decide,
+        };
+        const post = handlePost(server, options.verifyToken, options.verifyRuntime, backend, options.workspaceId);
+        yield* router.add("POST", MCP_PATH, (request) => {
+            const response = post(request);
+            const served = Option.isSome(warehouseQueries)
+                ? response.pipe(Effect.provideService(WarehouseQueries, warehouseQueries.value))
+                : response;
+            return served.pipe(Effect.map((response) => HttpServerResponse.setHeaders(response, CORS)));
+        });
+        yield* router.add("OPTIONS", MCP_PATH, PREFLIGHT);
+        yield* router.add("GET", MCP_PATH, (request) => handleGet(request, options, backend).pipe(Effect.map((response) => HttpServerResponse.setHeaders(response, CORS))));
+        yield* router.add("DELETE", MCP_PATH, METHOD_NOT_ALLOWED);
+    }));
+}