@milaboratories/pl-mcp-server 0.2.0

package/src/tools/data-query.ts

@@ -0,0 +1,308 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type {
+  PFrameHandle,
+  PTableHandle,
+  PTableColumnSpec,
+  PTableVector,
+} from "@milaboratories/pl-middle-layer";
+import {
+  Annotation,
+  pTableValue,
+  readAnnotation,
+  PFrameDriver,
+} from "@milaboratories/pl-model-common";
+import { z } from "zod";
+import type { ToolContext } from "./types";
+import { safeEval } from "./sandbox";
+import { errorResult, textResult } from "./types";
+
+const HEX_HASH_RE = /^[a-f0-9]{64}$/;
+
+/**
+ * Try to resolve a 64-char hex handle as PTable, then PFrame.
+ * Returns a summary object or the original string if neither works.
+ */
+async function resolveHandle(
+  handle: string,
+  driver: PFrameDriver,
+  maxColumns: number,
+  cache: Map<string, unknown>,
+): Promise<unknown> {
+  if (cache.has(handle)) return cache.get(handle);
+
+  // Try PTable first (has rows — more useful info)
+  try {
+    const spec = await driver.getSpec(handle as PTableHandle);
+    const shape = await driver.getShape(handle as PTableHandle);
+    const summary: Record<string, unknown> = {
+      _type: "PTable",
+      handle,
+      rows: shape.rows,
+      columnCount: spec.length,
+      columns: spec.slice(0, maxColumns).map((s: PTableColumnSpec, idx: number) => ({
+        index: idx,
+        type: s.type,
+        name: s.spec.name,
+        valueType: s.type === "column" ? s.spec.valueType : s.spec.type,
+        label: readAnnotation(s.spec, Annotation.Label),
+      })),
+    };
+    if (spec.length > maxColumns) {
+      summary.truncated = true;
+      summary.showing = maxColumns;
+    }
+    cache.set(handle, summary);
+    return summary;
+  } catch {
+    // not a PTable
+  }
+
+  // Try PFrame
+  try {
+    const columns = await driver.listColumns(handle as PFrameHandle);
+    const summary: Record<string, unknown> = {
+      _type: "PFrame",
+      handle,
+      columnCount: columns.length,
+      columns: columns.slice(0, maxColumns).map((c) => ({
+        name: c.spec.name,
+        valueType: c.spec.valueType,
+        label: readAnnotation(c.spec, Annotation.Label),
+      })),
+    };
+    if (columns.length > maxColumns) {
+      summary.truncated = true;
+      summary.showing = maxColumns;
+    }
+    cache.set(handle, summary);
+    return summary;
+  } catch {
+    // not a PFrame either
+  }
+
+  cache.set(handle, handle);
+  return handle;
+}
+
+/**
+ * Recursively walk a value tree, replacing 64-char hex handles
+ * with PFrame/PTable summaries (column specs + row count).
+ */
+async function resolveHandlesInValue(
+  value: unknown,
+  driver: Parameters<typeof resolveHandle>[1],
+  maxColumns: number,
+  cache: Map<string, unknown>,
+): Promise<unknown> {
+  if (value === null || value === undefined) return value;
+  if (typeof value === "string") {
+    return HEX_HASH_RE.test(value) ? resolveHandle(value, driver, maxColumns, cache) : value;
+  }
+  if (typeof value !== "object") return value;
+  if (Array.isArray(value)) {
+    return Promise.all(value.map((v) => resolveHandlesInValue(v, driver, maxColumns, cache)));
+  }
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    out[k] = await resolveHandlesInValue(v, driver, maxColumns, cache);
+  }
+  return out;
+}
+
+/** Converts a PTableVector column to a JSON-serializable array using the SDK helper. */
+function vectorToJson(vector: PTableVector, rows: number): (string | number | null)[] {
+  const result: (string | number | null)[] = [];
+  for (let i = 0; i < rows; i++) {
+    result.push(pTableValue(vector, i));
+  }
+  return result;
+}
+
+export function registerDataQueryTools(server: McpServer, ctx: ToolContext): void {
+  server.registerTool(
+    "get_block_outputs",
+    {
+      description:
+        "Get block output values as a JSON map. " +
+        "PFrame/PTable handles are resolved inline to summaries with column specs and row counts. " +
+        "Use this to discover block results and available data before querying tables.",
+      inputSchema: {
+        projectId: z.string().describe("Project ID"),
+        blockId: z.string().describe("Block ID"),
+        maxColumns: z
+          .number()
+          .optional()
+          .default(30)
+          .describe("Max columns to show per PFrame/PTable summary (default 30)."),
+      },
+    },
+    async ({ projectId, blockId, maxColumns }) => {
+      const project = await ctx.getOpenedProject(projectId);
+      const state = await project.getBlockState(blockId).getValue();
+      if (!state.outputs)
+        return errorResult(
+          "Block has no outputs yet.",
+          "The block may not have been run. Use get_project_overview to check its calculationStatus, then run_block if needed.",
+        );
+
+      const outputs = state.outputs as Record<string, { ok?: boolean; value?: unknown }>;
+      const driver = ctx.requireMl().internalDriverKit.pFrameDriver;
+      const cache = new Map<string, unknown>();
+
+      const result: Record<string, unknown> = {};
+      for (const [key, output] of Object.entries(outputs)) {
+        if (!output?.ok || output.value == null) {
+          result[key] = { ok: output?.ok ?? false };
+          continue;
+        }
+        result[key] = await resolveHandlesInValue(output.value, driver, maxColumns, cache);
+      }
+
+      return textResult(result);
+    },
+  );
+
+  server.registerTool(
+    "list_columns",
+    {
+      description:
+        "List all columns in a PFrame with their specs. Use get_block_outputs first to find the PFrame handle.",
+      inputSchema: {
+        pFrameHandle: z
+          .string()
+          .describe("PFrame handle (64-char hex hash from get_block_outputs)"),
+      },
+    },
+    async ({ pFrameHandle }) => {
+      const pFrameDriver = ctx.requireMl().internalDriverKit.pFrameDriver;
+      const columns = await pFrameDriver.listColumns(pFrameHandle as PFrameHandle);
+      return textResult(
+        columns.map((c) => ({
+          columnId: c.columnId,
+          name: c.spec.name,
+          valueType: c.spec.valueType,
+          label: readAnnotation(c.spec, Annotation.Label),
+          visibility: readAnnotation(c.spec, Annotation.Table.Visibility),
+          axes: c.spec.axesSpec.map((a) => ({
+            name: a.name,
+            type: a.type,
+            label: readAnnotation(a, Annotation.Label),
+          })),
+        })),
+      );
+    },
+  );
+
+  server.registerTool(
+    "query_table",
+    {
+      description:
+        "Query data from a PTable. Returns rows as arrays of values. Use get_block_outputs first to find the PTable handle. " +
+        "Use `transform` to process results server-side and return only what you need.",
+      inputSchema: {
+        pTableHandle: z
+          .string()
+          .describe("PTable handle (64-char hex hash from get_block_outputs)"),
+        columns: z
+          .array(z.number())
+          .optional()
+          .describe(
+            "Column indices to retrieve (default: all). Use get_block_outputs to see column indices.",
+          ),
+        offset: z.number().optional().default(0).describe("Row offset (default 0)"),
+        limit: z.number().optional().default(50).describe("Number of rows to return (default 50)."),
+        maxLimit: z
+          .number()
+          .optional()
+          .default(1000)
+          .describe("Upper bound for limit (default 1000). Increase for large exports."),
+        transform: z
+          .string()
+          .optional()
+          .describe(
+            "JS expression evaluated server-side against query results. " +
+              "Available variables: `rows` (array of row arrays), `columns` (column headers), `offset`, `rowCount`. " +
+              "Example: `rows.map(r => r[0])` — extract first column only.",
+          ),
+        transformTimeout: z
+          .number()
+          .optional()
+          .default(5000)
+          .describe("Timeout in ms for transform evaluation (default 5000)."),
+      },
+    },
+    async ({ pTableHandle, columns, offset, limit, maxLimit, transform, transformTimeout }) => {
+      const pFrameDriver = ctx.requireMl().internalDriverKit.pFrameDriver;
+      const handle = pTableHandle as PTableHandle;
+
+      let spec;
+      try {
+        spec = await pFrameDriver.getSpec(handle);
+      } catch (err) {
+        return textResult({ error: `getSpec failed: ${err}` });
+      }
+
+      const effectiveLimit = Math.min(limit, maxLimit);
+      const range = { offset, length: effectiveLimit };
+
+      // If no columns specified, get all
+      const columnIndices = columns ?? spec.map((_: PTableColumnSpec, i: number) => i);
+
+      let vectors: PTableVector[];
+      try {
+        vectors = await pFrameDriver.getData(handle, columnIndices, range);
+      } catch (err) {
+        return textResult({
+          error: `getData failed: ${err}`,
+          columnIndices,
+          range,
+        });
+      }
+
+      const actualRows = vectors.length > 0 ? vectors[0].data.length : 0;
+      const columnVectors = vectors.map((v) => vectorToJson(v, actualRows));
+      const rows: unknown[][] = [];
+      for (let r = 0; r < actualRows; r++) {
+        rows.push(columnVectors.map((col) => col[r]));
+      }
+
+      const columnHeaders = columnIndices.map((idx: number) => {
+        const s = spec[idx];
+        return {
+          index: idx,
+          type: s.type,
+          name: s.type === "column" ? s.spec.name : s.spec.name,
+          label: readAnnotation(s.spec, Annotation.Label),
+        };
+      });
+
+      if (transform) {
+        try {
+          const result = await safeEval(
+            transform,
+            {
+              rows,
+              columns: columnHeaders,
+              offset,
+              rowCount: actualRows,
+            },
+            transformTimeout,
+          );
+          return textResult(result);
+        } catch (e: unknown) {
+          return errorResult(
+            `Transform failed: ${e instanceof Error ? e.message : String(e)}`,
+            "Check your JS expression syntax. Available variables: rows, columns, offset, rowCount.",
+          );
+        }
+      }
+
+      return textResult({
+        offset,
+        rowCount: actualRows,
+        columns: columnHeaders,
+        rows,
+      });
+    },
+  );
+}

