# qs-docs MCP

Google Docs をAPIで読み書きする自作stdio MCP。Docs API v1 直叩き（documents.get / batchUpdate）。
claude.ai の Google Drive コネクタは読み取り＋メタデータ更新しかできないので、本文の編集口はこちら。

## 場所
- 実体: `~/.claude/mcp/qs-docs/`（index.js / src/auth.js,docs.js / authorize.js）
- 認証情報: `~/.gmail-mcp-credentials.json` を流用（GCloud project qs-gmail-mcp・Internal）
- トークン: `~/.docs-mcp-tokens.db`（node:sqlite・account="default"）
- スコープ: documents + drive

## セットアップ
1. GCloud project qs-gmail-mcp で **Docs API** を有効化（Drive APIは qs-slides で有効化済み）
2. `cd ~/.claude/mcp/qs-docs && node authorize.js` → ブラウザで kazuki.ishizuka@ 承認
3. `~/.claude.json` の mcpServers に qs-docs 登録 → /mcp で reconnect

## ツール
読み取り
- get_structure(documentId) … ブロックの並び（見出し/段落/表・startIndex/endIndex付き）。編集indexの取得元
- get_outline(documentId) … 見出しだけ階層付き
- read_text(documentId) … 全文プレーンテキスト（表はタブ区切り）
- export_markdown(documentId, outPath?) … markdownで書き出し

書き込み
- delete_section(documentId, heading, includeHeading?, dryRun?) … 見出しで節を丸ごと削除
- delete_ranges(documentId, ranges[], dryRun?) … index範囲削除（内部で降順整列）
- delete_table_column(documentId, tableIndex, columnIndex, dryRun?) … 表の列削除
- replace_text(documentId, replacements[]) … 一括置換（replace省略で削除）
- insert_text(documentId, index, text)
- create_document(title, markdown?, folderId?) … markdown渡しで見出し・表つき新規作成
- raw_batch_update(documentId, requests[]) … 任意のDocs APIリクエスト

## 設計メモ / ハマりどころ
- **index は編集のたびにズレる**。1回の batchUpdate に複数の編集を積むときは必ず後ろ（endIndex大）から当てる。delete_ranges は内部で降順ソート済み
- **破壊的操作は dryRun を先に通す**。消える実テキストが返るので、それを見てから実行する
- 節の範囲＝「その見出し〜次の同レベル以上の見出しの直前」。最後の節は本文末尾-1まで（Docsは最終セグメントの改行を消せない）
- API未有効・スコープ不足のエラーは対処法込みに包んである（有効化URLがそのまま出る）
- 表の列削除は tableCellLocation.tableStartLocation.index を要求する。get_structure が返す表の startIndex がそれ