🚀 Meow OS - Mobile Todo App with MCP Integration

A modern mobile-first todo application built with Next.js 14, Supabase, and Model Context Protocol (MCP) integration for AI agents. Features a beautiful Duolingo-inspired UI design with comprehensive todo management, group organization, and complete AI agent integration capabilities.

📱 Screenshots

✨ Features

Mobile App Experience

• 🎨 Duolingo-Inspired UI: Beautiful, gamified interface with achievement levels, streak counters, and progress bars
• 📱 Mobile-First Design: Optimized for mobile devices with touch-friendly interactions
• 🌈 Color-Coded Organization: Customizable colors for todos and groups with visual color picker
• 📂 Smart Todo Grouping: Organize tasks into categories like Personal, Work, Health, Shopping, Fitness, and Learning
• 🚀 Splash Screen: Engaging onboarding experience with smooth animations
• 🎯 Bottom Navigation: Easy access to Landing, Add, Groups, and Profile sections
• 📊 Dashboard Analytics: Quick stats, upcoming deadlines, and progress tracking
• 🔍 Smart Search & Filtering: Find todos by text, status, group, or deadline
• 🌍 Internationalization: Support for English and Chinese (Hong Kong) with easy language switching

Core Features

• 🔐 Enhanced Authentication: Complete auth flow with splash, login, register, and password reset pages
• 📝 Advanced Todo Management: Full CRUD operations with priorities, deadlines, colors, and group assignments
• 📊 Three-Tier Priority System: Visual priority indicators (Low, Medium, High) with color coding
• 📅 Smart Deadline Management: Calendar view with today, tomorrow, and this week categorization
• ⚙️ Comprehensive Settings: Profile management, API key generation, theme toggle, and data export/import
• 🔒 Advanced Security: Row-Level Security with user data isolation and secure API key management
• 🎨 Compact Todo Items: Inline edit/delete buttons for better UX and space efficiency
• 📱 Modal-based Group Management: Separate create/edit group modals for improved user experience
• 🌙 Enhanced Dark Theme: Full dark mode support across all components with consistent theming
• 🔘 Duolingo-style Buttons: Consistent 3D button styling with animations throughout the app
• 🎯 Better UI Consistency: Matched input/select styling for cohesive form elements

AI Agent Integration (MCP)

• 🤖 MCP Server: Complete Model Context Protocol implementation
• 📡 API Keys: Secure API key generation and management system
• 🔧 Four MCP Tools: Create, update, complete, and delete todos via AI agents
• 📋 Dynamic Resources: Todos exposed as MCP resources for AI consumption

🛠️ Tech Stack

Frontend

• Next.js 14 (App Router) - React framework with server-side rendering
• React 18 - UI library with server components
• TypeScript - Type safety and developer experience
• Tailwind CSS - Utility-first CSS framework with custom Duolingo color palette
• shadcn/ui - High-quality component library
• Framer Motion - Smooth animations and transitions
• next-intl - Internationalization with support for multiple languages
• Lucide React - Beautiful, customizable icons
• date-fns - Modern date utility library

Backend

• Next.js API Routes - Server-side API endpoints
• Supabase - PostgreSQL database with real-time capabilities
• Supabase Auth - Authentication with SSR support
• Row-Level Security - Database-level access control

AI Integration

• Model Context Protocol (MCP) - AI agent communication standard
• @modelcontextprotocol/sdk - Official MCP SDK for Node.js
• Direct MCP Server - Standalone MCP server for external AI agents
• API Key Authentication - Secure token-based authentication for AI agents

Development & Deployment

• Vercel - Hosting and deployment platform
• ESLint - Code linting and formatting
• PostCSS - CSS processing and optimization

🚀 Quick Start

1. Prerequisites

• Node.js 18+ and npm
• Supabase account and project (Create one here)
• Git for version control

2. Installation & Setup

1. Clone the repository:

   git clone https://github.com/your-username/meow-os-todo-webapp.git
   cd meow-os-todo-webapp
   npm install
   

2. Environment configuration:

   cp .env.example .env.local
   

   Configure your Supabase credentials in .env.local:

   NEXT_PUBLIC_SUPABASE_URL=your-supabase-project-url
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
   SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key
   

   💡 Tip: Find these values in your Supabase dashboard under Settings → API

3. Database setup: Execute the SQL script in your Supabase SQL Editor to create the required tables and security policies:

   # Run the database setup script
   psql -f supabase-setup.sql
   

   Or copy and paste the contents of supabase-setup.sql into your Supabase SQL Editor.

   This script creates:

   • Enhanced todos table with color support and UUID columns
   • Updated todo_groups table with color and icon fields, UUID columns, and inserted_at column
   • api_keys table for MCP authentication
   • Proper RLS policies and indexes
   • UUID migration with backward compatibility views

