verified-googledocs-mcp

verified-googledocs-mcp

書き込みに証拠が伴う、Google Docs 用の MCP サーバーです。すべての変更ツールは、書き込み後にドキュメントから対象コンテンツを再読み込みし、実際に変更された内容の証拠を返します。証拠には変更前後の抜粋、一致件数、変更前後のドキュメントのリビジョンが含まれます。編集が反映されていない場合、ツールが成功を報告することはありません。

ステータス： 20 個すべてのツールを実装済みで、オフラインのユニットテストスイートでテストし、ライブテストスイートで実際の Google Docs API と Drive API に対して検証しています。最初の 14 個は正式なライブ受け入れゲートに合格しており、リリース前にゲートを再実行します。uvx verified-googledocs-mcp でインストールできます。ステータスをご覧ください。

問題点

エージェントから汎用の Workspace MCP サーバー経由で Google Docs を操作すると、気づきにくく、コストのかかる問題が起こりがちです。

• 1 つのタブを対象とした findAndReplace が、気づかないうちにドキュメント内のすべてのタブを編集します。
• ドキュメントに曲がった引用符やノーブレークスペースが含まれていて、検索クエリには含まれていないため、理由も示されずに検索結果が「0 件」になります。
• 1 か所だけ置換するつもりが、繰り返し出てくる文に一致して、両方が置き換えられます。
• 「コメントを解決」する呼び出しが成功を返しても、コメントは未解決のままです。
• コメントの一覧表示で、提案された編集が完全に見落とされます。
• Markdown のマージによって文字化けしたテキストが挿入され、人が気づくのは数日後です。

これらには、タブを指定するようエージェントに指示する、引用符を正規化して再試行する、書き込みのたびに再読み込みする、解決結果を決して信用しないといった手順上の回避策があります。誰かが忘れるまでは、こうした指示で問題を防げます。このサーバーは、その規律を決定論的に機能するプロトコルに組み込みます。

検証済み書き込みの契約

すべての変更ツールは同じパイプラインを実行します。タブを読み込み、対象を特定し、リビジョンの前提条件を指定して編集を適用し、タブを再度読み込み、2 回目の読み込みに基づいた証拠を返します。戻り値は API 応答の単なるコピーではなく、サーバー側で再読み込みした結果に裏付けられた、呼び出し後のドキュメント状態についての報告です。

// replace_text(doc_id, tab_id, find="teh", replace="the", expected_matches=1)
{
  "applied": true,
  "match_count": 1,
  "rung": "exact",                 // which normalization rung matched
  "before": "...±200 chars around the edit, pre-write...",
  "after":  "...the same span, re-read after the write...",
  "revision_before": "ALm37BX...",
  "revision_after":  "ALm37Cy...",
  "audit_logged": true
}

問題がある場合、ツールはエージェントが推測せずに 1 回の往復で対処できる、型付きエラーを含む診断付きの明確な失敗を返します。

{
  "error_code": "MATCH_COUNT_MISMATCH",
  "message": "expected 1 match(es) but found 3 at rung 'exact'",
  "diagnostics": { "expected": 1, "actual": 3, "spans": [ /* every location */ ] },
  "retryable": false
}

保証の根拠

• デフォルトでタブを指定。 編集ツールでは tab_id の明示的な指定が必要です。ドキュメント全体を置換する機能はないため、1 つのタブへの編集がカバーレターや付録のタブに及ぶことはありません。
• 正規化の段階的な適用。 検索では、完全一致、曲がった引用符とまっすぐな引用符の同等性、ノーブレークスペースと連続する空白の同等性、ソフトハイフンの除去の順に試し、どの段階で一致したかを報告します。一致件数が 0 件の場合は、見つかった最も近い不一致箇所を含めて返します。
• 一致件数のガード。 expected_matches のデフォルト値は 1 です。実際の件数が異なる場合、ツールは編集を行わず、すべての一致箇所を返します。
• リビジョンの前提条件。 書き込みには、事前読み込み時の writeControl.requiredRevisionId が設定されます。そのため、操作中にドキュメントが変更されると、内容を確認せずに編集するのではなく、API が操作を拒否します。find_sections のセクション範囲には、算出時のリビジョンが記録され、古くなった範囲の適用は拒否されます。
• UTF-16 に準拠。 一致箇所の範囲は、Docs API がインデックス付けに使用する UTF-16 コード単位に対応付けられます。そのため、絵文字、結合文字、その他の補助平面文字があっても、編集位置がずれることはありません。
• 監査証跡。 すべての変更をローカルの JSONL ログに 1 行ずつ追記します。追記はベストエフォートで行い、書き込みが失敗することはありません。記録できなかった場合は、その旨が証拠に示されます（audit_logged: false）。

