@milaboratories/pl-mcp-server 0.2.0

package/src/tools/await.ts

@@ -0,0 +1,151 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { isTimeoutError } from "@milaboratories/pl-middle-layer";
+import { deriveDataFromStorage } from "@platforma-sdk/model";
+import { z } from "zod";
+import type { ToolContext } from "./types";
+import { summarizeOutputs } from "./tokens";
+import { safeEval } from "./sandbox";
+import { errorResult, textResult } from "./types";
+
+export function registerAwaitTools(server: McpServer, ctx: ToolContext): void {
+  server.registerTool(
+    "await_block_done",
+    {
+      description:
+        "Wait for a block to finish computation and outputs to stabilize. " +
+        "Returns block status, data, and concise output summary with token estimates. " +
+        "Use `transform` to extract specific data server-side on completion.",
+      inputSchema: {
+        projectId: z.string().describe("Project ID"),
+        blockId: z.string().describe("Block ID to wait for"),
+        timeout: z.number().optional().default(120000).describe("Timeout in ms (default 120000)"),
+        transform: z
+          .string()
+          .optional()
+          .describe(
+            "JS expression evaluated server-side when block completes. " +
+              "Available variables: `data` (block args), `outputs` (raw outputs), `block` (status info). " +
+              "Omit for default concise summary.",
+          ),
+        transformTimeout: z
+          .number()
+          .optional()
+          .default(5000)
+          .describe("Timeout in ms for transform evaluation (default 5000)."),
+      },
+    },
+    async ({ projectId, blockId, timeout, transform, transformTimeout }) => {
+      const project = await ctx.getOpenedProject(projectId);
+      const deadline = Date.now() + timeout;
+
+      while (Date.now() < deadline) {
+        const overview = await project.overview.getValue();
+        if (!overview) continue;
+        const block = overview.blocks.find((b) => b.id === blockId);
+        if (!block)
+          return errorResult(
+            `Block ${blockId} not found in project ${projectId}.`,
+            "Use get_project_overview to list all block IDs in this project.",
+          );
+
+        // Terminal error states — return immediately
+        if (block.calculationStatus === "Limbo") {
+          return errorResult(
+            "Block entered Limbo state (upstream failed or was stopped).",
+            "Check upstream blocks with get_project_overview. Fix or re-run the failed upstream, then retry.",
+          );
+        }
+
+        if (block.calculationStatus === "NotCalculated") {
+          return errorResult(
+            "Block has not been started.",
+            "Use run_block to start it first, then call await_block_done.",
+          );
+        }
+
+        if (block.calculationStatus === "Done") {
+          // Await stable block state with remaining time budget
+          const remaining = Math.max(deadline - Date.now(), 1000);
+          let state;
+          try {
+            state = await project
+              .getBlockState(blockId)
+              .awaitStableValue(AbortSignal.timeout(remaining));
+          } catch (e: unknown) {
+            if (isTimeoutError(e)) {
+              return textResult({
+                timedOut: true,
+                status: "Done",
+                note: "Computation done but outputs did not stabilize in time. Retry with a longer timeout.",
+              });
+            }
+            return errorResult(
+              `Failed to get block state: ${e instanceof Error ? e.message : String(e)}`,
+            );
+          }
+
+          const data = deriveDataFromStorage(state.blockStorage);
+
+          const blockInfo = {
+            id: block.id,
+            title: block.title ?? block.label,
+            calculationStatus: block.calculationStatus,
+            canRun: block.canRun,
+            stale: block.stale,
+            outputErrors: block.outputErrors,
+          };
+
+          if (transform) {
+            try {
+              const result = await safeEval(
+                transform,
+                {
+                  data,
+                  outputs: state.outputs,
+                  block: blockInfo,
+                },
+                transformTimeout,
+              );
+              return textResult({ status: "Done", block: blockInfo, result });
+            } catch (e: unknown) {
+              return errorResult(
+                `Transform failed: ${e instanceof Error ? e.message : String(e)}`,
+                "Check your JS expression syntax. Available variables: data, outputs, block.",
+              );
+            }
+          }
+
+          return textResult({
+            status: "Done",
+            block: blockInfo,
+            data,
+            outputs: summarizeOutputs(state.outputs as Record<string, unknown> | undefined),
+          });
+        }
+
+        // Still running — wait up to 5s for overview to change, then re-poll.
+        // Minimum 500ms delay to avoid busy-looping if awaitChange resolves immediately.
+        const pollStart = Date.now();
+        try {
+          const result = await project.overview.getFullValue();
+          await project.overview.awaitChange(AbortSignal.timeout(5000), result.uTag);
+        } catch {
+          // timeout or abort — just re-poll
+        }
+        const elapsed = Date.now() - pollStart;
+        if (elapsed < 500) {
+          await new Promise((r) => setTimeout(r, 500 - elapsed));
+        }
+      }
+
+      // Timed out while running
+      const overview = await project.overview.getValue();
+      const block = overview?.blocks.find((b) => b.id === blockId);
+      return textResult({
+        timedOut: true,
+        status: block?.calculationStatus ?? "Unknown",
+        hint: "The block is still running. Call await_block_done again with a longer timeout.",
+      });
+    },
+  );
+}

