NotionDev

Notion ↔ Asana ↔ Git Integration for Developers
Accelerate your development with AI context automatically loaded from your Notion specifications

NotionDev is designed for large projects that require focusing AI agents on precisely presented context to avoid code regressions. We implement a workflow with automatic context switching, based on your specifications. For this, we assume your application is organized into modules, and your modules into features. We also assume your modules and features are documented in two Notion databases.

NotionDev allows developers to automatically load the complete context of their features from Notion directly into AI coding assistants via AGENTS.md standard, while synchronizing with their assigned Asana tickets. They can then comment on Asana tickets, tag their code with implemented features, and reassign a ticket to the person who created it when work is completed.

NotionDev works in a multi-project environment: you can have multiple git projects locally, you can work on distinct features in each project.

✨ Features

• 🎯 Integrated workflow: Asana ticket + Notion documentation → AI Context → Code
• 🤖 Automatic AI Context: Direct export to AGENTS.md with complete specs
• 🔄 Multi-project: Automatic detection of current project
• 📋 Traceability: Automatic headers in code to link functional ↔ technical
• 🚀 Zero config per project: One global configuration for all your projects

🎯 Use Case

Before NotionDev:

# Manual and scattered workflow
1. Open Asana ticket
2. Search for documentation in Notion  
3. Copy-paste specs into AI assistant
4. Code without complete context
5. Code doesn't directly reference implemented specifications

With NotionDev:

# Automated and integrated workflow
notion-dev work TASK-123456789
# → Automatically loads entire context into AGENTS.md
# → Ready to code with AI 
# Generated code mentions implemented features

📋 Prerequisites

• Python 3.10+
• macOS
• API Access: Notion + Asana
• Notion Structure: "Modules" and "Features" databases with feature codes

Required Notion Structure

For NotionDev to work, your Notion workspace must contain 2 databases with the attributes below (case-sensitive):

"Modules" Database:

• name (Title): Module name
• description (Text): Short description
• status (Select): draft, review, validated, obsolete
• application (Select): service, backend, frontend
• code_prefix (Text): Feature code prefix (AU, DA, API...)
• repository_url (URL): GitHub repository URL - optional, for code cloning
• code_path (Text): Path within repository - optional
• branch (Text): Git branch to clone - optional, defaults to default branch

"Features" Database:

• code (Text): Unique code (AU01, DA02...) - required
• name (Title): Feature name - required
• status (Select): draft, review, validated, obsolete - required
• module (Relation): Link to parent module - required

🚀 Installation

Install from PyPI

CLI only:

pip install notion-dev

CLI + MCP Server (for Claude Code, Cursor, etc.):

pip install 'notion-dev[mcp]'

Update

# Update to latest version
pip install --upgrade notion-dev

# Update with MCP support
pip install --upgrade 'notion-dev[mcp]'

# Check current version
notion-dev --version

Install from Source

# Clone the repository
git clone https://github.com/grand-shooting/NotionDev.git
cd NotionDev

# Install in development mode
pip install -e .

First Time Setup

After installation:

# Create configuration directory
mkdir -p ~/.notion-dev

# Copy the example configuration
# You'll need to edit this with your tokens
cat > ~/.notion-dev/config.yml << 'EOF'
notion:
  token: "secret_YOUR_NOTION_TOKEN"
  database_modules_id: "YOUR_MODULES_DB_ID"
  database_features_id: "YOUR_FEATURES_DB_ID"

asana:
  access_token: "YOUR_ASANA_TOKEN"
  workspace_gid: "YOUR_WORKSPACE_ID"
  user_gid: "YOUR_USER_ID"
EOF

Configuration

1. Get API Tokens

🔑 Notion Token:

1. Ask your Notion workspace administrator for the existing NotionDev integration token
2. The token starts with secret_
3. Get the database IDs for modules and features from your admin URL format: notion.so/workspace/[DATABASE_ID]?v=...

Note: If you are the workspace admin and need to create a new integration, go to https://www.notion.so/my-integrations

🔑 Asana Token:

1. Go to https://app.asana.com/0/my-apps
2. Create a "Personal Access Token"
3. Copy the generated token
4. Get your workspace ID
5. Get your user account ID

