@aliceshimada/mica 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.0.3 - 2026-06-06
+
+- Deprecate `mica start`, `mica stop`, and `mica restart` commands.
+- `mica start` and bare `mica` (no args) are now aliases for `mica mcp`.
+- `mica mcp` starts an MCP stdio server, proxying to an existing bridge or starting a new one.
+
+## 1.0.2 - 2026-06-06
+
+- Add `mica mcp` command: starts an MCP stdio server that proxies to an existing bridge or starts a new one.
+- Add `/mcp/call` HTTP endpoint for proxied MCP tool execution.
+- Refactor backend tools to export `MICA_BACKEND_TOOL_DEFINITIONS` and `executeBackendMcpTool()` for reuse.
+- Update config snippets to use `mica mcp` instead of `mica start`.
+
 ## 1.0.1 - 2026-06-02
 
 - Implement `mica status`, including dashboard token recovery from the current session.

package/README.md

@@ -77,34 +77,32 @@ mica install
 Then fully quit and restart Wolfram Desktop. Open a notebook, start the MCP server, and connect your MCP client:
 
 ```bash
-mica start
+mica mcp
 ```
 
-Or from a release checkout:
+Or from a release checkout:
 
 ```bash
 git clone https://github.com/Alice-Shimada/mica.git
 cd mica
-npm ci
-npm run build
-node dist/src/cli/index.js install
-```
-
-Then fully quit and restart Wolfram Desktop. Open a notebook, start the MCP server, and connect your MCP client:
-
-```bash
-node dist/src/cli/index.js start
-```
-
-If MICA is installed on your `PATH`, the same release commands are:
-
-```bash
-mica install
-mica start
-mica doctor
-mica status
-mica stop
-mica restart
+npm ci
+npm run build
+node dist/src/cli/index.js install
+```
+
+Then fully quit and restart Wolfram Desktop. Open a notebook, start the MCP server, and connect your MCP client:
+
+```bash
+node dist/src/cli/index.js mcp
+```
+
+If MICA is installed on your `PATH`, the same release commands are:
+
+```bash
+mica install
+mica mcp
+mica doctor
+mica status
 ```
 
 Dashboard:
@@ -124,7 +122,7 @@ node dist/src/cli/index.js install --dry-run
 node dist/src/cli/index.js uninstall
 ```
 
-`mica status` prints the current session file, server URL, version, PID, live agent/notebook counts, and the token-bearing dashboard URL. If a server is already running, `mica start` prints that same status instead of failing with a port-in-use error, so you can recover the dashboard token at any time.
+`mica status` prints the current session file, server URL, version, PID, live agent/notebook counts, and the token-bearing dashboard URL. If a server is already running, `mica mcp` proxies to it instead of failing with a port-in-use error, so you can recover the dashboard token at any time.
 
 The legacy installer entry remains available for compatibility: `node scripts/install.js --dry-run`.
 
@@ -149,7 +147,7 @@ For OpenCode, the snippet uses the validated local MCP shape:
   "mcp": {
     "mica": {
       "type": "local",
-      "command": ["mica", "start"],
+      "command": ["mica", "mcp"],
       "enabled": true
     }
   }
@@ -163,7 +161,7 @@ For manual setup from a local checkout, use the built release entrypoint:
 ```toml
 [mcp_servers.mica]
 command = "node"
-args = ["/absolute/path/to/mica/dist/src/cli/index.js", "start"]
+args = ["/absolute/path/to/mica/dist/src/cli/index.js", "mcp"]
 ```
 
 For development, you can point an MCP client at the TypeScript entrypoint:
@@ -171,7 +169,7 @@ For development, you can point an MCP client at the TypeScript entrypoint:
 ```toml
 [mcp_servers.mica]
 command = "npx"
-args = ["tsx", "/absolute/path/to/mica/src/bun/index.ts"]
+args = ["tsx", "/absolute/path/to/mica/src/cli/index.ts", "mcp"]
 ```
 
 ## Agent Guide Prompt
@@ -302,9 +300,9 @@ The doctor checks Node version, package build, session file, auth token, server
 
 | Doctor output | Likely cause | Action |
 | --- | --- | --- |
-| `FAIL Session file` | Server never started | `mica start` |
+| `FAIL Session file` | Server never started | `mica mcp` |
 | `FAIL Auth token` | Token mismatch or expired | Restart the server |
-| `FAIL Server /status reachable` | Server not running | `mica start` |
+| `FAIL Server /status reachable` | Server not running | `mica mcp` |
 | `FAIL Live agent count: 0` | Wolfram not running or bridge not loaded | Restart Wolfram Desktop after install |
 | `FAIL Live notebook count: 0` | No notebook open or registered | Open a notebook in Wolfram Desktop |
 | `FAIL Kernel/init.m` | Installer not run | `mica install` |

package/README.zh-CN.md

@@ -77,7 +77,7 @@ mica install
 然后完全退出并重启 Wolfram Desktop。打开一个 Notebook，启动 MCP server，并连接你的 MCP client：
 
 ```bash
-mica start
+mica mcp
 ```
 
 或者从发布版 checkout 开始：
@@ -93,18 +93,16 @@ node dist/src/cli/index.js install
 然后完全退出并重启 Wolfram Desktop。打开一个 Notebook，启动 MCP server，并连接你的 MCP client：
 
 ```bash
