用途
logisheets-mcp 是一个 MCP（Model Context Protocol）服务器，封装了用 Rust 编写的电子表格引擎 LogiSheets，目标是给 AI 智能体一个“可以真正在其中思考”的电子表格：确定性的、与 Excel 兼容的计算，加上结构化记忆（块），最终产出真正的 .xlsx 文件。它采用 MIT 许可，运行在用户自己的机器上，可自托管。
主要能力
- 命名块（block）：块是工作表上的命名表格，行有键、列有名称，一切通过名称而非位置寻址。
- 列级公式：一个字段的公式为整列声明一次，而不是逐单元格声明。新增行会自动计算，不存在“第二十条公式写错”的问题。
- 有意义的引用：引用说明含义，例如按行键 Y3 的 pv 字段。在它上方插入一行，引用含义不变，因为它从未写“第 8 行”。
- 引擎拥有计算值：公式字段不能被模型自行算出的数字覆盖。
- 块可由智能体按需创建：无需事先准备。convert_to_block 可以把普通单元格区域转成块，从表头读取字段名并推断键列。
- 冷读（第二会话）：schema 写入 .xlsx，包含字段名、键列、引擎计算的字段及每条的规则。一次 list_blocks 调用即可让工作簿自我介绍；一次 describe_block 返回形如 #FIELD("revenue")*BLOCKREF("assum","margin","v") 的规则解释，而不是新的查找问题。块还携带描述文本（创建时给出或事后用 set_block_description 设置），存入文件并从 describe_block 返回。
- 图表重算：chart_from_block 把图表写入工作簿，图表存储引用而非数值，是原生 Excel c:chartSpace。修改源单元格，图表会跟随；新增区域会自动出现在图表中，因为系列绑定到字段而非单元格位置。chart_insert 对任意 A1 区域做同样的事。
- 场景与目标求解：preview_changes 和 goal_seek 改变模型探索方式——每个场景在独立临时分支上运行并丢弃，一个 4×4 敏感度网格是一次调用返回十六个数且不写入工作簿，逆向求解是一次调用而非逐步二分。trace 回答的是“什么读取了它”，而非“它读取了什么”。
- 分析与透视：分析块和透视表是引擎派生的摘要。智能体声明配方（哪个块、哪些字段、哪个函数），引擎据此生成所有公式；重命名源字段会重建摘要而非破坏它，后加的行也已被计入。两者都落在普通块中，因此 BLOCKREF("by_region", "East", "Q2") 可作为一个交叉表单元格并参与下一步计算。
- 文件输出：save_workbook 写出真实 .xlsx 并返回 MCP 资源链接（uri、媒体类型、大小），而不是字节。支持资源的宿主可从 workbook://current.xlsx 读取；export_xlsx 为不支持资源的宿主返回 base64。公式可以按 BLOCKREF("proj","Y3","pv") 形式写出供人阅读，或解析为普通坐标供 Excel 使用。
- 会话持久：一个 MCP 会话持有一个活动工作簿，跨工具调用保持存活，使其成为记忆而非计算器。
使用方式
需要 Node 20+。
对于 Claude Desktop，把以下内容加入 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json；Windows：%APPDATA%\Claude\claude_desktop_config.json），然后重启：
资料中该配置块的代码内容未提供。
任何启动 stdio 服务器的 MCP 宿主用法相同——Cursor 从 ~/.cursor/mcp.json 读取同样的块。
示例提示：
Build me a three-year revenue model: 100 units at $9.50 growing 40% a year, with a 30% cost of goods. Then save it to ~/model.xlsx.
数字由引擎返回而非模型猜测，.xlsx 中包含活的公式：在 Excel 中修改假设即可看到重算。若要在没有 LLM 的情况下查看同样效果，npm run build && npm run demo 会通过 stdio 驱动真实服务器并逐步校验每项断言。
作为库使用：createServer 返回 MCP Server、WorkbookSession 和工具映射，因此可以在任意传输层上托管。
与引擎同步开发：把 LogiSheets 检出为同级目录，构建其包，运行 npm run link:local，把三者符号链接进 node_modules，使本地引擎修改无需重装即可生效；每次 npm install 后需重跑。
工具集
默认暴露 32 个工具。资料说明：工具选择准确率会随列表增长而下降，且每个描述在每一轮都消耗上下文。
设置 LOGISHEETS_MCP_TOOLS=full 可扩展到 73 个：undo/redo、格式、合并、评论、检查点、块移动/调整大小、跨块链接、块权限、chart_suggest、定义与重命名名称、原始行列结构。变更类工具带有 MCP 的 readOnlyHint / destructiveHint 标注，宿主可据此置于审批之后。
图表工具保留命名空间前缀，而其他工具都去掉前缀：在其命名空间内它们叫 list、insert、update 和 delete。
公式与 Excel 兼容，外加 BLOCKREF(block, key, field) 用于按名称读取块单元格。在字段规则内部，#FIELD("name") 表示同一行的兄弟字段，#FIELD("name", "key") 表示同块中另一行（携带该键的行，绝不是位置偏移）。
list_names 属于核心工具面，而三个写定义名称的工具不属于，这是有意为之：定义名称是带标签的坐标范围，例如 Sales = Sheet1!$B$2:$B$20 在新增行时不会扩展，这正是块要消除的脆弱性。但他人构建的工作簿可能充满定义名称，不弄清 Sales 覆盖什么就无法读取 =SUM(Sales)，所以读取它们是定位，使用它们构建则是越过更好的工具。
关于透视表需注意：数字是活的，形状不是。没有公式能新增行，所以透视表构建后才首次出现在源中的分组会直接缺席——每个数字都对，表格不完整，且看不出哪里不对。describe_block 会指出缺失的分组，refresh_pivot 将其恢复，因此这对工具位于核心工具面。
适用场景
- 让 AI 智能体以确定性方式构建、修改和分析电子表格模型。
- 多场景“如果……会怎样”分析与目标求解，无需反复往返。
- 需要可被人打开、审计并继续使用的真实 .xlsx 输出。
- 跨会话理解既有工作簿：凭借保存的 schema 与块描述，后续会话无需先前上下文即可解读模型意图。
- 需要本地、无网络、可自托管运行的场景。
限制与安全
- 读写范围取决于服务器进程可到达的位置，这是本地 stdio 服务器的正常状态，与官方文件系统服务器姿态相同。应以仅具备预期访问权限的用户运行。
- 无套接字、无端口、无遥测。宿主以子进程方式启动，通过 stdin/stdout 交换换行分隔的 JSON-RPC；引擎是同一进程中的 WASM，因此公式是函数调用而非请求。气隙机器是受支持的运行方式。资料称已检查：在一次完整会话（创建块、附加字段规则、求值公式、保存 .xlsx）后，进程持有六个管道而无套接字，未监听任何端口。
- 资料中的性能对比数字、基准测试任务与结果、冷读测试的字节开销等，属于该仓库自身的测量与断言描述，此处不逐项复述；具体数值请以原仓库为准。
- 资料未提供定价或收费信息。
- 资料未提供配置块的具体代码内容，故不在此展示。
- 资料未提供除 Claude Desktop 与 Cursor 之外的具体宿主配置细节。