ファミリーごとの証拠

保証される内容は一律のペイロードではなく、ファミリーごとの不変条件です。各ファミリーは書き込み後にドキュメントを再読み込みし、そのファミリーが担う特性を証明します。すべての変更ツールには、revision_before、revision_after、audit_logged も含まれます。

ファミリー	ツール	証明する内容
テキスト編集	replace_text	match_count が expected_matches と一致すること、rung が一致した正規化パスを示すこと、before／after が編集範囲の前後それぞれ±200文字の抜粋であること。after は書き込み後に再読み込みした内容です
スタイル編集	format_text	runs_before／runs_after は、テキスト差分ではなく、一致した各範囲と重なる実際の textRun スタイルフラグを示します。compiled_request_kinds に updateTextStyle しか含まれないことで content_mutated: false が証明されます。冪等な再実行では書き込みが行われないため、style_mutated は false です
Markdown 範囲	replace_range_markdown、replace_tab_markdown、append_markdown	structural_match（書き込まれた Markdown が往復変換され、リストのネストの深さ、順序付き／順序なし、リンク先も保持されること）、input_blocks と post_blocks の件数、ミスマッチがあればその内容を示す structural_diff リスト。すべてのレスポンスには write_status（not_written／written_unverified／written_verified）と retry_safe も含まれます
構造	insert_image	inline_object_confirmed — 書き込み後のスキャンで、アンカー段落にインラインオブジェクトが見つかったこと
コメントの状態	add_anchored_comment、reply_to_comment、resolve_comment	再取得した resolved フラグ、reply_count、content、quoted_text、author。解決が反映されなかった場合は、成功を返すのではなく COMMENT_STILL_OPEN を返します
テーブル	replace_table_row、insert_table	replace_table_row：row_before／row_after を再読み込みし、cells_match で確認します。insert_table：table_confirmed と、確認済みの寸法および first_row を返します

読み取りおよび同期ツール（read_document、list_tabs、find_sections、 list_open_items、get_comment_thread、diff_tab_vs_file、list_tables、 get_table）は変更を加えず、applied／証拠のペイロードも含みません。 export_pdf もこの意味で読み取り／エクスポートツールです。ドキュメントには 何も変更が加わらないため、applied キーではなく、ファイル情報 （bytes_written、sha256、page_count）を返します。

ドライラン

8 つの変更ツール（replace_text、format_text、replace_range_markdown、 replace_tab_markdown、append_markdown、insert_image、replace_table_row、 insert_table）は dry_run=true を受け付けます。API への書き込みは行われず、レスポンスには applied: false、空の revision_after（書き込みがないため、新しいリビジョンはありません）、 audit_logged: false が含まれます。また、replace_text の場合は、事前読み取り結果に置換内容を 反映して予測した after 抜粋が、format_text の場合は、事前読み取り結果の runs に要求された スタイルを重ねて予測した runs_after が含まれます。format_text はさらに、ドライランかどうかに かかわらず、一致したテキストに要求されたスタイル値がすべてすでに適用されている場合は、書き込みを 一切行いません。これはツール本来の冪等な無操作処理であり、dry_run 固有の動作ではありません。 replace_table_row と insert_table では、dry_run によってインデックスの有効性を確実に判定でき ます。dry_run が true でも false でも、同じ組み立て済みリクエストリストを使ってインデックスを シミュレートするため、ドライランに合格すれば実際の書き込みも必ず成功します。編集を確定する前に、 指定した検索条件で正しい範囲が見つかることを確認するために使用してください。

