shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

todo_mcp_server

一个完整的Todo管理系统MCP服务器，集成了Kinde身份验证、Neon数据库和计费系统，支持通过Cursor AI进行交互，包含免费用户5条待办事项限制和付费升级功能。

article

README

🚀 带认证、数据库与计费功能的现代待办事项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 开发概念的学习项目。慢慢来，多尝试，不要犹豫探索代码！

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端