Todo MCP Server

🚀 带认证、数据库与计费功能的现代待办事项MCP服务器

这是一个完整的 模型上下文协议（MCP） 服务器项目，展示了结合认证、计费和数据库集成的现代Web开发实践。非常适合学习全栈开发的初学者！

🚀 快速开始

本项目创建了一个 待办事项管理系统，你可以通过 Cursor AI（或任何兼容MCP的客户端）与之交互。它包含以下功能：

• 通过 Kinde 实现 真实认证
• 带有免费额度限制的 计费系统
• 使用 Neon PostgreSQL 进行 数据库存储
• 通过 MCP 协议实现 AI 集成
• 用于认证的 Web 界面

✨ 主要特性

• 新用户可创建 5 条免费待办事项
• 可 升级为付费版 以创建无限数量的待办事项
• 通过 Google/社交登录实现 真实认证
• 使用 PostgreSQL 实现 数据库持久化
• 通过 Cursor 实现 AI 聊天集成
• 使用安全 cookie 进行 会话管理

🔧 技术细节

架构概述

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Cursor AI     │    │   MCP Server     │    │  Kinde Auth     │
│   (Your Chat)   │◄──►│   (This Project) │◄──►│   (Authentication)│
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │  Neon Database   │
                       │  (PostgreSQL)    │
                       └──────────────────┘

项目结构

mcp-todo-rebuild/
├── src/
│   ├── server.ts              # 主 MCP 服务器
│   ├── kinde-auth-server.ts   # 认证 Web 服务器
│   └── setup-db.ts           # 数据库设置脚本
├── dist/                     # 编译后的 JavaScript
├── package.json              # 依赖项和脚本
├── tsconfig.json            # TypeScript 配置
├── .env                     # 环境变量（需创建）
└── README.md               # 本文件

工作原理

1. MCP 服务器 (src/server.ts)

• 处理诸如“创建待办事项”、“列出待办事项”等 AI 聊天命令
• 管理用户认证和计费
• 连接数据库以实现数据持久化

2. 认证服务器 (src/kinde-auth-server.ts)

• 提供登录/注销的 Web 界面
• 处理与 Kinde 的 OAuth 流程
• 自动创建用户数据库记录

3. 数据库设置 (src/setup-db.ts)

• 创建必要的数据库表
• 设置索引以提高性能
• 初始化用户和待办事项模式

认证流程

1. 在 Cursor 聊天中 输入“login”
2. 点击链接 打开认证页面
3. 使用 Google（或其他提供商）登录
4. 从成功页面 复制令牌
5. 在 Cursor 中使用 “save_token”命令
6. 开始创建待办事项！

计费系统

• 免费套餐：每个用户可创建 5 条待办事项
• 付费套餐：可创建无限数量的待办事项（通过 Kinde 门户升级）
• 自动跟踪：系统自动跟踪使用情况
• 升级链接：达到限制时提供

数据库模式

用户表

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
);

待办事项表

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
);

📦 安装指南

前提条件

在开始之前，你需要：

1. Node.js（版本 18 或更高）
2. Neon 数据库 账户（免费）
3. Kinde 账户（免费）
4. Cursor IDE（用于 MCP 集成）

步骤 1：克隆并安装

# 克隆仓库
git clone <your-repo-url>
cd todo-mcp-server

# 安装依赖项
npm install

步骤 2：设置环境

# 运行设置脚本
chmod +x setup.sh
./setup.sh

这将创建一个包含占位符值的 .env 文件。

步骤 3：设置 Neon 数据库（免费）

1. 访问 neon.tech
2. 创建免费账户
3. 创建新数据库
4. 复制连接字符串
5. 更新 .env 文件：

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

步骤 4：设置 Kinde 认证（免费）

1. 访问 kinde.com
2. 创建免费账户
3. 创建新应用程序
4. 复制凭证
5. 更新 .env 文件：

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

步骤 5：初始化数据库

# 设置数据库表
npm run setup-db

步骤 6：构建并运行

# 构建项目
npm run build

# 启动 MCP 服务器
npm start

💻 使用示例

基础用法

1. 启动服务器

# 终端 1：启动 MCP 服务器
npm start

# 终端 2：启动认证服务器
npm run auth-server

2. 配置 Cursor

将以下内容添加到你的 Cursor MCP 配置文件 (~/.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. 在 Cursor 聊天中使用

配置完成后，你可以在 Cursor 中使用以下命令：

login                    # 获取认证 URL
save_token: <token>     # 保存登录令牌
list todos              # 查看待办事项
create todo             # 创建新的待办事项
update todo             # 更新现有待办事项
delete todo             # 删除待办事项
logout                  # 注销

📚 详细文档

开发命令

# 开发
npm run dev              # 在开发模式下运行 MCP 服务器
npm run auth-server     # 在开发模式下运行认证服务器

# 数据库
npm run setup-db        # 设置数据库表

# 生产
npm run build           # 为生产环境构建
npm start              # 运行生产服务器

配置

环境变量

创建一个包含以下变量的 .env 文件：

# 数据库
DATABASE_URL=postgresql://user:pass@host:port/db

# Kinde 认证
KINDE_ISSUER_URL=https://your-domain.kinde.com
KINDE_CLIENT_ID=your_client_id
KINDE_CLIENT_SECRET=your_client_secret

# 安全
JWT_SECRET=your_secret_key

# 环境
NODE_ENV=development

故障排除

常见问题

1. “未找到认证令牌”

   • 确保你已登录并保存了令牌
   • 检查认证服务器是否正在运行

2. “数据库连接失败”

   • 验证 DATABASE_URL 是否正确
   • 确保已运行 npm run setup-db

3. “Kinde 认证失败”

   • 检查 .env 中的 Kinde 凭证
   • 验证 Kinde 控制台中的重定向 URL

4. “Cursor 中未找到 MCP 服务器”

   • 更新 mcp.json 后重启 Cursor
   • 检查服务器是否通过 npm start 运行

调试模式

使用调试日志运行：

DEBUG=* npm run dev

学习资源

你将学到的内容

• MCP 协议：AI 助手与工具的交互方式
• OAuth 2.0：现代认证流程
• PostgreSQL：数据库设计和查询
• TypeScript：类型安全的 JavaScript 开发
• Express.js：Web 服务器开发
• 会话管理：用户状态持久化

关键概念

1. 模型上下文协议（MCP）：AI 工具集成的标准
2. OAuth 流程：无需密码的安全认证
3. JWT 令牌：安全的用户标识
4. 数据库关系：用户与待办事项的关系
5. 计费集成：免费增值商业模式

下一步计划

理解本项目后，你可以：

1. 添加更多功能：分类、截止日期、共享功能
2. 改进 UI：优化认证的 Web 界面
3. 添加真实计费：集成 Stripe
4. 部署：部署到 Vercel、Railway 或 AWS
5. 扩展：添加缓存、负载均衡

贡献

这是一个学习项目！欢迎你：

• 报告 bug
• 提出改进建议
• 添加新功能
• 创建教程

📄 许可证

本项目采用 MIT 许可证，你可以自由用于学习和项目开发！

寻求帮助

如果你遇到问题：

1. 查看上述故障排除部分
2. 验证所有环境变量是否已设置
3. 确保所有服务都在运行
4. 检查控制台中的错误消息

请记住：这是一个旨在教授现代 Web 开发概念的学习项目。慢慢来，多尝试，不要犹豫探索代码！