3 つの Markdown ツールでは、dry_run は構造予測にも適用されます（issue #65）。batchUpdate の 前に、コンパイル済みリクエストが予測するブロック構造（ネスト、番号付き／番号なし、見出し、表）を、 解析された入力 Markdown と比較します。この比較は dry_run でも実際の書き込みでも同じように行われ ます。不一致がある場合は、ドキュメントに手を加える前に STRUCTURE_PREDICTION_FAILED で拒否され ます。書き込み後に検証が失敗したと判明することはありません。この 3 つのツールのすべてのレスポンス （ドライラン、拒否、書き込み済み）には write_status が含まれ、値は not_written（ドライラン、 または事前チェックでの拒否：INDEX_SIMULATION_FAILED、STRUCTURE_PREDICTION_FAILED、もしくは 構造損失のガードレール）、written_unverified（batchUpdate が送信され受け付けられたものの、 書き込み後の再読み取りで一致が確認できなかった状態：VERIFICATION_FAILED）、または written_verified（確認済み）のいずれかです。さらに retry_safe ブール値も含まれます （written_unverified の場合のみ false です。変更状態が確認できない呼び出しを再試行すると、 最初の変更が確認できないまま、さらにもう一度変更してしまうおそれがあるためです。自動ロールバックは ありません。Docs にはリビジョンを復元するエンドポイントがなく、補償目的の Markdown 再書き込みも データ損失を伴うため、needs_manual_restore: true の場合は Docs のバージョン履歴から復元する必要が あります）。write_status／retry_safe は追加項目です。既存の applied フィールドの意味は、これまで の説明どおり変更されません。

8 つすべてのツールで、提案のない対象タブが必要です。 すべての変更ツールは、 suggestionsViewMode=PREVIEW_WITHOUT_SUGGESTIONS を指定した読み取り結果を使って書き込みインデックス を計算しますが、実際の書き込みは、保留中の提案を含むドキュメント本来のインデックス空間に対して 行われます。対象タブに保留中の挿入または削除の提案がある場合、これら 2 つのインデックス空間は 一致せず、書き込み位置がずれてしまいます。そのため、誤った位置への書き込みを黙って実行するリスクを 避けるため、すべての変更ツールは SUGGESTIONS_PRESENT で拒否します（dry_run と実行時の両方）。 まず Docs UI で保留中の提案を承認または却下してから、再試行してください（issue #56）。

ツール

用途に応じて選べる 20 個の専用ツールです。実際のドキュメントワークフローで使われる機能に絞り、 150 個のツールを備えた Workspace サーバーの機能を置き換えます。

読み取りと構造

ツール	機能
read_document	タブを Markdown、構造化された位置情報とスタイル runs、または見出しのみのアウトラインとして読み取ります
list_tabs	タブ ID、タイトル、ネストを一覧表示します
find_sections	見出しを検索し、ドキュメントのリビジョンが付与された範囲を返します
list_tables	タブ内の最上位の表をすべて、位置、サイズ、直前の見出しの情報とともに一覧表示します
get_table	1 つの表のセル全体を読み取ります

編集（検証済み、タブ単位）

ツール	機能
replace_text	タブ内で検索・置換します。正規化の段階的適用と一致ガードを備えています
format_text	updateTextStyle のみを使用して、一致したテキスト範囲に太字・斜体・下線を適用します。コンテンツは変更せず、結合セルを含む表内でも安全に使えます
replace_range_markdown	範囲を指定してセクションを Markdown に置き換えます
replace_tab_markdown	タブ全体のコンテンツを Markdown に置き換えます
append_markdown	タブに Markdown を追加します
insert_image	引用したアンカーまたは見出しの位置に画像を挿入します
replace_table_row	既存の表の1行を、プレーンテキストのセルでその場で上書きします
insert_table	insert_image と同様にアンカー位置を指定して、行データを入力した新しい表を挿入します

コメントと提案

ツール	機能
list_open_items	未解決のコメントおよび保留中の編集提案を一覧表示します。tab_id または include_all_tabs=true を渡してください
get_comment_thread	コメントの返信スレッド全体を読み取ります
add_anchored_comment	引用したテキストにアンカーを付けてコメントを追加します
reply_to_comment	コメントに返信します
resolve_comment	コメントを解決し、再クエリして実際に解決済みになったことを確認します

同期とエクスポート

ツール	機能
diff_tab_vs_file	タブの Markdown とローカルファイルを比較します
export_pdf	ドキュメント全体を PDF としてローカルパスにエクスポートします。レンダリング結果からページ数を可能な範囲で測定します

ステータス

段階的に構築しており、各ツールにはスタブではなく検証機能とテストが含まれています。

領域	状態
OAuth（verified-googledocs-mcp auth）、トークンキャッシュ	完了
read_document、list_tabs、find_sections	完了
検証カーネル（ロケーター、エラーエンベロープ、監査）	完了
replace_text（検証済み）＋適用ミドルウェア	完了
コメントツール＋list_open_items	完了
Markdown 書き込みツール＋diff_tab_vs_file	完了
表ツール（list_tables、get_table、replace_table_row、insert_table）＋export_pdf	完了。0.2.0 でリリース
format_text（スタイルのみの検証済み編集）	完了。0.2.0 でリリース
ライブ受け入れゲート	初回リリース分は完了 — レポート。リリース前に再実行してください
PyPI パッケージ化＋公開ワークフロー	完了。初回リリースは v0.1.0
MCP レジストリへの掲載	v0.1.0 で公開済み

インストール

このサーバーはご自身の OAuth 認証情報を使って Google と通信します。そのため、Google Cloud での設定は一度だけ行い、その後サーバーを MCP クライアントに登録します。

1. Google Cloud プロジェクト（OAuth 認証情報）

1. Google Cloud プロジェクトを作成し、Google Docs API と Google Drive API を有効にします（「API とサービス」→「ライブラリ」）。
2. OAuth 同意画面を設定します。ユーザータイプは 外部、公開ステータスは テストに設定し、テストユーザーにご自身の Google アカウントを追加します。（テストモードが重要です。アプリは登録したテストユーザーだけが利用でき、Google の審査に申請する必要はありません。）
3. タイプが デスクトップアプリの OAuth クライアント ID を作成し、クライアントシークレットの JSON を ~/.config/verified-googledocs-mcp/credentials.json にダウンロードします。（VERIFIED_GOOGLEDOCS_MCP_CREDENTIALS で保存先を変更できます。）

2. ターミナルで一度だけ認証する

uvx verified-googledocs-mcp auth

ブラウザーが開き、同意手続きが完了します。アプリは未検証でテストモードのため、Google に **「このアプリは Google によって確認されていません」**という画面が表示されます。詳細設定 → verified-googledocs-mcp（安全ではないページ）に移動をクリックして続行してください。個人用のデスクトップクライアントでは想定される動作です。ご自身のアプリに、ご自身としてローカルで実行する形でアクセスを許可しています。その後、更新可能なトークンが ~/.config/verified-googledocs-mcp/token.json にキャッシュされます。MCP クライアントはサーバーをヘッドレスで起動するため、認証はここでのみ実行され、サーバー内では実行されません。

3. 実行する

uvx verified-googledocs-mcp           # downloads + runs in one step
# or: pip install verified-googledocs-mcp

次に、サーバーを MCP クライアントに登録します。

ソースから実行する場合。 ローカルのクローンから実行するには、次のようにします。

git clone https://github.com/michaelrobertsutton/verified-googledocs-mcp
cd verified-googledocs-mcp
uv run verified-googledocs-mcp

Claude Code

プロジェクトローカルの .mcp.json がリポジトリに含まれています。プロジェクトをクローンして開くと、Claude Code が自動的に認識するため、手動で設定する必要はありません。

git clone https://github.com/michaelrobertsutton/verified-googledocs-mcp
cd verified-googledocs-mcp
claude  # .mcp.json is loaded automatically

すべてのプロジェクトで使用する場合（ユーザースコープ）。 ユーザースコープに一度だけ登録します。

