convexskills MCP — ユースケース, インストール & ライブデモ

なぜ使うのか

主な機能

実際のコード例付きConvex専用スキル12種
関数（query/mutation/action/HTTP）、スキーマ、リアルタイム、cron、ファイルストレージ、エージェントをカバー
セキュリティスキル2種：convex-security-checkとconvex-security-audit
スキーマ進化のためのマイグレーションパターン
再利用可能なコンポーネント作成用のconvex-component-authoring

ライブデモ

実際の動作

convexskills-skill.replay ▶ 準備完了

0/0

インストール

クライアントを選択

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "convexskills-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/waynesutton/convexskills",
        "~/.claude/skills/convexskills"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config を開く。保存後、アプリを再起動。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "convexskills-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/waynesutton/convexskills",
        "~/.claude/skills/convexskills"
      ],
      "_inferred": true
    }
  }
}

Cursor は Claude Desktop と同じ mcpServers スキーマを使用。プロジェクト設定はグローバルより優先。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "convexskills-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/waynesutton/convexskills",
        "~/.claude/skills/convexskills"
      ],
      "_inferred": true
    }
  }
}

Cline サイドバーの MCP Servers アイコンをクリックし、"Edit Configuration" を選択。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "convexskills-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/waynesutton/convexskills",
        "~/.claude/skills/convexskills"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop と同じ形式。Windsurf を再起動して反映。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "convexskills-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/waynesutton/convexskills",
        "~/.claude/skills/convexskills"
      ]
    }
  ]
}

Continue はマップではなくサーバーオブジェクトの配列を使用。

~/.config/zed/settings.json

{
  "context_servers": {
    "convexskills-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/waynesutton/convexskills",
          "~/.claude/skills/convexskills"
        ]
      }
    }
  }
}

context_servers に追加。保存時に Zed がホットリロード。

claude mcp add convexskills-skill -- git clone https://github.com/waynesutton/convexskills ~/.claude/skills/convexskills

ワンライナー。claude mcp list で確認、claude mcp remove で削除。

ユースケース

実用的な使い方： convexskills

リアルタイム＋認証＋ファイルアップロード付きの新規Convexアプリをスキャフォールドする

👤 新規Convexプロジェクトを始めるフルスタック開発者 ⏱ ~90 min intermediate

使うタイミング： ゼロから始める際に、最初のファイルから正しいConvexパターンを使いたい場合。

前提条件

Convex CLI — npm create convex

フロー

スキーマを設計する

convex-schema-validatorスキルを使用してください。users、projects、filesテーブルを適切なインデックス付きで設計してください。✓ コピーしました

→ スキーマがv.id()を使用し、インデックスが宣言され、リレーションが正しいこと
queryとmutationを接続する

convex-functionsスキルを使用してください。projectsのCRUDを実装してください。✓ コピーしました

→ 読み取りにquery、書き込みにmutationを使用し、actionの誤用がないこと
リアルタイムとファイルアップロードを追加する

convex-realtimeとconvex-file-storageを使って、projectsをファイル添付付きでライブ更新できるようにしてください。✓ コピーしました

→ ReactがuseQueryで購読し、ファイルがstorage.generateUploadUrlで保存されること

結果： 拡張可能な正しい構造のConvexアプリが完成します。

注意点

mutationで十分な箇所にactionを使ってしまう — スキルが強制するルール：DB書き込みにはmutation、外部I/Oにはaction

古い行をクリーンアップする日次cronジョブを追加する

👤 バックグラウンドメンテナンスを追加するConvex開発者 ⏱ ~20 min beginner

使うタイミング： ワーカーを別途立てずにスケジュールタスクが必要な場合。

フロー

cronスキルを使用する

convex-cron-jobsを使用してください。sessionsテーブルから30日以上前の行を削除する日次ジョブを追加してください。✓ コピーしました

→ crons.tsエントリ＋クリーンアップ用のinternal mutation
テストする

テスト用に手動でトリガーする方法を教えてください。✓ コピーしました

→ 開発専用HTTPアクションまたはCLIレシピ

結果： Convexのマネージドスケジューラー上で動作するcronジョブが完成します。

注意点

cronがinternal mutationではなくqueryを実行してしまう — スキルが削除処理にinternal mutationを強制します

Convexアプリの認可の穴を監査する

👤 本番リリース前の開発者 ⏱ ~45 min advanced

使うタイミング： アプリは完成しているが、認証のストレステストをまだ行っていない場合。

フロー

監査を実行する

このリポジトリに対してconvex-security-auditを実行してください。すべてのpublic mutationが適切な認証を行っているか確認してください。✓ コピーしました

→ 関数ごとの認証状況と重大度
修正する

IDチェックを追加し、未認証の読み取りにはnullを返すフォールバックを適用してください。✓ コピーしました

→ 関数にctx.authチェックが追加されること

結果： 本番リリース前に認証が強化されます。

注意点

「public＝未認証」というメンタルモデルに頼ってしまう — Convexのpublic関数はインターネットから到達可能です。スキルは認証チェックを必須とします

組み合わせ： github

組み合わせ

他のMCPと組み合わせて10倍の力を

convexskills-skill + github

スキルが設計＋実装し、GitHub MCPがPRを作成する

convexskillsで機能を構築してから、変更内容でPRを作成してください。✓ コピーしました

convexskills-skill + playwright-skill

Convexバックエンドを構築し、PlaywrightでUIをエンドツーエンドテストする

Convexバックエンドを実装してから、UIにアクセスしてリアルタイム更新を検証するplaywright-skillテストを書いてください。✓ コピーしました

ツール

このMCPが提供する機能

ツール	入力	呼び出すタイミング
convex-functions	function need	関数に関するあらゆる作業
convex-schema-validator	data model	テーブルの設計や変更時
convex-realtime	UI use case	リアクティブUIの追加時
convex-cron-jobs	scheduled task	定期的なバックグラウンド処理
convex-migrations	schema change	既存スキーマの変更時
convex-security-audit	repo	本番リリース前のレビュー

コストと制限

運用コスト

APIクォータ: スキル自体にはなし。Convex側に無料＋有料プランがあります
呼び出しあたりのトークン: スキルロードごとに2〜6kトークン
金額: 無料 — スキルはローカルです。Convexには充実した無料枠があります。
ヒント: フルセットの読み込みを避けるため、特定のスキル名を指定してください（例：convex-cron-jobs）。

セキュリティ

権限、シークレット、影響範囲

認証情報の保管： スキル内にクレデンシャルはありません。Convexのデプロイキーは.envに保管されます。

データ送信先： スキル自体からのデータ送出はありません

Convexのpublic関数はインターネットから到達可能です。本番リリース前に必ずconvex-security-auditを実行してください。

トラブルシューティング

よくあるエラーと対処法

Claudeがmutationで十分な箇所にactionを書いてしまう

スキルが強制する基本ルール：DBのみ → mutation、外部I/O → action。

スキーマ変更が既存データを壊してしまう

convex-migrationsスキルを使用してください。バックフィル付きの安全な移行を計画します。

useQueryがリアルタイムで更新されない

リアクティビティを確認してください。queryは古いインデックスではなく、変更されたデータを読み取る必要があります。

代替案

convexskills 他との比較

代替案	代わりに使う場面	トレードオフ
Manual Convex docs + examples	すでにConvexの経験が豊富な場合	スキルなしではオンボーディングが遅くなる
Framework-specific fullstack skills	Convexを使っていない場合	技術スタックが異なる

その他

リソース

📖 GitHub の公式 README を読む

🐙 オープンな issue を見る

🔍 400以上のMCPサーバーとSkillsを見る