Spreadsheet MCP Server (@zephyr-mcp/spreadsheet)

English | 中文

Spreadsheet MCP Server (@zephyr-mcp/spreadsheet)

TypeScript 製のモデルコンテキストプロトコル（MCP）サーバーです。LLM または API との連携を通じて、CSV/XLSX スプレッドシートファイルの表示、フィルタリング、並べ替え、更新を行えます。

機能

• スプレッドシートの情報を表示し、行をプレビューします
• 列と条件を指定して行をフィルタリングします
• 列を指定して行を並べ替えます（昇順／降順）
• 既存の XLSX ファイルに新しいシートを追加するか、新しいファイルを作成します
• CSV ファイルと XLSX ファイルに対応しています
• 2 次元配列を含む JSON 文字列として結果を返します（表示／フィルタリング／並べ替え用）
• 技術スタック：TypeScript、fastmcp、papaparse、xlsx、zod

インストールと使用方法

このパッケージは npx で直接実行するように設計されています。通常、インストールは不要です。

前提条件

• Node.js v18+（LTS バージョンを推奨）

MCP サーバーの実行

stdio モードでサーバーを起動します（Cline などのツールとの連携に使用します）。

npx @zephyr-mcp/spreadsheet

サーバーが起動し、標準入出力を介して MCP コマンドを待ち受けます。

開発

セットアップ

1. リポジトリをクローンします：

   git clone https://github.com/your-username/spreadsheet-mcp.git # 替换为你的仓库 URL
   cd spreadsheet-mcp
   

2. 依存関係をインストールします：

   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-mcp scope への公開権限があることを確認してください。
• CI でリリースを実行する場合は、GitHub リポジトリに必要な secrets を設定してください（例：NPM_TOKEN。デフォルトの token 権限が不十分な場合は、GitHub Release の作成に使用する PAT_TOKEN も必要になることがあります）。

手順：

1. ローカルの main ブランチが最新であり、作業ディレクトリに変更がないことを確認します。
2. リリース予定の変更がすべて main ブランチにマージされていることを確認します。
3. リリースコマンドを実行します：

   npm run release
   

4. release-it の案内に従って、次のプロセスを進めます：
   • Conventional Commits に基づいて次のバージョン番号を決定します。
   • 設定済みのフックを通じてテスト（npm test）とビルド（npm run build）を実行します。
   • CHANGELOG.md を更新します。
   • 変更（package.json、CHANGELOG.md）をコミットします。
   • Git タグを作成します。
   • コミットとタグをリモートリポジトリにプッシュします。
   • パッケージを npm に公開します。
   • GitHub Release を作成します。

コントリビューション

コントリビューションを歓迎します。次のガイドラインに従ってください。

1. ブランチ： 機能追加またはバグ修正のために、新しいブランチを作成してください。
2. コミット： Conventional Commits の規約に従ってコミットメッセージを記述してください。これは release-it による Changelog の自動生成とバージョン番号の更新に不可欠です。
3. コードスタイル： 一貫したコードスタイルを維持してください（ESLint などの linter の導入を検討できます）。
4. テスト： 新機能またはバグ修正のテストを tests/ ディレクトリに追加してください。すべてのテストが通ることを確認してください（npm test）。
5. プルリクエスト： main ブランチにプルリクエストを送信してください。

プロジェクト構成

.
├── .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：ファイル情報を表示し、指定した行数をプレビューします。ファイル情報とプレビューデータ（2 次元配列）を含む JSON 文字列を返します。rows パラメーターでプレビューする行数を指定します（0 はヘッダーのみ、デフォルトは 10、最大値はありません）。
• filter_spreadsheet：列と条件を指定して行をフィルタリングします。フィルタリング結果（2 次元配列）を含む JSON 文字列を返します。rows パラメーターで返す最大行数を指定します（デフォルトは一致するすべての行で、最大値はありません）。
• sort_spreadsheet：列を指定して行を並べ替えます。並べ替え結果（2 次元配列）を含む JSON 文字列を返します。rows パラメーターで返す最大行数を指定します（デフォルトはすべての行で、最大値はありません）。
• update_spreadsheet_with_new_sheet：データを XLSX ファイルの新しいシートに書き込みます

ライセンス

MIT License © 2025 Zephyr

作者

Zephyr