@aliceshimada/mica 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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.
+- Implement `mica config codex|claude-desktop|cursor|opencode` snippets.
+- Add `mica stop` and `mica restart`.
+- Make `mica start` print current status instead of failing when a server is already running.
+
 ## 1.0.0 - 2026-06-02
 
 - Initial public release as `@aliceshimada/mica`.

package/README.md

@@ -102,6 +102,9 @@ If MICA is installed on your `PATH`, the same release commands are:
 mica install
 mica start
 mica doctor
+mica status
+mica stop
+mica restart
 ```
 
 Dashboard:
@@ -121,16 +124,46 @@ 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.
+
 The legacy installer entry remains available for compatibility: `node scripts/install.js --dry-run`.
 
 ## MCP Client Config
 
-Use the built release entrypoint from your local checkout:
+Print a copy-pasteable MCP config snippet:
+
+```bash
+mica config codex
+mica config claude-desktop
+mica config cursor
+mica config opencode
+```
+
+MICA only prints snippets; it does not edit client config files for you.
+
+For OpenCode, the snippet uses the validated local MCP shape:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "mica": {
+      "type": "local",
+      "command": ["mica", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+When editing OpenCode config, restart OpenCode after saving; config is loaded at startup.
+
+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:
@@ -138,7 +171,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

package/README.zh-CN.md

@@ -102,6 +102,9 @@ node dist/src/cli/index.js start
 mica install
 mica start
 mica doctor
+mica status
+mica stop
+mica restart
 ```
 
 Dashboard：
@@ -121,16 +124,46 @@ 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。
+
 兼容用的 legacy 安装入口仍然可用：`node scripts/install.js --dry-run`。
 
 ## MCP Client 配置
 
