note.com MCP Server

# Notion → note.com Integration 実装で起こりやすいエラー／躓きポイント 本ドキュメントは、Notion → note.com 連携機能の実装・運用で発生しやすいエラーや、実装上の間違いポイントを整理したものです。 ## 1. 認証・権限まわりで起きやすい問題 ### 1.1 NOTION_TOKEN 未設定・誤設定 - **症状**: 起動時に例外、または Notion API から 401 - **原因**: `.env` 未設定 / Tokenのコピー漏れ / Integration Token 以外を指定 - **対策**: - `NOTION_TOKEN` の存在チェックを初期化時に必ず行う - 401エラーは即時終了・設定のヒントを返す ### 1.2 Notion Integration の接続漏れ - **症状**: 403（アクセス権なし） - **原因**: 対象ページ／DBに Integration が接続されていない - **対策**: - 403は「Integration 接続が必要」と明示 - Notion UI での接続手順をログやエラーメッセージに含める ### 1.3 note.com 認証情報の不足 - **症状**: note.com API で 401/403 - **原因**: 既存の `.env` 認証情報が不足 - **対策**: - `hasAuth()` 判定を必ず通す - 認証不足時のレスポンスを統一 --- ## 2. Notion API 由来のエラー ### 2.1 Rate Limit (429) - **症状**: 短時間に大量ブロック取得で 429 - **原因**: ブロック階層の深いページでの再帰取得 - **対策**: - `Retry-After` ヘッダ尊重 - 指数バックオフ（1s,2s,4s） - 取得バッチサイズを 100 に固定 ### 2.2 404 Not Found - **症状**: ページIDが見つからない - **原因**: ID誤り、削除済み、権限外 - **対策**: - 404はリトライせず即時終了 - IDの形式（ハイフン有無）を正規化 ### 2.3 画像URLの期限切れ - **症状**: 画像ダウンロードで 403/404 - **原因**: Notionの署名付きURLが期限切れ - **対策**: - インポート直前にダウンロードする - 失敗時は警告扱いで進行 --- ## 3. 変換ロジックでの誤りやすい点 ### 3.1 IR → Markdown 変換の見出しルール混乱 - **症状**: H1/H2/H3 のマッピングが崩れる - **原因**: Notionの見出しと note.com の見出し制限の混同 - **対策**: - 明示的マッピング（H1→H2, H2→H2, H3→H3）を固定 - 仕様は `plan.md` と同一に保つ ### 3.2 リストのネスト構造崩れ - **症状**: 連続リストが別要素として分断 - **原因**: `parseBlocks` 内で list grouping を実装していない - **対策**: - `groupListItems` のようなロジックで連続項目を束ねる ### 3.3 テーブルの変換崩れ - **症状**: Markdownテーブルが note.com で崩れる - **原因**: note.com の HTML サニタイズで `<table>` が不安定 - **対策**: - テーブルは Markdown で表現するが、崩れる場合は警告 - 代替表現（箇条書き等）も検討 ### 3.4 `<iframe>` など埋め込みタグが消える - **症状**: YouTube 埋め込みが消える - **原因**: `sanitizeHtmlForNote()` が iframe を削除 - **対策**: - 埋め込みはリンク表現に統一 - note.com の仕様変更がない限り iframe は使わない --- ## 4. 画像アップロード処理での躓き ### 4.1 Base64変換時のメモリ問題 - **症状**: 大きな画像でメモリ使用量が急増 - **原因**: 一括で Buffer → Base64 を配列化 - **対策**: - 最大サイズ制限の導入 - 失敗時は警告として処理継続 ### 4.2 S3アップロード 204 判定漏れ - **症状**: アップロード成功でもエラー扱い - **原因**: `response.ok` のみで判定 - **対策**: - 204も成功とみなす既存ロジックを流用 ### 4.3 本文画像置換の正規表現ミス - **症状**: 画像参照が HTML に置換されない - **原因**: `![[...]]` や `` のパターン不一致 - **対策**: - 正規表現のユニットテストを準備 - Obsidian形式/Markdown形式の両対応を確認 --- ## 5. note.com API との整合性で躓く点 ### 5.1 `post-draft-note-with-images` を直接 import できない - **症状**: TS compile error - **原因**: `note-tools.ts` は `registerNoteTools` しか export していない - **対策**: - 共通ロジックを utils に切り出し - または Notion側で API 呼び出しを再実装 ### 5.2 HTML直送信で本文が消える - **症状**: `<img>` 等が消失 - **原因**: note.com 側のサニタイズ - **対策**: - Markdown → `convertMarkdownToNoteHtml()` を必ず通す - `<figure>` 復元ロジックを維持 --- ## 6. 実装そのもので間違いやすいポイント - **Notion APIのレスポンス型が広い**ため、型定義が甘いと null参照になりやすい - `has_children` の場合の再帰取得漏れ - `child_page` / `child_database` の扱いを誤ると infinite loop の可能性 - `rich_text` が空配列の場合の `map` エラー --- ## 7. 進行中に躓きやすい場面 - **NotionページIDの取り扱い**（ハイフン有無、URLからの抽出） - **Notion DBとページの混同**（list-notion-pagesはDBに限定） - **note.com 側の仕様変更**（ヘッダ必須項目が変わることがある） - **エラー時のログ不足**（原因切り分けが困難） --- ## 8. 事前に用意しておくと良いチェックリスト - [ ] NOTION_TOKEN が `.env` に設定されている - [ ] Notionページ/DBに Integration が接続済み - [ ] note.com の認証情報が有効 - [ ] 画像サイズ上限を定めた - [ ] 変換テスト用の Notion ページを準備済み --- ## 9. トラブルシューティング例 ### 401 が出る - Notion Token の誤り → Token再発行 ### 403 が出る - Integration を該当ページに追加 ### 画像が本文に挿入されない - Markdown中の `![[...]]` が正規化されているか確認 ### 画像はアップロードされるが表示されない - HTML出力に `<figure>` が復元されているか確認 --- このドキュメントは実装時の「よくある失敗」を先回りして把握するための補助資料として利用する。