# @xlvane/mcp 中文文档

规范地址：https://npmcn.com/package/%40xlvane/mcp/

版本：1\.2\.2
npm 元数据更新时间：2026-11-02T22:02:02.725Z
中文译文更新时间：2026-11-02T22:56:23.435Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40xlvane/mcp
原文对照：https://npmcn.com/package/%40xlvane/mcp/?lang=original
项目主页：https://github.com/DevXord/xlvane#readme
源码仓库：https://github.com/DevXord/xlvane

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：48.2 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：2 个
- 首次发布：2026-11-02T17:15:35.241Z
- 最新版本发布：2026-11-02T20:58:43.384Z
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

用于XLSX文件的MCP服务器：检查，读取，写入，编辑，转换，比较和验证工作簿与xlvane，限制在开始时给定的目录。

## 安装

```sh
npm install @xlvane/mcp
```

也可以使用：`pnpm add @xlvane/mcp`、`yarn add @xlvane/mcp`、`bun add @xlvane/mcp`

## README

# @xlvane / mcp

为XLSX文件构建的MCP（模型上下文协议）服务器 [xlvane](https://www.npmjs.com/package/xlvane) 和官方MCP TypeScript SDK (`@modelcontextprotocol/server` 2.4.0，协议修订2026-07-28)。MCP客户端，比如编码代理，可以检查、读取、比较和验证工作簿，还可以选择通过工具而不是代码来编写、编辑和转换工作簿。

需要Node.js 22或更高版本。依赖关系: `xlvane` 和 `@modelcontextprotocol/server` (带 `@modelcontextprotocol/core` 和 `zod`）。

## 开始

```sh
npx @xlvane/mcp --root ./data                 # read-only, files inside ./data
npx @xlvane/mcp --root ./data --allow-write   # also write_table, edit_cells, convert
xlvane mcp --root ./data                      # the same server, through the xlvane CLI
```

许多MCP客户端采用这样的配置；检查客户端文档的确切格式和文件：

```json
{
  "mcpServers": {
    "xlvane": { "command": "npx", "args": ["@xlvane/mcp", "--root", "/absolute/path/to/data"] }
  }
}
```

| 选项 | 意义 |
| --- | --- |
| `--root <dir>` | 工具可能使用的目录；重复几次。必需的。工具调用中的相对路径是根据第一个路径解析的。 |
| `--allow-write` | 还要提供写文件的工具。没有它，他们根本就没有注册。 |
| `--max-file-size <bytes>` | 读取或写入的最大文件。默认64 MiB。 |
| `--max-rows <n>` | 最大行数为1 `read_table` 调用返回。默认的1000。 |
| `--max-response-chars <n>` | 最大的工具结果（也是一个错误），以其JSON文本的字符表示；消息再次携带相同的数据 `structuredContent`. `read_table` 返回符合(`truncated`， `nextOffset`）; 其他工具返回 `XLV_E_LIMIT_EXCEEDED`。默认1米（1 048 576）。 |

服务器通过标准输入和标准输出进行MCP通信；给人们的信息去了stderr。

## 工具

| 工具 | 写 | 它是做什么的 |
| --- | --- | --- |
| `inspect_workbook` | 否 | 工作表（也包括隐藏的工作表）、使用的范围、标题行、带有示例的列类型、合并的单元格、公式、警告。 |
| `read_table` | 否 | 作为标题行键控对象的工作表行；分页, `offset` 和 `limit`； 日期为ISO 8601。 |
| `diff` | 否 | 两个工作簿之间每个单元格的差异。 |
| `validate` | 否 | 读取警告和列规则(`name`， `type`， `optional`)与每个问题的单元格。 |
| `write_table` | 是 | 行到一个新的XLSX文件（报告预设：粗体标题，冻结行，自动过滤器，宽度）。 |
| `edit_cells` | 是 | 设置单元格并追加行，保持文件的其余部分不变。 |
| `convert` | 是 | XLSX到CSV/TSV/JSON和返回；CSV输出转义类似公式的文本。 |

每个工具都有一个JSON Schema作为其输入，并返回其结果为 `structuredContent` 和JSON文本。错误是工具的结果 `isError: true` 和 `XlvError` 数据：稳定 `code`, `location`,一个 `hint` 和 `details` (文档/ errors.md)。

## 安全

-   **目录:** 文件只能在 `--root` 目录。解析符号链接后检查路径，因此 `..`，绝对路径和外部链接被拒绝(`XLV_E_PATH_NOT_ALLOWED`）. 打开文件后会再次检查文件（路径必须仍然指向相同的文件），因此同时将其交换为链接没有帮助。拒绝通过符号链接进行写入。根之外的路径得到的答案是一样的，不管那里是否有东西存在。只读取常规文件。
-   **默认为只读：** 写工具只存在于 `--allow-write`。它们专门创建文件，并仅在调用通过时替换现有文件 `"overwrite": true`，通过临时文件和重命名；替换保留文件的权限，只读文件不被替换。可以写入根目录中的任何文件名，也可以写入点文件，例如 `.gitignore`； 选择相应的根。
-   **限制:** 上面的文件 `--max-file-size` 被拒绝阅读和写作，结果在上面 `--max-response-chars` 是吗？`read_table`)或拒绝。xlvane阅读器将其限制应用于不可信文件（ZIP炸弹、没有dtd或实体的XML、xlvane 1.1.1的预算）。 `validate` 最多列出1000个问题(`problemsTotal` 计数)。
-   **文件内容为data：** 值、工作表名称和其他文本来自文件，可能包含任何文本，也包括旨在影响模型的文本。服务器将其作为数据返回，而不进行解释。
-   **不执行代码：** 永远不会运行宏，永远不会遵循外部链接，也不会计算公式。

## API

```ts
import { createServer, runCli } from '@xlvane/mcp';
```

`createServer({ roots, allowWrite, maxFileBytes, maxRows, maxResponseChars })` 返回一个 `McpServer` 连接：连接到任何运输工具； `runCli(args)` 是命令行。

## 链接

-   每个版本的变化： [CHANGELOG.md](https://github.com/DevXord/xlvane/blob/main/CHANGELOG.md)
-   bug和问题： [GitHub的问题](https://github.com/DevXord/xlvane/issues)
-   报告漏洞： [SECURITY.md](https://github.com/DevXord/xlvane/blob/main/SECURITY.md)

许可协议:麻省理工学院。MCP SDK是在Apache-2.0下授权的。

## 常见问题

### @xlvane/mcp 是什么？

用于XLSX文件的MCP服务器：检查，读取，写入，编辑，转换，比较和验证工作簿与xlvane，限制在开始时给定的目录。

### 如何安装 @xlvane/mcp？

在项目目录运行 npm install @xlvane/mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 xlvane-mcp，可以用 npx xlvane-mcp 直接运行。

### @xlvane/mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @xlvane/mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @xlvane/mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @xlvane/mcp 可以商用吗？

@xlvane/mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @xlvane/mcp 还在维护吗？

最新版本 1\.2\.2 发布于 2026/11/03（今天）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/11/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。