-使用本地 checkout 中构建后的发布版入口：
+打印可复制的 MCP config snippet：
+
+```bash
+mica config codex
+mica config claude-desktop
+mica config cursor
+mica config opencode
+```
+
+MICA 只打印配置片段，不会替你编辑 client config 文件。
+
+OpenCode 的 snippet 使用经过验证的 local MCP 形状：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "mica": {
+      "type": "local",
+      "command": ["mica", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+编辑 OpenCode config 后需要重启 OpenCode；config 只在启动时加载。
+
+如果要从本地 checkout 手动设置，请使用构建后的发布版入口：
 
 ```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 入口：
@@ -138,7 +171,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

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 = "0.1.0";
+const DEFAULT_VERSION = "1.0.2";
 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 = "0.1.0";
+const MICA_PACKAGE_VERSION = "1.0.2";
 export async function startBunRuntime(deps = {}) {
     const config = deps.runtimeConfig ?? loadRuntimeConfig();
     const bridgeOnly = deps.bridgeOnly ?? config.bridgeOnly;

package/dist/src/cli/configSnippets.js

@@ -0,0 +1,36 @@
+const CLIENTS = ["codex", "claude-desktop", "cursor", "opencode"];
+export function runConfigCommand(argv) {
+    const client = argv[0];
+    if (!client || !CLIENTS.includes(client)) {
+        return {
+            exitCode: 1,
+            output: `Usage: mica config <${CLIENTS.join("|")}>\n`,
+        };
+    }
+    if (client === "codex") {
+        return ok(`[mcp_servers.mica]\ncommand = "mica"\nargs = ["mcp"]\n`);
+    }
+    if (client === "opencode") {
+        return ok(`${JSON.stringify({
+            $schema: "https://opencode.ai/config.json",
+            mcp: {
+                mica: {
+                    type: "local",
+                    command: ["mica", "mcp"],
+                    enabled: true,
+                },
+            },
+        }, null, 2)}\n`);
+    }
+    return ok(`${JSON.stringify({
+        mcpServers: {
+            mica: {
+                command: "mica",
+                args: ["mcp"],
+            },
+        },
+    }, null, 2)}\n`);
+}
+function ok(output) {
+    return { exitCode: 0, output };
+}

package/dist/src/cli/index.js

@@ -1,9 +1,16 @@
 #!/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
 // ---------------------------------------------------------------------------
@@ -17,6 +24,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
 // ---------------------------------------------------------------------------
@@ -25,6 +83,9 @@ export function helpText() {
 
 Commands:
   start                   Start the MICA bridge runtime (default)
+  stop                    Stop the running MICA bridge runtime
+  restart                 Stop then start the MICA bridge runtime
+  mcp                     Start MCP stdio server; proxy to an existing bridge if possible
   install [options]       Install MICA bridge into Wolfram
   uninstall [options]     Uninstall MICA bridge from Wolfram
   doctor                  Diagnose MICA bridge configuration
@@ -32,6 +93,7 @@ Commands:
   config codex            Configure for Codex
   config claude-desktop   Configure for Claude Desktop
   config cursor           Configure for Cursor
+  config opencode         Configure for OpenCode
 
 Options:
   --help, -h              Show this help message
@@ -44,6 +106,12 @@ export async function runCli(argv, deps) {
     const startRuntime = deps?.startRuntime;
     const runInstaller = deps?.runInstaller;
     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") {
@@ -72,6 +140,13 @@ export async function runCli(argv, deps) {
     }
     // 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;
+            }
+        }
         if (!startRuntime) {
             stderr.write("Error: startRuntime not available\n");
             return 1;
@@ -80,6 +155,40 @@ export async function runCli(argv, deps) {
         await runtime.keepAlive;
         return 0;
     }
+    // mcp
+    if (command === "mcp") {
+        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;
+        }
+        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") {
         if (!_runDoctor) {
@@ -90,10 +199,52 @@ export async function runCli(argv, deps) {
         stdout.write(output);
         return exitCode;
     }
-    // Future commands (listed in help but not yet implemented)
-    if (command === "status" || command === "config") {
-        stderr.write(`Command '${command}' is not yet implemented. Use --help for available commands.\n`);
-        return 1;
+    // status
+    if (command === "status") {
+        if (!_runStatus) {
+            stderr.write("Error: runStatus not available\n");
+            return 1;
+        }
+        const { exitCode, output } = await _runStatus();
+        stdout.write(output);
+        return exitCode;
+    }
+    // config
+    if (command === "config") {
+        if (!_runConfig) {
+            stderr.write("Error: runConfig not available\n");
+            return 1;
+        }
+        const { exitCode, output } = _runConfig(argv.slice(1));
+        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`);
@@ -108,7 +259,12 @@ 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

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync } from "node:fs";
+import { defaultSessionFile } from "../runtime/config.js";
+export async function runStatusCommand(deps = {}) {
+    const env = deps.env ?? process.env;
+    const _exists = deps.exists ?? existsSync;
+    const _readFile = deps.readFile ?? ((p) => readFileSync(p, "utf8"));
+    const _fetch = deps.fetch ??
+        (typeof globalThis.fetch === "function"
+            ? (url, init) => globalThis.fetch(url, init)
+            : undefined);
+    const lines = ["MICA status", ""];
+    const sessionFile = env.MICA_SESSION_FILE ?? defaultSessionFile(env);
+    const fail = (label, detail) => lines.push(`FAIL ${label}: ${detail}`);
+    const ok = (label, detail) => lines.push(`OK   ${label}: ${detail}`);
+    if (!_exists(sessionFile)) {
+        fail("Session file", `${sessionFile} (not found)`);
+        lines.push("FIX  Run: mica start");
+        return result(1, lines, false);
+    }
+    let session;
+    try {
+        session = JSON.parse(_readFile(sessionFile));
+    }
+    catch (error) {
+        fail("Session file", error instanceof Error ? error.message : String(error));
+        lines.push("FIX  Run: mica start");
+        return result(1, lines, false);
+    }
+    const baseUrl = session.baseUrl ?? `http://${session.host ?? "127.0.0.1"}:${session.port ?? 19791}`;
+    ok("Session file", sessionFile);
+    ok("Session target", baseUrl);
+    if (!session.authToken) {
+        fail("Auth token", "missing in session file");
+        lines.push("FIX  Restart MICA with: mica start");
+        return result(1, lines, false);
+    }
+    if (!_fetch) {
+        fail("Server /status reachable", "fetch unavailable");
+        return result(1, lines, false);
+    }
+    try {
+        const response = await _fetch(`${baseUrl}/status`, {
+            headers: { Authorization: `Bearer ${session.authToken}` },
+        });
+        if (response.status === 401) {
+            fail("Auth token", "401 Unauthorized");
+            lines.push("FIX  Restart MICA with: mica start");
+            return result(1, lines, false);
+        }
+        if (response.status !== 200) {
+            fail("Server /status reachable", `HTTP ${response.status}`);
+            lines.push("FIX  Run: mica start");
+            return result(1, lines, false);
+        }
+        const body = (await response.json());
+        const server = readRecord(body.server);
+        const agents = Array.isArray(body.agents) ? body.agents : [];
+        const notebooks = Array.isArray(body.notebooks) ? body.notebooks : [];
+        ok("Server", String(server.state ?? "running"));
+        ok("Version", String(server.version ?? session.version ?? "unknown"));
+        if (typeof session.pid === "number")
+            ok("PID", String(session.pid));
+        ok("Agents", String(agents.length));
+        ok("Notebooks", String(notebooks.length));
+        lines.push(`Dashboard: ${baseUrl}/#token=${session.authToken}`);
+        return result(0, lines, true);
+    }
+    catch (error) {
+        fail("Server /status reachable", error instanceof Error ? error.message : String(error));
+        lines.push("FIX  Run: mica start");
+        return result(1, lines, false);
+    }
+}
+function readRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function result(exitCode, lines, running) {
+    return { exitCode, output: `${lines.join("\n")}\n`, running };
+}

