Convex MCP Visual

凸形MCP视觉

](https://www.npmjs.com/package/convex-mcp-visual)

用于探索Converx数据库的模式可视化工具和仪表板工具。在终端输出旁边打开交互式浏览器UI。

特征：

• 具有图形视图、列表视图和文档浏览器的架构浏览器
• 用于查看已安装的Converx组件的组件浏览器
• 带有指标和图表的实时仪表板
• 带有关系检测的Mermaid ER图
• 用于文件和导入的代码库地铁地图
• 最近写入的表格热图
• 声明字段与推断字段的模式漂移视图
• 从日志中写入冲突报告
• 暗模式支持
• 多部署支持

三种使用方法：

凸引用：

• 部署密钥 -部署的身份验证
• 管理API -程序化项目管理
• 平台API -基于凸

Schema Graph View

快速开始

选项A：直接命令行界面（任何终端）：

# Install globally
npm install -g convex-mcp-visual

# Setup deploy key
convex-mcp-visual --setup

# Use it
convex-mcp-visual schema      # Browse schema
convex-mcp-visual components  # Browse installed components
convex-mcp-visual dashboard   # View metrics
convex-mcp-visual diagram     # Generate ER diagram
convex-mcp-visual subway      # Codebase subway map
convex-mcp-visual table-heatmap # Table writes heatmap
convex-mcp-visual schema-drift  # Declared vs inferred schema
convex-mcp-visual kanban      # Kanban board of jobs/agents
convex-mcp-visual write-conflicts --log-file logs.txt

选项B:MCP服务器（Claude/Cursor/OpenCode/Code）

# Auto-install to all MCP clients (Cursor, OpenCode, Claude Desktop, Codex)
npx convex-mcp-visual --install

# Or install to specific clients
npx convex-mcp-visual --install-cursor
npx convex-mcp-visual --install-opencode
npx convex-mcp-visual --install-claude
npx convex-mcp-visual --install-codex

# Claude Code CLI (alternative)
claude mcp add convex-visual -- npx convex-mcp-visual --stdio

# Codex CLI (alternative)
codex mcp add convex-visual -- npx convex-mcp-visual --stdio

# Setup deploy key
npx convex-mcp-visual --setup

选项C:Claude代码插件

# Add the marketplace
/plugin marketplace add waynesutton/convex-mcp-visual

# Install the plugin
/plugin install convex-visual@convex-visual-marketplace

看 Claude插件文档 有关插件结构的详细信息。

2.设置部署密钥

从Converx项目文件夹运行安装程序：

cd my-convex-app/
npx convex-mcp-visual --setup

安装向导从以下位置检测您的项目 .env.local 并为每个项目保存部署密钥。只需从Converx仪表板复制并粘贴密钥即可。

不添加 export CONVEX_DEPLOY_KEY=... 到您的shell配置文件 (~/.zshrc, ~/.bashrc等等）。全局导出覆盖每个项目的所有内容 .env.local 文件和 将每个项目连接到同一部署。如果您已经这样做了，请参阅 故障排除 用于移除步骤。

从获取部署密钥 dashboard.convex.dev 在“设置”>“部署密钥”下。

多个Converx应用程序

每个项目的一次性设置：

cd my-app-1/
npx convex-mcp-visual --setup
# Paste your deploy key when prompted, it saves to .env.local

在应用程序之间切换： 就 cd 到项目文件夹。MCP服务器从该文件夹中读取 .env.local 自动。

cd my-app-1/   # Now using my-app-1's Convex deployment
cd ../my-app-2/ # Now using my-app-2's Convex deployment

无需奔跑 --setup 再次在初始设置之后。

看 凸部署密钥 了解更多详情。

3.测试连接

npx convex-mcp-visual --test

4.使用它

克劳德的MCP命令：

所有工具都会打开一个交互式浏览器UI，并将输出返回给终端。模式浏览器默认为图形视图（带有表关系的可视化图表）。

架构图特征：

• 自动从外键模式中检测表关系
• 终端的ASCII/Unicode输出
• 浏览器中带有主题选项的SVG图
• 可导出的美人鱼代码
• 组件分组支持

组件浏览器功能：

• 列出所有已安装的Converx组件
• 检测已知的组件类型（代理、身份验证、速率限制器等）
• 显示组件表架构和文档计数
• “组件”选项卡集成在架构浏览器UI中

文档

• 安装指南 -配置和MCP客户端设置
• 工具参考 -参数和键盘快捷键
• 建筑 -它是如何工作的
• 故障排除 -常见问题和修复
• 局限性 -已知限制
• 插件分发 -克劳德代码市场
• Claude插件结构 -插件和市场文件
• 用户指南：架构浏览器 -使用模式浏览器
• 用户指南：仪表板 -使用仪表板

配置

CLI安装（推荐）

配置任何MCP客户端的最快方法：

# Install to all detected MCP clients
npx convex-mcp-visual --install

# Or target specific clients
npx convex-mcp-visual --install-cursor
npx convex-mcp-visual --install-opencode
npx convex-mcp-visual --install-claude

这会自动更新每个客户端的配置文件。

克劳德桌面（手册）

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "convex-visual": {
      "command": "npx",
      "args": ["convex-mcp-visual", "--stdio"],
      "env": {
        "CONVEX_DEPLOY_KEY": "prod:your-deployment|your-key"
      }
    }
  }
}

