掲載済み (2026-03-21号)
#173 155文字 • 1分

全Notion利用者のための、Coding Agentに対応したCLIを作った話

日本語

掲載情報

概要

Notion Remote MCPをラップし、Coding Agentが自律的に利用しやすい設計思想(構造化エラー、JSON出力、OAuth対応)を組み込んだ多機能なNotion CLIの紹介。

詳細内容

Notion公式CLIの制限(REST APIラッパー、手動トークン管理)を克服するため、OAuthでワークスペース全体にアクセス可能なRemote MCPをベースとしたCLIツール「@sakasegawa/ncli」を開発。本記事では、Claude Code等のCoding Agentを主要ユーザーと想定した「Agent時代のCLI設計」の4原則(Agent可読なJSON出力、エラーヒントによる段階的開示、What+Why+Hint構造のエラー、Escape Hatchとしての直接API呼び出し)を詳説している。技術スタックはTypeScriptとCommander.jsを用い、PKCE対応のOAuth認証やレートリミット時の自動リトライ、MCPエラーをパターンマッチして解決策を提示するヒントシステムなどを実装。検索からDB操作、ページ作成、コメント管理まで多岐にわたる機能を備え、エージェントのワークフローを強力に支援する内容となっている。