claude mcp add verified-googledocs-mcp --scope user -- uvx verified-googledocs-mcp

これにより ~/.claude.json に書き込まれ、このマシン上のすべての Claude Code セッションでサーバーを利用できるようになります。uvx が Claude Code の PATH にない場合は、フルパスを使用してください（which uvx で確認できます）。

Claude Desktop およびその他のクライアント

ほとんどのクライアントでは、標準の mcpServers 設定ブロックを使用します。クライアントの設定ファイルに次の内容を追加してください。

{
  "mcpServers": {
    "verified-googledocs-mcp": {
      "command": "uvx",
      "args": ["verified-googledocs-mcp"]
    }
  }
}

ヘッドレスクライアントでの PATH に関する注意： Claude Desktop などのクライアントは、Homebrew やユーザーローカルの bin ディレクトリが含まれていない可能性のある最小限の PATH で、サブプロセスとしてサーバーを起動します。uvx が見つからない場合は、フルパス（"command": "/opt/homebrew/bin/uvx"）を使用してください。which uvx で確認できます。Apple Silicon では Homebrew のプレフィックスは /opt/homebrew、Intel Mac では /usr/local です。

起動タイムアウトに関する注意。 初回の uvx 起動時にはパッケージとその依存関係がダウンロードされるため、クライアントの MCP 起動タイムアウトを超え、接続に失敗することがあります。ターミナルで auth コマンド（uvx verified-googledocs-mcp auth）を一度実行して、キャッシュを事前に準備してください。いずれにしても実行するコマンドであり、パッケージが uvx キャッシュにインストールされるため、クライアントの起動が速くなります。

ソースから実行する場合。 PyPI からではなく、ローカルクローンから実行する場合：

{
  "mcpServers": {
    "verified-googledocs-mcp": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["run", "verified-googledocs-mcp"],
      "cwd": "/path/to/verified-googledocs-mcp"
    }
  }
}

ログ／stderr。 サーバーは stderr にログを出力します。MCP クライアントはログを取得しますが、インラインでは表示しません。接続またはツール呼び出しに失敗した場合は、クライアントの MCP ログを確認してください。macOS の Claude Desktop の場合は ~/Library/Logs/Claude/mcp*.log にあります。そこに AUTH_EXPIRED というエンベロープがある場合、トークンがないか、有効期限が切れています。auth コマンドを再実行してください。

サーバーは documents と drive のスコープを使用します（コメントには Drive が必要です）。認証情報のパスは VERIFIED_GOOGLEDOCS_MCP_CREDENTIALS で上書きできます。

セキュリティと権限

これはシングルユーザー向けのローカルサーバーです。MCP クライアントによって起動され、stdio 経由でユーザー自身として動作します。ネットワークリスナーもホスト型サービスも共有認証情報もありません。ユーザー自身の Google 権限のみを使用します。

