# Spreadsheet MCP Server

Google Spreadsheet 操作用の MCP (Model Context Protocol) サーバーです。
Cursor などの AI アシスタントから Google スプレッドシートを参照・操作できます。

## 機能

### 読み取り系ツール (Phase 1)

| ツール | 説明 |
|--------|------|
| `get_sheet_metadata` | シート一覧、列名、行数を取得 |
| `get_sheet_data` | 指定範囲のセルデータを取得 |
| `get_column_values` | 特定列の全値を取得 |
| `get_sheet_structure` | ヘッダー、データ型推定、サンプルデータを取得 |
| `search_in_sheet` | 特定文字列を検索 |
| `check_sheet_errors` | セルエラー（#REF!, #VALUE! 等）を検出 |

### 書き込み系ツール (Phase 2)

| ツール | 説明 |
|--------|------|
| `create_spreadsheet` | 新規スプレッドシートを作成 |
| `create_sheet` | 既存スプレッドシートにシートを追加 |
| `set_headers` | ヘッダー行を設定 |
| `append_rows` | データ行を追加 |

### 書式設定ツール (Phase 3)

| ツール | 説明 |
|--------|------|
| `format_sheet` | ヘッダースタイル、列幅、交互行カラーを設定 |
| `set_data_validation` | ドロップダウン、数値範囲などの入力規則を設定 |

## セットアップ

### 1. 依存関係のインストール

```bash
cd spreadsheet-mcp
npm install
```

### 2. ビルド

```bash
npm run build
```

### 3. 認証情報の設定

このサーバーは以下の認証情報ファイルを使用します：

- **Credential Store**: `./config/credentials.json`（自動作成）

初回実行時、ブラウザが開いて認証フローが始まります。個人の Google アカウントでログインして権限を許可してください。

### 4. Cursor への設定追加

Cursor の MCP 設定ファイル (`~/.cursor/mcp.json` または プロジェクトの `.cursor/mcp.json`) に以下を追加：

```json
{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["~/spreadsheet-mcp/dist/index.js"]
    }
  }
}
```

## 使用例

### シートの構造を確認

```
「このスプレッドシートの構造を見せて」
→ get_sheet_structure を使用
```

### 特定範囲のデータを取得

```
「Sheet1 の A1:D10 のデータを取得して」
→ get_sheet_data を使用
```

### 列の値パターンを確認

```
「D列の値のパターンを教えて」
→ get_column_values を使用
```

### 新規スプレッドシートを作成

```
「新しいスプレッドシートを作成して」
→ create_spreadsheet を使用
```

## プロンプトテンプレート

設定シートを作成する際のプロンプトテンプレートを用意しています：

📄 **[prompts/create-config-sheet.md](prompts/create-config-sheet.md)**

- 既存シートを参考にして新機能用シートを作成
- ゼロから設定シートを作成
- 具体的な使用例

## 安全性

書き込み系ツールには `dry_run` オプションがあります。
`dry_run: true` を指定すると、実際の変更は行わずにプレビューのみを表示します。

## 開発

```bash
# ビルド
npm run build

# 実行
npm start

# 開発（ビルド + 実行）
npm run dev
```

## ライセンス

MIT

# spreadsheet-mcp