package/dist/src/cli/stop.js

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { defaultSessionFile } from "../runtime/config.js";
+export async function runStopCommand(deps = {}) {
+    const env = deps.env ?? process.env;
+    const sessionFile = env.MICA_SESSION_FILE ?? defaultSessionFile(env);
+    const _exists = deps.exists ?? existsSync;
+    const _readFile = deps.readFile ?? ((p) => readFileSync(p, "utf8"));
+    const _kill = deps.kill ?? ((pid, signal) => { process.kill(pid, signal); });
+    const _unlink = deps.unlink ?? ((p) => { unlinkSync(p); });
+    if (!_exists(sessionFile)) {
+        return { exitCode: 1, output: `MICA is not running\nSession file not found: ${sessionFile}\n` };
+    }
+    let session;
+    try {
+        session = JSON.parse(_readFile(sessionFile));
+    }
+    catch (error) {
+        return { exitCode: 1, output: `Cannot read session file: ${error instanceof Error ? error.message : String(error)}\n` };
+    }
+    if (typeof session.pid !== "number" || !Number.isInteger(session.pid) || session.pid <= 0) {
+        return { exitCode: 1, output: "Cannot stop MICA: session file has no valid pid\n" };
+    }
+    try {
+        _kill(session.pid, "SIGTERM");
+    }
+    catch (error) {
+        return { exitCode: 1, output: `Cannot stop MICA pid ${session.pid}: ${error instanceof Error ? error.message : String(error)}\n` };
+    }
+    try {
+        _unlink(sessionFile);
+    }
+    catch {
+        // The process may have already removed or replaced it; stopping still succeeded.
+    }
+    return { exitCode: 0, output: `MICA stopped\nPID: ${session.pid}\n` };
+}

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 = "0.1.0") {
+export function createMicaMcpServer(name, version = "1.0.2") {
     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.0",
+  "version": "1.0.2",
   "description": "Local MCP bridge for controlling live Wolfram Desktop / Mathematica notebooks.",
   "type": "module",
   "repository": {

package/src/bun/index.ts

@@ -11,7 +11,7 @@ import { writeSessionFile } from "../runtime/session.js";
 import { createBunHttpApp } from "./httpServer.js";
 
 const MCP_SERVER_NAME = "mica-bun";
-const MICA_PACKAGE_VERSION = "0.1.0";
+const MICA_PACKAGE_VERSION = "1.0.2";
 
 export type BunRuntimeDeps = {
   bridgeOnly?: boolean;