# sheets-write-mcp-server

Google Sheets への**書き込み専用** MCP サーバー。[google-sheets-mcp-server](https://github.com/tg-tool/google-sheets-mcp-server)（読み取り専用）の対になる存在で、**読み取りツールは持たない**。読むだけなら readonly を使う。

## 設計思想

コミュニティ製の Sheets MCP は「アカウント内の全シートに読み書き可」という過剰権限になりがち。本サーバーは書き込みという破壊的操作を扱うため、全ツールが以下の**安全パイプライン**を通る：

```
whitelist（fail-closed）→ サイズ制限 → dry_run → 書込前スナップショット → 実行 → 監査ログ
```

- **ホワイトリスト**：`~/.config/sheets-write-mcp/allowed_spreadsheets.yaml` に登録された spreadsheet（さらに sheet 単位で絞り込み可）にしか書き込めない。ファイルが無い・壊れている場合は全拒否（fail-closed）。編集は即反映（再起動不要）
- **dry_run**：削除系ツール（clear_range / delete_rows / delete_columns / delete_sheet）は**デフォルトで dry_run=true**。実行計画と現在値のプレビューを返すだけで、明示的に `dry_run=false` を渡すまで何も起きない
- **書込前スナップショット**：上書き・削除される値（数式は数式文字列のまま）を `~/.local/share/sheets-write-mcp/rollback/` に保存してから書き込む。スナップショット取得に失敗したら書き込みは実行されない。spreadsheet ごとに直近50世代
- **監査ログ**：全操作（拒否・dry_run・エラー含む）を `~/.local/share/sheets-write-mcp/audit.jsonl` に1行1レコードで記録
- **サイズ制限**：1回の操作で 5,000 セル超は `force=true` が必要
- 外部送信は Google APIs のみ。第三者サーバー経由なし

### ロールバックの範囲

スナップショットが守るのは**値と構造**（行・列・シートの中身）。**セル書式（色・罫線・条件付き書式等）の復元は対象外**——書式事故は Google Sheets 本体の版履歴（ファイル > 変更履歴）で救済できるため、スナップショットの複雑化に見合わないと判断。`schema_version` フィールドがあるので将来拡張は可能。

## ツール（18本・3層）

| 層 | ツール | dry_run 既定 |
|---|---|---|
| L1 値 | `update_range` / `batch_update_values` / `append_rows` | false |
| L1 値 | `clear_range` | **true** |
| L2 構造 | `insert_rows` / `insert_columns` / `add_sheet` / `duplicate_sheet` / `rename_sheet` | false |
| L2 構造 | `delete_rows` / `delete_columns` / `delete_sheet` | **true** |
| L3 装飾 | `set_number_format` / `set_cell_style` / `set_conditional_format` / `set_data_validation` / `set_basic_filter` / `protect_range` | false |

- 数式は既定で数式として解釈される（`USER_ENTERED`）。`raw=true` で文字列として格納
- シート指定は名前・gid どちらでも可
- L3 は指定した項目だけを fields マスクで更新（触っていない書式は保持）
- 対象外：ピボット・グラフ（将来）／スプレッドシート自体の作成・削除・共有（Drive API 管轄）／表示・ツール・拡張機能メニュー（API 非対応）

## セットアップ

```bash
git clone <this repo> && cd sheets-write-mcp-server
python3 -m venv .venv && .venv/bin/pip install -e .

# 1. OAuth クライアント（readonly と同じものを使い回せる）
mkdir -p ~/.config/sheets-write-mcp
cp ~/.config/sheets-mcp/credentials.json ~/.config/sheets-write-mcp/

# 2. ホワイトリスト作成
cat > ~/.config/sheets-write-mcp/allowed_spreadsheets.yaml <<'EOF'
spreadsheets:
  - id: "<spreadsheet ID>"
    note: "（用途メモ）"
    writable_sheets: "*"        # または ["シート名", ...]
EOF

# 3. OAuth を一度通す（ブラウザが開く。token.json が書き込みスコープで生成される）
.venv/bin/python -c "from sheets_write_mcp.auth import _load_credentials; _load_credentials()"
```

トークンは readonly（`spreadsheets.readonly`）とは別ファイル・別スコープ（`spreadsheets`）。

## Claude Code / Claude Desktop への登録

```bash
claude mcp add sheets-write -- /path/to/sheets-write-mcp-server/.venv/bin/sheets-write-mcp
```

Claude Desktop（`claude_desktop_config.json`）で readonly と並走：

```json
{
  "mcpServers": {
    "sheets-readonly": { "command": "/path/to/sheets-mcp-server/.venv/bin/sheets-mcp" },
    "sheets-write":    { "command": "/path/to/sheets-write-mcp-server/.venv/bin/sheets-write-mcp" }
  }
}
```

## 環境変数

| 変数 | デフォルト |
|---|---|
| `SHEETS_WRITE_MCP_CREDENTIALS` | `~/.config/sheets-write-mcp/credentials.json` |
| `SHEETS_WRITE_MCP_TOKEN` | `~/.config/sheets-write-mcp/token.json` |
| `SHEETS_WRITE_MCP_WHITELIST` | `~/.config/sheets-write-mcp/allowed_spreadsheets.yaml` |
| `SHEETS_WRITE_MCP_DATA_DIR` | `~/.local/share/sheets-write-mcp/` |

## 開発

```bash
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -q       # 110+ tests
.venv/bin/python -m ruff check src/ tests/
```

`grid.py`（A1⇔GridRange 変換）が範囲計算の単一障害点。1-indexed（ユーザー向け）と 0-indexed（GridRange）の変換ミスは「隣の行を消す」事故に直結するため、境界値テストを最も厚くしている。

## 既知の制約

- スナップショットは `valueRenderOption=FORMULA` で取得するため、数式セルの**計算結果値**は保存されない（数式は保存され、復元時に再計算される）
- `rename_sheet` 後はホワイトリストのシート名指定が旧名のままになる——リネーム後に yaml を更新すること