@milaboratories/pl-mcp-server 0.2.0

package/src/tools/tokens.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, it } from "vitest";
+import { estimateTokens } from "./tokens";
+
+// --- Test data ---
+
+const flatObject = { name: "Alice", age: 30, active: true };
+
+const nestedObject = {
+  user: { name: "Bob", address: { city: "NYC", zip: "10001" } },
+};
+
+const flatArray = [1, 2, 3, "four", true, null];
+
+const nestedArray = [[1, 2], [3, [4, 5]], "deep"];
+
+const mixedDeep = {
+  a: [{ b: [{ c: "leaf" }] }],
+  d: { e: { f: { g: 42 } } },
+};
+
+const typedArrayValue = new Uint8Array([0, 1, 2, 255]);
+
+const largeFlat = Array.from({ length: 100 }, (_, i) => `item-${i}`);
+
+const wideObject = Object.fromEntries(Array.from({ length: 50 }, (_, i) => [`key${i}`, i]));
+
+const deepChain = (() => {
+  let obj: Record<string, unknown> = { value: "bottom" };
+  for (let i = 0; i < 20; i++) obj = { nested: obj };
+  return obj;
+})();
+
+const emptyContainers = { emptyObj: {}, emptyArr: [], emptyStr: "", nested: { also: {} } };
+
+// Helper: actual token estimate from JSON.stringify
+function actualTokens(v: unknown): number {
+  return Math.ceil(JSON.stringify(v).length / 4);
+}
+
+// --- Tests ---
+
+describe("estimateTokens", () => {
+  describe("primitives", () => {
+    it("null → 1 token ('null' = 4 chars)", () => {
+      expect(estimateTokens(null)).toBe(1);
+    });
+
+    it("undefined → 1 token (treated as null)", () => {
+      expect(estimateTokens(undefined)).toBe(1);
+    });
+
+    it("empty string → 1 token ('\"\"' = 2 chars)", () => {
+      expect(estimateTokens("")).toBe(1);
+    });
+
+    it("short string matches actual", () => {
+      expect(estimateTokens("hello")).toBe(actualTokens("hello"));
+    });
+
+    it("number matches actual", () => {
+      expect(estimateTokens(42)).toBe(actualTokens(42));
+      expect(estimateTokens(3.14)).toBe(actualTokens(3.14));
+      expect(estimateTokens(0)).toBe(actualTokens(0));
+    });
+
+    it("boolean matches actual", () => {
+      expect(estimateTokens(true)).toBe(actualTokens(true));
+      expect(estimateTokens(false)).toBe(actualTokens(false));
+    });
+
+    it("bigint estimates like number", () => {
+      const t = estimateTokens(BigInt(12345));
+      expect(typeof t).toBe("number");
+      expect(t).toBeGreaterThan(0);
+    });
+  });
+
+  describe("typed arrays", () => {
+    it("Uint8Array matches actual", () => {
+      // JSON.stringify(new Uint8Array([0,1,2,255])) doesn't work directly,
+      // but our function estimates as if it were [0,1,2,255]
+      expect(estimateTokens(typedArrayValue)).toBe(actualTokens([0, 1, 2, 255]));
+    });
+
+    it("empty Uint8Array → brackets only", () => {
+      expect(estimateTokens(new Uint8Array([]))).toBe(actualTokens([]));
+    });
+
+    it("Int32Array", () => {
+      const arr = new Int32Array([100, 200, 300]);
+      expect(estimateTokens(arr)).toBe(actualTokens([100, 200, 300]));
+    });
+  });
+
+  describe("arrays", () => {
+    it("empty array matches actual", () => {
+      expect(estimateTokens([])).toBe(actualTokens([]));
+    });
+
+    it("flat number array matches actual", () => {
+      expect(estimateTokens([1, 2, 3])).toBe(actualTokens([1, 2, 3]));
+    });
+
+    it("mixed array matches actual", () => {
+      expect(estimateTokens(flatArray)).toBe(actualTokens(flatArray));
+    });
+
+    it("nested array matches actual", () => {
+      expect(estimateTokens(nestedArray)).toBe(actualTokens(nestedArray));
+    });
+  });
+
+  describe("objects", () => {
+    it("empty object matches actual", () => {
+      expect(estimateTokens({})).toBe(actualTokens({}));
+    });
+
+    it("flat object matches actual", () => {
+      expect(estimateTokens(flatObject)).toBe(actualTokens(flatObject));
+    });
+
+    it("nested object matches actual", () => {
+      expect(estimateTokens(nestedObject)).toBe(actualTokens(nestedObject));
+    });
+  });
+
+  describe("complex structures", () => {
+    it("mixed deep ≈ actual", () => {
+      expect(estimateTokens(mixedDeep)).toBe(actualTokens(mixedDeep));
+    });
+
+    it("deep chain ≈ actual", () => {
+      expect(estimateTokens(deepChain)).toBe(actualTokens(deepChain));
+    });
+
+    it("empty containers ≈ actual", () => {
+      expect(estimateTokens(emptyContainers)).toBe(actualTokens(emptyContainers));
+    });
+
+    it("large flat array ≈ actual", () => {
+      const est = estimateTokens(largeFlat) as number;
+      const act = actualTokens(largeFlat);
+      expect(Math.abs(est - act)).toBeLessThanOrEqual(1); // rounding
+    });
+
+    it("wide object ≈ actual", () => {
+      const est = estimateTokens(wideObject) as number;
+      const act = actualTokens(wideObject);
+      expect(Math.abs(est - act)).toBeLessThanOrEqual(1);
+    });
+  });
+
+  describe("node limit", () => {
+    it("respects small node limit on flat array", () => {
+      const arr = [1, 2, 3, 4, 5]; // 6 nodes: 1 array + 5 numbers
+      const result = estimateTokens(arr, 3);
+      expect(typeof result).toBe("string");
+      expect(result).toContain("truncated");
+      expect(result).toContain("3 nodes");
+    });
+
+    it("respects small node limit on object", () => {
+      const result = estimateTokens({ a: 1, b: 2, c: 3 }, 2);
+      expect(typeof result).toBe("string");
+      expect(result).toContain("truncated");
+    });
+
+    it("returns number when within limit", () => {
+      expect(typeof estimateTokens([1, 2], 10)).toBe("number");
+    });
+
+    it("node limit = 1 overflows on container with children", () => {
+      const result = estimateTokens([1], 1);
+      expect(typeof result).toBe("string");
+      expect(result).toContain("truncated");
+    });
+
+    it("node limit = 1 allows single primitive", () => {
+      expect(typeof estimateTokens(42, 1)).toBe("number");
+    });
+
+    it("truncated result includes partial token count", () => {
+      // [1, 2, 3] with limit 2: node1=array, node2=1, node3>limit
+      const result = estimateTokens([1, 2, 3], 2) as string;
+      expect(result).toMatch(/^>\d+/);
+      expect(result).toContain("truncated at 2 nodes");
+    });
+
+    it("deeply nested hits limit", () => {
+      const result = estimateTokens({ a: { b: { c: { d: 1 } } } }, 3);
+      expect(typeof result).toBe("string");
+      expect(result).toContain("truncated");
+    });
+
+    it("large flat array within default limit", () => {
+      expect(typeof estimateTokens(largeFlat)).toBe("number");
+    });
+
+    it("wide object within default limit", () => {
+      expect(typeof estimateTokens(wideObject)).toBe("number");
+    });
+  });
+
+  describe("accuracy vs JSON.stringify", () => {
+    it("estimate equals actual for simple cases", () => {
+      const cases = [null, 42, "test", true, false, [1, 2, 3], { a: 1 }, { x: "hello", y: [1, 2] }];
+      for (const c of cases) {
+        expect(estimateTokens(c)).toBe(actualTokens(c));
+      }
+    });
+
+    it("estimate within 1 token of actual for larger structures", () => {
+      const cases = [
+        flatObject,
+        nestedObject,
+        flatArray,
+        mixedDeep,
+        deepChain,
+        wideObject,
+        largeFlat,
+      ];
+      for (const c of cases) {
+        const est = estimateTokens(c) as number;
+        const act = actualTokens(c);
+        expect(Math.abs(est - act)).toBeLessThanOrEqual(1);
+      }
+    });
+  });
+
+  describe("edge cases", () => {
+    it("function treated as empty object", () => {
+      expect(typeof estimateTokens(() => {})).toBe("number");
+    });
+
+    it("symbol treated as empty object", () => {
+      expect(typeof estimateTokens(Symbol("test"))).toBe("number");
+    });
+  });
+});

