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

# Clone the repository
git clone <your-repo-url>
cd todo-mcp-server

# Install dependencies
npm install

Step 2: Set Up Environment

# 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
2. Create a free account
3. Create a new database
4. Copy your connection string
5. Update your .env file:

DATABASE_URL=postgresql://your-connection-string-here

Step 4: Set Up Kinde Authentication (Free)

1. Go to kinde.com
2. Create a free account
3. Create a new application
4. Copy your credentials
5. Update your .env file:

KINDE_ISSUER_URL=https://your-domain.kinde.com
KINDE_CLIENT_ID=your_client_id
KINDE_CLIENT_SECRET=your_client_secret

Step 5: Initialize Database

# Set up database tables
npm run setup-db

Step 6: Build and Run

# 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

# 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):

{
  "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

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

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

# 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:

# 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:

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!