• スコープ。 documents と drive を要求します。drive スコープ全体は編集だけに必要な範囲より広いものの、コメントと提案のツール（すでにアクセス権のあるドキュメントに関するコメントの一覧表示、返信、解決）は、より範囲の狭い drive.file スコープではアクセスできない、任意の既存ファイルに対して Drive API 経由で動作します。drive はツール一式全体をカバーする最小限のスコープです。コメントツールが不要であれば、フォークしてより狭いスコープに変更できます。
• 保存中の認証情報。 OAuth クライアントシークレットは ~/.config/verified-googledocs-mcp/credentials.json に保存され、キャッシュされたトークン（更新トークンを含む）は所有者のみがアクセスできる権限（0600、0700 のディレクトリ内）で ~/.config/verified-googledocs-mcp/token.json に書き込まれます。どちらもシークレットとして扱ってください。更新トークンが漏えいすると、Google アカウントのセキュリティ設定で取り消すまで、drive と documents の全アクセス権が付与されます。どちらのファイルもコミットされることはありません（両方とも gitignore の対象です）。
• 監査ログ。 変更操作のたびに ~/.local/state/verified-googledocs-mcp/audit.jsonl（こちらも 0600）に追記されます。各行には、タイムスタンプ、ドキュメント ID、タブ ID、ツール名、エビデンスのペイロードが記録されます。ペイロードには変更前後のコンテンツ抜粋が含まれます。抜粋なしでメタデータのみを記録するには、環境変数 VERIFIED_GOOGLEDOCS_MCP_AUDIT_EXCERPTS を偽と評価される値（0、false、no、off）に設定します。その場合、before／after フィールドは "[redacted; N chars]" に置き換えられ、その他のフィールドはすべて保持されます。ログの保存先は XDG_STATE_HOME で上書きできます。
• ローカルファイルとの差分。 diff_tab_vs_file はローカルファイルを読み込み、Doc のタブとディスク上の Markdown を比較します。読み込み前にシンボリックリンクを解決し、VERIFIED_GOOGLEDOCS_MCP_ALLOWED_FILE_ROOTS（プラットフォーム形式のパスリスト。デフォルトはサーバープロセスの作業ディレクトリではなく、ユーザーのホームディレクトリ）配下のパスのみを許可します。MCP クライアントでは通常、このサーバーを特定のリポジトリ（例：--directory /path/to/GoogleDocs-MCP）に固定して登録する一方、差分の対象は呼び出し元が実際に作業している別のプロジェクトにあることがほとんどです。そのため、ホームディレクトリをデフォルトにしています。起動ディレクトリに限定すると、リポジトリをまたぐ差分がすべてデフォルトで失敗してしまうためです。さらに範囲を狭める（例：単一のリポジトリに戻す）場合や、範囲を広げる場合は、サーバープロセスで VERIFIED_GOOGLEDOCS_MCP_ALLOWED_FILE_ROOTS を設定し、ディレクトリを : 区切り（Windows では ; 区切り）で指定してからサーバーを再起動してください。拒否されたパスのエラーには環境変数の名前と現在設定されている allowed_roots が含まれるため、不足しているものを正確に確認できます。これは実際の境界であり、無制限ではありません。たとえば、エージェントが /etc/passwd や他のユーザーのホームディレクトリとの差分を要求しても拒否されます。ホームディレクトリ全体をデフォルトで許可するため、ドキュメントの内容がエージェントをだまして認証情報を読み込ませる（プロンプトインジェクション）ことも防ぐ必要があります。たとえば、「~/.ssh/id_rsa との差分を取る」と指示する段落があるケースです。そのため、ホームディレクトリ配下の .ssh、.aws、.gnupg、.netrc、.git-credentials、.config/gh、.docker/config.json、.npmrc は、設定済みの許可ルートにかかわらず常に拒否リストに含まれます。また、VERIFIED_GOOGLEDOCS_MCP_MAX_DIFF_FILE_BYTES（デフォルトは 1000000）を超えるサイズのファイルも拒否されます。export_pdf の出力パスにも同じポリシーが適用されます。同じ VERIFIED_GOOGLEDOCS_MCP_ALLOWED_FILE_ROOTS の許可リストと、例外のない同じ認証情報パス拒否リストが適用されるため、PDF の出力先が ~/.ssh になる（またはそこに上書きされる）ことも、差分処理で ~/.ssh を読み込むことと同様にできません。

エラーコード

失敗時には、型付きエンベロープ（error_code、message、diagnostics、retryable）が返されます。

