English | 中文
一个基于 TypeScript 的模型上下文协议 (MCP) 服务器，用于通过 LLM 或 API 集成来查看、筛选、排序和更新 CSV/XLSX 电子表格文件。
- 查看电子表格信息并预览行
- 按列和条件筛选行
- 按列排序行 (升序/降序)
- 向现有 XLSX 文件添加新工作表或创建新文件
- 支持 CSV 和 XLSX 文件
- 以包含二维数组的 JSON 字符串形式返回结果 (用于查看/筛选/排序)
- 技术栈：TypeScript, fastmcp, papaparse, xlsx, zod
此包设计为直接使用 npx 运行。典型用法无需安装。
- Node.js v18+ (推荐 LTS 版本)
在 stdio 模式下启动服务器 (用于与 Cline 等工具集成):
npx @zephyr-mcp/spreadsheet服务器将启动并通过标准输入/输出监听 MCP 命令。
- 克隆仓库：
git clone https://github.com/your-username/spreadsheet-mcp.git # 替换为你的仓库 URL cd spreadsheet-mcp
- 安装依赖：
npm install
使用 tsx 进行带热重载的开发：
npm run dev使用 Vite 将 TypeScript 编译为 JavaScript (输出到 dist/):
npm run build使用 Vitest 运行测试：
# 运行所有测试一次并生成覆盖率报告
npm test
# 在监视模式下运行测试
npm run test:watch本项目使用 release-it 自动化发布流程，包括版本号更新、Changelog 生成、Git 打标、npm 发布以及创建 GitHub Releases。
发布先决条件：
- 确保你拥有仓库的推送权限。
- 确保你拥有在 npm 上发布到
@zephyr-mcpscope 的权限。 - 如果在 CI 中运行发布，请在 GitHub 仓库中配置必要的 secrets (例如
NPM_TOKEN，如果默认 token 权限不足，可能还需要用于创建 GitHub Release 的PAT_TOKEN)。
步骤：
- 确保你的本地
main分支是最新状态，并且工作目录是干净的。 - 确保所有计划发布的变更都已合并到
main分支。 - 运行发布命令：
npm run release
release-it将引导你完成整个过程：- 根据 Conventional Commits 确定下一个版本号。
- 通过配置的钩子运行测试 (
npm test) 和构建 (npm run build)。 - 更新
CHANGELOG.md。 - 提交变更 (
package.json,CHANGELOG.md)。 - 创建 Git 标签。
- 将提交和标签推送到远程仓库。
- 将包发布到 npm。
- 创建 GitHub Release。
欢迎贡献！请遵循以下指南：
- 分支： 为你的功能或错误修复创建一个新分支。
- 提交： 遵循
release-it自动生成 Changelog 和更新版本号至关重要。 - 代码风格： 保持一致的代码风格 (可以考虑添加 ESLint 等 linter)。
- 测试： 为新功能或错误修复在
tests/目录下添加测试。确保所有测试通过 (npm test)。 - Pull Request: 向
main分支提交 Pull Request。
.
├── .github/workflows/ # GitHub Actions 工作流 (CI)
│ └── ci.yml
├── dist/ # 编译后的 JavaScript 输出 (Git 忽略)
├── node_modules/ # 依赖项 (Git 忽略)
├── src/ # 源代码
│ ├── server.ts # MCP 服务器入口, 工具注册
│ └── spreadsheetUtils.ts # 电子表格解析、筛选、格式化、写入
├── tests/ # 单元/集成测试
│ └── server.test.ts
├── .gitattributes
├── .gitignore
├── .release-it.json # release-it 配置
├── CHANGELOG.md # 自动生成的更新日志
├── LICENSE
├── package.json
├── README.md # 本文档 (中文)
├── README.en.md # 英文文档
├── tsconfig.json
└── vite.config.ts # Vite & Vitest 配置
view_spreadsheet: 查看文件信息并预览指定行数。返回包含文件信息和预览数据（二维数组）的 JSON 字符串。rows参数指定预览行数（0 表示仅表头，默认为 10，无最大限制）。filter_spreadsheet: 按列和条件筛选行。返回包含筛选结果（二维数组）的 JSON 字符串。rows参数指定返回的最大行数（默认为所有匹配行，无最大限制）。sort_spreadsheet: 按列排序行。返回包含排序结果（二维数组）的 JSON 字符串。rows参数指定返回的最大行数（默认为所有行，无最大限制）。update_spreadsheet_with_new_sheet: 将数据写入 XLSX 文件的新工作表
MIT License © 2025 Zephyr
Zephyr