package/src/tools/tokens.ts

@@ -0,0 +1,84 @@
+const NODE_LIMIT = 10_000;
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * Estimate the number of LLM tokens needed to represent a value as JSON,
+ * without actually serializing it. Walks the object tree and sums up
+ * the JSON character lengths, then divides by ~4 chars/token.
+ *
+ * Returns token estimate, or a string like ">1234 (truncated at 10000 nodes)"
+ * if the object graph is too large to fully traverse.
+ */
+export function estimateTokens(value: unknown, nodeLimit = NODE_LIMIT): number | string {
+  let nodes = 0;
+  let chars = 0;
+
+  /** Returns true if node limit exceeded. */
+  function walk(v: unknown): boolean {
+    if (++nodes > nodeLimit) return true;
+    if (v === null || v === undefined) {
+      chars += 4; // "null"
+      return false;
+    }
+    switch (typeof v) {
+      case "string":
+        chars += v.length + 2; // content + quotes
+        return false;
+      case "number":
+        chars += String(v).length;
+        return false;
+      case "boolean":
+        chars += v ? 4 : 5; // "true" or "false"
+        return false;
+      case "bigint":
+        chars += String(v).length;
+        return false;
+      default:
+        break;
+    }
+    if (v instanceof Uint8Array || ArrayBuffer.isView(v)) {
+      // serialized as array of numbers
+      const arr = v as Uint8Array;
+      chars += 2 + Math.max(0, arr.length - 1); // [] + commas
+      for (let i = 0; i < arr.length; i++) {
+        chars += String(arr[i]).length;
+      }
+      return false;
+    }
+    if (Array.isArray(v)) {
+      chars += 2; // []
+      if (v.length > 1) chars += v.length - 1; // commas
+      for (const item of v) {
+        if (walk(item)) return true;
+      }
+      return false;
+    }
+    if (typeof v === "object") {
+      const entries = Object.entries(v as Record<string, unknown>);
+      chars += 2; // {}
+      if (entries.length > 1) chars += entries.length - 1; // commas
+      for (const [k, val] of entries) {
+        chars += k.length + 3; // "key":
+        if (walk(val)) return true;
+      }
+    }
+    return false;
+  }
+
+  const overflow = walk(value);
+  const tokens = Math.ceil(chars / CHARS_PER_TOKEN);
+  return overflow ? `>${tokens} (truncated at ${nodeLimit} nodes)` : tokens;
+}
+
+/** Summarize block outputs as concise key/ok/hasValue/tokensEstimate entries. */
+export function summarizeOutputs(
+  outputs: Record<string, unknown> | undefined,
+): { key: string; ok: boolean; hasValue: boolean; tokensEstimate?: number | string }[] {
+  if (!outputs) return [];
+  return Object.entries(outputs).map(([key, out]) => {
+    const o = out as { ok?: boolean; value?: unknown } | undefined;
+    const hasValue = o?.value != null;
+    const tokensEstimate = hasValue ? estimateTokens(o!.value) : undefined;
+    return { key, ok: o?.ok ?? false, hasValue, tokensEstimate };
+  });
+}

package/src/tools/types.ts

@@ -0,0 +1,34 @@
+import type {
+  AuthorMarker,
+  MiddleLayer,
+  Project,
+  ProjectListEntry,
+} from "@milaboratories/pl-middle-layer";
+import type { PlMcpServerCallbacks } from "../server";
+
+export type { AuthorMarker };
+
+export interface ToolContext {
+  getMl: () => MiddleLayer | null;
+  requireMl: () => MiddleLayer;
+  resolveProject: (projectId: string) => Promise<ProjectListEntry>;
+  getOpenedProject: (projectId: string) => Promise<Project>;
+  callbacks: PlMcpServerCallbacks;
+  /** Returns an AuthorMarker with auto-incrementing localVersion for this MCP session. */
+  getAuthorMarker: () => AuthorMarker;
+}
+
+export function textResult(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data) }],
+  };
+}
+
+/** Return an MCP error result with an actionable hint for the AI agent. */
+export function errorResult(message: string, hint?: string) {
+  const text = hint ? `${message}\n\nHint: ${hint}` : message;
+  return {
+    content: [{ type: "text" as const, text }],
+    isError: true,
+  };
+}

package/src/tools/ui-interaction.ts

@@ -0,0 +1,156 @@
+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 registerUIInteractionTools(server: McpServer, ctx: ToolContext): void {
+  server.registerTool(
+    "click",
+    {
+      description:
+        "Click at coordinates (x, y) in the application window. Use capture_screenshot to find element positions.",
+      inputSchema: {
+        x: z.number().describe("X coordinate"),
+        y: z.number().describe("Y coordinate"),
+        doubleClick: z.boolean().optional().describe("Double click"),
+      },
+    },
+    async ({ x, y, doubleClick }) => {
+      if (!ctx.callbacks.sendInputEvent) {
+        return errorResult(
+          "UI interaction 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 clickCount = doubleClick ? 2 : 1;
+      await ctx.callbacks.sendInputEvent({
+        type: "mouseDown",
+        x,
+        y,
+        button: "left",
+        clickCount,
+      });
+      await ctx.callbacks.sendInputEvent({ type: "mouseUp", x, y, button: "left", clickCount });
+      return textResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "type_text",
+    {
+      description: "Type text into the currently focused element",
+      inputSchema: {
+        text: z.string().describe("Text to type"),
+      },
+    },
+    async ({ text }) => {
+      if (!ctx.callbacks.sendInputEvent) {
+        return errorResult(
+          "UI interaction 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",
+        );
+      }
+      for (const char of text) {
+        await ctx.callbacks.sendInputEvent({ type: "keyDown", keyCode: char });
+        await ctx.callbacks.sendInputEvent({ type: "char", keyCode: char });
+        await ctx.callbacks.sendInputEvent({ type: "keyUp", keyCode: char });
+      }
+      return textResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "press_key",
+    {
+      description: "Press a keyboard key (Enter, Tab, Escape, Backspace, ArrowDown, ArrowUp, etc.)",
+      inputSchema: {
+        key: z
+          .string()
+          .describe("Key name (e.g. 'Enter', 'Tab', 'Escape', 'Backspace', 'ArrowDown')"),
+        modifiers: z
+          .array(z.enum(["shift", "control", "alt", "meta"]))
+          .optional()
+          .describe("Modifier keys to hold"),
+      },
+    },
+    async ({ key, modifiers }) => {
+      if (!ctx.callbacks.sendInputEvent) {
+        return errorResult(
+          "UI interaction 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",
+        );
+      }
+      await ctx.callbacks.sendInputEvent({
+        type: "keyDown",
+        keyCode: key,
+        ...(modifiers && {
+          shift: modifiers.includes("shift"),
+          control: modifiers.includes("control"),
+          alt: modifiers.includes("alt"),
+          meta: modifiers.includes("meta"),
+        }),
+      });
+      await ctx.callbacks.sendInputEvent({
+        type: "keyUp",
+        keyCode: key,
+        ...(modifiers && {
+          shift: modifiers.includes("shift"),
+          control: modifiers.includes("control"),
+          alt: modifiers.includes("alt"),
+          meta: modifiers.includes("meta"),
+        }),
+      });
+      return textResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "scroll",
+    {
+      description: "Scroll the page at a given position",
+      inputSchema: {
+        x: z.number().describe("X coordinate to scroll at"),
+        y: z.number().describe("Y coordinate to scroll at"),
+        deltaX: z.number().optional().default(0).describe("Horizontal scroll amount"),
+        deltaY: z.number().describe("Vertical scroll amount (negative = up, positive = down)"),
+      },
+    },
+    async ({ x, y, deltaX, deltaY }) => {
+      if (!ctx.callbacks.sendInputEvent) {
+        return errorResult(
+          "UI interaction 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",
+        );
+      }
+      await ctx.callbacks.sendInputEvent({
+        type: "mouseWheel",
+        x,
+        y,
+        deltaX: deltaX ?? 0,
+        deltaY,
+      });
+      return textResult({ ok: true });
+    },
+  );
+
+  server.registerTool(
+    "execute_js",
+    {
+      description:
+        "Execute JavaScript in the renderer process and return the result. Useful for querying DOM, reading text, or complex interactions.",
+      inputSchema: {
+        code: z.string().describe("JavaScript code to execute"),
+      },
+    },
+    async ({ code }) => {
+      if (!ctx.callbacks.executeJavaScript) {
+        return errorResult(
+          "JS execution 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 result = await ctx.callbacks.executeJavaScript(code);
+      return textResult(result);
+    },
+  );
+}