@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/service/mcp/input-schema.d.ts

@@ -0,0 +1,6 @@
+import type { JsonSchemaObject } from "../../analyze.js";
+/**
+ * MCP clients use different regex engines. Omit Unicode property pattern assertions from the
+ * immutable advertised input schema; the original Effect schema still validates every tool call.
+ */
+export declare function mcpInputSchema(schema: JsonSchemaObject): JsonSchemaObject;

package/dist/service/mcp/input-schema.js

@@ -0,0 +1,126 @@
+const SCHEMA_MAPS = new Set([
+    "$defs",
+    "definitions",
+    "properties",
+    "patternProperties",
+    "dependentSchemas",
+    "dependencies",
+]);
+const SCHEMA_ARRAYS = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+const SCHEMA_VALUES = new Set([
+    "items",
+    "additionalItems",
+    "contains",
+    "additionalProperties",
+    "unevaluatedItems",
+    "unevaluatedProperties",
+    "propertyNames",
+    "not",
+    "if",
+    "then",
+    "else",
+    "contentSchema",
+]);
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** An escaped backslash is literal text, not the start of a Unicode property escape. */
+function hasUnicodeProperty(pattern) {
+    for (let index = 0; index < pattern.length; index++) {
+        if (pattern[index] !== "\\") {
+            continue;
+        }
+        index++;
+        if ((pattern[index] === "p" || pattern[index] === "P") && pattern[index + 1] === "{") {
+            return true;
+        }
+    }
+    return false;
+}
+function project(value, relaxReferences = false) {
+    if (!isObject(value)) {
+        return value;
+    }
+    const result = { ...value };
+    const changed = new Set();
+    let propertyPatternsRemoved = false;
+    for (const [key, child] of Object.entries(value)) {
+        // A referenced definition may have been relaxed elsewhere in this schema document.
+        if (relaxReferences && ["$ref", "$dynamicRef", "$recursiveRef"].includes(key)) {
+            changed.add(key);
+            continue;
+        }
+        if (key === "pattern" && typeof child === "string" && hasUnicodeProperty(child)) {
+            delete result[key];
+            changed.add(key);
+            continue;
+        }
+        let projected = child;
+        if (SCHEMA_MAPS.has(key) && isObject(child)) {
+            if (key === "patternProperties" && Object.keys(child).some(hasUnicodeProperty)) {
+                delete result[key];
+                changed.add(key);
+                propertyPatternsRemoved = true;
+                continue;
+            }
+            const entries = Object.entries(child).map(([name, schema]) => [name, project(schema, relaxReferences)]);
+            if (entries.some(([name, schema]) => schema !== child[name])) {
+                projected = Object.fromEntries(entries);
+            }
+        }
+        else if ((SCHEMA_ARRAYS.has(key) || key === "items") && Array.isArray(child)) {
+            const schemas = child.map((schema) => project(schema, relaxReferences));
+            if (schemas.some((schema, index) => schema !== child[index])) {
+                projected = schemas;
+            }
+        }
+        else if (SCHEMA_VALUES.has(key)) {
+            projected = project(child, relaxReferences);
+        }
+        if (projected !== child) {
+            result[key] = projected;
+            changed.add(key);
+        }
+    }
+    if (changed.size === 0) {
+        return value;
+    }
+    // Removing an assertion must only relax the advertised schema. Negation, exclusive unions,
+    // conditionals and evaluation-dependent limits would otherwise reject previously valid input.
+    if (changed.has("not")) {
+        delete result.not;
+    }
+    if (changed.has("if")) {
+        delete result.if;
+        delete result.then;
+        delete result.else;
+    }
+    if (changed.has("oneOf") && Array.isArray(result.oneOf)) {
+        result.allOf = [...(Array.isArray(result.allOf) ? result.allOf : []), { anyOf: result.oneOf }];
+        delete result.oneOf;
+    }
+    if (changed.has("contains")) {
+        delete result.maxContains;
+    }
+    if (propertyPatternsRemoved) {
+        delete result.additionalProperties;
+    }
+    delete result.unevaluatedProperties;
+    delete result.unevaluatedItems;
+    return result;
+}
+const inputSchemas = new WeakMap();
+/**
+ * MCP clients use different regex engines. Omit Unicode property pattern assertions from the
+ * immutable advertised input schema; the original Effect schema still validates every tool call.
+ */
+export function mcpInputSchema(schema) {
+    const cached = inputSchemas.get(schema);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const first = project(schema);
+    const result = (first === schema ? schema : project(schema, true));
+    inputSchemas.set(schema, result);
+    return result;
+}

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

@@ -0,0 +1,26 @@
+import type { PermissionHolder } from "../../permissions.js";
+import type { CallerContext } from "../caller-context.js";
+import { type McpTool } from "./tools.js";
+export declare const TOOL_LIST_LIMIT = 128;
+export declare const TOOL_LIST_BYTES = 500000;
+/** A tool as `tools/list` lists it, with a confirmable action's card facts in its annotations. */
+export declare function toolDefinition(tool: McpTool): {
+    _meta?: Readonly<Record<string, unknown>> | undefined;
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: import("../../analyze.js").JsonSchemaObject;
+    annotations: import("./tools.js").McpToolAnnotations | {
+        "segmentstream/confirmation": import("./confirmation.js").ConfirmationFacts;
+        readOnlyHint: boolean;
+        destructiveHint?: boolean;
+        irreversibleHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint: boolean;
+    };
+};
+/** Standard MCP operation definitions; pagination never substitutes search or dispatch tools. */
+export declare function listTools(tools: ReadonlyArray<McpTool>, principal: PermissionHolder, caller: CallerContext, hash: string, cursor?: unknown): {
+    tools: Array<ReturnType<typeof toolDefinition>>;
+    nextCursor?: string;
+};

package/dist/service/mcp/listing.js

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto";
+import { DiscoveryError } from "../discovery.js";
+import { CONFIRMATION_FACTS } from "./confirmation.js";
+import { mcpInputSchema } from "./input-schema.js";
+import { visibleTools } from "./tools.js";
+export const TOOL_LIST_LIMIT = 128;
+export const TOOL_LIST_BYTES = 500_000;
+/** A tool as `tools/list` lists it, with a confirmable action's card facts in its annotations. */
+export function toolDefinition(tool) {
+    return {
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        inputSchema: mcpInputSchema(tool.inputSchema),
+        annotations: tool.confirmation === undefined
+            ? tool.annotations
+            : { ...tool.annotations, [CONFIRMATION_FACTS]: tool.confirmation },
+        ...(tool._meta === undefined ? {} : { _meta: tool._meta }),
+    };
+}
+function invalidCursor() {
+    throw new DiscoveryError({
+        error: "invalid_cursor",
+        detail: "The tool-list cursor is invalid or the catalog or permissions changed. Restart tools/list.",
+    });
+}
+/** Standard MCP operation definitions; pagination never substitutes search or dispatch tools. */
+export function listTools(tools, principal, caller, hash, cursor) {
+    const visible = visibleTools(tools, principal, caller);
+    const scope = createHash("sha256")
+        .update(JSON.stringify([
+        hash,
+        caller.kind,
+        [...new Set(principal.permissions)].sort(),
+        visible.map(({ name }) => name),
+    ]))
+        .digest("hex");
+    let start = 0;
+    if (cursor !== undefined) {
+        if (typeof cursor !== "string" || cursor.length > 4096 || !/^[A-Za-z0-9_-]+$/.test(cursor)) {
+            return invalidCursor();
+        }
+        let decoded;
+        try {
+            decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        }
+        catch {
+            return invalidCursor();
+        }
+        if (typeof decoded !== "object" ||
+            decoded === null ||
+            !("scope" in decoded) ||
+            !("last" in decoded) ||
+            decoded.scope !== scope ||
+            typeof decoded.last !== "string") {
+            return invalidCursor();
+        }
+        const last = decoded.last;
+        const position = visible.findIndex(({ name }) => name === last);
+        if (position < 0) {
+            return invalidCursor();
+        }
+        start = position + 1;
+    }
+    // Eve 0.85 calls listTools once, unlike AI SDK's tools() which follows nextCursor.
+    // Keep deployed runtime clients working; both paths expose the same direct operations.
+    if (caller.kind === "runtime") {
+        return { tools: visible.slice(start).map(toolDefinition) };
+    }
+    const selected = [];
+    // Leave room for the JSON-RPC envelope and cursor. Never cut a tool's input contract.
+    let bytes = 1024;
+    for (const tool of visible.slice(start, start + TOOL_LIST_LIMIT)) {
+        const item = toolDefinition(tool);
+        const added = Buffer.byteLength(JSON.stringify(item)) + 1;
+        // An individually larger definition gets its own page rather than disappearing.
+        if (selected.length > 0 && bytes + added > TOOL_LIST_BYTES) {
+            break;
+        }
+        selected.push(item);
+        bytes += added;
+    }
+    const last = selected.at(-1);
+    return {
+        tools: selected,
+        ...(last !== undefined && start + selected.length < visible.length
+            ? {
+                nextCursor: Buffer.from(JSON.stringify({ scope, last: last.name })).toString("base64url"),
+            }
+            : {}),
+    };
+}

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