コード	意味
ZERO_MATCH	正規化手順をすべて実行しても対象が見つかりません。診断情報には最も近い不一致候補が含まれます
MATCH_COUNT_MISMATCH	expected_matches と異なる件数が見つかりました。編集は行われず、すべての位置が返されます
REVISION_CONFLICT	読み取り後、書き込み前にドキュメントが変更されました。再読み込みしてから再試行してください
VERIFICATION_FAILED	書き込みは実行されましたが、書き込み後の再読み込みで想定した最終状態を確認できませんでした
STALE_RANGE	ドキュメントが変更された後に find_sections の範囲が使用されました。find_sections を再実行してください
TAB_NOT_FOUND	不明な tab_id です。利用可能なタブが一覧表示されます
STRUCTURAL_BOUNDARY	マッチが段落または表のセルの境界をまたいでいます
UNSUPPORTED_MARKDOWN	サポート対象外の Markdown です。該当する構文が示されます
QUOTE_NOT_FOUND	コメントのアンカーテキストが見つかりません。最も近い候補が返されます
COMMENT_STILL_OPEN	解決が要求されましたが、再クエリの結果、コメントが未解決のままです
INVALID_INPUT	引数が空、または矛盾しています
IMAGE_SOURCE_UNSUPPORTED	画像ソースがローカルパスです。取得可能な URL が必要です
AUTH_EXPIRED	有効なトークンがありません。verified-googledocs-mcp auth を実行してください
INDEX_SIMULATION_FAILED	Markdown の書き込み要求をコンパイルすると無効なインデックスになることが、API 呼び出し前に検出されました。dry_run と実際の書き込みの両方で同じエラーが発生するため、dry_run が成功すれば書き込みも必ず成功します
TABLE_NOT_FOUND	指定された table_index がタブに存在しません。最初に list_tables を呼び出してください
SUGGESTIONS_PRESENT	対象のタブに保留中の挿入または削除の提案があります。誤ったインデックス空間に基づいてインデックスを計算しないよう、書き込みは拒否されます（issue #56）。提案を承認または却下してから再試行してください
INVALID_RANGE	呼び出し元が指定した範囲がタブの現在の範囲に収まっていないか、Docs API 自体がインデックスまたは範囲の無効な書き込みを拒否しました（API のメッセージがそのまま含まれます）
INDEX_MODEL_DIVERGENCE	テキストランの計算された UTF-16 長が、Docs API から報告された endIndex と一致しません。この読み取りから得られたオフセットは信頼できません
STRUCTURE_PREDICTION_FAILED	Markdown の書き込み要求をコンパイルすると、入力のブロック構造（ネスト、順序付き／順序なし、見出し、表）が再現されません。要求の効果を予測し、解析済みの入力と比較することで、API 呼び出し前に検出されます（issue #65）。dry_run と実際の書き込みの両方で同じエラーが発生するため、dry_run が成功すれば書き込みも必ず検証に成功します

開発

uv run --extra dev pytest                 # unit tests (offline) + coverage
uv run --extra dev ruff check src tests   # lint
uv run --extra dev ruff format src tests  # format
uv run --extra dev mypy src               # type check

単体テストは合成 Docs API フィクスチャとメモリ内 MCP クライアントを使用するため、テストスイート全体をオフラインで実行できます（ライブテストは実行されません）。ライブ受け入れテストスイート（tests/live/ 内）は、実際のスクラッチドキュメントに対して pytest tests/live --run-live で実行し、OAuth 認証情報が必要です。これはリリース前のゲートであり、CI では実行されません。詳細は docs/acceptance-report.md を参照してください。

モジュール構成と検証パイプラインについては docs/architecture.md、完全な仕様については PRD.md、汎用 Workspace MCP サーバーから移行する方法については docs/cutover.md、このプロジェクトに基づいて開発する方法については CONTRIBUTING.md を参照してください。

制限事項

• 提案された編集の承認または却下は、一般提供されている Google Docs API では実行できません。このサーバーはコメントとともに提案を表示しますが、実際の操作は Docs の UI で手動で行う必要があります。2026 年 7 月時点で、Google は提案の承認／却下／削除リクエストを文書化していますが、Workspace Developer Preview Program のみで利用できます。安定版の v1 では拒否されます（2026-07-17 に確認済み）。これが一般提供（GA）されると、検証済みの accept_suggestion／reject_suggestion ツールをビルドできるようになります。
• ローカルでの単一ユーザー利用。 stdio トランスポート、キャッシュするトークンは 1 つで、ホスト型モードやマルチユーザーモードには対応していません。
• 対応するのは Docs のみです。 Gmail、Calendar、Sheets は設計上、対象外です。
• Markdown は固定のサブセットです（見出し、太字／斜体、リスト、表、リンク）。それ以外は近似的に処理するのではなく、明確なエラーを返して拒否します。

ライセンス

MIT、© 2026 Michael Sutton。