| name | notion-uploader-downloader |
| version | 2.1.0 |
| description | Bidirectional sync between Markdown and Notion. Upload .md files with images to Notion pages/databases, append to existing pages, or download Notion content back to markdown. Supports rich formatting, tables, code blocks, GitHub-flavored markdown, and recursive page hierarchy downloads with YAML frontmatter for round-trip sync. |
| allowed-tools | ["Bash(python3 scripts/notion_upload.py*)","Bash(python3 scripts/notion_download.py*)","Bash(python3 scripts/notion_download_recursive.py*)","Read(*/references/*)","Read(*/guides/*)"] |
| metadata | {"pda_version":"1.0","tier1_budget":150,"tier2_budget":600,"tier3_budget_per_guide":1500,"max_request_budget":10000,"requires":["python3>=3.8","pip"],"config_required":["NOTION_TOKEN","NOTION_PARENT_PAGE"]} |
Notion Uploader/Downloader - Orchestrator (Tier 2)
PDA Tier: 2 (Decision Tree & Routing Logic)
Token Budget: ~600 tokens
Purpose: Classify intent and route to appropriate Tier 3 workflow guides
Intent Classification Decision Tree
Classify user intent into ONE category and load the corresponding Tier 3 guide:
1. UPLOAD Intent 📤
Triggers: "upload", "publish", "save to notion", "create page", mentions .md file path
User Goal: Send markdown file TO Notion
Route: guides/workflows/upload-workflow.md (+1,250 tokens)
Validation: Markdown file path must be provided
2. DOWNLOAD Intent 📥
Triggers: "download", "export", "backup", Notion URL provided, "get from notion"
User Goal: Extract content FROM Notion (single page)
Route: guides/workflows/download-workflow.md (+850 tokens)
Validation: Page ID or Notion URL must be provided
2b. RECURSIVE DOWNLOAD Intent 📥🔄
Triggers: "download all", "recursive", "all child pages", "entire hierarchy", "whole section", "backup everything", "download tree"
User Goal: Extract a page AND all its child pages recursively
Route: guides/workflows/recursive-download-workflow.md (+1,100 tokens)
Validation: Page ID or Notion URL must be provided
Output: Folder structure with mapping.json, YAML frontmatter in each file
3. UPDATE/APPEND Intent ➕
Triggers: "update", "append", "add to", mentions "page-id" with .md file
User Goal: Add content to EXISTING Notion page
Route: guides/workflows/update-workflow.md (+1,100 tokens)
Validation: Both markdown file AND page ID required
4. CONFIGURATION Intent ⚙️
Triggers: "setup", "configure", "install", "token not found", "how do I set up"
User Goal: Initial setup or configuration help
Route: guides/setup/configuration-guide.md (+700 tokens)
Auto-trigger: If NOTION_TOKEN or NOTION_PARENT_PAGE not found
5. TROUBLESHOOTING Intent 🔧
Triggers: "error", "failed", "not working", "404", "object_not_found", "broken"
User Goal: Fix an error or issue
Route: guides/troubleshooting/error-resolution.md (+950 tokens)
Auto-trigger: If script execution fails
6. TECHNICAL REFERENCE Intent 📚
Triggers: "how does", "what elements", "supported features", "mappings", "can it handle"
User Goal: Understand capabilities or technical details
Route: Load specific reference based on question:
- Element mappings →
references/MAPPINGS.md (+515 tokens)
- Quick commands →
references/QUICK_START.md (+320 tokens)
- Technical details →
references/IMPLEMENTATION_SUMMARY.md (+1,090 tokens)
Resource Catalog (Tier 3 - Load On-Demand ONLY)
Loading Policy: NEVER load proactively. Load ONLY when routed above.
Workflow Guides (guides/workflows/)
| Guide | Tokens | When to Load |
|---|
upload-workflow.md | ~1,250 | Upload Intent (#1) |
download-workflow.md | ~850 | Download Intent (#2) |
recursive-download-workflow.md | ~1,100 | Recursive Download Intent (#2b) |
update-workflow.md | ~1,100 | Update Intent (#3) |
Setup Guides (guides/setup/)
| Guide | Tokens | When to Load |
|---|
configuration-guide.md | ~700 | Configuration Intent (#4) or config error |
first-time-setup.md | ~600 | User explicitly asks for setup walkthrough |
Troubleshooting (guides/troubleshooting/)
| Guide | Tokens | When to Load |
|---|
error-resolution.md | ~950 | Troubleshooting Intent (#5) or script failure |
Reference Docs (references/)
| Guide | Tokens | When to Load |
|---|
MAPPINGS.md | ~515 | Questions about supported elements |
QUICK_START.md | ~320 | Questions about command syntax |
IMPLEMENTATION_SUMMARY.md | ~1,090 | Deep technical questions |
Token Budget Management
Current Request Status:
- ✅ Tier 1 (Metadata): ~150 tokens (loaded)
- ✅ Tier 2 (This Orchestrator): ~600 tokens (loaded)
- ⏳ Tier 3: 0 tokens (awaiting intent classification)
- Remaining Budget: 9,250 tokens for Tier 3 resources
Loading Rules:
- Load EXACTLY ONE workflow guide for current intent
- Load reference guides ONLY when workflow explicitly requires OR user asks technical question
- Load troubleshooting ONLY on errors or explicit user request
- Track cumulative tokens after each load
- Warn if total exceeds 8,000 tokens
Skill Integration Points
PlantUML Skill (/Users/richardhightower/.claude/skills/plantuml):
- When: Markdown contains
puml or plantuml code blocks
- Action: MUST invoke PlantUML skill FIRST before upload
- Script:
python scripts/process_markdown_puml.py <file.md> --format png
- Output: Use transformed
*_with_images.md for upload
- Reason: Notion doesn't natively render PlantUML
Error Handling & Fallback Logic
Missing NOTION_TOKEN:
→ Route to Configuration Intent (#4)
Missing NOTION_PARENT_PAGE (and no --parent-id/--database-id/--page-id):
→ Route to Configuration Intent (#4)
Script Execution Fails:
→ Route to Troubleshooting Intent (#5)
Unknown/Ambiguous Intent:
→ Use AskUserQuestion tool to clarify, then re-classify
Resource Not Found (guide file missing):
→ Apologize, explain PDA structure may be incomplete, ask user what they need
Quick Reference (Non-Expandable)
Core Scripts:
scripts/notion_upload.py - Upload markdown to Notionscripts/notion_download.py - Download single Notion page to markdownscripts/notion_download_recursive.py - Recursively download page + childrenscripts/notion_utils.py - Shared utilities (token/parent discovery)
Configuration:
- File:
.env.notion (NOTION_TOKEN=..., NOTION_PARENT_PAGE=...)
- Search Path: Current dir → Parent dirs → Environment variables
Python Requirements:
- Version: Python 3.8+
- Install:
pip install -r scripts/requirements.txt
- Dependencies: requests, python-dotenv
PDA Compliance Checklist
- ✅ Decision tree with 6 clear intents
- ✅ Explicit routing to Tier 3 resources
- ✅ Token budgets documented for all resources
- ✅ Lazy loading policy (no proactive loads)
- ✅ No embedded workflows or comprehensive guides
- ✅ Error handling with fallback routing
- ✅ Integration points identified (PlantUML)
- ✅ Resource catalog with load conditions
- ✅ Token tracking instructions
- ✅ Under 100 lines (target: ~95 lines)