@@ -0,0 +1,85 @@
+import { Schema } from "effect";
+import { type DimensionType } from "../../metric-filters.js";
+import type { OntologyManifest, PropertyManifest } from "../../manifest.js";
+/**
+ * The metric tools, named as dbt names its MCP tools: `list_metrics` names what the
+ * caller may compute, `get_dimensions` what metrics can be grouped and filtered by,
+ * `get_dimension_values` the values a dimension takes, and `query_metrics` computes them. A metric
+ * is an entity's, `entity.metric`, or the model's, by its bare name. Every answer is the caller's:
+ * it names only what they may read, by the same route rules `query_metrics` resolves.
+ */
+/** One metric, as `list_metrics` lists it. */
+export interface Metric {
+    readonly name: string;
+    readonly label: string;
+    readonly unit: "number" | "currency" | "ratio" | "percent";
+    /** What it means: its description, conditions and balance rule, or what it reads and aligns. */
+    readonly description: string;
+    /** The entity whose rows it is computed over; absent for a model metric. */
+    readonly entity?: string;
+    /** A model metric's inputs: the entity metrics it reads. */
+    readonly reads?: ReadonlyArray<string>;
+}
+/** One dimension, as `get_dimensions` lists it: a name `query_metrics` takes as it is. */
+export interface Dimension {
+    readonly name: string;
+    readonly label: string;
+    readonly type: DimensionType;
+    readonly description?: string;
+    /** A choice field's values. */
+    readonly values?: ReadonlyArray<string>;
+}
+/** The most dimensions one answer lists; `search` narrows a longer list. */
+export declare const DIMENSIONS_LIMIT = 300;
+/** How many values `get_dimension_values` returns by default, and at most. */
+export declare const VALUES_DEFAULT = 100;
+export declare const VALUES_LIMIT: 1000;
+export declare const ListMetricsInput: Schema.Struct<{
+    readonly search: Schema.optionalKey<Schema.String>;
+}>;
+export declare const GetDimensionsInput: Schema.Struct<{
+    readonly metrics: Schema.$Array<Schema.String>;
+    readonly search: Schema.optionalKey<Schema.String>;
+}>;
+export declare const GetDimensionValuesInput: Schema.Struct<{
+    readonly dimension: Schema.String;
+    readonly metrics: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly search: Schema.optionalKey<Schema.String>;
+    readonly filters: Schema.optionalKey<Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+/** Every metric the caller may compute, entity metrics first, in declaration order. */
+export declare function listMetrics(manifest: OntologyManifest, permissions: ReadonlyArray<string>, search?: string): ReadonlyArray<Metric>;
+/** Whether the caller may compute anything: the metric tools are listed only then. */
+export declare function hasMetrics(manifest: OntologyManifest, permissions: ReadonlyArray<string>): boolean;
+/**
+ * What every given metric can be grouped and filtered by. The candidates are the properties of
+ * each metric's entity and of the entities it reaches, by name, or by route where a target is
+ * reached in several ways; each is kept only when the shared resolver accepts it for all the given
+ * metrics, alignments of model metrics included, and the caller may read every entity it touches.
+ */
+export declare function metricDimensions(manifest: OntologyManifest, permissions: ReadonlyArray<string>, metrics: ReadonlyArray<string>, search?: string): {
+    readonly dimensions: ReadonlyArray<Dimension>;
+    readonly truncated: boolean;
+} | {
+    readonly reason: string;
+};
+/** How `get_dimension_values` answers: from the definition, or by computing a metric. */
+export type ValuesPlan = {
+    readonly kind: "options";
+    readonly property: PropertyManifest;
+} | {
+    readonly kind: "boolean";
+} | {
+    readonly kind: "query";
+    readonly metrics: ReadonlyArray<string>;
+} | {
+    readonly kind: "refused";
+    readonly reason: string;
+};
+/**
+ * How to find a dimension's values. A choice field's are its options and a boolean's are true and
+ * false. Any other dimension's values are those it takes among a metric's rows: the given metrics,
+ * or the first metric the caller may compute that reaches it, its own entity's first.
+ */
+export declare function planDimensionValues(manifest: OntologyManifest, permissions: ReadonlyArray<string>, dimension: string, metrics?: ReadonlyArray<string>): ValuesPlan;

package/dist/service/mcp/metric-tools.js

@@ -0,0 +1,258 @@
+import { Schema } from "effect";
+import { dimensionTypeOf } from "../../metric-filters.js";
+import { METRIC_QUERY_NAME_PATTERN, inputEntities, resolveMetricRoutes, } from "../../metric-routes.js";
+import { humanize } from "../../names.js";
+import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
+import { metricDescription, metricsFor, modelMetricDescription, modelMetricsFor, reachesOf, } from "../../render.js";
+import { METRIC_QUERY_LIMITS } from "../schemas.js";
+/** The record id of a stored entity. */
+const ID = "id";
+/** The most dimensions one answer lists; `search` narrows a longer list. */
+export const DIMENSIONS_LIMIT = 300;
+/** A dimension's description is clipped to this many code points. */
+const DESCRIPTION_LIMIT = 160;
+/** How many values `get_dimension_values` returns by default, and at most. */
+export const VALUES_DEFAULT = 100;
+export const VALUES_LIMIT = METRIC_QUERY_LIMITS.rows;
+const Name = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(200));
+const Search = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(200));
+const Metrics = Schema.Array(Name).check(Schema.isMinLength(1), Schema.isMaxLength(METRIC_QUERY_LIMITS.metrics));
+export const ListMetricsInput = Schema.Struct({ search: Schema.optionalKey(Search) });
+export const GetDimensionsInput = Schema.Struct({
+    metrics: Metrics,
+    search: Schema.optionalKey(Search),
+});
+export const GetDimensionValuesInput = Schema.Struct({
+    dimension: Name,
+    metrics: Schema.optionalKey(Metrics),
+    search: Schema.optionalKey(Search),
+    // Checked as query_metrics checks its filters, by the metric query the values come from.
+    filters: Schema.optionalKey(Schema.Array(Schema.Json)),
+    limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: VALUES_LIMIT }))),
+});
+function readable(entity, permissions) {
+    return isAllowed(permissionOf(entity, READ_VERB), { permissions });
+}
+/** Whether every word of the search occurs in one of the texts, ignoring case. */
+function matches(search, texts) {
+    if (search === undefined) {
+        return true;
+    }
+    const haystack = texts
+        .filter((text) => text !== undefined)
+        .join(" ")
+        .toLowerCase();
+    return search
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((word) => word !== "")
+        .every((word) => haystack.includes(word));
+}
+/** At most `maximum` code points of `text`, ending with an ellipsis when it was cut. */
+function clip(text, maximum) {
+    const points = Array.from(text.trim());
+    return points.length <= maximum ? points.join("") : `${points.slice(0, maximum - 1).join("")}…`;
+}
+/** Every metric the caller may compute, entity metrics first, in declaration order. */
+export function listMetrics(manifest, permissions, search) {
+    const listed = [
+        ...metricsFor(manifest, permissions).map(({ name, entity, metric }) => ({
+            name,
+            label: metric.label,
+            unit: metric.unit,
+            description: metricDescription(entity, metric),
+            entity: entity.name,
+        })),
+        ...modelMetricsFor(manifest, permissions).map((metric) => ({
+            name: metric.name,
+            label: metric.label,
+            unit: metric.unit,
+            description: modelMetricDescription(metric),
+            reads: metric.inputs,
+        })),
+    ];
+    return listed.filter((metric) => matches(search, [metric.name, metric.label, metric.description]));
+}
+/** Whether the caller may compute anything: the metric tools are listed only then. */
+export function hasMetrics(manifest, permissions) {
+    return (metricsFor(manifest, permissions).length > 0 ||
+        modelMetricsFor(manifest, permissions).length > 0);
+}
+const UNKNOWN_METRIC = (name) => `${name} is not a metric you may compute; list_metrics names them.`;
+/** The entities a metric is computed over: its entity, or a model metric's input entities. */
+function metricEntities(manifest, permissions, name) {
+    const dot = name.indexOf(".");
+    if (dot === -1) {
+        const metric = (manifest.metrics ?? []).find((candidate) => candidate.name === name);
+        const entities = metric === undefined ? [] : inputEntities(metric);
+        return entities.length > 0 && entities.every((entity) => readable(entity, permissions))
+            ? entities
+            : { reason: UNKNOWN_METRIC(name) };
+    }
+    const entity = manifest.entities.find((candidate) => candidate.name === name.slice(0, dot));
+    const metric = name.slice(dot + 1);
+    return entity !== undefined &&
+        readable(entity.name, permissions) &&
+        (entity.metrics ?? []).some((candidate) => candidate.name === metric)
+        ? [entity.name]
+        : { reason: UNKNOWN_METRIC(name) };
+}
+/**
+ * The `id` of a stored entity, which its replication view carries and the shared resolver accepts as
+ * a dimension though no property declares it. It is labeled as a property without a label is.
+ */
+function storedIdOf(entity) {
+    return entity.source === undefined &&
+        !entity.builtIn &&
+        !entity.properties.some((property) => property.name === ID)
+        ? [
+            {
+                name: ID,
+                type: "text",
+                label: humanize(ID),
+                optional: false,
+                unique: true,
+                managed: true,
+            },
+        ]
+        : [];
+}
+function dimensionsOf(entity, prefix, via) {
+    return [...storedIdOf(entity), ...entity.properties].flatMap((property) => {
+        const type = dimensionTypeOf(property.type);
+        if (type === undefined) {
+            return [];
+        }
+        const description = property.description?.trim() ?? "";
+        return [
+            {
+                name: `${prefix}.${property.name}`,
+                label: `${entity.label} · ${property.label}${via === undefined ? "" : ` (via ${via})`}`,
+                type,
+                ...(description === "" ? {} : { description: clip(description, DESCRIPTION_LIMIT) }),
+                ...(property.options === undefined
+                    ? {}
+                    : { values: property.options.map((option) => option.value) }),
+            },
+        ];
+    });
+}
+/**
+ * What every given metric can be grouped and filtered by. The candidates are the properties of
+ * each metric's entity and of the entities it reaches, by name, or by route where a target is
+ * reached in several ways; each is kept only when the shared resolver accepts it for all the given
+ * metrics, alignments of model metrics included, and the caller may read every entity it touches.
+ */
+export function metricDimensions(manifest, permissions, metrics, search) {
+    const owners = new Set();
+    for (const metric of metrics) {
+        const entities = metricEntities(manifest, permissions, metric);
+        if ("reason" in entities) {
+            return entities;
+        }
+        for (const entity of entities) {
+            owners.add(entity);
+        }
+    }
+    const candidates = new Map();
+    const add = (target, prefix, via) => {
+        const entity = manifest.entities.find((candidate) => candidate.name === target);
+        for (const dimension of entity === undefined ? [] : dimensionsOf(entity, prefix, via)) {
+            if (!candidates.has(dimension.name)) {
+                candidates.set(dimension.name, dimension);
+            }
+        }
+    };
+    for (const owner of owners) {
+        add(owner, owner, undefined);
+        for (const { target, routes, ambiguous } of reachesOf(manifest, owner, permissions)) {
+            if (ambiguous) {
+                for (const route of routes) {
+                    add(target, `${owner}.${route}`, route);
+                }
+            }
+            else {
+                add(target, target, undefined);
+            }
+        }
+    }
+    const found = [...candidates.values()].filter((dimension) => {
+        const routes = resolveMetricRoutes(manifest, {
+            metrics,
+            dimensions: [dimension.name],
+        });
+        return (routes.ok &&
+            routes.touched.every((entity) => readable(entity, permissions)) &&
+            matches(search, [dimension.name, dimension.label, dimension.description]));
+    });
+    return {
+        dimensions: found.slice(0, DIMENSIONS_LIMIT),
+        truncated: found.length > DIMENSIONS_LIMIT,
+    };
+}
+function propertyOf(manifest, identity) {
+    const dot = identity.indexOf(".");
+    const entity = manifest.entities.find((candidate) => candidate.name === identity.slice(0, dot));
+    return entity?.properties.find((property) => property.name === identity.slice(dot + 1));
+}
+function fixed(property) {
+    if (property?.options !== undefined) {
+        return { kind: "options", property };
+    }
+    return property?.type === "boolean" ? { kind: "boolean" } : undefined;
+}
+/**
+ * How to find a dimension's values. A choice field's are its options and a boolean's are true and
+ * false. Any other dimension's values are those it takes among a metric's rows: the given metrics,
+ * or the first metric the caller may compute that reaches it, its own entity's first.
+ */
+export function planDimensionValues(manifest, permissions, dimension, metrics) {
+    if (!new RegExp(METRIC_QUERY_NAME_PATTERN).test(dimension)) {
+        return {
+            kind: "refused",
+            reason: `${dimension} is not a dimension name; get_dimensions lists them.`,
+        };
+    }
+    const segments = dimension.split(".");
+    // entity.property names its property directly, without resolving a metric's route.
+    const direct = segments.length === 2 && readable(segments[0], permissions)
+        ? propertyOf(manifest, dimension)
+        : undefined;
+    const known = fixed(direct);
+    if (known !== undefined) {
+        return known;
+    }
+    const own = segments[0];
+    const candidates = metrics === undefined
+        ? listMetrics(manifest, permissions)
+            .toSorted((a, b) => Number(b.entity === own) - Number(a.entity === own))
+            .map((metric) => [metric.name])
+        : [metrics];
+    let refusal;
+    for (const candidate of candidates) {
+        const routes = resolveMetricRoutes(manifest, {
+            metrics: candidate,
+            dimensions: [dimension],
+        });
+        if (!routes.ok) {
+            refusal ??= routes.reason;
+            continue;
+        }
+        if (!routes.touched.every((entity) => readable(entity, permissions))) {
+            continue;
+        }
+        const identity = routes.entities[0]?.dimensions[0]?.identity;
+        return ((identity === undefined ? undefined : fixed(propertyOf(manifest, identity))) ?? {
+            kind: "query",
+            metrics: candidate,
+        });
+    }
+    return {
+        kind: "refused",
+        reason: metrics !== undefined && refusal !== undefined
+            ? refusal
+            : direct === undefined && refusal !== undefined && candidates.length > 0
+                ? refusal
+                : `No metric you may compute reaches ${dimension}, so its values cannot be listed.`,
+    };
+}