package/src/tools/logs.ts

@@ -0,0 +1,97 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { isAnyLogHandle } from "@milaboratories/pl-model-common";
+import type { AnyLogHandle } from "@milaboratories/pl-model-common";
+import { z } from "zod";
+import type { ToolContext } from "./types";
+import { errorResult, textResult } from "./types";
+
+export function registerLogTools(server: McpServer, ctx: ToolContext): void {
+  server.registerTool(
+    "get_block_logs",
+    {
+      description:
+        "Read execution logs for a block. Extracts log handles from block outputs and reads log content. Returns logs keyed by sample/run ID.",
+      inputSchema: {
+        projectId: z.string().describe("Project ID"),
+        blockId: z.string().describe("Block ID"),
+        lines: z.number().optional().default(100).describe("Number of lines per log (default 100)"),
+        sampleId: z
+          .string()
+          .optional()
+          .describe("Specific sample/key to read logs for (reads all if omitted)"),
+      },
+    },
+    async ({ projectId, blockId, lines, sampleId }) => {
+      const project = await ctx.getOpenedProject(projectId);
+      const state = await project.getBlockState(blockId).getValue();
+      if (!state.outputs)
+        return errorResult(
+          "Block has no outputs yet.",
+          "The block may not have been run. Use get_project_overview to check its calculationStatus, then run_block if needed.",
+        );
+
+      // Scan all outputs for log handles (log+ready:// or log+live://)
+      const outputs = state.outputs as Record<
+        string,
+        { ok?: boolean; value?: { data?: { key: string[]; value: unknown }[] } }
+      >;
+      const logEntries: { outputKey: string; key: string[]; handle: AnyLogHandle }[] = [];
+      for (const [outputKey, output] of Object.entries(outputs)) {
+        if (!output?.ok || !output.value?.data) continue;
+        for (const entry of output.value.data) {
+          if (isAnyLogHandle(entry.value)) {
+            logEntries.push({ outputKey, key: entry.key, handle: entry.value });
+          }
+        }
+      }
+
+      if (logEntries.length === 0) {
+        return errorResult(
+          "No log handles found in block outputs.",
+          "This block may not produce logs, or it hasn't run yet. Use get_block_outputs to inspect available output types.",
+        );
+      }
+
+      const logDriver = ctx.requireMl().driverKit.logDriver;
+      const results: Record<string, string> = {};
+
+      for (const entry of logEntries) {
+        const key = entry.key.join("/");
+        if (sampleId && !entry.key.includes(sampleId)) continue;
+        try {
+          const response = await logDriver.lastLines(entry.handle, lines);
+          if (response.shouldUpdateHandle) {
+            results[key] = "[log handle stale — block may still be running, retry later]";
+          } else {
+            results[key] = new TextDecoder().decode(response.data);
+          }
+        } catch (err) {
+          results[key] = `Error reading log: ${err}`;
+        }
+      }
+
+      return textResult(results);
+    },
+  );
+
+  server.registerTool(
+    "get_app_log",
+    {
+      description: "Read recent lines from the application log. Useful for debugging errors.",
+      inputSchema: {
+        lines: z.number().optional().default(50).describe("Number of lines to return (default 50)"),
+        search: z.string().optional().describe("Filter lines containing this substring"),
+      },
+    },
+    async ({ lines, search }) => {
+      if (!ctx.callbacks.readAppLog) {
+        return errorResult(
+          "App log reading is not available.",
+          "This feature requires the desktop app integration.",
+        );
+      }
+      const log = await ctx.callbacks.readAppLog(lines, search);
+      return textResult({ log });
+    },
+  );
+}