-node dist/src/cli/index.js start
+node dist/src/cli/index.js mcp
 ```
 
 如果 MICA 已经安装在你的 `PATH` 中，也可以使用等价的发布版命令：
 
 ```bash
 mica install
-mica start
+mica mcp
 mica doctor
 mica status
-mica stop
-mica restart
 ```
 
 Dashboard：
@@ -124,7 +122,7 @@ node dist/src/cli/index.js install --dry-run
 node dist/src/cli/index.js uninstall
 ```
 
-`mica status` 会打印当前 session file、server URL、version、PID、live agent/notebook 数量，以及带 token 的 dashboard URL。如果 server 已经在运行，`mica start` 会打印同样的 status，而不是因为端口占用直接失败；因此你随时可以用它找回 dashboard token。
+`mica status` 会打印当前 session file、server URL、version、PID、live agent/notebook 数量，以及带 token 的 dashboard URL。如果 server 已经在运行，`mica mcp` 会代理到已有后端，而不是因为端口占用直接失败；因此你随时可以用它找回 dashboard token。
 
 兼容用的 legacy 安装入口仍然可用：`node scripts/install.js --dry-run`。
 
@@ -149,7 +147,7 @@ OpenCode 的 snippet 使用经过验证的 local MCP 形状：
   "mcp": {
     "mica": {
       "type": "local",
-      "command": ["mica", "start"],
+      "command": ["mica", "mcp"],
       "enabled": true
     }
   }
@@ -163,7 +161,7 @@ OpenCode 的 snippet 使用经过验证的 local MCP 形状：
 ```toml
 [mcp_servers.mica]
 command = "node"
-args = ["/absolute/path/to/mica/dist/src/cli/index.js", "start"]
+args = ["/absolute/path/to/mica/dist/src/cli/index.js", "mcp"]
 ```
 
 开发时也可以让 MCP client 指向 TypeScript 入口：
@@ -171,7 +169,7 @@ args = ["/absolute/path/to/mica/dist/src/cli/index.js", "start"]
 ```toml
 [mcp_servers.mica]
 command = "npx"
-args = ["tsx", "/absolute/path/to/mica/src/bun/index.ts"]
+args = ["tsx", "/absolute/path/to/mica/src/cli/index.ts", "mcp"]
 ```
 
 ## Agent Guide Prompt
@@ -302,9 +300,9 @@ Doctor 会检查 Node 版本、package build、session file、auth token、serve
 
 | Doctor output | 可能原因 | 操作 |
 | --- | --- | --- |
-| `FAIL Session file` | Server 尚未启动 | `mica start` |
+| `FAIL Session file` | Server 尚未启动 | `mica mcp` |
 | `FAIL Auth token` | Token 不匹配或已过期 | 重启 server |
-| `FAIL Server /status reachable` | Server 未运行 | `mica start` |
+| `FAIL Server /status reachable` | Server 未运行 | `mica mcp` |
 | `FAIL Live agent count: 0` | Wolfram 未运行或 bridge 未加载 | 安装后重启 Wolfram Desktop |
 | `FAIL Live notebook count: 0` | 没有打开或注册的 Notebook | 在 Wolfram Desktop 中打开 Notebook |
 | `FAIL Kernel/init.m` | 尚未运行安装器 | `mica install` |

package/dist/src/bun/httpServer.js

@@ -1,8 +1,9 @@
 import { timingSafeEqual } from "node:crypto";
 import http from "node:http";
+import { executeBackendMcpTool } from "../mcp/backendTools.js";
 import { renderDashboard } from "./dashboard.js";
 const JSON_BODY_LIMIT_BYTES = 1024 * 1024;
-const DEFAULT_VERSION = "1.0.1";
+const DEFAULT_VERSION = "1.0.3";
 export async function createBunHttpApp({ state, host = "127.0.0.1", port, authToken, version = DEFAULT_VERSION }) {
     const runtimeInfo = {
         host,
@@ -66,6 +67,14 @@ export function createFetchHandler(state, options = {}) {
                     requests: summarizeRequests(state.queue.snapshot()),
                 });
             }
+            if (request.method === "POST" && url.pathname === "/mcp/call") {
+                const body = await readJsonObjectBody(request);
+                const tool = readRequiredString(body.tool, "tool");
+                const args = readOptionalRecord(body.arguments) ?? {};
+                const clientSessionId = readOptionalString(body.clientSessionId);
+                const result = await executeBackendMcpTool(state, tool, args, { sessionId: clientSessionId });
+                return jsonResponse(result);
+            }
             if (request.method === "POST" && url.pathname === "/agents/register") {
                 const body = await readJsonObjectBody(request);
                 const agentSessionId = readRequiredString(body.agentSessionId, "agentSessionId");
@@ -213,6 +222,8 @@ async function startNodeFallbackServer(fetchHandler, host, port) {
             await writeNodeResponse(outgoing, jsonResponse({ error: { code: "INTERNAL_ERROR", message } }, 500));
         }
     });