package/dist/service/mcp/request-log.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Observe the stateless transport at the HTTP boundary, including authentication failures,
+ * preflights, unsupported HTTP methods and failures to initialize the service runtime.
+ */
+export declare function observeMcpRequest(request: Request): ((response: Response, requestId: string, durationMs?: number) => Promise<void>) | undefined;

package/dist/service/mcp/request-log.js

@@ -0,0 +1,53 @@
+import { MCP_PATH } from "./server.js";
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Observe the stateless transport at the HTTP boundary, including authentication failures,
+ * preflights, unsupported HTTP methods and failures to initialize the service runtime.
+ */
+export function observeMcpRequest(request) {
+    if (new URL(request.url).pathname !== MCP_PATH) {
+        return undefined;
+    }
+    const started = performance.now();
+    // Consume the clone as well as the original: diagnostics must not disturb the request body.
+    const message = request.method === "POST"
+        ? request
+            .clone()
+            .json()
+            .catch(() => undefined)
+        : Promise.resolve();
+    const origin = request.headers.get("origin");
+    const originHost = origin !== null && URL.canParse(origin) ? new URL(origin).host : null;
+    return async (response, requestId, durationMs = Math.round((performance.now() - started) * 100) / 100) => {
+        const body = await message;
+        const rpcMethod = isObject(body) && typeof body.method === "string" ? body.method : null;
+        // Log SSE at response start. Cloning/reading it would delay headers and buffer every heartbeat.
+        const streaming = response.headers.get("content-type")?.startsWith("text/event-stream");
+        const bytes = streaming ? undefined : await response.clone().arrayBuffer();
+        let toolCount = null;
+        if (rpcMethod === "tools/list" && response.status === 200 && bytes && bytes.byteLength > 0) {
+            const payload = JSON.parse(new TextDecoder().decode(bytes));
+            if (isObject(payload) && isObject(payload.result) && Array.isArray(payload.result.tools)) {
+                toolCount = payload.result.tools.length;
+            }
+        }
+        console.info(JSON.stringify({
+            event: "ontology.mcp.request",
+            requestId,
+            httpMethod: request.method,
+            rpcMethod,
+            status: response.status,
+            durationMs,
+            responseBytes: bytes?.byteLength ?? null,
+            toolCount,
+            protocolVersion: request.headers.get("mcp-protocol-version"),
+            originPresent: origin !== null,
+            originHost,
+            authKind: /^Bearer\s+\S/i.test(request.headers.get("authorization") ?? "")
+                ? "bearer"
+                : "none",
+        }));
+    };
+}