Todo MCP Server

🚀 認証、データベース、課金機能を備えたモダンなTodo MCPサーバー

このプロジェクトは、認証、課金、データベース統合を備えた、モダンなWeb開発手法を実証する完全なModel Context Protocol (MCP) サーバーです。フルスタック開発を学ぶ初心者に最適です！

🚀 クイックスタート

このプロジェクトの機能

このプロジェクトは、Cursor AI（またはMCP互換のクライアント）を通じて対話できるTodo管理システムを作成します。以下の機能が含まれています。

• Kindeによる実際の認証
• 無料利用制限付きの課金システム
• Neon PostgreSQLによるデータベースストレージ
• MCPプロトコルを通じたAI統合
• 認証用のWebインターフェース

前提条件

始める前に、以下が必要です。

1. Node.js（バージョン18以上）
2. Neon Databaseアカウント（無料）
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

✨ 主な機能

• 新規ユーザーには5つの無料Todo
• 無制限のTodoを利用するには有料プランにアップグレード
• Google/ソーシャルログインによる実際の認証
• PostgreSQLによるデータベースの永続化
• Cursorを通じたAIチャット統合
• セキュアなクッキーによるセッション管理

📚 ドキュメント

アーキテクチャの概要

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   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)

• "create todo"、"list todos"などのAIチャットコマンドを処理します。
• ユーザー認証と課金を管理します。
• データの永続化のためにデータベースに接続します。

2. 認証サーバー (src/kinde-auth-server.ts)

• ログイン/ログアウト用のWebインターフェースを提供します。
• KindeとのOAuthフローを処理します。
• ユーザーデータベースレコードを自動的に作成します。

3. データベースセットアップ (src/setup-db.ts)

• 必要なデータベーステーブルを作成します。
• パフォーマンスのためにインデックスを設定します。
• ユーザーとTodoのスキーマを初期化します。

使い方

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              # あなたのTodoを表示する
create todo             # 新しいTodoを作成する
update todo             # 既存のTodoを更新する
delete todo             # Todoを削除する
logout                  # ログアウトする

認証フロー

1. Cursorチャットで**"login"** と入力します。
2. URLをクリックして認証ページを開きます。
3. Google（または他のプロバイダー）でログインします。
4. 成功ページからトークンをコピーします。
5. Cursorで**"save_token"** コマンドを使用します。
6. Todoの作成を始めましょう！

課金システム

• 無料プラン: ユーザーごとに5つのTodo
• 有料プラン: 無制限のTodo（Kindeポータルを通じてアップグレード）
• 自動追跡: システムが自動的に使用状況を追跡します。
• アップグレードURL: 制限に達したときに提供されます。

データベーススキーマ

ユーザーテーブル

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

Todoテーブル

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

開発コマンド

# 開発用
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. "No authentication token found"

   • ログインしてトークンを保存したことを確認してください。
   • 認証サーバーが実行されていることを確認してください。

2. "Database connection failed"

   • DATABASE_URLが正しいことを確認してください。
   • npm run setup-dbを実行したことを確認してください。

3. "Kinde authentication failed"

   • .envファイルのKinde資格情報を確認してください。
   • KindeダッシュボードのリダイレクトURLを確認してください。

4. "MCP server not found in Cursor"

   • mcp.jsonを更新した後にCursorを再起動してください。
   • npm startでサーバーが実行されていることを確認してください。

デバッグモード

デバッグログを有効にして実行します。

DEBUG=* npm run dev

学習リソース

学べること

• MCPプロトコル: AIアシスタントがツールとどのように対話するか
• OAuth 2.0: モダンな認証フロー
• PostgreSQL: データベースの設計とクエリ
• TypeScript: 型安全なJavaScript開発
• Express.js: Webサーバーの開発
• セッション管理: ユーザー状態の永続化

重要な概念

1. Model Context Protocol (MCP): AIツール統合の標準
2. OAuthフロー: パスワードなしの安全な認証
3. JWTトークン: 安全なユーザー識別
4. データベースの関係: ユーザーとTodoの関係
5. 課金統合: フリーミアムビジネスモデル

次のステップ

このプロジェクトを理解したら、以下のことができます。

1. 機能の追加: カテゴリ、期限、共有機能などを追加する
2. UIの改善: 認証用のWebインターフェースを改善する
3. 実際の課金システムの追加: Stripeとの統合
4. デプロイ: Vercel、Railway、またはAWSにホストする
5. スケーリング: キャッシュ、ロードバランシングを追加する

貢献方法

これは学習用のプロジェクトです！自由に以下のことを行ってください。

• バグの報告
• 改善案の提案
• 新機能の追加
• チュートリアルの作成

📄 ライセンス

MITライセンス - 学習やプロジェクトに自由に使用できます！

ヘルプが必要な場合

もし困った場合は、以下を確認してください。

1. 上記のトラブルシューティングセクションを確認する
2. すべての環境変数が設定されていることを確認する
3. すべてのサービスが実行されていることを確認する
4. コンソールにエラーメッセージが表示されていないか確認する

覚えておいてください: これはモダンなWeb開発の概念を教えるための学習用プロジェクトです。ゆっくりと試して、コードを自由に探索してください！