package/src/tools/block-state.ts

@@ -0,0 +1,115 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { deriveDataFromStorage } from "@platforma-sdk/model";
+import { z } from "zod";
+import type { ToolContext } from "./types";
+import { summarizeOutputs } from "./tokens";
+import { safeEval } from "./sandbox";
+import { errorResult, textResult } from "./types";
+
+export function registerBlockStateTools(server: McpServer, ctx: ToolContext): void {
+  server.registerTool(
+    "get_project_overview",
+    {
+      description:
+        "Get project overview with all blocks and their statuses (calculationStatus, canRun, stale, errors, upstreams/downstreams)",
+      inputSchema: {
+        projectId: z.string().describe("Project ID (must be opened)"),
+      },
+    },
+    async ({ projectId }) => {
+      const project = await ctx.getOpenedProject(projectId);
+      const overview = await project.overview.getValue();
+      if (!overview) return errorResult("Project overview not available yet.");
+      return textResult({
+        label: overview.meta.label,
+        blocks: overview.blocks.map((b) => ({
+          id: b.id,
+          title: b.title ?? b.label,
+          calculationStatus: b.calculationStatus,
+          canRun: b.canRun,
+          stale: b.stale,
+          inputsValid: b.inputsValid,
+          outputErrors: b.outputErrors,
+          upstreams: b.upstreams,
+          downstreams: b.downstreams,
+        })),
+      });
+    },
+  );
+
+  server.registerTool(
+    "get_block_state",
+    {
+      description:
+        "Get block state. Returns block args (data) and a concise output summary with token estimates by default. " +
+        "Use `transform` to extract specific data server-side without loading full outputs into context.\n\n" +
+        "Default: returns `{ data, outputs: [{ key, ok, hasValue, tokensEstimate }] }`\n\n" +
+        "Transform examples:\n" +
+        "- `outputs.logs?.value` — get one specific output value\n" +
+        "- `data` — get only block args\n" +
+        "- `({ preset: outputs.preset?.value, qc: outputs.qc?.value })` — get specific outputs",
+      inputSchema: {
+        projectId: z.string().describe("Project ID"),
+        blockId: z.string().describe("Block ID"),
+        transform: z
+          .string()
+          .optional()
+          .describe(
+            "JS expression evaluated server-side against full block state. " +
+              "Available variables: `data` (block args), `outputs` (raw outputs object). " +
+              "Omit for default concise summary.",
+          ),
+        transformTimeout: z
+          .number()
+          .optional()
+          .default(5000)
+          .describe("Timeout in ms for transform evaluation (default 5000)."),
+      },
+    },
+    async ({ projectId, blockId, transform, transformTimeout }) => {
+      const project = await ctx.getOpenedProject(projectId);
+      const state = await project.getBlockState(blockId).getValue();
+      const data = deriveDataFromStorage(state.blockStorage);
+      if (transform) {
+        try {
+          const result = await safeEval(
+            transform,
+            { data, outputs: state.outputs },
+            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: data, outputs.",
+          );
+        }
+      }
+      return textResult({
+        data,
+        outputs: summarizeOutputs(state.outputs as Record<string, unknown> | undefined),
+      });
+    },
+  );
+
+  server.registerTool(
+    "set_block_data",
+    {
+      description: "Set the user-facing data of a block (triggers args derivation and staging)",
+      inputSchema: {
+        projectId: z.string().describe("Project ID"),
+        blockId: z.string().describe("Block ID"),
+        data: z.record(z.unknown()).describe("Block data object"),
+      },
+    },
+    async ({ projectId, blockId, data }) => {
+      const project = await ctx.getOpenedProject(projectId);
+      await project.mutateBlockStorage(
+        blockId,
+        { operation: "update-block-data", value: data },
+        ctx.getAuthorMarker(),
+      );
+      return textResult({ ok: true });
+    },
+  );
+}