光标/VS代码（手动）

增添 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "convex-visual": {
      "command": "npx",
      "args": ["convex-mcp-visual", "--stdio"]
    }
  }
}

OpenCode（手动）

增添 ~/.config/opencode/opencode.json:

{
  "mcp": {
    "convex-visual": {
      "command": "npx",
      "args": ["convex-mcp-visual", "--stdio"]
    }
  }
}

Codex CLI（手动）

增添 ~/.codex/config.toml:

[mcp_servers.convex-visual]
command = "npx"
args = ["-y", "convex-mcp-visual", "--stdio"]

或者使用CLI命令：

codex mcp add convex-visual -- npx convex-mcp-visual --stdio

看 食品法典委员会MCP文件 了解更多详情。

CLI参考

MCP客户端安装命令

# Install to MCP clients (updates config files automatically)
npx convex-mcp-visual --install           # All detected clients
npx convex-mcp-visual --install-cursor    # Cursor only
npx convex-mcp-visual --install-opencode  # OpenCode only
npx convex-mcp-visual --install-claude    # Claude Desktop only
npx convex-mcp-visual --install-codex     # Codex CLI only

# Uninstall from MCP clients
npx convex-mcp-visual --uninstall         # All clients
npx convex-mcp-visual --uninstall-cursor  # Cursor only
npx convex-mcp-visual --uninstall-codex   # Codex CLI only

直接CLI命令

convex-mcp-visual schema               # Browse schema in graph view (default)
convex-mcp-visual schema --graph       # Explicitly open graph view
convex-mcp-visual schema --list        # Browse schema in list view
convex-mcp-visual schema --table users # Focus on specific table
convex-mcp-visual schema --json        # JSON output only

convex-mcp-visual dashboard            # View metrics dashboard

convex-mcp-visual diagram              # Generate Mermaid ER diagram
convex-mcp-visual diagram --theme dracula
convex-mcp-visual diagram --ascii      # ASCII output for terminal
convex-mcp-visual subway               # Codebase subway map
convex-mcp-visual table-heatmap        # Table writes heatmap
convex-mcp-visual schema-drift         # Declared vs inferred schema
convex-mcp-visual write-conflicts --log-file logs.txt

convex-mcp-visual kanban               # Kanban board (auto-detect)
convex-mcp-visual kanban --jobs        # Scheduled functions and crons
convex-mcp-visual kanban --agents      # AI agent threads

MCP服务器选项

convex-mcp-visual [options]

MCP Client Install:
--install            Install to all MCP clients
--install-cursor     Install to Cursor
--install-opencode   Install to OpenCode
--install-claude     Install to Claude Desktop
--install-codex      Install to Codex CLI
--uninstall          Remove from all MCP clients

Server Options:
--stdio              Run in stdio mode (default for MCP)
--http               Run in HTTP mode
--port          Port for HTTP mode (default: 3001)
--deployment   Connect to specific deployment
--test               Test Convex connection
--setup              Interactive setup wizard
--config             Show all detected config sources
-v, --version        Show version number
-h, --help           Show help

升级

# Check your current version
npx convex-mcp-visual --version

# If using npx, you get the latest version automatically
npx convex-mcp-visual@latest --version

# If installed globally, update with
npm update -g convex-mcp-visual

卸载

# Remove from all MCP clients
npx convex-mcp-visual --uninstall

# Or remove from specific clients
npx convex-mcp-visual --uninstall-cursor
npx convex-mcp-visual --uninstall-opencode
npx convex-mcp-visual --uninstall-claude
npx convex-mcp-visual --uninstall-codex

# Remove from Claude Code (alternative)
claude mcp remove convex-visual

# Remove from Codex CLI (alternative)
codex mcp remove convex-visual

# Remove global package
npm uninstall -g convex-mcp-visual

故障排除

部署错误或部署密钥卡住

如果该工具一直连接到错误的Converx部署，则全局配置将覆盖您的本地项目设置。

1.检查活动的配置：

npx convex-mcp-visual --config

2.清除全局环境变量：

unset CONVEX_DEPLOY_KEY
echo $CONVEX_DEPLOY_KEY

如果变量在新端子中重新出现，则表示已将其添加到外壳配置文件中。在编辑器中打开文件并删除 export CONVEX_DEPLOY_KEY=... 线路：

拆下线路后，打开一个新的终端以确认线路已断开。

3.删除旧的全局配置文件：

rm ~/.convex-mcp-visual.json

此文件是由旧版本的 --setup。删除它会使每个项目 .env.local 文件优先。

4.根据项目配置使用：

在每个Converx项目文件夹中，运行 --setup 或创建 .env.local 文件：

CONVEX_DEPLOY_KEY="prod:your-deployment-name|your-admin-key"

5.验证：

npx convex-mcp-visual --test

配置优先级

找到的第一个来源获胜：

1. CONVEX_DEPLOY_KEY 环境变量（最高优先级）
2. CONVEX_URL 环境变量
3. .env.local 在当前目录中
4. .convex/deployment.json 在当前目录中
5. ~/.convex/config.json （Converx CLI登录会话）
6. ~/.convex-mcp-visual.json （传统全局回退）

有关更多问题，请参阅 故障排除文档.

贡献

看 发展 获取构建说明。

git clone https://github.com/waynesutton/convex-mcp-visual.git
cd convex-mcp-visual
npm install
npm run build

许可证

麻省理工学院