@datalayer/core 1.1.60 → 1.2.10

package/lib/api/mcp/gateway.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What every gateway client shares: where the REST routes are, and how a
+ * wire document becomes a model.
+ *
+ * The configured URL is the MCP resource — `https://mcp.datalayer.run/mcp`,
+ * the address an agent connects to and the audience a token names. The
+ * REST routes live on the same host under `/api/mcp/v1`, so the resource
+ * path is taken off before a route is appended.
+ *
+ * Wire documents are snake case and the models camel case, as with
+ * Contents, with one difference: a task's `result` and an audit row's
+ * `redactedArguments` are a tool's own — their keys are the tool's
+ * argument and output names and must survive as typed — so the envelope is
+ * converted around them, never through them.
+ *
+ * @module api/mcp/gateway
+ */
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+import { contentsToCamelCase, contentsToSnakeCase } from '../../models/contents/index.js';
+/** The host and scheme of the gateway, without the `/mcp` resource path. */
+export const mcpGatewayOrigin = (mcpServerUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => {
+    const trimmed = mcpServerUrl.replace(/\/+$/, '');
+    return trimmed.endsWith('/mcp') ? trimmed.slice(0, -'/mcp'.length) : trimmed;
+};
+/** A REST route of the gateway, with its query string. */
+export const mcpUrl = (mcpServerUrl, suffix, query = {}) => {
+    const parameters = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== null && value !== '') {
+            parameters.set(key, String(value));
+        }
+    }
+    const search = parameters.toString();
+    return `${mcpGatewayOrigin(mcpServerUrl)}${API_BASE_PATHS.MCP}${suffix}${search ? `?${search}` : ''}`;
+};
+/** A route outside the versioned API: `/api/mcp/version`, `/api/mcp/healthz`. */
+export const mcpServiceUrl = (mcpServerUrl, suffix) => `${mcpGatewayOrigin(mcpServerUrl)}/api/mcp${suffix}`;
+/** The fields whose keys belong to a tool, not to the contract. */
+const PRESERVED_FIELDS = new Set(['result', 'redacted_arguments', 'client_info', 'input', 'output']);
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const camelKey = (key) => key.replace(/_([a-zA-Z0-9])/g, (_, character) => character.toUpperCase());
+/**
+ * A wire document as a model: snake case to camel case through the envelope,
+ * the preserved fields carried as they came.
+ */
+export const fromWire = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(item => fromWire(item));
+    }
+    if (!isObject(value)) {
+        return value;
+    }
+    const converted = {};
+    for (const [key, item] of Object.entries(value)) {
+        converted[camelKey(key)] = PRESERVED_FIELDS.has(key) ? item : fromWire(item);
+    }
+    return converted;
+};
+/** A request body as the gateway reads it. */
+export const toWire = (value) => contentsToSnakeCase(value);
+/** For the few answers with no tool-owned field, the Contents converter as is. */
+export const fromWireStrict = (value) => contentsToCamelCase(value);

package/lib/api/mcp/generated.d.ts

@@ -0,0 +1,22 @@
+export interface HTTPValidationError {
+    detail?: Array<ValidationError>;
+}
+export interface ValidationError {
+    loc: Array<string | number>;
+    msg: string;
+    type: string;
+    input?: unknown;
+    ctx?: Record<string, unknown>;
+}
+/** One REST route the gateway declares. */
+export interface McpGatewayRoute {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    operationId: string;
+    parameters: Array<{
+        name: string;
+        in: string;
+    }>;
+}
+/** The gateway version the routes were read from: 0.0.1. */
+export declare const MCP_GATEWAY_ROUTES: ReadonlyArray<McpGatewayRoute>;

package/lib/api/mcp/generated.js