+    server.timeout = 0;
+    server.requestTimeout = 0;
     await new Promise((resolve, reject) => {
         server.once("error", reject);
         server.listen(port, host, () => {
@@ -313,6 +324,13 @@ function readOptionalString(value) {
     const text = value.trim();
     return text ? text : undefined;
 }
+function readOptionalRecord(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("BAD_REQUEST");
+    return value;
+}
 function readOptionalNumber(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }

package/dist/src/bun/index.js

@@ -8,7 +8,7 @@ import { loadRuntimeConfig } from "../runtime/config.js";
 import { writeSessionFile } from "../runtime/session.js";
 import { createBunHttpApp } from "./httpServer.js";
 const MCP_SERVER_NAME = "mica-bun";
-const MICA_PACKAGE_VERSION = "1.0.1";
+const MICA_PACKAGE_VERSION = "1.0.3";
 export async function startBunRuntime(deps = {}) {
     const config = deps.runtimeConfig ?? loadRuntimeConfig();
     const bridgeOnly = deps.bridgeOnly ?? config.bridgeOnly;

package/dist/src/cli/configSnippets.js

@@ -8,7 +8,7 @@ export function runConfigCommand(argv) {
         };
     }
     if (client === "codex") {
-        return ok(`[mcp_servers.mica]\ncommand = "mica"\nargs = ["start"]\n`);
+        return ok(`[mcp_servers.mica]\ncommand = "mica"\nargs = ["mcp"]\n`);
     }
     if (client === "opencode") {
         return ok(`${JSON.stringify({
@@ -16,7 +16,7 @@ export function runConfigCommand(argv) {
             mcp: {
                 mica: {
                     type: "local",
-                    command: ["mica", "start"],
+                    command: ["mica", "mcp"],
                     enabled: true,
                 },
             },
@@ -26,7 +26,7 @@ export function runConfigCommand(argv) {
         mcpServers: {
             mica: {
                 command: "mica",
-                args: ["start"],
+                args: ["mcp"],
             },
         },
     }, null, 2)}\n`);

package/dist/src/cli/index.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { startBunRuntime } from "../bun/index.js";
+import { createMicaMcpServer, registerMicaPrompts } from "../mcp/prompts.js";
+import { registerProxyMcpTools } from "../mcp/proxyTools.js";
+import { defaultSessionFile } from "../runtime/config.js";
 import { runConfigCommand } from "./configSnippets.js";
 import { runDoctor } from "./doctor.js";
 import { runStatusCommand } from "./status.js";
-import { runStopCommand } from "./stop.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -20,6 +23,57 @@ function resolveProjectRoot() {
     }
     return dir;
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isAddressInUse(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const record = error;
+    return record.code === "EADDRINUSE" || String(record.message ?? "").includes("EADDRINUSE");
+}
+function sessionFileFromArgs(argv, env = process.env) {
+    const index = argv.indexOf("--session-file");
+    if (index >= 0 && argv[index + 1] && !argv[index + 1].startsWith("--")) {
+        return argv[index + 1];
+    }
+    return env.MICA_SESSION_FILE ?? defaultSessionFile(env);
+}
+export async function readLiveSession(argv = [], deps = {}) {
+    const env = deps.env ?? process.env;
+    const exists = deps.exists ?? existsSync;
+    const readFile = deps.readFile ?? ((filePath) => readFileSync(filePath, "utf8"));
+    const fetchImpl = deps.fetch ?? globalThis.fetch;
+    const sessionFile = sessionFileFromArgs(argv, env);
+    if (!exists(sessionFile) || typeof fetchImpl !== "function")
+        return undefined;
+    let session;
+    try {
+        session = JSON.parse(readFile(sessionFile));
+    }
+    catch {
+        return undefined;
+    }
+    if (!session.baseUrl || !session.authToken)
+        return undefined;
+    try {
+        const response = await fetchImpl(`${session.baseUrl}/status`, {
+            headers: { authorization: `Bearer ${session.authToken}` },
+        });
+        return response.status === 200 ? { baseUrl: session.baseUrl, authToken: session.authToken } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function startProxyMcpRuntime(session, deps = {}) {
+    const server = deps.createMcpServer?.() ?? createMicaMcpServer("mica-proxy");
+    registerProxyMcpTools(server, session);
+    registerMicaPrompts(server);
+    const transport = deps.createTransport?.() ?? new StdioServerTransport();
+    await server.connect(transport);
+    return { keepAlive: new Promise(() => { }) };
+}
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -27,9 +81,7 @@ export function helpText() {
     return `Usage: mica <command> [options]
 
 Commands:
-  start                   Start the MICA bridge runtime (default)
-  stop                    Stop the running MICA bridge runtime
-  restart                 Stop then start the MICA bridge runtime
+  mcp                     Run MCP stdio server (proxy to existing bridge or launch new)
   install [options]       Install MICA bridge into Wolfram
   uninstall [options]     Uninstall MICA bridge from Wolfram
   doctor                  Diagnose MICA bridge configuration
@@ -52,7 +104,9 @@ export async function runCli(argv, deps) {
     const _runDoctor = deps?.runDoctor;
     const _runStatus = deps?.runStatus;
     const _runConfig = deps?.runConfig;
-    const _runStop = deps?.runStop;
+    const _readLiveSession = deps?.readLiveSession ?? (() => readLiveSession(argv.slice(1)));
+    const _startProxyRuntime = deps?.startProxyRuntime ?? ((session) => startProxyMcpRuntime(session));
+    const _sleep = deps?.sleep ?? sleep;
     const command = argv[0];
     // --help / -h
     if (command === "--help" || command === "-h") {
@@ -79,22 +133,39 @@ export async function runCli(argv, deps) {
         stdout.write(output);
         return 0;
     }
-    // start or no args
-    if (command === "start" || command === undefined) {
-        if (_runStatus) {
-            const status = await _runStatus();
-            if (status.running) {
-                stdout.write(status.output);
-                return status.exitCode;
-            }
+    // mcp (also start, or no args)
+    if (command === "mcp" || command === "start" || command === undefined) {
+        const existingSession = await _readLiveSession();
+        if (existingSession) {
+            const proxyRuntime = await _startProxyRuntime(existingSession);
+            await proxyRuntime.keepAlive;
+            return 0;
         }
         if (!startRuntime) {
             stderr.write("Error: startRuntime not available\n");
             return 1;
         }
-        const runtime = await startRuntime();
-        await runtime.keepAlive;
-        return 0;
+        try {
+            const runtime = await startRuntime();
+            await runtime.keepAlive;
+            return 0;
+        }
+        catch (error) {
+            if (!isAddressInUse(error))
+                throw error;
+            for (let attempt = 0; attempt < 20; attempt += 1) {
+                await _sleep(100);
+                const racedSession = await _readLiveSession();
+                if (racedSession) {
+                    const proxyRuntime = await _startProxyRuntime(racedSession);
+                    await proxyRuntime.keepAlive;
+                    return 0;
+                }
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            stderr.write(`Error: MICA bridge port is already in use, but no live session became available. ${message}\n`);
+            return 1;
+        }
     }
     // doctor
     if (command === "doctor") {
@@ -126,33 +197,6 @@ export async function runCli(argv, deps) {
         stdout.write(output);
         return exitCode;
     }
-    // stop
-    if (command === "stop") {
-        if (!_runStop) {
-            stderr.write("Error: runStop not available\n");
-            return 1;
-        }
-        const { exitCode, output } = await _runStop();
-        stdout.write(output);
-        return exitCode;
-    }
-    // restart
-    if (command === "restart") {
-        if (!_runStop) {
-            stderr.write("Error: runStop not available\n");
-            return 1;
-        }
-        if (!startRuntime) {
-            stderr.write("Error: startRuntime not available\n");
-            return 1;
-        }
-        const stopResult = await _runStop();
-        if (stopResult.output)
-            stdout.write(stopResult.output);
-        const runtime = await startRuntime();
-        await runtime.keepAlive;
-        return 0;
-    }
     // Unknown command
     stderr.write(`Unknown command: ${command}\n`);
     return 1;
@@ -166,10 +210,11 @@ async function main() {
     const { runInstaller, detectWolframUserBase } = (await import(installerUrl));
     const exitCode = await runCli(process.argv.slice(2), {
         startRuntime: async () => startBunRuntime(),
+        startProxyRuntime: async (session) => startProxyMcpRuntime(session),
+        readLiveSession: async () => readLiveSession(process.argv.slice(3)),
         runInstaller,
         runStatus: async () => runStatusCommand(),
         runConfig: runConfigCommand,
-        runStop: async () => runStopCommand(),
         runDoctor: async () => runDoctor({
             projectRoot,
             detectWolframUserBase: () => detectWolframUserBase(),

package/dist/src/cli/status.js

@@ -14,7 +14,7 @@ export async function runStatusCommand(deps = {}) {
     const ok = (label, detail) => lines.push(`OK   ${label}: ${detail}`);
     if (!_exists(sessionFile)) {
         fail("Session file", `${sessionFile} (not found)`);
-        lines.push("FIX  Run: mica start");
+        lines.push("FIX  Run: mica mcp");
         return result(1, lines, false);
     }
     let session;
@@ -23,7 +23,7 @@ export async function runStatusCommand(deps = {}) {
     }
     catch (error) {
         fail("Session file", error instanceof Error ? error.message : String(error));
-        lines.push("FIX  Run: mica start");
+        lines.push("FIX  Run: mica mcp");
         return result(1, lines, false);
     }
     const baseUrl = session.baseUrl ?? `http://${session.host ?? "127.0.0.1"}:${session.port ?? 19791}`;
@@ -31,7 +31,7 @@ export async function runStatusCommand(deps = {}) {
     ok("Session target", baseUrl);
     if (!session.authToken) {
         fail("Auth token", "missing in session file");
-        lines.push("FIX  Restart MICA with: mica start");
+        lines.push("FIX  Restart MICA with: mica mcp");
         return result(1, lines, false);
     }
     if (!_fetch) {
@@ -44,12 +44,12 @@ export async function runStatusCommand(deps = {}) {
         });
         if (response.status === 401) {
             fail("Auth token", "401 Unauthorized");
-            lines.push("FIX  Restart MICA with: mica start");
+            lines.push("FIX  Restart MICA with: mica mcp");
             return result(1, lines, false);
         }
         if (response.status !== 200) {
             fail("Server /status reachable", `HTTP ${response.status}`);
-            lines.push("FIX  Run: mica start");
+            lines.push("FIX  Run: mica mcp");
             return result(1, lines, false);
         }
         const body = (await response.json());
@@ -67,7 +67,7 @@ export async function runStatusCommand(deps = {}) {
     }
     catch (error) {
         fail("Server /status reachable", error instanceof Error ? error.message : String(error));
-        lines.push("FIX  Run: mica start");
+        lines.push("FIX  Run: mica mcp");
         return result(1, lines, false);
     }
 }

package/dist/src/mcp/backendTools.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { DEFAULT_TIMEOUTS_MS } from "../backend/protocol.js";
 import { abortEvaluationSchema, deleteCellSchema, getCellOutputSchema, insertCellSchema, listCellsSchema, modifyCellSchema, noArgsSchema, readArtifactSchema, readCellSchema, runCellSchema, selectNotebookSchema, saveNotebookSchema, symbolLookupSchema, } from "./toolSchemas.js";
 import { INSERT_ANCHOR_GUIDANCE, notebookToolDescription } from "./descriptions.js";
-import { toolSuccess, withToolErrors } from "./toolResults.js";
+import { toolFailure, toolSuccess, withToolErrors } from "./toolResults.js";
 function assertLiveAgent(state) {
     if (!state.requireLiveAgent().ok) {
         throw new Error("NO_LIVE_AGENT");
@@ -75,26 +75,121 @@ function ensurePermission(notebook, tool, permission) {
         throw new Error(`PERMISSION_DENIED: ${tool}`);
     }
 }
-function registerQueuedNotebookTool(server, state, 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 }, async () => {
-            if (process.env.MICA_STRICT_TARGETING === "1" && config.requiresExplicitTarget) {
-                const hasNotebookId = typeof recordArgs.notebookId === "string" && recordArgs.notebookId.trim().length > 0;
-                const hasDisplayName = typeof recordArgs.displayName === "string" && recordArgs.displayName.trim().length > 0;
-                if (!hasNotebookId && !hasDisplayName) {
-                    throw new Error("EXPLICIT_NOTEBOOK_REQUIRED");
-                }
-            }
-            const target = resolveToolTarget(state, recordArgs, extra);
-            ensurePermission(target.notebook, config.name, config.permission);
-            return queueNotebookOperation(state, target, config.name, recordArgs, config.timeoutMs(recordArgs), extra);
-        });
-    });
-}
-export function registerBackendMcpTools(server, state) {
-    server.tool("mma_status", notebookToolDescription("Report backend status and notebook registry state."), noArgsSchema.shape, async (_args, extra) => {
-        return withToolErrors({ tool: "mma_status" }, () => {
+const queuedNotebookTools = [
+    {
+        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,
+        permission: "ReadNotebook",
+        timeoutMs: () => DEFAULT_TIMEOUTS_MS.symbolLookup,
+    },
+    {
+        name: "mma_list_cells",
+        summary: "List cells in the attached active Mathematica notebook.",
+        schema: listCellsSchema.shape,
+        permission: "ReadNotebook",
+        timeoutMs: () => DEFAULT_TIMEOUTS_MS.listCells,
+    },
+    {
+        name: "mma_read_cell",
+        summary: "Read one cell from the attached Mathematica notebook.",
+        schema: readCellSchema.shape,
+        permission: "ReadNotebook",
+        timeoutMs: () => DEFAULT_TIMEOUTS_MS.readCell,
+    },
+    {
+        name: "mma_insert_cell",
+        summary: "Insert a cell through the Mathematica FrontEnd bridge.",
+        schema: insertCellSchema.shape,
+        permission: "InsertCell",
+        timeoutMs: () => DEFAULT_TIMEOUTS_MS.insertCell,
+        extraGuidance: INSERT_ANCHOR_GUIDANCE,
+        requiresExplicitTarget: true,
+    },
+    {
+        name: "mma_modify_cell",
+        summary: "Modify one existing cell through the Mathematica FrontEnd bridge.",
+        schema: modifyCellSchema.shape,
+        permission: "ModifyCell",
+        timeoutMs: () => DEFAULT_TIMEOUTS_MS.mutation,
+        requiresExplicitTarget: true,
+    },
+    {
+        name: "mma_delete_cell",
+        summary: "Delete one cell through the Mathematica FrontEnd bridge.",
+        schema: deleteCellSchema.shape,
+        permission: "DeleteCell",
+        timeoutMs: () => DEFAULT_TIMEOUTS_MS.mutation,
+        requiresExplicitTarget: true,
+    },
+    {
+        name: "mma_run_cell",
+        summary: "Run one cell in the attached Mathematica notebook.",
+        schema: runCellSchema.shape,
+        permission: "RunCell",
+        timeoutMs: (args) => {
+            const timeoutSec = typeof args.timeoutSec === "number" ? args.timeoutSec : 120;
+            return timeoutSec * 1000;
+        },
+        requiresExplicitTarget: true,
+    },
+    {
+        name: "mma_abort_evaluation",
+        summary: "Abort the running Wolfram evaluation in the attached notebook.",
+        schema: abortEvaluationSchema.shape,
+        permission: "RunCell",
+        timeoutMs: () => DEFAULT_TIMEOUTS_MS.mutation,
+        requiresExplicitTarget: true,
+    },
+    {
+        name: "mma_get_cell_output",
+        summary: "Read output and messages for one Mathematica notebook cell, refreshing completed run status when observed.",
+        schema: getCellOutputSchema.shape,
+        permission: "ReadNotebook",
+        timeoutMs: () => DEFAULT_TIMEOUTS_MS.readCell,
+    },
+    {
+        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,
+        permission: "ReadNotebook",
+        timeoutMs: () => DEFAULT_TIMEOUTS_MS.readCell,
+    },
+    {
+        name: "mma_save_notebook",
+        summary: "Save the attached Mathematica notebook through the FrontEnd.",
+        schema: saveNotebookSchema.shape,
+        permission: "SaveNotebook",
+        timeoutMs: () => DEFAULT_TIMEOUTS_MS.mutation,
+        requiresExplicitTarget: true,
+    },
+];
+export const MICA_BACKEND_TOOL_DEFINITIONS = [
+    {
+        name: "mma_status",
+        description: notebookToolDescription("Report backend status and notebook registry state."),
+        schema: noArgsSchema.shape,
+    },
+    {
+        name: "mma_list_notebooks",
+        description: notebookToolDescription("List notebooks registered with the Mathematica bridge Palette."),
+        schema: noArgsSchema.shape,
+    },
+    {
+        name: "mma_select_notebook",
+        description: notebookToolDescription("Select the active Mathematica notebook in the backend registry."),
+        schema: selectNotebookSchema.shape,
+    },
+    ...queuedNotebookTools.map((config) => ({
+        name: config.name,
+        description: notebookToolDescription(config.summary, config.extraGuidance),
+        schema: config.schema,
+    })),
+];
+export async function executeBackendMcpTool(state, tool, args = {}, extra) {
+    const recordArgs = args && typeof args === "object" && !Array.isArray(args) ? args : {};
+    if (tool === "mma_status") {
+        return withToolErrors({ tool }, () => {
             sweepStateLiveness(state);
             return toolSuccess({
                 server: "running",
@@ -103,16 +198,15 @@ export function registerBackendMcpTools(server, state) {
                 agents: liveAgents(state),
             });
         });
-    });
-    server.tool("mma_list_notebooks", notebookToolDescription("List notebooks registered with the Mathematica bridge Palette."), noArgsSchema.shape, async (_args, extra) => {
-        return withToolErrors({ tool: "mma_list_notebooks" }, () => {
+    }
+    if (tool === "mma_list_notebooks") {
+        return withToolErrors({ tool }, () => {
             sweepStateLiveness(state);
             return toolSuccess({ notebooks: state.notebooks.listLive(), activeNotebookId: liveActiveNotebookId(state, extra?.sessionId) });
         });
-    });
-    server.tool("mma_select_notebook", notebookToolDescription("Select the active Mathematica notebook in the backend registry."), selectNotebookSchema.shape, async (args, extra) => {
-        const recordArgs = args;
-        return withToolErrors({ tool: "mma_select_notebook", args: recordArgs }, () => {
+    }
+    if (tool === "mma_select_notebook") {
+        return withToolErrors({ tool, args: recordArgs }, () => {
             const clientSessionId = extra?.sessionId;
             const target = resolveToolTarget(state, recordArgs, extra);
             state.setActiveNotebook(target.notebook.notebookId);
@@ -120,97 +214,26 @@ export function registerBackendMcpTools(server, state) {
                 state.setActiveNotebook(target.notebook.notebookId, clientSessionId);
             return toolSuccess({ activeNotebookId: state.activeNotebookId, notebook: target.notebook });
         });
+    }
+    const queuedConfig = queuedNotebookTools.find((config) => config.name === tool);
+    if (!queuedConfig) {
+        return toolFailure(new Error(`UNKNOWN_TOOL: ${tool}`), { tool, args: recordArgs });
+    }
+    return withToolErrors({ tool: queuedConfig.name, args: recordArgs }, async () => {
+        if (process.env.MICA_STRICT_TARGETING === "1" && queuedConfig.requiresExplicitTarget) {
+            const hasNotebookId = typeof recordArgs.notebookId === "string" && recordArgs.notebookId.trim().length > 0;
+            const hasDisplayName = typeof recordArgs.displayName === "string" && recordArgs.displayName.trim().length > 0;
+            if (!hasNotebookId && !hasDisplayName) {
+                throw new Error("EXPLICIT_NOTEBOOK_REQUIRED");
+            }
+        }
+        const target = resolveToolTarget(state, recordArgs, extra);
+        ensurePermission(target.notebook, queuedConfig.name, queuedConfig.permission);
+        return queueNotebookOperation(state, target, queuedConfig.name, recordArgs, queuedConfig.timeoutMs(recordArgs), extra);
     });
-    const queuedNotebookTools = [
-        {
-            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,
-            permission: "ReadNotebook",
-            timeoutMs: () => DEFAULT_TIMEOUTS_MS.symbolLookup,
-        },
-        {
-            name: "mma_list_cells",
-            summary: "List cells in the attached active Mathematica notebook.",
-            schema: listCellsSchema.shape,
-            permission: "ReadNotebook",
-            timeoutMs: () => DEFAULT_TIMEOUTS_MS.listCells,
-        },
-        {
-            name: "mma_read_cell",
-            summary: "Read one cell from the attached Mathematica notebook.",
-            schema: readCellSchema.shape,
-            permission: "ReadNotebook",
-            timeoutMs: () => DEFAULT_TIMEOUTS_MS.readCell,
-        },
-        {
-            name: "mma_insert_cell",
-            summary: "Insert a cell through the Mathematica FrontEnd bridge.",
-            schema: insertCellSchema.shape,
-            permission: "InsertCell",
-            timeoutMs: () => DEFAULT_TIMEOUTS_MS.insertCell,
-            extraGuidance: INSERT_ANCHOR_GUIDANCE,
-            requiresExplicitTarget: true,
-        },
-        {
-            name: "mma_modify_cell",
-            summary: "Modify one existing cell through the Mathematica FrontEnd bridge.",
-            schema: modifyCellSchema.shape,
-            permission: "ModifyCell",
-            timeoutMs: () => DEFAULT_TIMEOUTS_MS.mutation,
-            requiresExplicitTarget: true,
-        },
-        {
-            name: "mma_delete_cell",
-            summary: "Delete one cell through the Mathematica FrontEnd bridge.",
-            schema: deleteCellSchema.shape,
-            permission: "DeleteCell",
-            timeoutMs: () => DEFAULT_TIMEOUTS_MS.mutation,
-            requiresExplicitTarget: true,
-        },
-        {
-            name: "mma_run_cell",
-            summary: "Run one cell in the attached Mathematica notebook.",
-            schema: runCellSchema.shape,
-            permission: "RunCell",
-            timeoutMs: (args) => {
-                const timeoutSec = typeof args.timeoutSec === "number" ? args.timeoutSec : 120;
-                return timeoutSec * 1000;
-            },
-            requiresExplicitTarget: true,
-        },
-        {
-            name: "mma_abort_evaluation",
-            summary: "Abort the running Wolfram evaluation in the attached notebook.",
-            schema: abortEvaluationSchema.shape,
-            permission: "RunCell",
-            timeoutMs: () => DEFAULT_TIMEOUTS_MS.mutation,
-            requiresExplicitTarget: true,
-        },
-        {
-            name: "mma_get_cell_output",
-            summary: "Read output and messages for one Mathematica notebook cell, refreshing completed run status when observed.",
-            schema: getCellOutputSchema.shape,
-            permission: "ReadNotebook",
-            timeoutMs: () => DEFAULT_TIMEOUTS_MS.readCell,
-        },
-        {
-            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,
-            permission: "ReadNotebook",
-            timeoutMs: () => DEFAULT_TIMEOUTS_MS.readCell,
-        },
-        {
-            name: "mma_save_notebook",
-            summary: "Save the attached Mathematica notebook through the FrontEnd.",
-            schema: saveNotebookSchema.shape,
-            permission: "SaveNotebook",
-            timeoutMs: () => DEFAULT_TIMEOUTS_MS.mutation,
-            requiresExplicitTarget: true,
-        },
-    ];
-    for (const config of queuedNotebookTools) {
-        registerQueuedNotebookTool(server, state, config);
+}
+export function registerBackendMcpTools(server, state) {
+    for (const definition of MICA_BACKEND_TOOL_DEFINITIONS) {
+        server.tool(definition.name, definition.description, definition.schema, (args, extra) => executeBackendMcpTool(state, definition.name, args, extra));
     }
 }

package/dist/src/mcp/prompts.js

@@ -33,7 +33,7 @@ export const MICA_AGENT_INSTRUCTIONS = [
     "Tools:",
     ...TOOL_GUIDE.map(([name, description]) => `- ${name}: ${description}`),
 ].join("\n");
-export function createMicaMcpServer(name, version = "1.0.1") {
+export function createMicaMcpServer(name, version = "1.0.3") {
     return new McpServer({ name, version }, { instructions: MICA_AGENT_INSTRUCTIONS });
 }
 export function registerMicaPrompts(server) {

package/dist/src/mcp/proxyTools.js

@@ -0,0 +1,36 @@
+import { MICA_BACKEND_TOOL_DEFINITIONS } from "./backendTools.js";
+import { toolFailure } from "./toolResults.js";
+export function registerProxyMcpTools(server, session, deps = {}) {
+    for (const definition of MICA_BACKEND_TOOL_DEFINITIONS) {
+        server.tool(definition.name, definition.description, definition.schema, async (args, extra) => {
+            return callProxyTool(session, definition.name, args, extra, deps);
+        });
+    }
+}
+async function callProxyTool(session, tool, args, extra, deps) {
+    const fetchImpl = deps.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+        return toolFailure(new Error("FETCH_UNAVAILABLE"), { tool, args });
+    }
+    try {
+        const response = await fetchImpl(`${session.baseUrl}/mcp/call`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${session.authToken}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                tool,
+                arguments: args ?? {},
+                ...(extra?.sessionId ? { clientSessionId: extra.sessionId } : {}),
+            }),
+        });
+        if (!response.ok) {
+            return toolFailure(new Error(`MCP_PROXY_HTTP_${response.status}`), { tool, args });
+        }
+        return (await response.json());
+    }
+    catch (error) {
+        return toolFailure(error, { tool, args });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliceshimada/mica",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Local MCP bridge for controlling live Wolfram Desktop / Mathematica notebooks.",
   "type": "module",
   "repository": {
@@ -23,7 +23,6 @@
   },
   "files": [
     "dist/src",
-    "src/bun/index.ts",
     "paclet",
     "README.md",
     "README.zh-CN.md",

package/src/bun/index.ts

@@ -1,120 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { randomUUID } from "node:crypto";
-import { pathToFileURL } from "node:url";
-import { BackendState } from "../backend/backendState.js";
-import { registerBackendMcpTools } from "../mcp/backendTools.js";
-import { createMicaMcpServer, registerMicaPrompts } from "../mcp/prompts.js";
-import type { MicaRuntimeConfig } from "../runtime/config.js";
-import { loadRuntimeConfig } from "../runtime/config.js";
-import { writeSessionFile } from "../runtime/session.js";
-import { createBunHttpApp } from "./httpServer.js";
-
-const MCP_SERVER_NAME = "mica-bun";
-const MICA_PACKAGE_VERSION = "1.0.1";
-
-export type BunRuntimeDeps = {
-  bridgeOnly?: boolean;
-  createHttpApp?: typeof createBunHttpApp;
-  createMcpServer?: () => Pick<McpServer, "connect" | "prompt" | "tool">;
-  createTransport?: () => StdioServerTransport;
-  installSignalHandlers?: (onSignal: (signal: NodeJS.Signals) => void) => () => void;
-  runtimeConfig?: MicaRuntimeConfig;
-  state?: BackendState;
-  version?: string;
-  writeSessionFile?: typeof writeSessionFile;
-};
-
-export type BunRuntime = {
-  state: BackendState;
-  httpApp: Awaited<ReturnType<typeof createBunHttpApp>>;
-  stop: () => Promise<void>;
-  keepAlive: Promise<void>;
-};
-
-export async function startBunRuntime(deps: BunRuntimeDeps = {}): Promise<BunRuntime> {
-  const config = deps.runtimeConfig ?? loadRuntimeConfig();
-  const bridgeOnly = deps.bridgeOnly ?? config.bridgeOnly;
-  const state = deps.state ?? new BackendState(() => `notebook-${randomUUID()}`);
-  const createHttpApp = deps.createHttpApp ?? createBunHttpApp;
-  const createMcpServer = deps.createMcpServer ?? (() => createMicaMcpServer(MCP_SERVER_NAME));
-  const createTransport = deps.createTransport ?? (() => new StdioServerTransport());
-  const writeSession = deps.writeSessionFile ?? writeSessionFile;
-  const version = deps.version ?? MICA_PACKAGE_VERSION;
-  const installSignalHandlers =
-    deps.installSignalHandlers ??
-    ((onSignal: (signal: NodeJS.Signals) => void) => {
-      process.once("SIGINT", onSignal);
-      process.once("SIGTERM", onSignal);
-      return () => {
-        process.off("SIGINT", onSignal);
-        process.off("SIGTERM", onSignal);
-      };
-    });
-  const httpApp = await createHttpApp({ state, host: config.host, port: config.preferredPort, authToken: config.authToken, version });
-  let cleanupSignals = () => {};
-  let stopped = false;
-  let stopPromise: Promise<void> | undefined;
-
-  const stop = async (): Promise<void> => {
-    if (stopPromise) return stopPromise;
-    stopPromise = (async () => {
-      if (stopped) return;
-      stopped = true;
-      cleanupSignals();
-      await httpApp.stop();
-    })();
-    return stopPromise;
-  };
-
-  const onSignal = (signal: NodeJS.Signals) => {
-    void stop().finally(() => process.exit(0));
-  };
-
-  try {
-    cleanupSignals = installSignalHandlers(onSignal);
-    await writeSession(config.sessionFile, {
-      host: config.host,
-      port: httpApp.port,
-      authToken: config.authToken,
-      pid: process.pid,
-      version,
-      status: "running",
-    });
-    const server = createMcpServer();
-    registerBackendMcpTools(server as McpServer, state);
-    registerMicaPrompts(server);
-
-    console.error(`Bun HTTP server listening on http://${config.host}:${httpApp.port}`);
-    console.error(`Dashboard: http://${config.host}:${httpApp.port}/#token=${config.authToken}`);
-    if (!bridgeOnly) {
-      console.error("Bun MCP mode enabled; connecting stdio transport.");
-      await server.connect(createTransport());
-    }
-  } catch (error) {
-    await stop();
-    throw error;
-  }
-
-  return {
-    state,
-    httpApp,
-    stop,
-    keepAlive: new Promise<void>(() => {})
-  };
-}
-
-async function main(): Promise<void> {
-  const runtime = await startBunRuntime();
-  await runtime.keepAlive;
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  main().catch((error) => {
-    const message = error instanceof Error ? error.stack ?? error.message : String(error);
-    console.error(message);
-    process.exitCode = 1;
-  });
-}
-
-export { MCP_SERVER_NAME };