package/src/tools/ping.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolContext } from "./types";
+import { textResult } from "./types";
+
+export function registerPingTool(server: McpServer, ctx: ToolContext): void {
+  server.registerTool("ping", { description: "Health check" }, async () => {
+    return textResult({ status: "ok", connected: !!ctx.getMl() });
+  });
+}

package/src/tools/projects.ts

@@ -0,0 +1,84 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { resourceIdToString } from "@milaboratories/pl-middle-layer";
+import { z } from "zod";
+import type { ToolContext } from "./types";
+import { textResult } from "./types";
+
+export function registerProjectTools(server: McpServer, ctx: ToolContext): void {
+  server.registerTool(
+    "list_projects",
+    { description: "List all projects with their IDs, labels, and status" },
+    async () => {
+      const ml = ctx.requireMl();
+      await ml.projectList.refreshState();
+      const projects = await ml.projectList.awaitStableValue();
+      return textResult(
+        projects.map((p) => ({
+          projectId: resourceIdToString(p.rid),
+          label: p.meta.label,
+          opened: p.opened,
+          created: p.created.toISOString(),
+          lastModified: p.lastModified.toISOString(),
+        })),
+      );
+    },
+  );
+
+  server.registerTool(
+    "create_project",
+    {
+      description: "Create a new project",
+      inputSchema: { label: z.string().describe("Project name") },
+    },
+    async ({ label }) => {
+      const rid = await ctx.requireMl().createProject({ label });
+      const projectId = resourceIdToString(rid);
+      await ctx.callbacks.onProjectCreated?.(projectId);
+      return textResult({ projectId });
+    },
+  );
+
+  server.registerTool(
+    "open_project",
+    {
+      description: "Open a project for editing. Required before working with blocks.",
+      inputSchema: {
+        projectId: z.string().describe("Project ID from list_projects or create_project"),
+      },
+    },
+    async ({ projectId }) => {
+      const entry = await ctx.resolveProject(projectId);
+      await ctx.requireMl().openProject(entry.rid);
+      await ctx.callbacks.onProjectOpened?.(projectId);
+      return textResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "close_project",
+    {
+      description: "Close an opened project, releasing its resources",
+      inputSchema: { projectId: z.string().describe("Project ID") },
+    },
+    async ({ projectId }) => {
+      const entry = await ctx.resolveProject(projectId);
+      await ctx.requireMl().closeProject(entry.rid);
+      await ctx.callbacks.onProjectClosed?.(projectId);
+      return textResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "delete_project",
+    {
+      description: "Delete a project permanently. The project must be closed first.",
+      inputSchema: { projectId: z.string().describe("Project ID") },
+    },
+    async ({ projectId }) => {
+      const entry = await ctx.resolveProject(projectId);
+      await ctx.requireMl().deleteProject(entry.id);
+      await ctx.callbacks.onProjectDeleted?.(projectId);
+      return textResult({ ok: true });
+    },
+  );
+}

package/src/tools/sandbox.ts

@@ -0,0 +1,62 @@
+import { getQuickJS, type QuickJSRuntime } from "quickjs-emscripten";
+
+/** Lazily initialized QuickJS runtime shared across evaluations. */
+let sharedRuntime: QuickJSRuntime | undefined;
+
+async function getRuntime(): Promise<QuickJSRuntime> {
+  if (!sharedRuntime) {
+    const quickjs = await getQuickJS();
+    sharedRuntime = quickjs.newRuntime();
+    sharedRuntime.setMemoryLimit(1024 * 1024 * 16); // 16 MB
+    sharedRuntime.setMaxStackSize(1024 * 320);
+  }
+  return sharedRuntime;
+}
+
+/**
+ * Evaluate a JS expression in a QuickJS sandbox.
+ * Variables from `context` are injected as globals.
+ * Data is marshaled via JSON — no access to Node APIs, filesystem, or process.
+ */
+export async function safeEval(
+  expression: string,
+  context: Record<string, unknown>,
+  timeout: number,
+): Promise<unknown> {
+  const runtime = await getRuntime();
+
+  // Set interrupt handler for timeout
+  const deadline = Date.now() + timeout;
+  runtime.setInterruptHandler(() => Date.now() > deadline);
+
+  const vm = runtime.newContext();
+  try {
+    // Inject context variables via JSON
+    const contextJson = JSON.stringify(context);
+    const setup = `const __ctx = JSON.parse(${JSON.stringify(contextJson)});
+${Object.keys(context)
+  .map((k) => `const ${k} = __ctx[${JSON.stringify(k)}];`)
+  .join("\n")}`;
+    const setupResult = vm.evalCode(setup, "setup.js", { type: "global" });
+    if (setupResult.error) {
+      const err = vm.dump(setupResult.error);
+      setupResult.error.dispose();
+      throw new Error(`Context setup failed: ${err}`);
+    }
+    setupResult.value.dispose();
+
+    // Evaluate the expression
+    const result = vm.evalCode(`JSON.stringify((${expression}))`, "transform.js");
+    if (result.error) {
+      const err = vm.dump(result.error);
+      result.error.dispose();
+      throw new Error(String(err));
+    }
+    const json = vm.getString(result.value);
+    result.value.dispose();
+    return JSON.parse(json);
+  } finally {
+    runtime.setInterruptHandler(() => false);
+    vm.dispose();
+  }
+}

package/src/tools/screenshot.ts

@@ -0,0 +1,48 @@
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ToolContext } from "./types";
+import { errorResult } from "./types";
+
+export function registerScreenshotTool(server: McpServer, ctx: ToolContext): void {
+  server.registerTool(
+    "capture_screenshot",
+    {
+      description:
+        "Capture a screenshot of the current application window. Optionally save to a file.",
+      inputSchema: {
+        savePath: z
+          .string()
+          .optional()
+          .describe(
+            "Absolute file path to save the screenshot as PNG. If omitted, returns the image inline only.",
+          ),
+      },
+    },
+    async ({ savePath }: { savePath?: string }) => {
+      if (!ctx.callbacks.captureScreenshot) {
+        return errorResult(
+          "Screenshot capture is not available.",
+          "Make sure the MCP server is running inside Platforma Desktop and MCP connected properly. If everything is fine check Electron logs with get_app_log",
+        );
+      }
+      const base64Png = await ctx.callbacks.captureScreenshot();
+
+      if (savePath) {
+        const absPath = resolve(savePath);
+        await writeFile(absPath, Buffer.from(base64Png, "base64"), { flag: "wx" });
+        return {
+          content: [
+            { type: "image" as const, data: base64Png, mimeType: "image/png" },
+            { type: "text" as const, text: `Screenshot saved to ${absPath}` },
+          ],
+        };
+      }
+
+      return {
+        content: [{ type: "image" as const, data: base64Png, mimeType: "image/png" }],
+      };
+    },
+  );
+}