# Spreadsheet MCP Server

このプロジェクトは、Google SpreadsheetのデータにアクセスするためのModel Context Protocol (MCP) サーバーです。LLMがスプレッドシート情報を直接利用できるようにします。

## 機能

- スプレッドシートの基本情報（シート一覧など）の取得
- 特定シートのデータの取得とマークダウン形式での整形
- MCPクライアント（Claude for Desktopなど）と統合

## インストール

```bash
# リポジトリのクローン
git clone https://github.com/your-username/spreadsheet-mcp-server.git
cd spreadsheet-mcp-server

# 依存関係のインストール
npm install

# 環境変数の設定
cp .env.example .env
# .envファイルを編集してGAS_WEB_APP_URLとGAS_API_KEYを設定

# ビルド
npm run build
```

## 環境変数の設定

サーバーの設定には、以下の環境変数が使用されます：

- `GAS_WEB_APP_URL`: Google Apps Script Web AppのURL
- `GAS_API_KEY`: Google Apps Script Web Appのアクセス用APIキー

これらの環境変数は `.env` ファイルに設定できます：

```
GAS_WEB_APP_URL=https://script.google.com/macros/s/your-deployment-id/exec
GAS_API_KEY=your-api-key
```

環境変数が設定されていない場合、サーバーはモックモードで動作し、実際のGoogleスプレッドシートにはアクセスしません。

## 使用方法

### スタンドアロンでの起動

```bash
npm start
```

### Claude for Desktopとの統合

Claude for Desktopの設定ファイル (`claude_desktop_config.json`) に以下を追加します：

```json
{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["<absolute-path-to-project>/build/index.js"]
    }
  }
}
```

環境変数を設定するには、以下のように`env`フィールドを追加します：

```json
{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["<absolute-path-to-project>/build/index.js"],
      "env": {
        "GAS_WEB_APP_URL": "https://script.google.com/macros/s/your-deployment-id/exec",
        "GAS_API_KEY": "your-api-key"
      }
    }
  }
}
```

設定ファイルは以下の場所にあります：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%AppData%\\Claude\\claude_desktop_config.json`

### MCP Inspectorでテスト

```bash
npx @modelcontextprotocol/inspector node build/index.js
```

## 提供するツール

### getSpreadsheet

スプレッドシートの基本情報と含まれるシート一覧を取得します。

**入力パラメータ**:
- `url`: スプレッドシートのURL

**出力**:
- スプレッドシート名、ID、シート一覧（行数・列数を含む）

### getSheetData

スプレッドシートの特定シートのデータを取得します。

**入力パラメータ**:
- `url`: スプレッドシートのURL
- `sheetName`: 取得するシート名

**出力**:
- シートデータ（マークダウンテーブル形式）

## 開発

### プロジェクト構造

```
src/
├── index.ts           # エントリポイント
├── server.ts          # MCPサーバー設定
├── config.ts          # 環境変数と設定管理
├── tools/             # ツール実装
│   ├── getSpreadsheet.ts
│   ├── getSheetData.ts
│   └── index.ts
├── api/               # API処理
│   ├── README.md      # API仕様
│   ├── spreadsheet.ts
│   └── types.ts
└── utils/             # ユーティリティ
    └── format.ts
```

### テスト

```bash
# 単体テスト実行
npm test

# ウォッチモードでテスト
npm run test:watch
```

## Google Apps Scriptとの連携について

このサーバーは、実際の使用時にはGoogle Apps ScriptのWeb Appと連携して動作します：

1. Google Apps Scriptで[Web App](https://developers.google.com/apps-script/guides/web)を作成する
2. Webアプリ側でスプレッドシートにアクセスするAPIを実装する（`api/README.md`参照）
3. APIキーを設定し、環境変数`GAS_WEB_APP_URL`と`GAS_API_KEY`で連携する

このアプローチにより、Google認証フローを回避し、スプレッドシートのセキュリティを維持できます。

環境変数が設定されていない場合は、モックモードで動作し、テスト用のデータが返されます。

## ライセンス

MIT