Skip to content

feat(notion): CLI integration — REST client, ask agent, MCP tools#186

Merged
rafeegnash merged 1 commit into
masterfrom
feat/notion-cli
Jun 2, 2026
Merged

feat(notion): CLI integration — REST client, ask agent, MCP tools#186
rafeegnash merged 1 commit into
masterfrom
feat/notion-cli

Conversation

@rafeegnash
Copy link
Copy Markdown
Collaborator

Summary

  • Adds internal/notion/ (client, pages, databases, blocks, markdown, users, conversation, status, static_commands) mirroring the Sentry/Linear shape
  • clanker notion {ask, list, get, search, page, db} for natural-language and direct ops
  • 10 MCP tools registered alongside existing providers (6 read + 4 destructive — create_page, append_blocks, update_page_properties, create_database_row)
  • Surfaces Notion's share-with-integration gotcha in the ask prompt and empty-state copy — tokens start with zero access, this is the feat: discover, compliance flags and more aws services #1 papercut

Notes

  • Auth: Authorization: Bearer <token> + Notion-Version: 2022-06-28 (opposite of Linear, which uses the raw key)
  • Bounded block fetch (depth ≤ 3, total ≤ 200 blocks) to keep get blocks predictable against the 3 req/sec rate limit
  • 429 backoff honors Retry-After, capped at 30s; network-retry uses exponential backoff
  • Minimal markdown→blocks converter (paragraphs, headings, lists, todos, code fences, quotes, dividers) — round-trips back via BlocksToMarkdown
  • Status snapshot derives page/db counts from a single /search call instead of three round-trips
  • Config: notion.integration_token + optional notion.default_database_id; env fallback NOTION_API_KEY / NOTION_DATABASE_ID
  • History at ~/.clanker/notion-{workspace}.json

Test plan

  • go test -race ./internal/notion/... — happy path, 429 with Retry-After, share-failure empty results, auth-error envelope extraction, conversation round-trip, markdown→blocks fidelity, safeSlug path-traversal defense
  • go build ./... clean
  • clanker notion --help renders subcommand tree
  • End-to-end with real token: clanker notion search "runbook", clanker notion page append --page <id> --text "## test", clanker notion ask "what databases do we have?"
  • MCP smoke test: clanker mcp --transport stdio exposes clanker_notion_* tools

Adds an internal/notion package mirroring the Sentry/Linear shape: REST
client with Bearer auth + Notion-Version header, 429 backoff honoring
Retry-After, pages/databases/blocks/users operations, bounded recursive
block-tree fetch, minimal markdown↔blocks converter, and per-workspace
conversation history.

Surfaces the Notion share-with-integration gotcha in empty-state copy
and the ask-flow system prompt — the most common UX papercut for fresh
integrations.

CLI: `clanker notion {list,get,search,page,db,ask}`. MCP: 10 tools
(6 read + 4 destructive) registered alongside the existing providers.
@rafeegnash rafeegnash merged commit 7e654fe into master Jun 2, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant