@aliceshimada/mica 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 1.0.0 - 2026-06-02
+
+- Initial public release as `@aliceshimada/mica`.
+- Local MCP bridge for controlling live Wolfram Desktop / Mathematica notebooks.
+- Reversible installer, CLI entrypoint, doctor command, dashboard token flow, and bounded notebook output/artifact responses.
+- Bilingual README (English / 简体中文).
+
+## 0.1.0 - 2026-06-02
+
+- Initial MICA productization release metadata.
+- Local MCP bridge for controlling live Wolfram Desktop / Mathematica notebooks.
+- Reversible installer, CLI entrypoint, doctor command, dashboard token flow, and bounded notebook output/artifact responses.

package/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing
+
+## Development checks
+
+Before opening a pull request, run:
+
+```bash
+npm test
+npm run typecheck
+npm run build
+node scripts/install.js --dry-run
+```
+
+When changing installer behavior, update installer tests. When changing MCP tools or HTTP endpoints, update the matching protocol tests.
+
+## Security reports
+
+For a security issue or security report, use the process in [SECURITY.md](SECURITY.md). Do not publish bearer tokens, local session files, or private notebook content in public issues.
+
+## Local paths
+
+Avoid committing machine-specific paths or development-only notes. Documentation should use placeholders such as `/absolute/path/to/mica`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alice-Shimada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,308 @@
+# MICA
+
+**Mathematica Interactive Control Agent**
+
+English | [简体中文](README.zh-CN.md)
+
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+![Node](https://img.shields.io/badge/node-%3E%3D20-5FA04E?logo=node.js&logoColor=white)
+![Bun](https://img.shields.io/badge/runtime-Bun-f3e7d3?logo=bun&logoColor=111111)
+![MCP](https://img.shields.io/badge/protocol-MCP-2563eb)
+![Wolfram Desktop](https://img.shields.io/badge/Wolfram%20Desktop-14.1%2B-dd1100)
+![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-111827)
+
+MICA is a local MCP bridge for Wolfram Desktop / Mathematica. It lets an MCP-capable coding agent work through the notebook you already have open: list notebooks, inspect cells, insert and edit code, run evaluations, read outputs/messages, abort long computations, and look up Wolfram Language documentation without directly writing `.nb` files or launching a detached `wolframscript` workflow.
+
+![MICA architecture hero](docs/assets/mica-readme-hero.png)
+
+## Why MICA?
+
+- **Works in real notebooks**: the agent acts on visible Wolfram Desktop notebooks, not a detached headless kernel.
+- **Human-visible agent work**: inserted code, outputs, messages, and edits appear in the notebook where you can review them.
+- **Notebook-aware targeting**: agents can list open notebooks, select the intended notebook, and use strict targeting for mutating tools.
+- **Agent-friendly protocol**: `mma_status`, `mma_list_notebooks`, structured errors, bounded outputs, artifact paging, and the `mica_notebook_workflow` prompt tell agents how to proceed safely.
+- **Permission-gated control**: read, insert, modify, delete, run, and save permissions are explicit.
+- **Local-first security model**: the bridge binds to `127.0.0.1`, uses a generated bearer token, and does not include a remote access mode.
+- **Release-minded install path**: install/uninstall is reversible and keeps timestamped `Kernel/init.m` backups.
+
+## Why work through the notebook you already have open?
+
+Traditional automation usually copies code into a separate script or starts a headless kernel. That is useful for batch jobs, but it loses the context that makes notebooks valuable. MICA keeps the agent in the same FrontEnd workflow you are using.
+
+- **Preserves live context**: definitions, prior cells, rich outputs, messages, and notebook structure stay in the real working notebook.
+- **Keeps the human in the loop**: you can watch what the agent inserts, interrupt a long evaluation, edit a cell yourself, or rerun something manually.
+- **Improves auditability**: code execution happens as notebook cells instead of an opaque raw-eval endpoint, leaving visible cells and outputs behind.
+- **Reduces context loss**: the agent can read nearby cells, outputs, and messages before deciding what to do next.
+- **Handles multiple notebooks**: the agent can discover open notebooks and target the intended one by current `notebookId` or display name.
+- **Fits exploratory Wolfram work**: plots, dynamic output, formatted boxes, and FrontEnd notebook operations remain part of the workflow.
+
+## How It Works
+
+```text
+MCP client / coding agent
+        |
+        | stdio MCP
+        v
+MICA MCP server + localhost dashboard
+        |
+        | HTTP queue on 127.0.0.1:19791
+        v
+Hidden Wolfram FrontEnd control agent
+        |
+        | NotebookRead / NotebookWrite / Cells / CellObject
+        v
+Your already-open Mathematica notebook
+```
+
+The hidden Wolfram agent runs from a dedicated `MMAAgentControl` FrontEnd evaluator. Your normal notebooks stay on their own evaluator, while MICA keeps polling, queueing, timeout handling, and abort requests responsive.
+
+## Requirements
+
+| Requirement | Notes |
+| --- | --- |
+| Wolfram Desktop / Mathematica | 14.1+ supported. 13.x / 14.0 experimental (may work but not formally tested). Headless Wolfram Engine is not supported for live notebook control. |
+| Node.js | 20 or newer. |
+| Bun | Optional. Used for Bun development scripts. The release CLI runs through Node. |
+| MCP client | Codex, Claude Desktop, Cursor, or any stdio MCP client. |
+
+## Quick Start
+
+Install globally from npm:
+
+```bash
+npm install -g @aliceshimada/mica
+mica install
+```
+
+Then fully quit and restart Wolfram Desktop. Open a notebook, start the MCP server, and connect your MCP client:
+
+```bash
+mica start
+```
+
+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
+```
+
+Dashboard:
+
+```text
+Use the `Dashboard: http://127.0.0.1:<port>/#token=<token>` URL printed by the MICA server.
+```
+
+The dashboard is token-gated: opening `/` without the URL fragment does not fetch or display bridge data. With the printed token URL, it shows grouped diagnostics for Server, Security, Agents, Notebooks, and Requests. Click Agents or Notebooks to open a shared details panel below the overview cards.
+
+The installer edits only your per-user Wolfram `Kernel/init.m`, creates a timestamped backup, and prints MCP client config snippets. It does not edit system Wolfram files and does not edit MCP client configs for you.
+
+Dry run and uninstall:
+
+```bash
+node dist/src/cli/index.js install --dry-run
+node dist/src/cli/index.js uninstall
+```
+
+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:
+
+```toml
+[mcp_servers.mica]
+command = "node"
+args = ["/absolute/path/to/mica/dist/src/cli/index.js", "start"]
+```
+
+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"]
+```
+
+## Agent Guide Prompt
+
+MICA exposes usage guidance in two MCP-facing places:
+
+- Server initialization `instructions`
+- Reusable prompt: `mica_notebook_workflow`
+
+The prompt tells the agent to start with `mma_status` or `mma_list_notebooks`, use current `notebookId` values, avoid hidden/offscreen notebooks, avoid detached `wolframscript` for live-notebook work, and handle structured `ok: true` / `ok: false` responses.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `mma_status` | Report server, agent, and notebook registry state. |
+| `mma_list_notebooks` | List registered live notebooks and the active notebook id. |
+| `mma_select_notebook` | Select the active notebook by `notebookId` or unambiguous `displayName`. |
+| `mma_symbol_lookup` | Look up Wolfram Language usage, options, attributes, and documentation URLs. |
+| `mma_list_cells` | List cells in the selected notebook. |
+| `mma_read_cell` | Read one cell's content and metadata. |
+| `mma_insert_cell` | Insert a cell; use `afterCellId="__end__"` to append. |
+| `mma_modify_cell` | Modify an existing cell. |
+| `mma_delete_cell` | Delete an existing cell. |
+| `mma_run_cell` | Evaluate one cell with a timeout. |
+| `mma_abort_evaluation` | Abort the current notebook evaluation. |
+| `mma_get_cell_output` | Read output and messages for a cell. |
+| `mma_read_artifact` | Read large output or message artifacts by byte page. |
+| `mma_save_notebook` | Save the notebook when `SaveNotebook` permission is granted. |
+
+All MCP tools return JSON text plus `structuredContent`.
+
+```json
+{ "ok": true, "result": "..." }
+```
+
+`mma_read_cell` truncates large cell content, outputs, and messages by default to keep MCP responses bounded. `mma_get_cell_output` keeps small outputs/messages inline and returns artifact metadata for large entries; pass the returned `artifactId` to `mma_read_artifact` with `offset` and `limit` to page through the full text. Artifact ids are deterministic but ephemeral: they are resolved by rescanning the current notebook, so notebook edits or reruns can make an id stale or point to updated content. Reading outputs or artifacts may also refresh a completed cell's run status. Output status values include `running`, `abort_requested`, `aborted`, `finished`, `timeout`, and `unknown`; `abort_requested` means MICA sent an abort signal but has not yet observed terminal completion. Pass `maxBytes` (positive integer, up to 1 MiB) to request a different response budget. Truncated or artifact-backed responses include `truncated`, `originalByteLength`, and `returnedByteLength` metadata.
+
+Expected failures are structured and set the MCP `isError` flag:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "PERMISSION_DENIED",
+    "message": "The selected notebook did not grant permission for this tool.",
+    "retryable": false,
+    "tool": "mma_save_notebook"
+  }
+}
+```
+
+## Manual Wolfram Startup
+
+If you do not want to edit `Kernel/init.m`, start Wolfram Desktop and evaluate the following after replacing the path:
+
+```wolfram
+Get["/absolute/path/to/mica/paclet/Kernel/MMAAgentBridge.wl"];
+MMAAgentBridge`Private`$BridgePermissions = <|
+  "ReadNotebook" -> True,
+  "InsertCell" -> True,
+  "ModifyCell" -> True,
+  "DeleteCell" -> True,
+  "RunCell" -> True,
+  "SaveNotebook" -> False
+|>;
+MMAAgentBridge`StartMMAAgentControlKernel[]
+```
+
+## Development
+
+```bash
+npm test
+npm run typecheck
+npm run build
+npm run dev:mcp
+npm run dev:bridge
+```
+
+Common commands:
+
+| Command | Use |
+| --- | --- |
+| `npm run dev:mcp` | Start the TypeScript MCP server through `tsx`. |
+| `npm run dev:bridge` | Start the TypeScript bridge and dashboard without stdio MCP. |
+| `npm run dev:bun:mcp` | Start the MCP server through Bun. |
+| `npm run dev:bun` | Start the bridge and dashboard through Bun without stdio MCP. |
+| `npm run dev:legacy` | Start the legacy Node HTTP bridge for Palette compatibility testing. |
+| `npm run build` | Emit production JavaScript under `dist/`. |
+
+## Verification Checklist
+
+```bash
+npm test
+npm run typecheck
+npm run build
+node dist/src/cli/index.js install --dry-run
+node dist/src/cli/index.js doctor
+```
+
+Live smoke test:
+
+1. Run `node dist/src/cli/index.js install`.
+2. Fully restart Wolfram Desktop.
+3. Open a notebook.
+4. Confirm `mma_status` reports an online agent and a registered notebook.
+5. Confirm insert, read, modify, run, get-output, delete, abort, and symbol lookup work against that notebook.
+6. Run `node dist/src/cli/index.js uninstall` and confirm the marked block is removed from `Kernel/init.m`.
+
+See also:
+
+- [Manual Smoke Test](docs/qa/manual-smoke-test.md) — full release checklist.
+- [Support Matrix](docs/qa/support-matrix.md) — platform and runtime coverage.
+
+## Troubleshooting
+
+Run the built-in doctor first — it diagnoses the most common issues without side effects:
+
+```bash
+node dist/src/cli/index.js doctor
+# or if installed globally:
+mica doctor
+```
+
+The doctor checks Node version, package build, session file, auth token, server reachability, live agent/notebook counts, Wolfram user base, `Kernel/init.m`, and the MICA autoload block. Each check reports `OK` or `FAIL` with a suggested `FIX` line.
+
+**Common failures and fixes:**
+
+| Doctor output | Likely cause | Action |
+| --- | --- | --- |
+| `FAIL Session file` | Server never started | `mica start` |
+| `FAIL Auth token` | Token mismatch or expired | Restart the server |
+| `FAIL Server /status reachable` | Server not running | `mica start` |
+| `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` |
+| `FAIL Autoload block` | Installer not run or uninstalled | `mica install` |
+| `FAIL Package build` | Build artifacts missing | `npm run build` |
+
+If the doctor passes but you still see `NO_LIVE_AGENT`, `NOTEBOOK_STALE`, or connection errors in your MCP client, fully quit and restart Wolfram Desktop, then restart the MICA server.
+
+## Security Model
+
+- MICA binds its HTTP bridge to `127.0.0.1`.
+- MICA writes a local session file with a generated auth token and requires `Authorization: Bearer <token>` for protocol endpoints.
+- The dashboard token is carried in the URL fragment (`#token=...`), not in the HTTP request path.
+- The dashboard URL, including the local bearer token, is printed to the server startup log for the current user session.
+- MICA does not include a remote access mode.
+- There is no arbitrary shell tool and no direct raw-eval MCP endpoint.
+- Notebook mutation goes through Wolfram FrontEnd APIs and explicit permissions.
+- `mma_save_notebook` is disabled by default in the installer permission block.
+- The Node/Bun process does not directly edit `.nb` files.
+
+## Explicit Notebook Targeting
+
+Set `MICA_STRICT_TARGETING=1` to require explicit `notebookId` (or `displayName`) for all mutating MCP tools (`mma_insert_cell`, `mma_modify_cell`, `mma_delete_cell`, `mma_run_cell`, `mma_abort_evaluation`, `mma_save_notebook`). Read-only notebook tools (`mma_list_cells`, `mma_read_cell`, `mma_get_cell_output`) continue to use the active notebook, and `mma_symbol_lookup` is unaffected because it does not target a notebook. When strict targeting is enabled and no selector is provided, the tool returns error code `EXPLICIT_NOTEBOOK_REQUIRED` with `retryable: false`. Default behavior (no env var or any value other than `"1"`) is unchanged.
+
+## Known Limitations
+
+- Cancellation is best-effort when the Wolfram kernel is already busy.
+- Cell ids are session-local and can change after reopening a notebook.
+- FrontEnd notebook operations are currently serialized.
+- The legacy Palette flow remains only for compatibility during migration; the documented release path is the CLI plus MCP server.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,308 @@
+# MICA
+
+**Mathematica Interactive Control Agent**
+
+简体中文 | [English](README.md)
+
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+![Node](https://img.shields.io/badge/node-%3E%3D20-5FA04E?logo=node.js&logoColor=white)
+![Bun](https://img.shields.io/badge/runtime-Bun-f3e7d3?logo=bun&logoColor=111111)
+![MCP](https://img.shields.io/badge/protocol-MCP-2563eb)
+![Wolfram Desktop](https://img.shields.io/badge/Wolfram%20Desktop-14.1%2B-dd1100)
+![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-111827)
+
+MICA 是一个面向 Wolfram Desktop / Mathematica 的本地 MCP 桥接器。它让支持 MCP 的代码 Agent 通过你已经打开的 Notebook 工作：列出 Notebook、检查 cell、插入和编辑代码、运行求值、读取输出与消息、中止长时间计算，并查询 Wolfram Language 文档；整个过程不需要直接写入 `.nb` 文件，也不需要切到脱离 FrontEnd 的 `wolframscript` 工作流。
+
+![MICA architecture hero](docs/assets/mica-readme-hero.png)
+
+## 为什么选择 MICA？
+
+- **直接作用于真实 Notebook**：Agent 操作的是 Wolfram Desktop 中可见的 Notebook，而不是一个分离的 headless kernel。
+- **Agent 的工作对人可见**：插入的代码、输出、消息和编辑都会出现在 Notebook 里，方便你检查。
+- **Notebook-aware targeting**：Agent 可以列出已打开的 Notebook，选择目标 Notebook，并为会修改 Notebook 的工具启用严格目标选择。
+- **面向 Agent 的协议设计**：`mma_status`、`mma_list_notebooks`、结构化错误、有界输出、artifact 分页，以及 `mica_notebook_workflow` prompt 会告诉 Agent 如何安全推进。
+- **显式权限控制**：读取、插入、修改、删除、运行和保存权限都显式配置。
+- **本地优先的安全模型**：桥接服务绑定到 `127.0.0.1`，使用生成的 bearer token，不提供远程访问模式。
+- **面向发布的安装路径**：安装和卸载可逆，并会为 `Kernel/init.m` 创建带时间戳的备份。
+
+## 为什么通过已经打开的 Notebook 工作？
+
+传统自动化通常会把代码复制到独立脚本中，或者启动 headless kernel。这对批处理任务很有用，但会丢失 Notebook 本身的上下文。MICA 让 Agent 留在你正在使用的同一个 FrontEnd 工作流里。
+
+- **保留实时上下文**：已有定义、前面的 cell、富输出、消息和 Notebook 结构都留在真实工作 Notebook 中。
+- **人始终在回路中**：你可以看到 Agent 插入了什么，手动中断长时间求值，自己编辑 cell，或者手动重新运行某段内容。
+- **更容易审计**：代码执行发生在 Notebook cell 中，而不是不可见的 raw-eval 端点中；Notebook 会留下可见的 cell 和输出。
+- **减少上下文损失**：Agent 可以先读取附近的 cell、输出和消息，再决定下一步怎么做。
+- **支持多个 Notebook**：Agent 可以发现已打开的 Notebook，并通过当前 `notebookId` 或显示名称定位目标。
+- **适合探索式 Wolfram 工作**：图形、动态输出、格式化 box，以及 FrontEnd Notebook 操作都仍然是工作流的一部分。
+
+## 工作方式
+
+```text
+MCP client / coding agent
+        |
+        | stdio MCP
+        v
+MICA MCP server + localhost dashboard
+        |
+        | HTTP queue on 127.0.0.1:19791
+        v
+Hidden Wolfram FrontEnd control agent
+        |
+        | NotebookRead / NotebookWrite / Cells / CellObject
+        v
+Your already-open Mathematica notebook
+```
+
+隐藏的 Wolfram Agent 运行在专用的 `MMAAgentControl` FrontEnd evaluator 中。你的普通 Notebook 继续使用自己的 evaluator；MICA 负责保持轮询、队列、超时处理和中止请求的响应性。
+
+## 环境要求
+
+| 要求 | 说明 |
+| --- | --- |
+| Wolfram Desktop / Mathematica | 支持 14.1+。13.x / 14.0 为 experimental（可能可用，但未正式测试）。Headless Wolfram Engine 不支持 live Notebook 控制。 |
+| Node.js | 20 或更新版本。 |
+| Bun | 可选。用于 Bun 开发脚本。发布版 CLI 通过 Node 运行。 |
+| MCP client | Codex、Claude Desktop、Cursor，或任何 stdio MCP client。 |
+
+## 快速开始
+
+从 npm 全局安装：
+
+```bash
+npm install -g @aliceshimada/mica
+mica install
+```
+
+然后完全退出并重启 Wolfram Desktop。打开一个 Notebook，启动 MCP server，并连接你的 MCP client：
+
+```bash
+mica start
+```
+
+或者从发布版 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
+```
+
+然后完全退出并重启 Wolfram Desktop。打开一个 Notebook，启动 MCP server，并连接你的 MCP client：
+
+```bash
+node dist/src/cli/index.js start
+```
+
+如果 MICA 已经安装在你的 `PATH` 中，也可以使用等价的发布版命令：
+
+```bash
+mica install
+mica start
+mica doctor
+```
+
+Dashboard：
+
+```text
+使用 MICA server 打印的 `Dashboard: http://127.0.0.1:<port>/#token=<token>` URL。
+```
+
+Dashboard 使用 token gate：直接打开 `/` 不会获取或显示桥接数据。使用打印出的 token URL 时，它会按 Server、Security、Agents、Notebooks 和 Requests 分组展示诊断信息。点击 Agents 或 Notebooks 可以在概览卡片下方打开共享详情面板。
+
+安装器只会编辑当前用户的 Wolfram `Kernel/init.m`，创建带时间戳的备份，并打印 MCP client 配置片段。它不会编辑系统级 Wolfram 文件，也不会替你编辑 MCP client 配置。
+
+Dry run 和卸载：
+
+```bash
+node dist/src/cli/index.js install --dry-run
+node dist/src/cli/index.js uninstall
+```
+
+兼容用的 legacy 安装入口仍然可用：`node scripts/install.js --dry-run`。
+
+## MCP Client 配置
+
+使用本地 checkout 中构建后的发布版入口：
+
+```toml
+[mcp_servers.mica]
+command = "node"
+args = ["/absolute/path/to/mica/dist/src/cli/index.js", "start"]
+```
+
+开发时也可以让 MCP client 指向 TypeScript 入口：
+
+```toml
+[mcp_servers.mica]
+command = "npx"
+args = ["tsx", "/absolute/path/to/mica/src/bun/index.ts"]
+```
+
+## Agent Guide Prompt
+
+MICA 在两个 MCP-facing 位置暴露使用指导：
+
+- Server initialization `instructions`
+- 可复用 prompt：`mica_notebook_workflow`
+
+这个 prompt 会要求 Agent 从 `mma_status` 或 `mma_list_notebooks` 开始，使用当前的 `notebookId`，避免操作隐藏或离屏 Notebook，避免用 detached `wolframscript` 调试 live Notebook，并处理结构化的 `ok: true` / `ok: false` 响应。
+
+## 工具
+
+| Tool | 用途 |
+| --- | --- |
+| `mma_status` | 报告 server、agent 和 Notebook registry 状态。 |
+| `mma_list_notebooks` | 列出已注册的 live Notebook 和 active notebook id。 |
+| `mma_select_notebook` | 通过 `notebookId` 或无歧义的 `displayName` 选择 active Notebook。 |
+| `mma_symbol_lookup` | 查询 Wolfram Language 的 usage、options、attributes 和文档 URL。 |
+| `mma_list_cells` | 列出所选 Notebook 中的 cell。 |
+| `mma_read_cell` | 读取单个 cell 的内容和 metadata。 |
+| `mma_insert_cell` | 插入 cell；使用 `afterCellId="__end__"` 可以追加到末尾。 |
+| `mma_modify_cell` | 修改已有 cell。 |
+| `mma_delete_cell` | 删除已有 cell。 |
+| `mma_run_cell` | 在 timeout 限制下求值一个 cell。 |
+| `mma_abort_evaluation` | 中止当前 Notebook 求值。 |
+| `mma_get_cell_output` | 读取 cell 的输出和消息。 |
+| `mma_read_artifact` | 按 byte page 读取大输出或大消息 artifact。 |
+| `mma_save_notebook` | 在授予 `SaveNotebook` 权限时保存 Notebook。 |
+
+所有 MCP 工具都会返回 JSON text 和 `structuredContent`。
+
+```json
+{ "ok": true, "result": "..." }
+```
+
+`mma_read_cell` 默认会截断大的 cell 内容、输出和消息，以保持 MCP 响应有界。`mma_get_cell_output` 会把小输出和消息内联返回，并为大条目返回 artifact metadata；把返回的 `artifactId` 传给 `mma_read_artifact`，并提供 `offset` 和 `limit`，即可分页读取完整文本。Artifact id 是确定性的但短生命周期：它们通过重新扫描当前 Notebook 来解析，所以 Notebook 被编辑或重新运行后，id 可能失效，或者指向更新后的内容。读取输出或 artifact 也可能刷新已完成 cell 的运行状态。输出状态包括 `running`、`abort_requested`、`aborted`、`finished`、`timeout` 和 `unknown`；`abort_requested` 表示 MICA 已发送中止信号，但还没有观察到终态完成。可以传入 `maxBytes`（正整数，最大 1 MiB）来请求不同的响应预算。截断或 artifact-backed 响应会包含 `truncated`、`originalByteLength` 和 `returnedByteLength` metadata。
+
+预期内失败会被结构化，并设置 MCP `isError` flag：
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "PERMISSION_DENIED",
+    "message": "The selected notebook did not grant permission for this tool.",
+    "retryable": false,
+    "tool": "mma_save_notebook"
+  }
+}
+```
+
+## 手动启动 Wolfram 侧桥接
+
+如果你不想编辑 `Kernel/init.m`，可以启动 Wolfram Desktop，并在替换路径后求值以下代码：
+
+```wolfram
+Get["/absolute/path/to/mica/paclet/Kernel/MMAAgentBridge.wl"];
+MMAAgentBridge`Private`$BridgePermissions = <|
+  "ReadNotebook" -> True,
+  "InsertCell" -> True,
+  "ModifyCell" -> True,
+  "DeleteCell" -> True,
+  "RunCell" -> True,
+  "SaveNotebook" -> False
+|>;
+MMAAgentBridge`StartMMAAgentControlKernel[]
+```
+
+## 开发
+
+```bash
+npm test
+npm run typecheck
+npm run build
+npm run dev:mcp
+npm run dev:bridge
+```
+
+常用命令：
+
+| Command | 用途 |
+| --- | --- |
+| `npm run dev:mcp` | 通过 `tsx` 启动 TypeScript MCP server。 |
+| `npm run dev:bridge` | 启动 TypeScript bridge 和 dashboard，不启用 stdio MCP。 |
+| `npm run dev:bun:mcp` | 通过 Bun 启动 MCP server。 |
+| `npm run dev:bun` | 通过 Bun 启动 bridge 和 dashboard，不启用 stdio MCP。 |
+| `npm run dev:legacy` | 启动 legacy Node HTTP bridge，用于 Palette 兼容性测试。 |
+| `npm run build` | 在 `dist/` 下输出生产 JavaScript。 |
+
+## 验证清单
+
+```bash
+npm test
+npm run typecheck
+npm run build
+node dist/src/cli/index.js install --dry-run
+node dist/src/cli/index.js doctor
+```
+
+Live smoke test：
+
+1. 运行 `node dist/src/cli/index.js install`。
+2. 完全重启 Wolfram Desktop。
+3. 打开一个 Notebook。
+4. 确认 `mma_status` 报告 online agent 和已注册 Notebook。
+5. 确认 insert、read、modify、run、get-output、delete、abort 和 symbol lookup 都能作用于该 Notebook。
+6. 运行 `node dist/src/cli/index.js uninstall`，并确认 `Kernel/init.m` 中标记的 block 已被移除。
+
+另见：
+
+- [Manual Smoke Test](docs/qa/manual-smoke-test.md) — 完整发布检查清单。
+- [Support Matrix](docs/qa/support-matrix.md) — 平台和运行时覆盖情况。
+
+## Troubleshooting
+
+优先运行内置 doctor；它会无副作用地诊断最常见问题：
+
+```bash
+node dist/src/cli/index.js doctor
+# 或者，如果已经全局安装：
+mica doctor
+```
+
+Doctor 会检查 Node 版本、package build、session file、auth token、server 可达性、live agent/notebook 数量、Wolfram user base、`Kernel/init.m` 和 MICA autoload block。每项检查都会报告 `OK` 或 `FAIL`，并给出建议的 `FIX` 行。
+
+**常见失败与修复：**
+
+| Doctor output | 可能原因 | 操作 |
+| --- | --- | --- |
+| `FAIL Session file` | Server 尚未启动 | `mica start` |
+| `FAIL Auth token` | Token 不匹配或已过期 | 重启 server |
+| `FAIL Server /status reachable` | Server 未运行 | `mica start` |
+| `FAIL Live agent count: 0` | Wolfram 未运行或 bridge 未加载 | 安装后重启 Wolfram Desktop |
+| `FAIL Live notebook count: 0` | 没有打开或注册的 Notebook | 在 Wolfram Desktop 中打开 Notebook |
+| `FAIL Kernel/init.m` | 尚未运行安装器 | `mica install` |
+| `FAIL Autoload block` | 尚未安装或已卸载 | `mica install` |
+| `FAIL Package build` | 缺少 build artifacts | `npm run build` |
+
+如果 doctor 通过，但 MCP client 中仍看到 `NO_LIVE_AGENT`、`NOTEBOOK_STALE` 或连接错误，请完全退出并重启 Wolfram Desktop，然后重启 MICA server。
+
+## 安全模型
+
+- MICA 将 HTTP bridge 绑定到 `127.0.0.1`。
+- MICA 会写入包含生成 auth token 的本地 session file，并要求 protocol endpoints 使用 `Authorization: Bearer <token>`。
+- Dashboard token 放在 URL fragment（`#token=...`）中，而不是 HTTP request path 中。
+- Dashboard URL（包含本地 bearer token）会打印到当前用户会话的 server startup log。
+- MICA 不提供远程访问模式。
+- MICA 不包含任意 shell 工具，也没有直接 raw-eval MCP endpoint。
+- Notebook 修改通过 Wolfram FrontEnd API 和显式权限完成。
+- 安装器权限 block 默认禁用 `mma_save_notebook`。
+- Node/Bun 进程不会直接编辑 `.nb` 文件。
+
+## 显式 Notebook Targeting
+
+设置 `MICA_STRICT_TARGETING=1` 后，所有会修改 Notebook 的 MCP 工具（`mma_insert_cell`、`mma_modify_cell`、`mma_delete_cell`、`mma_run_cell`、`mma_abort_evaluation`、`mma_save_notebook`）都必须显式提供 `notebookId`（或 `displayName`）。只读 Notebook 工具（`mma_list_cells`、`mma_read_cell`、`mma_get_cell_output`）仍然使用 active Notebook，`mma_symbol_lookup` 不受影响，因为它不针对某个 Notebook。启用 strict targeting 后，如果未提供 selector，工具会返回 error code `EXPLICIT_NOTEBOOK_REQUIRED`，并设置 `retryable: false`。默认行为（未设置 env var，或值不是 `"1"`）保持不变。
+
+## 已知限制
+
+- 当 Wolfram kernel 已经繁忙时，取消操作是 best-effort。
+- Cell id 是 session-local 的，重新打开 Notebook 后可能变化。
+- FrontEnd Notebook 操作目前是串行化的。
+- Legacy Palette flow 仅保留用于迁移期兼容；文档化的发布路径是 CLI + MCP server。
+
+## License
+
+MIT — 见 [LICENSE](LICENSE)。