@aliceshimada/mica 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 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,11 +124,41 @@ 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", "start"],
+      "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]

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,11 +124,41 @@ 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", "start"],
+      "enabled": true
+    }
+  }
+}
+```
+
+编辑 OpenCode config 后需要重启 OpenCode；config 只在启动时加载。
+
+如果要从本地 checkout 手动设置，请使用构建后的发布版入口：
 
 ```toml
 [mcp_servers.mica]

package/dist/src/bun/httpServer.js

@@ -2,7 +2,7 @@ import { timingSafeEqual } from "node:crypto";
 import http from "node:http";
 import { renderDashboard } from "./dashboard.js";
 const JSON_BODY_LIMIT_BYTES = 1024 * 1024;
-const DEFAULT_VERSION = "0.1.0";
+const DEFAULT_VERSION = "1.0.1";
 export async function createBunHttpApp({ state, host = "127.0.0.1", port, authToken, version = DEFAULT_VERSION }) {
     const runtimeInfo = {
         host,

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.1";
 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 = ["start"]\n`);
+    }
+    if (client === "opencode") {
+        return ok(`${JSON.stringify({
+            $schema: "https://opencode.ai/config.json",
+            mcp: {
+                mica: {
+                    type: "local",
+                    command: ["mica", "start"],
+                    enabled: true,
+                },
+            },
+        }, null, 2)}\n`);
+    }
+    return ok(`${JSON.stringify({
+        mcpServers: {
+            mica: {
+                command: "mica",
+                args: ["start"],
+            },
+        },
+    }, null, 2)}\n`);
+}
+function ok(output) {
+    return { exitCode: 0, output };
+}

package/dist/src/cli/index.js

@@ -3,7 +3,10 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { startBunRuntime } from "../bun/index.js";
+import { runConfigCommand } from "./configSnippets.js";
 import { runDoctor } from "./doctor.js";
+import { runStatusCommand } from "./status.js";
+import { runStopCommand } from "./stop.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -25,6 +28,8 @@ 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
   install [options]       Install MICA bridge into Wolfram
   uninstall [options]     Uninstall MICA bridge from Wolfram
   doctor                  Diagnose MICA bridge configuration
@@ -32,6 +37,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 +50,9 @@ 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 command = argv[0];
     // --help / -h
     if (command === "--help" || command === "-h") {
@@ -72,6 +81,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;
@@ -90,10 +106,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`);
@@ -109,6 +167,9 @@ async function main() {
     const exitCode = await runCli(process.argv.slice(2), {
         startRuntime: async () => startBunRuntime(),
         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/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.1") {
     return new McpServer({ name, version }, { instructions: MICA_AGENT_INSTRUCTIONS });
 }
 export function registerMicaPrompts(server) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliceshimada/mica",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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.1";
 
 export type BunRuntimeDeps = {
   bridgeOnly?: boolean;