🔑 GitHub Token (Optional):

1. Go to https://github.com/settings/tokens
2. Generate a new token with repo scope (for private repositories)
3. Copy the generated token
4. This is only needed if you want to clone private repositories for code analysis

2. Configure config.yml

# Copy the template
cp ~/.notion-dev/config.example.yml ~/.notion-dev/config.yml

# Edit with your tokens
nano ~/.notion-dev/config.yml

notion:
  token: "secret_YOUR_NOTION_TOKEN"
  database_modules_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  database_features_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

asana:
  access_token: "x/YOUR_ASANA_TOKEN"
  workspace_gid: "1234567890123456"
  user_gid: "1234567890123456"

# Optional: GitHub configuration for repository cloning
github:
  token: "ghp_YOUR_GITHUB_TOKEN"  # Optional, only for private repos
  clone_dir: "/tmp/notiondev"     # Where to clone repositories
  shallow_clone: true             # Use --depth 1 for faster cloning

3. Test Installation

# First test
notion-dev status
notion-dev tickets

MCP Server Configuration

If you installed with MCP support (pip install 'notion-dev[mcp]'), you can use NotionDev as an MCP server in AI coding assistants.

Claude Code

Add to your Claude Code MCP settings (~/.claude/claude_desktop_config.json or via Claude Code settings):

