@aliceshimada/mica 1.0.0

package/dist/src/mcp/toolSchemas.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+export const noArgsSchema = z.object({}).strict();
+const notebookIdField = z.string().min(1);
+const notebookSelectorFields = {
+    notebookId: notebookIdField.optional(),
+    displayName: z.string().min(1).optional()
+};
+const maxBytesField = z.number().int().positive().max(1024 * 1024);
+export const selectNotebookSchema = z.object({
+    notebookId: notebookIdField.optional(),
+    displayName: z.string().min(1).optional()
+}).strict();
+export const readCellSchema = z.object({
+    ...notebookSelectorFields,
+    cellId: z.string().min(1),
+    maxBytes: maxBytesField.optional()
+}).strict();
+export const insertCellSchema = z.object({
+    ...notebookSelectorFields,
+    afterCellId: z.string().min(1).optional(),
+    style: z.string().min(1).default("Input"),
+    content: z.string()
+}).strict();
+export const modifyCellSchema = z.object({
+    ...notebookSelectorFields,
+    cellId: z.string().min(1),
+    content: z.string()
+}).strict();
+export const deleteCellSchema = z.object({
+    ...notebookSelectorFields,
+    cellId: z.string().min(1)
+}).strict();
+export const runCellSchema = z.object({
+    ...notebookSelectorFields,
+    cellId: z.string().min(1),
+    timeoutSec: z.number().int().positive().max(3600).default(120)
+}).strict();
+export const abortEvaluationSchema = z.object({
+    ...notebookSelectorFields
+}).strict();
+export const getCellOutputSchema = z.object({
+    ...notebookSelectorFields,
+    cellId: z.string().min(1),
+    maxBytes: maxBytesField.optional()
+}).strict();
+export const readArtifactSchema = z.object({
+    ...notebookSelectorFields,
+    artifactId: z.string().min(1),
+    offset: z.number().int().nonnegative().default(0),
+    limit: z.number().int().positive().max(1024 * 1024).default(65_536)
+}).strict();
+export const listCellsSchema = z.object({
+    ...notebookSelectorFields
+}).strict();
+export const saveNotebookSchema = z.object({
+    ...notebookSelectorFields
+}).strict();
+export const symbolLookupSchema = z.object({
+    query: z.string().min(1).describe("Symbol name or partial search term")
+}).strict();

package/dist/src/mcp/tools.js

@@ -0,0 +1,161 @@
+import { abortEvaluationSchema, deleteCellSchema, getCellOutputSchema, listCellsSchema, insertCellSchema, modifyCellSchema, noArgsSchema, readArtifactSchema, readCellSchema, selectNotebookSchema, saveNotebookSchema, runCellSchema, symbolLookupSchema } from "./toolSchemas.js";
+import { INSERT_ANCHOR_GUIDANCE, notebookToolDescription } from "./descriptions.js";
+import { toolSuccess, withToolErrors } from "./toolResults.js";
+export function assertBridgeReadyForTool(status) {
+    if (!status.paletteConnected) {
+        throw new Error("Mathematica Palette is not connected. Open the MMA Agent Bridge palette and click 'Allow control of current Notebook'.");
+    }
+    if (!status.notebookAttached) {
+        throw new Error("No Mathematica notebook is attached. Click 'Allow control of current Notebook' in the MMA Agent Bridge palette.");
+    }
+}
+export function resolveNotebookTarget(args, status) {
+    const explicit = args.notebookId;
+    if (typeof explicit === "string" && explicit.length > 0) {
+        const knownNotebook = status.notebooks?.some((notebook) => notebook.notebookId === explicit) ?? false;
+        if (!knownNotebook) {
+            throw new Error(`Unknown notebookId: ${explicit}`);
+        }
+        return explicit;
+    }
+    const displayName = args.displayName;
+    if (typeof displayName === "string" && displayName.trim().length > 0) {
+        throw new Error("Display-name notebook selection is not supported in the Node MCP tool path yet.");
+    }
+    if (typeof status.activeNotebookId === "string" && status.activeNotebookId.length > 0) {
+        return status.activeNotebookId;
+    }
+    throw new Error("No Mathematica notebook is selected");
+}
+/**
+ * Enqueue a tool call through the bridge queue and wire MCP-client
+ * cancellation via the AbortSignal provided by the SDK.
+ *
+ * When the MCP client cancels the tool call the SDK fires the signal's
+ * `abort` event. We call `queue.cancelFromMcp` so the request is rejected
+ * immediately (queued) or a one-shot cancellation notification is stored
+ * for the Palette (claimed). The listener is removed after the promise
+ * settles to avoid leaks.
+ */
+async function enqueueRequestWithCancellation(queue, tool, args, extra) {
+    const { requestId, promise } = queue.enqueueWithId(tool, args);
+    // If the signal was already aborted before we enqueued, cancel immediately.
+    if (extra?.signal?.aborted) {
+        queue.cancelFromMcp(requestId, "MCP client cancelled operation");
+    }
+    const onAbort = () => {
+        queue.cancelFromMcp(requestId, "MCP client cancelled operation");
+    };
+    // Only add the listener if the signal exists and isn't already aborted.
+    if (extra?.signal && !extra.signal.aborted) {
+        extra.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    try {
+        const result = await promise;
+        return toolSuccess(result);
+    }
+    finally {
+        extra?.signal?.removeEventListener("abort", onAbort);
+    }
+}
+async function enqueueWithCancellation(queue, getStatus, tool, args, extra) {
+    const status = getStatus();
+    assertBridgeReadyForTool(status);
+    const notebookId = resolveNotebookTarget(args, status);
+    return enqueueRequestWithCancellation(queue, tool, { ...args, notebookId }, extra);
+}
+function registerLegacyQueuedTool(server, queue, getStatus, config) {
+    server.tool(config.name, notebookToolDescription(config.summary, config.extraGuidance), config.schema, async (args, extra) => {
+        const recordArgs = args;
+        return withToolErrors({ tool: config.name, args: recordArgs }, () => enqueueWithCancellation(queue, getStatus, config.name, recordArgs, extra));
+    });
+}
+export function registerMmaTools(server, queue, getStatus) {
+    server.tool("mma_status", notebookToolDescription("Report Mathematica bridge, Palette, and notebook attachment status."), noArgsSchema.shape, async () => withToolErrors({ tool: "mma_status" }, () => toolSuccess(getStatus())));
+    server.tool("mma_list_notebooks", notebookToolDescription("List notebooks registered with the Mathematica bridge Palette."), noArgsSchema.shape, async () => {
+        return withToolErrors({ tool: "mma_list_notebooks" }, () => {
+            const status = getStatus();
+            return toolSuccess({ notebooks: status.notebooks ?? [], activeNotebookId: status.activeNotebookId });
+        });
+    });
+    server.tool("mma_select_notebook", notebookToolDescription("Select the active Mathematica notebook in the Palette registry."), selectNotebookSchema.shape, async (args, extra) => {
+        const recordArgs = args;
+        return withToolErrors({ tool: "mma_select_notebook", args: recordArgs }, () => {
+            const status = getStatus();
+            if (!status.paletteConnected) {
+                throw new Error("Mathematica Palette is not connected. Open the MMA Agent Bridge palette and click 'Allow control of current Notebook'.");
+            }
+            const notebookId = args.notebookId;
+            if (typeof args.displayName === "string" && args.displayName.trim().length > 0 && typeof notebookId !== "string") {
+                throw new Error("Display-name notebook selection is not supported in the Node MCP tool path yet.");
+            }
+            if (typeof notebookId !== "string" ||
+                notebookId.length === 0 ||
+                !(status.notebooks?.some((notebook) => notebook.notebookId === notebookId) ?? false)) {
+                throw new Error(`Unknown notebookId: ${notebookId}`);
+            }
+            return enqueueRequestWithCancellation(queue, "mma_select_notebook", recordArgs, extra);
+        });
+    });
+    const queuedTools = [
+        {
+            name: "mma_list_cells",
+            summary: "List cells in the attached active Mathematica notebook.",
+            schema: listCellsSchema.shape,
+        },
+        {
+            name: "mma_read_cell",
+            summary: "Read one cell from the attached Mathematica notebook.",
+            schema: readCellSchema.shape,
+        },
+        {
+            name: "mma_insert_cell",
+            summary: "Insert a cell through the Mathematica FrontEnd bridge.",
+            schema: insertCellSchema.shape,
+            extraGuidance: INSERT_ANCHOR_GUIDANCE,
+        },
+        {
+            name: "mma_modify_cell",
+            summary: "Modify one existing cell through the Mathematica FrontEnd bridge.",
+            schema: modifyCellSchema.shape,
+        },
+        {
+            name: "mma_delete_cell",
+            summary: "Delete one cell through the Mathematica FrontEnd bridge.",
+            schema: deleteCellSchema.shape,
+        },
+        {
+            name: "mma_run_cell",
+            summary: "Run one cell in the attached Mathematica notebook.",
+            schema: runCellSchema.shape,
+        },
+        {
+            name: "mma_abort_evaluation",
+            summary: "Abort the running Wolfram evaluation in the attached notebook.",
+            schema: abortEvaluationSchema.shape,
+        },
+        {
+            name: "mma_get_cell_output",
+            summary: "Read output and messages for one Mathematica notebook cell, refreshing completed run status when observed.",
+            schema: getCellOutputSchema.shape,
+        },
+        {
+            name: "mma_read_artifact",
+            summary: "Read one large output or message artifact by byte page. Artifact ids are resolved against current notebook state and may become stale after notebook edits or reruns.",
+            schema: readArtifactSchema.shape,
+        },
+        {
+            name: "mma_save_notebook",
+            summary: "Save the attached Mathematica notebook through the FrontEnd.",
+            schema: saveNotebookSchema.shape,
+        },
+        {
+            name: "mma_symbol_lookup",
+            summary: "Look up Wolfram Language symbol documentation. Provide an exact symbol name (e.g. 'Plot') for full details including usage, options, attributes, and documentation URL, or a partial name (e.g. 'integrate') for a list of matching symbols.",
+            schema: symbolLookupSchema.shape,
+        },
+    ];
+    for (const config of queuedTools) {
+        registerLegacyQueuedTool(server, queue, getStatus, config);
+    }
+}

package/dist/src/runtime/config.js

@@ -0,0 +1,76 @@
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 19_791;
+export function defaultSessionFile(env = process.env) {
+    const home = env.HOME || env.USERPROFILE || process.cwd();
+    return path.join(home, ".mica", "session.json");
+}
+export function generateAuthToken() {
+    return randomBytes(32).toString("base64url");
+}
+export function loadRuntimeConfig(options = {}) {
+    const env = options.env ?? process.env;
+    const argv = options.argv ?? process.argv.slice(2);
+    const cli = parseCliArgs(argv);
+    return {
+        host: cli.host ?? env.MICA_HOST ?? DEFAULT_HOST,
+        preferredPort: cli.port ?? parseOptionalPort(env.MICA_PORT, "MICA_PORT") ?? DEFAULT_PORT,
+        sessionFile: cli.sessionFile ?? env.MICA_SESSION_FILE ?? defaultSessionFile(env),
+        authToken: cli.token ?? nonEmptyString(env.MICA_TOKEN) ?? (options.randomToken ?? generateAuthToken)(),
+        bridgeOnly: cli.bridgeOnly,
+    };
+}
+function parseCliArgs(argv) {
+    const parsed = { bridgeOnly: false };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        switch (arg) {
+            case "--host":
+                parsed.host = readFlagValue(argv, index, arg);
+                index += 1;
+                break;
+            case "--port":
+                parsed.port = parseRequiredPort(readFlagValue(argv, index, arg), arg);
+                index += 1;
+                break;
+            case "--session-file":
+                parsed.sessionFile = readFlagValue(argv, index, arg);
+                index += 1;
+                break;
+            case "--token":
+                parsed.token = readFlagValue(argv, index, arg);
+                index += 1;
+                break;
+            case "--bridge-only":
+                parsed.bridgeOnly = true;
+                break;
+            default:
+                break;
+        }
+    }
+    return parsed;
+}
+function readFlagValue(argv, index, flag) {
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
+}
+function parseOptionalPort(value, source) {
+    if (!value)
+        return undefined;
+    return parseRequiredPort(value, source);
+}
+function parseRequiredPort(value, source) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port <= 0) {
+        throw new Error(`${source} must be a positive integer port`);
+    }
+    return port;
+}
+function nonEmptyString(value) {
+    return value && value.length > 0 ? value : undefined;
+}
+export { DEFAULT_HOST, DEFAULT_PORT };