package/src/tools/blocks.ts

@@ -0,0 +1,222 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { BlockPackSpecAny } from "@milaboratories/pl-middle-layer";
+import { z } from "zod";
+import type { ToolContext } from "./types";
+import { errorResult, textResult } from "./types";
+
+export function registerBlockTools(server: McpServer, ctx: ToolContext): void {
+  server.registerTool(
+    "add_block",
+    {
+      description:
+        "Add a block to an opened project. Spec can be from-registry-v2 (for published blocks) or dev-v2 (for local dev blocks).",
+      inputSchema: {
+        projectId: z.string().describe("Project ID (must be opened)"),
+        label: z.string().describe("Block label"),
+        spec: z
+          .union([
+            z.object({
+              type: z.literal("from-registry-v2"),
+              registryUrl: z.string().describe("Registry URL"),
+              id: z.object({
+                organization: z.string(),
+                name: z.string(),
+                version: z.string(),
+              }),
+            }),
+            z.object({
+              type: z.literal("dev-v2"),
+              folder: z.string().describe("Path to block folder"),
+            }),
+          ])
+          .describe("Block pack specification"),
+      },
+    },
+    async ({ projectId, label, spec }) => {
+      const project = await ctx.getOpenedProject(projectId);
+      const blockId = await project.addBlock(
+        label,
+        spec as BlockPackSpecAny,
+        undefined,
+        ctx.getAuthorMarker(),
+      );
+      return textResult({ blockId });
+    },
+  );
+
+  server.registerTool(
+    "update_block",
+    {
+      description:
+        "Update an existing block's pack (reload from registry or dev folder). Use after rebuilding a dev block to pick up changes without removing/re-adding it.",
+      inputSchema: {
+        projectId: z.string().describe("Project ID (must be opened)"),
+        blockId: z.string().describe("Block ID to update"),
+        spec: z
+          .union([
+            z.object({
+              type: z.literal("from-registry-v2"),
+              registryUrl: z.string().describe("Registry URL"),
+              id: z.object({
+                organization: z.string(),
+                name: z.string(),
+                version: z.string(),
+              }),
+            }),
+            z.object({
+              type: z.literal("dev-v2"),
+              folder: z.string().describe("Path to block folder"),
+            }),
+          ])
+          .describe("Block pack specification"),
+        resetArgs: z
+          .boolean()
+          .optional()
+          .describe("Reset block arguments to initial values (default: false)"),
+      },
+    },
+    async ({ projectId, blockId, spec, resetArgs }) => {
+      const project = await ctx.getOpenedProject(projectId);
+      await project.updateBlockPack(
+        blockId,
+        spec as BlockPackSpecAny,
+        resetArgs ?? false,
+        ctx.getAuthorMarker(),
+      );
+      return textResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "remove_block",
+    {
+      description: "Remove a block from an opened project",
+      inputSchema: {
+        projectId: z.string().describe("Project ID"),
+        blockId: z.string().describe("Block ID to remove"),
+      },
+    },
+    async ({ projectId, blockId }) => {
+      const project = await ctx.getOpenedProject(projectId);
+      await project.deleteBlock(blockId, ctx.getAuthorMarker());
+      return textResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "run_block",
+    {
+      description: "Run a block. Stale upstream blocks are started automatically.",
+      inputSchema: {
+        projectId: z.string().describe("Project ID"),
+        blockId: z.string().describe("Block ID to run"),
+      },
+    },
+    async ({ projectId, blockId }) => {
+      const project = await ctx.getOpenedProject(projectId);
+      await project.runBlock(blockId);
+      return textResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "stop_block",
+    {
+      description: "Stop a running block",
+      inputSchema: {
+        projectId: z.string().describe("Project ID"),
+        blockId: z.string().describe("Block ID to stop"),
+      },
+    },
+    async ({ projectId, blockId }) => {
+      const project = await ctx.getOpenedProject(projectId);
+      await project.stopBlock(blockId);
+      return textResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "reorder_blocks",
+    {
+      description: "Reorder blocks in a project. Must provide ALL block IDs in the desired order.",
+      inputSchema: {
+        projectId: z.string().describe("Project ID"),
+        blockIds: z.array(z.string()).describe("All block IDs in the desired order"),
+      },
+    },
+    async ({ projectId, blockIds }) => {
+      const project = await ctx.getOpenedProject(projectId);
+      await project.reorderBlocks(blockIds);
+      return textResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "list_available_blocks",
+    {
+      description:
+        "List available blocks from configured registries. Optional query to filter by name.",
+      inputSchema: {
+        query: z
+          .string()
+          .optional()
+          .describe("Filter blocks by name (case-insensitive substring match)"),
+      },
+    },
+    async ({ query }) => {
+      if (!ctx.callbacks.listAvailableBlocks) {
+        return errorResult(
+          "Block registry is not available.",
+          "This usually means the desktop app encounters a problem connecting block registry. Check Settings > Override Main Registry find which registry really in use and check connection.",
+        );
+      }
+      const blocks = await ctx.callbacks.listAvailableBlocks(query);
+      return textResult(blocks);
+    },
+  );
+
+  server.registerTool(
+    "get_block_info",
+    {
+      description:
+        "Get detailed info about a specific block package from the registry. Use list_available_blocks first to find the block.",
+      inputSchema: {
+        registryUrl: z.string().describe("Registry URL (from list_available_blocks)"),
+        organization: z.string().describe("Organization name"),
+        name: z.string().describe("Block package name"),
+        version: z.string().describe("Block version"),
+      },
+    },
+    async ({ registryUrl, organization, name, version }) => {
+      if (!ctx.callbacks.getBlockInfo) {
+        return errorResult(
+          "Block info is not available in this environment.",
+          'Maybe the name of the block was written incerrectly. Use list_available_blocks to browse blocks instead. Or ask user to check "Additional Registries" in Settings panel',
+        );
+      }
+      const info = await ctx.callbacks.getBlockInfo(registryUrl, organization, name, version);
+      return textResult(info);
+    },
+  );
+
+  server.registerTool(
+    "select_block",
+    {
+      description: "Navigate the desktop UI to show a specific block's interface",
+      inputSchema: {
+        projectId: z.string().describe("Project ID"),
+        blockId: z.string().describe("Block ID to display"),
+      },
+    },
+    async ({ projectId, blockId }) => {
+      if (!ctx.callbacks.selectBlock) {
+        return errorResult(
+          "Failed to select the block.",
+          "This feature requires server connected and open project. Use get_connection_status and list_projects to check. If there are no connection, use list_connections and ask user which should be used.",
+        );
+      }
+      await ctx.callbacks.selectBlock(projectId, blockId);
+      return textResult({ ok: true });
+    },
+  );
+}

package/src/tools/connection.ts

@@ -0,0 +1,63 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ToolContext } from "./types";
+import { errorResult, textResult } from "./types";
+
+export function registerConnectionTools(server: McpServer, ctx: ToolContext): void {
+  server.registerTool(
+    "get_connection_status",
+    { description: "Get current server connection status" },
+    async () => {
+      if (!ctx.callbacks.getConnectionStatus) {
+        return textResult({ connected: !!ctx.getMl() });
+      }
+      return textResult(await ctx.callbacks.getConnectionStatus());
+    },
+  );
+
+  server.registerTool(
+    "list_connections",
+    { description: "List saved server connections" },
+    async () => {
+      if (!ctx.callbacks.listConnections) {
+        return errorResult(
+          "Connection management is not available.",
+          "The desktop app integration may not support this feature.",
+        );
+      }
+      return textResult(await ctx.callbacks.listConnections());
+    },
+  );
+
+  server.registerTool(
+    "connect_to_server",
+    {
+      description: "Connect to a Platforma server. Use list_connections to see saved servers.",
+      inputSchema: {
+        addr: z.string().describe("Server address (e.g. https://pl6.demo2.platforma.bio:6346)"),
+        login: z.string().describe("Username"),
+        password: z.string().optional().describe("Password (uses saved token if omitted)"),
+      },
+    },
+    async ({ addr, login, password }) => {
+      if (!ctx.callbacks.connectToServer) {
+        return errorResult(
+          "Failed to connect to Platforma Server.",
+          "Check that provided URL is available and accepts connecitons.",
+        );
+      }
+      return textResult(await ctx.callbacks.connectToServer(addr, login, password));
+    },
+  );
+
+  server.registerTool("disconnect", { description: "Disconnect from current server" }, async () => {
+    if (!ctx.callbacks.disconnect) {
+      return errorResult(
+        "Failed to disconnect.",
+        "More likely it's because connection is already closed. Could check it with 'get_connection_status' tool.",
+      );
+    }
+    await ctx.callbacks.disconnect();
+    return textResult({ ok: true });
+  });
+}