{
  "mcpServers": {
    "notiondev": {
      "command": "notion-dev-mcp",
      "args": []
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project or global settings):

{
  "mcpServers": {
    "notiondev": {
      "command": "notion-dev-mcp",
      "args": []
    }
  }
}

Claude.ai Web Interface (Remote MCP)

NotionDev can be used directly in Claude.ai via the remote MCP server:

1. Go to Claude.ai Settings → Integrations → Add MCP Server
2. Enter the server URL: https://notiondev.grand-shooting.com/mcp
3. Click "Connect" to authorize

The remote server uses a no-auth mode with a default user, making it easy to deploy for teams.

For self-hosted deployments, you can add a secret URL prefix for security:

# Set a secret key on Fly.io
fly secrets set MCP_URL_SECRET_KEY=your-secret-uuid --app your-app

# Then use the URL: https://your-app.fly.dev/{secret}/mcp

Available MCP Tools

Once configured, the following tools are available in your AI assistant:

📖 Usage

Main Commands

# View current project info
notion-dev info [--json]

# List your assigned Asana tickets
notion-dev tickets [--json]

# Work on a specific ticket
notion-dev work TASK-123456789 [--yes] [--json]

# Get context for a feature (other than the one in the Asana ticket)
notion-dev context --feature AU01 [--yes]

# Record a comment on the ticket in Asana
notion-dev comment "This is a comment"

# Mark work as completed (reassigns to creator)
notion-dev done

# Interactive mode
notion-dev interactive

Asana Ticket Management

# List projects in portfolio
notion-dev projects [--json]

# Create a new ticket
notion-dev create-ticket --name "AU01 - Fix login" [--feature AU01] [--notes "..."] [--due 2025-02-01] [--project PROJECT_GID] [--json]

# Update an existing ticket
notion-dev update-ticket TASK_ID [--name "New name"] [--notes "..."] [--append] [--due 2025-02-01] [--assignee USER_GID] [--json]

Notion Module Commands

# List all modules
notion-dev modules [--json]

# Get module details (includes repository_url, branch, code_path)
notion-dev module ND [--json]

# Create a new module
notion-dev create-module --name "Auth" --description "Authentication" --prefix AUTH [--application Backend] [--content "..."] [--json]

# Update module documentation
notion-dev update-module ND --content "# New docs..." [--append] [--json]

Notion Feature Commands

# List all features (optionally filter by module)
notion-dev features [--module ND] [--json]

# Get feature details (includes parent module's repository info)
notion-dev feature ND01 [--json]

# Create a new feature (code auto-generated)
notion-dev create-feature --name "New Feature" --module ND [--content "..."] [--plan "free,premium"] [--rights "admin,user"] [--json]

# Update feature documentation
notion-dev update-feature ND01 --content "# Updated docs..." [--append] [--json]

JSON Output

All commands support --json output for scripting and MCP integration:

notion-dev tickets --json | jq '.tasks[0].feature_code'
notion-dev module ND --json | jq '.module.repository_url'
notion-dev feature ND01 --json | jq '.feature.module_repository_url'

Typical Developer Workflow

To understand the spirit of NotionDev, here's an example workflow. In this example, we assume documentation has been validated in Notion (Definition of Ready), and Asana tickets have been added to the current sprint, assigned to developers. We put ourselves in the developer's shoes.

🌅 Morning - Choose Your Ticket

cd ~/projects/my-saas-frontend
notion-dev tickets

                    My Asana Tickets                    
┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ ID      ┃ Name                             ┃ Feature     ┃ Status      ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ 23456789│ Implement Google SSO             │ AU02        │ 🔄 In progress │
│ 34567890│ Dashboard analytics              │ DA01        │ 🔄 In progress │
└─────────┴────────────────────────────────┴─────────────┴─────────────┘

🎯 Start Working

notion-dev work 23456789

📋 Asana Ticket
AU02 - Implement Google SSO

ID: 1234567890123456
Feature Code: AU02
Status: 🔄 In progress
Project: my-saas-frontend

🎯 Feature
AU02 - SSO Google Login

Module: User Authentication
Status: validated
Plans: premium
User Rights: standard, admin

Export context to AGENTS.md? [Y/n]: y
✅ Context exported to /Users/dev/projects/my-saas-frontend/AGENTS.md
💡 You can now open your AI coding assistant and start coding!

💻 Develop with AI Assistant

# Open your AI coding assistant with loaded context
# (Claude Code, Cursor, VS Code Copilot, etc.)
code .

The AI context automatically contains:

• ✅ Complete specifications for feature AU02
• ✅ User Authentication module documentation
• ✅ Code standards with mandatory headers
• ✅ AI instructions adapted to the project

🔄 Switch Projects

# Switch to another project - automatic detection
cd ~/projects/my-saas-api
notion-dev info

📊 Project: my-saas-api
Name: my-saas-api
Path: /Users/dev/projects/my-saas-api
Cache: /Users/dev/projects/my-saas-api/.notion-dev
Git Repository: ✅ Yes

Traceability Headers

In the context loaded in the AGENTS.md file, NotionDev adds instructions for the AI agent to automatically insert a header in each project file with the feature code. The goal is to verify functional code coverage and avoid regressions since the AI agent has instructions not to modify code corresponding to a feature other than the one being worked on.

/**
 * NOTION FEATURES: AU02
 * MODULES: User Authentication
 * DESCRIPTION: Google OAuth authentication service
 * LAST_SYNC: 2025-01-15
 */
export class GoogleAuthService {
  // Implementation...
}

🏗️ Architecture

Automatic Multi-project

NotionDev automatically detects the project from the current directory:

~/projects/
├── saas-frontend/          # notion-dev → Context "saas-frontend"
│   └── .notion-dev/        # Isolated cache
├── saas-api/              # notion-dev → Context "saas-api"  
│   └── .notion-dev/        # Isolated cache
└── saas-admin/            # notion-dev → Context "saas-admin"
    └── .notion-dev/        # Isolated cache

⚙️ Advanced Configuration

Context Size Management

The context_max_length parameter controls the maximum size of the AGENTS.md file to ensure compatibility with your AI model's context window:

ai:
  # For Claude Opus/Sonnet (recommended)
  context_max_length: 100000  # ~100KB
  
  # For GPT-3.5 (more limited)
  context_max_length: 32000   # ~32KB

How it works:

• Default: 100,000 characters
• If content exceeds the limit, it's intelligently truncated
• Priority is given to critical sections (headers, rules, project context)
• Documentation is truncated first if needed
• A message [Content truncated to fit context limits] is added when truncation occurs

Checking truncation: After running notion-dev work, check the logs:

AGENTS.md created: 45000 chars                    # Normal
AGENTS.md created: 100000 chars (truncated from 125000)  # Truncated

Language Configuration

NotionDev enforces English for all code and comments, regardless of documentation language:

• Documentation: Can be in any language (French, English, etc.)
• Generated code: Always in English
• Comments: Always in English
• Variable/function names: Always in English

This is automatically enforced through the AGENTS.md file.

Custom Shell Aliases

# In ~/.zshrc or ~/.bash_profile
alias nd="notion-dev"
alias ndt="notion-dev tickets"
alias ndw="notion-dev work"
alias ndi="notion-dev info"

🔧 Troubleshooting

Common Errors

❌ "Invalid configuration"

# Check tokens
notion-dev info
# Retest config
~/notion-dev-install/test_config.sh

Debug Logs

NotionDev uses rotating logs to prevent disk space issues:

# View detailed logs
tail -f ~/.notion-dev/notion-dev.log

# Debug with verbose level
export NOTION_DEV_LOG_LEVEL=DEBUG
notion-dev tickets

Log rotation:

• Maximum file size: 10MB
• Keeps 5 backup files (notion-dev.log.1 through .5)
• Automatic rotation when size limit is reached
• Logs location: ~/.notion-dev/notion-dev.log

🤝 Contributing

Local Development

# Clone and install in development mode
git clone https://github.com/your-org/notion-dev.git
cd notion-dev
python -m venv venv
source venv/bin/activate
pip install -e .

Project Structure

notion-dev/
├── notion_dev/
│   ├── __init__.py           # Package init with embedded setup.py
│   ├── cli/
│   │   └── main.py           # Click CLI commands and Rich UI
│   ├── core/                 # Business logic
│   │   ├── asana_client.py   # Asana API client (requests)
│   │   ├── config.py         # YAML config with dataclasses
│   │   ├── context_builder.py # AI context generator (AGENTS.md)
│   │   ├── github_client.py  # GitHub repo cloning
│   │   ├── models.py         # Data models (Module, Feature, AsanaTask)
│   │   └── notion_client.py  # Notion API client (SDK)
│   └── mcp_server/
│       └── server.py         # MCP server (FastMCP) - wraps CLI commands
├── tests/
│   └── unit/                 # Unit tests
├── install_notion_dev.sh     # Installation script
└── README.md

📝 Changelog

v2.0.0 (2026-01-17)

• ✅ Remote MCP Server for Claude.ai - Full integration with Claude.ai web interface
• ✅ No-auth mode - MCP server can run without OAuth for simplified deployment
• ✅ URL Secret Key - Optional endpoint obscurity with secret URL prefix
• ✅ Streamable HTTP transport - New recommended transport (replaces deprecated SSE)
• ✅ Deployed on Fly.io (notiondev-prod.fly.dev)

v1.4.0 (2025-12-30)

• ✅ Refactored MCP server to use CLI commands exclusively (single source of truth)
• ✅ Added --json output to work command for MCP integration
• ✅ Added module_repository_url, module_branch, module_code_path to feature command output

v1.3.0 (2025-12-26)

• ✅ Added GitHub integration for module repository cloning
• ✅ New MCP tools: clone_module, get_cloned_repo_info, cleanup_cloned_repos
• ✅ Added repository_url, branch, code_path fields to Module model
• ✅ Added notiondev_list_projects MCP tool

v1.2.0 (2025-12-25)

• ✅ Added Notion CRUD commands: modules, module, features, feature
• ✅ Added create-module, create-feature, update-module, update-feature commands
• ✅ Added --project option to create-ticket command
• ✅ Added --json output to all new commands

v1.1.0 (2025-12-20)

• ✅ Added MCP server support (notion-dev[mcp])
• ✅ FastMCP integration with 19 tools available
• ✅ Full Asana ticket management via MCP

v1.0.3 (2025-01-28)

• ✅ Added JSON output support for tickets and info commands
• ✅ Published to PyPI as notion-dev
• ✅ Added automated release workflow

v1.0.0 (2025-01-26)

• ✅ Initial release
• ✅ Automatic multi-project support
• ✅ Notion + Asana + AI assistant integration
• ✅ Automatic traceability headers
• ✅ Asana API 5.2.0 compatible client

📄 License

MIT License - see LICENSE for details.

💬 Support

• Issues: GitHub Issues
• Documentation: Wiki
• Discussions: GitHub Discussions

Developed with ❤️ to accelerate AI-assisted development