package/dist/src/runtime/session.js

@@ -0,0 +1,14 @@
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+export async function writeSessionFile(sessionFile, input) {
+    const session = {
+        ...input,
+        baseUrl: `http://${input.host}:${input.port}`,
+        updatedAt: input.updatedAt ?? new Date().toISOString(),
+    };
+    await mkdir(path.dirname(sessionFile), { recursive: true });
+    const tempFile = `${sessionFile}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tempFile, `${JSON.stringify(session, null, 2)}\n`, "utf8");
+    await rename(tempFile, sessionFile);
+    return session;
+}

package/dist/src/runtimeOptions.js

@@ -0,0 +1,3 @@
+export function runtimeModeFromArgs(args) {
+    return args.includes("--bridge-only") ? "bridge-only" : "mcp";
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export const DEFAULT_BRIDGE_HOST = "127.0.0.1";
+export const DEFAULT_BRIDGE_PORT = 19791;

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@aliceshimada/mica",
+  "version": "1.0.0",
+  "description": "Local MCP bridge for controlling live Wolfram Desktop / Mathematica notebooks.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Alice-Shimada/mica.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Alice-Shimada/mica/issues"
+  },
+  "homepage": "https://github.com/Alice-Shimada/mica#readme",
+  "keywords": [
+    "mcp",
+    "wolfram",
+    "mathematica",
+    "notebook",
+    "agent"
+  ],
+  "bin": {
+    "mica": "dist/src/cli/index.js"
+  },
+  "files": [
+    "dist/src",
+    "src/bun/index.ts",
+    "paclet",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "scripts/install.js"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start:mcp": "node dist/src/bun/index.js",
+    "dev:mcp": "tsx src/bun/index.ts",
+    "dev:bridge": "tsx src/bun/index.ts --bridge-only",
+    "dev:bun:mcp": "bun run src/bun/index.ts",
+    "dev:bun": "bun run src/bun/index.ts --bridge-only",
+    "dev:legacy": "tsx src/index.ts --bridge-only",
+    "dev:legacy:mcp": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.13.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT"
+}

package/paclet/FrontEnd/Palettes/MMAAgentBridge.nb

@@ -0,0 +1,22 @@
+Notebook[
+ {
+  Cell[
+   BoxData[
+    ButtonBox[
+     "Open MMA Agent Bridge",
+     ButtonFunction :> (
+       Needs["MMAAgentBridge`"];
+       MMAAgentBridge`StartMMAAgentPalette[]
+     ),
+     Evaluator -> Automatic,
+     Method -> "Queued"
+    ]
+   ],
+   "Input"
+  ]
+ },
+ WindowTitle -> "MMA Agent Bridge Launcher",
+ Saveable -> False,
+ FrontEndVersion -> "13.0 for Microsoft Windows (64-bit) (June 19, 2021)",
+ StyleDefinitions -> "Default.nb"
+]