@@ -0,0 +1,213 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The gateway version the routes were read from: 0.0.1. */
+export const MCP_GATEWAY_ROUTES = [
+    {
+        method: 'GET',
+        path: '/.well-known/mcp-server',
+        operationId: 'server_card_endpoint__well_known_mcp_server_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/.well-known/oauth-protected-resource',
+        operationId: 'protected_resource_metadata_endpoint__well_known_oauth_protected_resource_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/.well-known/oauth-protected-resource/mcp',
+        operationId: 'protected_resource_metadata_endpoint__well_known_oauth_protected_resource_mcp_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/healthz',
+        operationId: 'healthz_endpoint_api_mcp_healthz_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/readyz',
+        operationId: 'readyz_endpoint_api_mcp_readyz_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/activity',
+        operationId: 'activity_endpoint_api_mcp_v1_activity_get',
+        parameters: [{ name: 'org', in: 'query' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/alerts',
+        operationId: 'alerts_endpoint_api_mcp_v1_alerts_get',
+        parameters: [
+            { name: 'org', in: 'query' },
+            { name: 'scope', in: 'query' },
+            { name: 'unacknowledged', in: 'query' },
+        ],
+    },
+    {
+        method: 'POST',
+        path: '/api/mcp/v1/alerts/test',
+        operationId: 'test_alert_rule_endpoint_api_mcp_v1_alerts_test_post',
+        parameters: [],
+    },
+    {
+        method: 'POST',
+        path: '/api/mcp/v1/alerts/{alert_uid}/acknowledge',
+        operationId: 'acknowledge_alert_endpoint_api_mcp_v1_alerts__alert_uid__acknowledge_post',
+        parameters: [{ name: 'alert_uid', in: 'path' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/audit',
+        operationId: 'audit_endpoint_api_mcp_v1_audit_get',
+        parameters: [
+            { name: 'org', in: 'query' },
+            { name: 'team', in: 'query' },
+            { name: 'user', in: 'query' },
+            { name: 'client', in: 'query' },
+            { name: 'agent', in: 'query' },
+            { name: 'tool', in: 'query' },
+            { name: 'method', in: 'query' },
+            { name: 'decision', in: 'query' },
+            { name: 'outcome', in: 'query' },
+            { name: 'notebook', in: 'query' },
+            { name: 'source', in: 'query' },
+            { name: 'task', in: 'query' },
+            { name: 'since', in: 'query' },
+            { name: 'until', in: 'query' },
+            { name: 'cursor', in: 'query' },
+            { name: 'limit', in: 'query' },
+            { name: 'export', in: 'query' },
+        ],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/audit/forwarding',
+        operationId: 'audit_forwarding_endpoint_api_mcp_v1_audit_forwarding_get',
+        parameters: [{ name: 'org', in: 'query' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/bindings',
+        operationId: 'list_bindings_endpoint_api_mcp_v1_bindings_get',
+        parameters: [{ name: 'kind', in: 'query' }],
+    },
+    {
+        method: 'DELETE',
+        path: '/api/mcp/v1/bindings/{binding_uid}',
+        operationId: 'delete_binding_endpoint_api_mcp_v1_bindings__binding_uid__delete',
+        parameters: [{ name: 'binding_uid', in: 'path' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/notebooks/{notebook_uid}/tasks',
+        operationId: 'list_notebook_tasks_endpoint_api_mcp_v1_notebooks__notebook_uid__tasks_get',
+        parameters: [
+            { name: 'notebook_uid', in: 'path' },
+            { name: 'cursor', in: 'query' },
+            { name: 'limit', in: 'query' },
+        ],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/operations/jobs',
+        operationId: 'operations_jobs_endpoint_api_mcp_v1_operations_jobs_get',
+        parameters: [],
+    },
+    {
+        method: 'POST',
+        path: '/api/mcp/v1/operations/runtime-ended',
+        operationId: 'runtime_ended_endpoint_api_mcp_v1_operations_runtime_ended_post',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/operations/workers',
+        operationId: 'operations_workers_endpoint_api_mcp_v1_operations_workers_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/operations/workflows',
+        operationId: 'workflows_operations_endpoint_api_mcp_v1_operations_workflows_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/organizations/{org_uid}/overview',
+        operationId: 'organization_overview_endpoint_api_mcp_v1_organizations__org_uid__overview_get',
+        parameters: [
+            { name: 'org_uid', in: 'path' },
+            { name: 'team', in: 'query' },
+        ],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/organizations/{org_uid}/usage',
+        operationId: 'organization_usage_endpoint_api_mcp_v1_organizations__org_uid__usage_get',
+        parameters: [
+            { name: 'org_uid', in: 'path' },
+            { name: 'team', in: 'query' },
+        ],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/policy',
+        operationId: 'policy_endpoint_api_mcp_v1_policy_get',
+        parameters: [
+            { name: 'agent', in: 'query' },
+            { name: 'org', in: 'query' },
+            { name: 'team', in: 'query' },
+        ],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/tasks',
+        operationId: 'list_tasks_endpoint_api_mcp_v1_tasks_get',
+        parameters: [
+            { name: 'notebook', in: 'query' },
+            { name: 'sandbox', in: 'query' },
+            { name: 'agent', in: 'query' },
+            { name: 'status', in: 'query' },
+            { name: 'org', in: 'query' },
+            { name: 'cursor', in: 'query' },
+            { name: 'limit', in: 'query' },
+        ],
+    },
+    {
+        method: 'DELETE',
+        path: '/api/mcp/v1/tasks/{task_uid}',
+        operationId: 'cancel_task_endpoint_api_mcp_v1_tasks__task_uid__delete',
+        parameters: [{ name: 'task_uid', in: 'path' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/tasks/{task_uid}',
+        operationId: 'get_task_endpoint_api_mcp_v1_tasks__task_uid__get',
+        parameters: [{ name: 'task_uid', in: 'path' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/tasks/{task_uid}/events',
+        operationId: 'task_events_endpoint_api_mcp_v1_tasks__task_uid__events_get',
+        parameters: [{ name: 'task_uid', in: 'path' }],
+    },
+    {
+        method: 'POST',
+        path: '/api/mcp/v1/tasks/{task_uid}/input',
+        operationId: 'answer_task_endpoint_api_mcp_v1_tasks__task_uid__input_post',
+        parameters: [{ name: 'task_uid', in: 'path' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/version',
+        operationId: 'version_endpoint_api_mcp_version_get',
+        parameters: [],
+    },
+];

package/lib/api/mcp/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The Jupyter MCP Server's REST API: tasks, bindings, audit, activity,
+ * policy and operations. The MCP endpoint itself is not here — an agent
+ * speaks JSON-RPC to it; a browser reads what the agents did.
+ *
+ * @module api/mcp
+ */
+export * from './generated';
+export * from './gateway';
+export * from './tasks';
+export * from './bindings';
+export * from './audit';
+export * from './activity';
+export * from './organizations';
+export * from './policy';
+export * from './operations';
+export * from './observability';

package/lib/api/mcp/index.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The Jupyter MCP Server's REST API: tasks, bindings, audit, activity,
+ * policy and operations. The MCP endpoint itself is not here — an agent
+ * speaks JSON-RPC to it; a browser reads what the agents did.
+ *
+ * @module api/mcp
+ */
+export * from './generated.js';
+export * from './gateway.js';
+export * from './tasks.js';
+export * from './bindings.js';
+export * from './audit.js';
+export * from './activity.js';
+export * from './organizations.js';
+export * from './policy.js';
+export * from './operations.js';
+export * from './observability.js';

package/lib/api/mcp/observability.d.ts

@@ -0,0 +1,141 @@
+import { type DashboardData } from '../otel/dashboards';
+import type { OtelLog, OtelSpan } from '../otel/types';
+import type { McpTask } from '../../models/McpTask';
+/**
+ * The `service.name` the gateway exports under, and the one its workers use.
+ *
+ * The bare service name, like every other Datalayer service (`contents`,
+ * `iam`, `runtimes`): `instrument(app, name)` is what sets it. A worker is a
+ * process of its own and is filed separately, so a worker's last lines stay
+ * queryable after the process is gone.
+ */
+export declare const MCP_GATEWAY_SERVICE_NAME = "jupyter-mcp-server";
+/** The `service.name` a worker's relayed output is filed under. */
+export declare const MCP_WORKER_SERVICE_NAME = "jupyter-mcp-worker";
+/**
+ * The `service.name` the durable execution service exports under.
+ *
+ * The `durable.*` metrics come from there, not from the gateway. Querying
+ * them against the gateway would be well formed, would be answered
+ * truthfully with nothing, and would render a legitimate-looking zero — the
+ * same failure that had three panels querying `mcp.forwarded` and
+ * `mcp.sandbox_lost`. `serviceNameFor` exists so the question is answered
+ * once rather than at each call site.
+ */
+export declare const MCP_DURABLE_SERVICE_NAME = "datalayer-durable";
+/**
+ * Which service emits a metric.
+ *
+ * A metric's service is a property of the metric, not of the caller. Reading
+ * it from here is what keeps a new panel from inheriting whichever constant
+ * happened to be in scope where it was written.
+ */
+export declare const serviceNameFor: (metric: McpMetricName) => string;
+/** The metric catalog `telemetry.py` owns; no ad-hoc counters. */
+export declare const MCP_METRIC_CATALOG: readonly ["mcp.calls", "mcp.call.duration", "mcp.refusals", "mcp.limit.unenforced", "mcp.forwards", "mcp.workers", "mcp.worker_start_seconds", "mcp.bindings", "mcp.sandbox.lost", "mcp.tasks", "mcp.task.duration", "durable.step.duration", "durable.queue.wait", "durable.recoveries", "sandbox.launch_seconds", "mcp.audit.writes", "mcp.audit.write_failures", "mcp.dependency.duration", "mcp.dependency.timeouts", "mcp.dependency.ready", "mcp.readiness.failures", "mcp.audit.deleted", "mcp.jobs", "mcp.job.duration"];
+export type McpMetricName = (typeof MCP_METRIC_CATALOG)[number];
+/** The four SLIs, and the catalog metric each is read from. */
+export declare const MCP_SLI_METRICS: {
+    readonly availability: "mcp.calls";
+    readonly latency: "mcp.call.duration";
+    readonly taskSuccess: "mcp.tasks";
+    readonly sandboxLaunch: "sandbox.launch_seconds";
+};
+/** The OTEL service's built-in dashboard the four SLIs are read from. */
+export declare const MCP_SERVICE_LEVELS_DASHBOARD = "mcp-service-levels";
+/**
+ * Its panels, by the ids the OTEL service gives them. A contract test there
+ * holds them, so a panel renamed on the service fails a test rather than
+ * reading here as nothing measured.
+ */
+export declare const MCP_SERVICE_LEVEL_PANELS: {
+    readonly callsByOutcome: "mcp-calls-by-outcome";
+    readonly callDurationP95: "mcp-call-duration-p95";
+    readonly tasksByStatus: "mcp-tasks-by-status";
+    readonly sandboxLaunchP95: "sandbox-launch_seconds-by-provider-p95";
+    readonly sandboxLaunches: "sandbox-launch_seconds-by-provider-count";
+};
+export interface McpMetricsFilters {
+    /** The `client_id` of one agent: read from spans, not from metrics. */
+    agent?: string;
+    org?: string;
+    /** ISO 8601; the reading starts there. */
+    since?: string;
+    limit?: number;
+}
+export interface McpSliSummary {
+    /** Share of calls that were neither 5xx nor `-32001`; `null` with no call. */
+    availability: number | null;
+    /** p95 of the synchronous tools' call duration, in milliseconds. */
+    p95CallDurationMs: number | null;
+    /** `completed` over terminal tasks. */
+    taskSuccessRate: number | null;
+    /** p95 sandbox launch, in seconds, by provider. */
+    p95SandboxLaunchSeconds: Record<string, number>;
+    /** How many calls, tasks and launches the numbers rest on. */
+    samples: {
+        calls: number;
+        tasks: number;
+        launches: number;
+    };
+}
+export interface McpMetricsSnapshot {
+    filters: McpMetricsFilters;
+    /** The catalog metrics the OTEL service holds points of, in catalog order. */
+    reporting: McpMetricName[];
+    /** The `mcp.request` spans a per-agent or per-organization reading rests on. */
+    spans: OtelSpan[];
+    slis: McpSliSummary;
+    readAt: string;
+}
+/** The nearest-rank percentile of a sample; `null` for an empty one. */
+export declare const percentile: (values: number[], fraction: number) => number | null;
+/**
+ * The SLIs from the service levels dashboard — the platform-wide reading.
+ *
+ * Its panels arrive summarised: calls and tasks as how much each counter grew
+ * over the window, the two p95s from their histograms' buckets. The call
+ * duration is recorded in seconds and shown in milliseconds. A panel with
+ * nothing in it reads as not measured, never as a zero.
+ */
+export declare const summarizeServiceLevels: (data: DashboardData) => McpSliSummary;
+/**
+ * The SLIs over `mcp.request` spans — the per-agent or per-organization
+ * reading, since metrics carry neither label.
+ */
+export declare const summarizeRequestSpans: (spans: OtelSpan[], filters?: McpMetricsFilters) => McpSliSummary;
+/** The four SLIs and the catalog, for everyone or for one agent or organization. */
+export declare const fetchMcpMetrics: (token: string, filters?: McpMetricsFilters, otelUrl?: string) => Promise<McpMetricsSnapshot>;
+/** A span with its children, as a tree reads. */
+export interface McpSpanNode {
+    span: OtelSpan;
+    children: McpSpanNode[];
+}
+/** The spans of a trace as a tree, roots first, siblings by start time. */
+export declare const spanTree: (spans: OtelSpan[]) => McpSpanNode[];
+export interface McpRunTrace {
+    taskUid: string;
+    traceId: string;
+    spans: OtelSpan[];
+    tree: McpSpanNode[];
+}
+/** "Show me this run": the spans of the task's trace. A task without one has none yet. */
+export declare const fetchRunTrace: (token: string, task: Pick<McpTask, "uid" | "traceId">, otelUrl?: string) => Promise<McpRunTrace>;
+/**
+ * The spans of one trace, named directly.
+ *
+ * A synchronous call has no task — it finished inside its own request — but
+ * it does carry a trace, which is what the audit row records and what
+ * "show me this call" means before durable execution exists.
+ */
+export declare const fetchTraceSpans: (token: string, traceId: string, otelUrl?: string) => Promise<McpRunTrace>;
+export interface McpRunLogs {
+    taskUid: string;
+    traceId: string;
+    records: OtelLog[];
+}
+/** The log lines of a run, gateway and worker alike, by the trace they carry. */
+export declare const fetchMcpLogs: (token: string, task: Pick<McpTask, "uid" | "traceId">, options?: {
+    limit?: number;
+    severity?: string;
+}, otelUrl?: string) => Promise<McpRunLogs>;