Todo MCP Server

# Modern Todo MCP Server with Authentication, Database & Billing A complete **Model Context Protocol (MCP)** server that demonstrates modern web development practices with authentication, billing, and database integration. Perfect for beginners learning full-stack development! ## What This Project Does This project creates a **Todo Management System** that you can interact with through **Cursor AI** (or any MCP-compatible client). It includes: - **Real Authentication** with Kinde - **Billing System** with free tier limits - **Database Storage** with Neon PostgreSQL - **AI Integration** through MCP protocol - **Web Interface** for authentication ## Key Features - **5 Free Todos** for new users - **Upgrade to Paid** for unlimited todos - **Real Authentication** with Google/social login - **Database Persistence** with PostgreSQL - **AI Chat Integration** through Cursor - **Session Management** with secure cookies ## Architecture Overview ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Cursor AI │ │ MCP Server │ │ Kinde Auth │ │ (Your Chat) │◄──►│ (This Project) │◄──►│ (Authentication)│ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ ▼ ┌──────────────────┐ │ Neon Database │ │ (PostgreSQL) │ └──────────────────┘ ``` ## Prerequisites Before you start, you'll need: 1. **Node.js** (version 18 or higher) 2. **A Neon Database** account (free) 3. **A Kinde account** (free) 4. **Cursor IDE** (for MCP integration) ## Quick Start Guide ### Step 1: Clone and Install ```bash # Clone the repository git clone <your-repo-url> cd todo-mcp-server # Install dependencies npm install ``` ### Step 2: Set Up Environment ```bash # Run the setup script chmod +x setup.sh ./setup.sh ``` This creates a `.env` file with placeholder values. ### Step 3: Set Up Neon Database (Free) 1. Go to [neon.tech](https://neon.tech) 2. Create a free account 3. Create a new database 4. Copy your connection string 5. Update your `.env` file: ```env DATABASE_URL=postgresql://your-connection-string-here ``` ### Step 4: Set Up Kinde Authentication (Free) 1. Go to [kinde.com](https://kinde.com) 2. Create a free account 3. Create a new application 4. Copy your credentials 5. Update your `.env` file: ```env KINDE_ISSUER_URL=https://your-domain.kinde.com KINDE_CLIENT_ID=your_client_id KINDE_CLIENT_SECRET=your_client_secret ``` ### Step 5: Initialize Database ```bash # Set up database tables npm run setup-db ``` ### Step 6: Build and Run ```bash # Build the project npm run build # Start the MCP server npm start ``` ## Project Structure ``` mcp-todo-rebuild/ ├── src/ │ ├── server.ts # Main MCP server │ ├── kinde-auth-server.ts # Authentication web server │ └── setup-db.ts # Database setup script ├── dist/ # Compiled JavaScript ├── package.json # Dependencies and scripts ├── tsconfig.json # TypeScript configuration ├── .env # Environment variables (create this) └── README.md # This file ``` ## How It Works ### 1. **MCP Server** (`src/server.ts`) - Handles AI chat commands like "create todo", "list todos" - Manages user authentication and billing - Connects to database for data persistence ### 2. **Auth Server** (`src/kinde-auth-server.ts`) - Provides web interface for login/logout - Handles OAuth flow with Kinde - Automatically creates user database records ### 3. **Database Setup** (`src/setup-db.ts`) - Creates necessary database tables - Sets up indexes for performance - Initializes user and todo schemas ## How to Use ### 1. Start the Servers ```bash # Terminal 1: Start MCP server npm start # Terminal 2: Start auth server npm run auth-server ``` ### 2. Configure Cursor Add this to your Cursor MCP configuration (`~/.cursor/mcp.json`): ```json { "mcpServers": { "todo-mcp-server": { "command": "node", "args": ["dist/server.js"], "cwd": "/path/to/your/project", "env": { "DATABASE_URL": "your_database_url", "KINDE_ISSUER_URL": "your_kinde_issuer", "KINDE_CLIENT_ID": "your_client_id", "KINDE_CLIENT_SECRET": "your_client_secret", "JWT_SECRET": "your_jwt_secret", "NODE_ENV": "development" } } } } ``` ### 3. Use in Cursor Chat Once configured, you can use these commands in Cursor: ``` login # Get authentication URL save_token: <token> # Save your login token list todos # View your todos create todo # Create a new todo update todo # Update an existing todo delete todo # Delete a todo logout # Log out ``` ## Authentication Flow 1. **Type "login"** in Cursor chat 2. **Click the URL** to open authentication page 3. **Login with Google** (or other providers) 4. **Copy your token** from the success page 5. **Use "save_token"** command in Cursor 6. **Start creating todos!** ## Billing System - **Free Tier**: 5 todos per user - **Paid Tier**: Unlimited todos (upgrade through Kinde portal) - **Automatic Tracking**: System tracks usage automatically - **Upgrade URL**: Provided when limit is reached ## Database Schema ### Users Table ```sql CREATE TABLE users ( id SERIAL PRIMARY KEY, user_id TEXT UNIQUE NOT NULL, name TEXT, email TEXT, subscription_status TEXT DEFAULT 'free', plan TEXT DEFAULT 'free', free_todos_used INTEGER DEFAULT 0, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); ``` ### Todos Table ```sql CREATE TABLE todos ( id SERIAL PRIMARY KEY, user_id TEXT NOT NULL, title TEXT NOT NULL, description TEXT, completed BOOLEAN DEFAULT FALSE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); ``` ## Development Commands ```bash # Development npm run dev # Run MCP server in development npm run auth-server # Run auth server in development # Database npm run setup-db # Set up database tables # Production npm run build # Build for production npm start # Run production server ``` ## Configuration ### Environment Variables Create a `.env` file with these variables: ```env # Database DATABASE_URL=postgresql://user:pass@host:port/db # Kinde Authentication KINDE_ISSUER_URL=https://your-domain.kinde.com KINDE_CLIENT_ID=your_client_id KINDE_CLIENT_SECRET=your_client_secret # Security JWT_SECRET=your_secret_key # Environment NODE_ENV=development ``` ## Troubleshooting ### Common Issues 1. **"No authentication token found"** - Make sure you've logged in and saved your token - Check that the auth server is running 2. **"Database connection failed"** - Verify your DATABASE_URL is correct - Make sure you've run `npm run setup-db` 3. **"Kinde authentication failed"** - Check your Kinde credentials in `.env` - Verify your redirect URLs in Kinde dashboard 4. **"MCP server not found in Cursor"** - Restart Cursor after updating `mcp.json` - Check that the server is running with `npm start` ### Debug Mode Run with debug logging: ```bash DEBUG=* npm run dev ``` ## Learning Resources ### What You'll Learn - **MCP Protocol**: How AI assistants interact with tools - **OAuth 2.0**: Modern authentication flows - **PostgreSQL**: Database design and queries - **TypeScript**: Type-safe JavaScript development - **Express.js**: Web server development - **Session Management**: User state persistence ### Key Concepts 1. **Model Context Protocol (MCP)**: Standard for AI tool integration 2. **OAuth Flow**: Secure authentication without passwords 3. **JWT Tokens**: Secure user identification 4. **Database Relations**: User-todo relationships 5. **Billing Integration**: Freemium business models ## Next Steps Once you understand this project, you can: 1. **Add More Features**: Categories, due dates, sharing 2. **Improve UI**: Better web interface for auth 3. **Add Real Billing**: Stripe integration 4. **Deploy**: Host on Vercel, Railway, or AWS 5. **Scale**: Add caching, load balancing ## Contributing This is a learning project! Feel free to: - Report bugs - Suggest improvements - Add new features - Create tutorials ## License MIT License - feel free to use this for learning and projects! ## Need Help? If you get stuck: 1. Check the troubleshooting section above 2. Verify all environment variables are set 3. Make sure all services are running 4. Check the console for error messages Remember: This is a learning project designed to teach modern web development concepts. Take your time, experiment, and don't hesitate to explore the code!