convex-agent-skillz MCP — 使用場景, 安裝 & 即時演示

為什麼要用

核心特性

深度 Convex 模式 — 查詢、mutation、action、HTTP 端點
即時功能：在線狀態、串流、協作編輯
持久化操作：工作流程、佇列、排程任務
驗證模式 — 通用版，以及 Clerk 與 WorkOS 專屬設定
AI agent 模式：執行緒、工具呼叫、RAG、持久化訊息歷史

即時演示

實際使用效果

convex-agent-skillz-skill.replay ▶ 就緒

0/0

安裝

選擇你的客戶端

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

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

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

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

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

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit

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

點擊 Cline 側欄中的 MCP Servers 圖示，然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json

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

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "convex-agent-skillz-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/PolarCoding85/convex-agent-skillz",
        "~/.claude/skills/convex-agent-skillz"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列，而非映射。

~/.config/zed/settings.json

{
  "context_servers": {
    "convex-agent-skillz-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/PolarCoding85/convex-agent-skillz",
          "~/.claude/skills/convex-agent-skillz"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add convex-agent-skillz-skill -- git clone https://github.com/PolarCoding85/convex-agent-skillz ~/.claude/skills/convex-agent-skillz

一行命令搞定。用 claude mcp list 驗證，claude mcp remove 移除。

使用場景

實戰用法： convex-agent-skillz

為現有 Convex 應用程式加入即時在線狀態

👤 正在加入協作功能的 Convex 開發者 ⏱ ~45 min intermediate

何時使用： 你已有一個應用程式，想加入 Figma 風格的「誰在線上」指示器，又不想自己架設 socket 伺服器。

前置條件

將 Skill 複製到專案的 .claude 資料夾中 — git clone https://github.com/PolarCoding85/convex-agent-skillz 後，將 .claude/ 複製到專案根目錄

步驟

描述功能需求

Using the Convex skillz — add presence to the documents page. Show cursors and usernames.✓ 已複製

→ Claude 使用 Convex 的在線狀態模式（mutation + 響應式查詢）實作，而非自訂 WebSocket
處理斷線情況

What about cleanup when users close the tab?✓ 已複製

→ 提供符合 Convex 慣例的過期在線狀態清理策略

結果： 具備完整清理機制的在線狀態功能。

注意事項

使用與 Convex 響應式機制衝突的自訂在線狀態模式 — Skill 會引導你採用慣用寫法；非必要不要覆蓋

搭配使用： filesystem

正確將 Clerk 驗證整合至 Convex

👤 將 Clerk 接入全新或現有 Convex 應用程式的開發者 ⏱ ~30 min intermediate

何時使用： 你選擇了 Clerk，希望第一次就把 Convex 整合做對。

步驟

串接 Provider

Convex skillz — integrate Clerk auth with Convex. Set up the JWT template and the Convex auth config.✓ 已複製

→ Claude 正確參照 Clerk JWT 範本名稱及 auth.config.ts 設定
保護查詢

Now gate the documents query so only the owner can read.✓ 已複製

→ 使用 ctx.auth.getUserIdentity() 模式並進行適當的身份驗證

結果： 通過程式碼審查且不會跨租戶洩漏資料的驗證機制。

在 Convex 上建立具有持久化執行緒的 AI Agent

👤 正在開發聊天或 agent 產品的開發者 ⏱ ~90 min advanced

何時使用： 你需要跨 session 保留的執行緒訊息歷史。

步驟

設計執行緒資料模型

Convex skillz — agent threads table + message history + tool calling metadata.✓ 已複製

→ 涵蓋串流、不完整訊息及工具呼叫狀態的 schema 設計
接上串流

Stream the assistant response back via a reactive query.✓ 已複製

→ 利用 Convex 響應式特性的部分訊息模式

結果： 原生 Convex 的 agent 執行緒層，可隨需求擴展。

組合

與其他 MCP 搭配，撬動十倍槓桿

convex-agent-skillz-skill + github

為功能新增建立符合 Convex 慣例的差異 PR

Implement the presence feature, commit and open PR with the Convex skill patterns noted.✓ 已複製

convex-agent-skillz-skill + filesystem

在同一個 session 中跨 schema、函式與 UI 進行開發

Update convex/schema.ts, add the mutation, and wire up the React hook.✓ 已複製

工具

此 MCP 暴露的能力

工具	輸入參數	何時呼叫
queries_mutations_actions	feature intent	任何 convex/ 目錄下的開發工作
realtime_patterns	feature (presence / streaming / collab)	即時功能開發
auth_setup	provider (Clerk / WorkOS / custom)	串接驗證機制
durable_ops	workflow intent	長時間執行或需要重試的邏輯
ai_agent_threads	agent feature description	在 Convex 上開發 agent 產品

成本與限制

運行它的成本

API 配額: Skill 本身不消耗 API 配額
每次呼叫 Token 數: 中等 — 模式依情境按需載入
費用: 免費 — Skill 為本地檔案。Convex 本身有其獨立計費方式。
提示: 將 Skill 放在專案的 .claude/ 目錄而非全域設定 — 自動啟用在專案範圍內效果最佳。

安全

權限、密鑰、影響範圍

憑證儲存： Skill 中不含任何憑證。你的驗證服務商金鑰請存放於自己的環境變數中。

資料出站： Skill 本身不產生任何資料外送 — 程式碼保留在本地

驗證模式假設你已在 Clerk/WorkOS 中正確設定 JWT 範本 — 請同時閱讀其官方文件。

故障排查

常見錯誤與修復

Skill not invoked — Claude writes non-Convex-idiomatic code

明確說明「use the Convex skillz」，或確保你正在 convex/ 目錄內工作。

驗證： ls <project>/.claude/agents/convex-expert.md

SKILL.md frontmatter wrong

重新從 repo 複製 .claude/ 目錄。

驗證： head <project>/.claude/skills/*/SKILL.md

Wrong trigger keywords — auth pattern doesn't use your provider

明確指定驗證服務商（「with Clerk」／「with WorkOS」）。

替代方案

convex-agent-skillz 對比其他方案

替代方案	何時用它替代	權衡
Convex official docs	你偏好查閱第一手資料而非精選 Skill	無法在 agent 中自動啟用
Hand-rolled patterns	你是有經驗的 Convex 開發者	你將自行重新發明這些模式；Skill 的作用是讓 Claude 一致地套用你的模式

convex-agent-skillz