todo_mcp_server by sholajegede - 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:

Node.js (version 18 or higher)
A Neon Database account (free)
A Kinde account (free)
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)

Go to neon.tech
Create a free account
Create a new database
Copy your connection string
Update your .env file:

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

Step 4: Set Up Kinde Authentication (Free)

Go to kinde.com
Create a free account
Create a new application
Copy your credentials
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

Type "login" in Cursor chat
Click the URL to open authentication page
Login with Google (or other providers)
Copy your token from the success page
Use "save_token" command in Cursor
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

"No authentication token found"
- Make sure you've logged in and saved your token
- Check that the auth server is running
"Database connection failed"
- Verify your DATABASE_URL is correct
- Make sure you've run npm run setup-db
"Kinde authentication failed"
- Check your Kinde credentials in .env
- Verify your redirect URLs in Kinde dashboard
"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

Model Context Protocol (MCP): Standard for AI tool integration
OAuth Flow: Secure authentication without passwords
JWT Tokens: Secure user identification
Database Relations: User-todo relationships
Billing Integration: Freemium business models

Next Steps

Once you understand this project, you can:

Add More Features: Categories, due dates, sharing
Improve UI: Better web interface for auth
Add Real Billing: Stripe integration
Deploy: Host on Vercel, Railway, or AWS
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:

Check the troubleshooting section above
Verify all environment variables are set
Make sure all services are running
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!