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 開發概念的學習項目。慢慢來，多嘗試，不要猶豫探索代碼！