4. Start the development server:

   npm run dev
   

   The application will be available at:

   • Web App: http://localhost:3000 - Main todo interface
   • MCP Server: http://localhost:3000/api/mcp - AI agent endpoint

3. First Steps

1. Register an account at http://localhost:3000/login
2. Create your first todo in the web interface
3. Generate an API key in Settings for AI agent access
4. Test the MCP integration using the provided tools

🤖 MCP Integration Guide

Understanding MCP

Model Context Protocol (MCP) enables AI agents to interact with your todo app programmatically. The app exposes:

• 📋 Resources: Your todos as readable resources
• 🛠️ Tools: Four operations for todo management
• 🔑 Authentication: Secure API key-based access

MCP Server Architecture

The app provides two MCP integration methods:

1. Direct API Endpoint: http://localhost:3000/api/mcp
2. Standalone MCP Server: Using mcp-direct.js for external tools

API Key Management

1. Navigate to Settings: http://localhost:3000/settings
2. Generate API Key: Click "Generate New API Key"
3. Copy the Key: Store it securely (it's only shown once)
4. Use in AI Agents: Configure your AI agent with the key

Testing MCP Functionality

Use these curl commands to test the MCP API (replace YOUR_API_KEY with your actual key):

# Test authentication and list todos
curl -X POST "http://localhost:3000/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "resources/list",
    "params": {},
    "id": 1
  }'

# Create a new todo
curl -X POST "http://localhost:3000/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "create-todo",
      "arguments": {
        "text": "Buy groceries",
        "priority": 1
      }
    },
    "id": 2
  }'

# Update a todo
curl -X POST "http://localhost:3000/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "update-todo",
      "arguments": {
        "id": 1,
        "text": "Buy organic groceries"
      }
    },
    "id": 3
  }'

# Mark todo as completed
curl -X POST "http://localhost:3000/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "complete-todo",
      "arguments": {
        "id": 1
      }
    },
    "id": 4
  }'

External MCP Server (mcp-direct.js)

For AI agents that need a standalone MCP server:

1. Configure the MCP server:

   {
     "servers": {
       "todo-webapp-direct": {
         "command": "node",
         "args": ["mcp-direct.js"],
         "env": {
           "MCP_API_URL": "http://localhost:3000/api/mcp",
           "MCP_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

2. Run the server:

   node mcp-direct.js
   

MCP Tools Reference

1. create-todo

Creates a new todo item with optional priority and deadline.

Parameters:

• text (required): Todo text content (1-500 characters)
• priority (optional): Priority level (0=Low, 1=Medium, 2=High)
• deadline (optional): Deadline in YYYY-MM-DD format

2. update-todo

Updates an existing todo item.

Parameters:

• id (required): Todo ID to update
• text (optional): New todo text
• priority (optional): New priority level
• deadline (optional): New deadline
• completed (optional): Mark as completed/incomplete

3. complete-todo

Marks a todo as completed.

Parameters:

• id (required): Todo ID to complete

4. delete-todo

Permanently deletes a todo.

Parameters:

• id (required): Todo ID to delete

MCP Resources

Todos are exposed as MCP resources with the URI pattern: todo://{id}

Each resource includes:

• Title: Todo text
• Description: Status, priority, and deadline information
• Content: Formatted markdown with full todo details

🚀 Deployment

Vercel Deployment (Recommended)

1. Prepare for deployment:

   npm run build
   npm run type-check
   

2. Deploy to Vercel:

   vercel --prod
   

3. Configure environment variables in Vercel Dashboard:

   • NEXT_PUBLIC_SUPABASE_URL
   • NEXT_PUBLIC_SUPABASE_ANON_KEY
   • SUPABASE_SERVICE_ROLE_KEY

4. Your MCP endpoint will be available at: https://your-app.vercel.app/api/mcp

Manual Deployment

For custom server deployment:

npm run build
npm start

The app will be available at http://localhost:3000 with MCP at /api/mcp.

Environment Variables for Production

Ensure these environment variables are set in your production environment:

NEXT_PUBLIC_SUPABASE_URL=your-production-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-production-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-production-service-role-key

🛠️ Development

Available Scripts

Script	Description
npm run dev	Start development server with hot reloading
npm run build	Build optimized production bundle
npm run start	Start production server
npm run lint	Run ESLint checks and auto-fix issues
npm run type-check	Run TypeScript type checking

Project Structure

meow-os-todo-webapp/
├── app/                          # Next.js 14 App Router
│   ├── api/                      # API routes
│   │   ├── mcp/                  # MCP server endpoint
│   │   │   └── route.ts          # Main MCP implementation
│   │   ├── todos/                # Todo CRUD operations
│   │   │   ├── route.ts          # List & create todos
│   │   │   └── [id]/route.ts     # Update & delete todos
│   │   ├── groups/               # Group management API
│   │   │   ├── route.ts          # List & create groups
│   │   │   └── [id]/route.ts     # Update & delete groups
│   │   ├── user/                 # User profile API
│   │   │   └── route.ts          # User data management
│   │   └── settings/             # Settings API
│   │       └── api-keys/         # API key management
│   │           ├── route.ts      # List & create API keys
│   │           └── [id]/route.ts # Delete API keys
│   ├── splash/                   # Onboarding pages
│   │   └── page.tsx              # Splash screen
│   ├── welcome/                  # Welcome page
│   │   └── page.tsx              # Feature showcase
│   ├── login/                    # Authentication pages
│   │   ├── page.tsx              # Login form
│   │   └── actions.ts            # Auth server actions
│   ├── register/                 # Registration page
│   │   └── page.tsx              # Register form
│   ├── forgot-password/          # Password reset
│   │   └── page.tsx              # Forgot password form
│   ├── reset-password/           # Password reset
│   │   └── page.tsx              # Reset password form
│   ├── landing/                  # Dashboard/Landing
│   │   └── page.tsx              # Main dashboard
│   ├── add/                      # Add todo page
│   │   └── page.tsx              # Todo creation form
│   ├── groups/                   # Group management
│   │   ├── page.tsx              # Groups list
│   │   └── [id]/page.tsx         # Individual group view
│   ├── profile/                  # User profile
│   │   └── page.tsx              # Profile and settings
│   ├── home/                     # Home redirect page
│   │   └── page.tsx              # Redirect to main todos page
│   ├── globals.css               # Global styles with Duolingo theme
│   ├── layout.tsx                # Root layout with navigation
│   └── page.tsx                  # Main todos page
├── components/                   # React components
│   ├── ui/                       # shadcn/ui components
│   │   ├── button.tsx            # Enhanced with duolingo-button styling
│   │   ├── card.tsx
│   │   ├── dialog.tsx
│   │   ├── input.tsx
│   │   ├── select.tsx            # Updated for styling consistency
│   │   ├── badge.tsx
│   │   └── drawer.tsx
│   ├── modals/                   # Modal components
│   │   ├── create-group-modal.tsx # Modal for creating new groups
│   │   └── edit-group-modal.tsx   # Modal for editing existing groups
│   ├── shared/                   # Shared components
│   │   └── app-bar.tsx           # Enhanced with dark theme support
│   ├── bottom-nav.tsx            # Mobile bottom navigation
│   ├── color-picker.tsx          # Color selection component
│   ├── language-switcher.tsx     # Language toggle
│   ├── todo-item-compact.tsx     # Compact todo item with inline actions
│   └── edit-todo-modal.tsx       # Todo editing modal
├── lib/                          # Utilities and helpers
│   ├── utils.ts                  # Tailwind merge utilities
│   └── i18n.ts                   # Internationalization config
├── translations/                 # I18n translation files
│   ├── en.json                   # English translations
│   └── zh-HK.json                # Chinese (Hong Kong) translations
├── public/                       # Static assets
│   └── manifest.json             # PWA manifest
├── .vscode/                      # VS Code configuration
│   ├── extensions.json           # Recommended extensions
│   └── settings.json             # VS Code settings
├── mcp-direct.js                 # Standalone MCP server
├── middleware.ts                 # Authentication middleware
├── supabase-setup.sql             # Complete database schema setup
├── tailwind.config.js            # Tailwind with Duolingo colors
├── tsconfig.json                 # TypeScript configuration
└── next.config.js                # Next.js configuration

Database Schema

The application uses the following enhanced Supabase tables:

todos

• id: Primary key (bigint)
• user_id: Foreign key to auth.users (uuid)
• group_id: Foreign key to todo_groups (bigint, nullable)
• text: Todo content (text)
• completed: Completion status (boolean)
• is_finished: Alternative completion flag (boolean)
• priority: Priority level 0-2 (integer)
• deadline: Optional deadline (date)
• color: Hex color code for visual theming (varchar, default: '#3B82F6')
• inserted_at: Creation timestamp
• created_at: Created timestamp
• updated_at: Last update timestamp

todo_groups

• id: Primary key (bigint)
• user_id: Foreign key to auth.users (uuid)
• title: Group name (text)
• icon: Group icon name for UI rendering (text, default: 'FolderOpen')
• color: Hex color code for group theming (varchar, default: '#3B82F6')
• inserted_at: Creation timestamp (added via supabase-schema-update.sql)
• created_at: Created timestamp
• updated_at: Last update timestamp

api_keys

• id: Primary key (bigint)
• user_id: Foreign key to auth.users (uuid)
• name: Human-readable key name (text)
• key: API key string with 'mcp_' prefix (text)
• created_at: Creation timestamp
• last_used: Last usage timestamp (nullable)

All tables include comprehensive Row-Level Security (RLS) policies ensuring users can only access their own data.

Key Features Implementation

Mobile App Architecture

• Bottom Navigation: /landing (dashboard), /add (create todo), /groups (manage groups), /profile (settings)
• Duolingo Theme: Custom color palette with green (#58CC02), blue (#1CB0F6), orange (#FF9600), red (#FF4B4B), purple (#CE82FF), and pink (#FF86B7)
• Color System: Visual color picker with 8 predefined colors for todos and groups
• Gamification: Streak counters, achievement levels, progress bars, and completion tracking
• Responsive Design: Mobile-first approach with touch-friendly interactions and optimized spacing

Authentication Flow

• Enhanced Auth Pages: Splash screen, welcome page, separate login/register forms with graphics
• Password Recovery: Complete forgot/reset password flow with email verification
• Server-side authentication using Supabase SSR with enhanced middleware protection
• HTTP-only cookies for secure session management with automatic token refresh

Security Implementation

• Row-Level Security (RLS) on all tables
• User isolation enforced at database level
• API key authentication for MCP endpoints
• Secure key generation using crypto.randomBytes

MCP Integration Architecture

• Standards-compliant MCP server implementation
• JSON-RPC 2.0 protocol support
• Resource and tool exposure patterns
• Error handling with proper MCP error codes
• Authentication middleware for API key validation

Development Guidelines

Code Style

• TypeScript for type safety
• ESLint for code consistency
• Tailwind CSS for styling
• Server components by default
• Client components only when needed

Best Practices

• Server actions for form submissions
• Error boundaries for graceful error handling
• Loading states for better UX
• Responsive design with mobile-first approach
• Accessibility considerations in UI components

🔒 Security

Authentication & Authorization

• Supabase Auth with email/password flow
• Server-side session validation in middleware
• Row-Level Security policies on all tables
• API key-based authentication for MCP endpoints

Data Protection

• User data isolation via RLS policies
• Secure API key generation with cryptographic randomness
• HTTP-only cookies prevent XSS attacks
• Environment variable protection for sensitive keys

Security Headers

• Content Security Policy via Next.js
• HTTPS enforcement in production
• Secure cookie settings with SameSite protection

API Security

• Rate limiting considerations for MCP endpoints
• Input validation on all API routes
• SQL injection prevention via Supabase client
• CORS configuration for API endpoints

🐛 Troubleshooting

Common Issues

Database Connection Issues

# Check environment variables
echo $NEXT_PUBLIC_SUPABASE_URL
echo $NEXT_PUBLIC_SUPABASE_ANON_KEY

# Verify database connection
npm run dev
# Check browser console for errors

MCP Authentication Failures

# Verify API key format (should start with 'mcp_')
# Check API key in database
# Ensure Authorization header is correctly formatted

Build/Type Errors

# Run type checking
npm run type-check

# Fix ESLint issues
npm run lint

# Clear Next.js cache
rm -rf .next
npm run dev

Getting Help

• Next.js Issues: Next.js Documentation
• Supabase Issues: Supabase Documentation
• MCP Issues: MCP Documentation
• TypeScript Issues: TypeScript Handbook

Debug Mode

Enable debug logging:

# Development with debug logs
DEBUG=* npm run dev

# Or specific modules
DEBUG=mcp:* npm run dev

📚 Additional Resources

Learning Resources

• Next.js 14 App Router Guide
• Supabase Auth with Next.js
• Model Context Protocol Specification
• Tailwind CSS Documentation

Community & Support

• Next.js GitHub
• Supabase Community
• MCP GitHub

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Setup for Contributors

1. Install dependencies: npm install
2. Set up environment: Copy .env.example to .env.local
3. Run type checks: npm run type-check
4. Run linter: npm run lint
5. Test locally: npm run dev

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Next.js Team for the amazing framework
• Supabase Team for the fantastic backend-as-a-service
• MCP Team for the innovative AI agent protocol
• shadcn/ui for the beautiful component library
• Vercel for the seamless deployment platform

---

Built with ❤️ using Next.js 14, Supabase, and Model Context Protocol

This project demonstrates the power of modern web development combined with AI agent integration capabilities.