内容
# Visily MCP
Visily MCP 服务器将您的 Visily 设计引入 AI 编码代理。指向 Visily 看板或屏幕，您的代理可以找到它，将其转换为应用程序代码，或提取其主题令牌 — 使用您的 Visily 设计系统作为真实来源。
> [!NOTE]
> **访问要求。** Visily MCP 仅适用于 **Pro 或 Business** 计划的工作空间，您是工作空间创建者或具有 **编辑器** 许可证。免费工作空间和查看者/访客角色不受支持。每次请求都会强制执行此限制。
## 功能
- **将 Visily 设计转换为代码。** 从 Visily 屏幕或看板生成生产就绪的代码 — 无论 UI 是在 Visily 中由 AI 生成还是手动编写。代理重建语义响应组件（默认堆栈：React + TypeScript + Tailwind v4 + shadcn/ui），而不是粘贴静态导出。
- **查找看板或屏幕并获取其链接。** 通过描述（例如“我在 4.6 版本中使用的看板”）查找设计，代理返回一个链接以打开它 — 无需离开您的编辑器。
- **应用看板的主题。** 拉取看板的设计系统作为 shadcn/Tailwind v4 令牌，并将其应用于另一个应用程序的样式。
## 安装和连接
身份验证是 **OAuth** — 您的客户端在首次使用时提示您登录 Visily。无需管理 API 密钥。
当前的 Visily MCP 服务器 URL 是：
```
https://app.visily.ai/api/mcp
```
每个平台的插件文件都位于 [`plugins/<platform>/`](plugins/) 下。
### Claude Code
```bash
claude plugin marketplace add visily-app/mcp-plugins
claude plugin install visily@visily
```
然后重新加载 Claude Code 并运行 `/mcp` → 选择 `visily` → 完成 OAuth 登录。完整教程：[`installation-guides/claude.md`](installation-guides/claude.md)。
### Cursor
Cursor 2.5+ 打包插件 — 从代理聊天中的本地克隆安装：
```
/add-plugin ./plugins/cursor
```
重新加载 Cursor；MCP 服务器出现在 **设置 → MCP** （首次使用时 OAuth）下，Visily 技能会自动加载。详情：[`plugins/cursor/README.md`](plugins/cursor/README.md)。
### Codex
```bash
codex plugin marketplace add visily-app/mcp-plugins
codex plugin add visily@visily
```
通过 OAuth 授权首次使用。完整教程：[`installation-guides/codex.md`](installation-guides/codex.md)。
### ChatGPT
ChatGPT 通过 **开发者模式** 自定义连接器连接到远程 MCP 服务器（Plus、Pro、Business 或 Enterprise）。启用 **设置 → 连接器 → 高级 → 开发者模式**，添加一个指向上述服务器 URL 的自定义连接器，并完成 OAuth。然后将 [`plugins/chatgpt/AGENTS.md`](plugins/chatgpt/AGENTS.md) 粘贴到项目/GPT 的说明中。步骤：[`plugins/chatgpt/SETUP.md`](plugins/chatgpt/SETUP.md)。
### Antigravity
复制 [`plugins/antigravity/.agents/`](plugins/antigravity) 到您的项目根目录，并将 [`plugins/antigravity/mcp_config.json`](plugins/antigravity/mcp_config.json) 合并到您的全局 MCP 配置中。详情：[`installation-guides/antigravity.md`](installation-guides/antigravity.md)。
### Kiro
复制 [`plugins/kiro/`](plugins/kiro) 到您的 Kiro 权力目录（它包含 `POWER.md`、每个意图的 `steering/` 工作流和 `mcp.json`）。将 `mcp.json` 合并到您的 Kiro MCP 配置中，并通过 OAuth 授权。该权力在 Visily URL 和查找/构建/主题意图上激活。
### Lovable
将 [`plugins/lovable/AGENTS.md`](plugins/lovable/AGENTS.md) 提交到您的仓库根目录，并在 Lovable UI 中添加 Visily MCP 连接器。详情：[`plugins/lovable/SETUP.md`](plugins/lovable/SETUP.md)。
### v0 (Vercel)
[v0](https://v0.app) 原生支持自定义 MCP 服务器。通过 **设置 → MCP 连接** （或提示表单中的 **添加 MCP** ）添加上述服务器 URL，并通过 OAuth 授权，然后将 [`plugins/v0/AGENTS.md`](plugins/v0/AGENTS.md) 提交到您的仓库根目录。详情：[`plugins/v0/SETUP.md`](plugins/v0/SETUP.md)。
### 其他编辑器（Streamable HTTP）
任何支持 Streamable-HTTP MCP 的客户端都可以使用此配置连接：
```json
{
"mcpServers": {
"visily": {
"url": "https://app.visily.ai/api/mcp"
}
}
}
```
这涵盖了 VS Code（Copilot）、Windsurf、Cline、Gemini CLI 和类似工具。请查看客户端的文档，了解 MCP 服务器配置的位置；OAuth 在首次使用时运行。
> [!NOTE]
> **Google AI Studio** 尚不支持 MCP 连接器（它仅通过第三方浏览器桥接器工作，我们不推荐使用）。对于 Google 原生选项，请使用 **Firebase Studio** ，它通过 `.idx/mcp.json` 支持 MCP 服务器 — 放入相同的 URL 配置中。我们将在 AI Studio 推出原生 MCP 支持时添加一流的配方。
## 提示您的代理
给代理一个 Visily 链接和明确的意图。代理从 URL 中提取 ID — 它不会打开页面。
**示例**
- “查找我在 4.6 版本中使用的 Visily 看板并给我链接。”
- “使用以下 Visily 屏幕构建 React + Tailwind：`https://app.visily.ai/projects/abc/boards/456/elements/789`”
- “使用我的 `src/components/ui` 组件在 Next.js 中实现此看板。”
- “将我的 Visily 看板主题应用于此应用的 `globals.css`。”
Visily URL 的格式如下：
```
https://app.visily.ai/projects/{projectId}/boards/{boardId}/elements/{elementId}
```
## 结构化您的 Visily 文件以获得更好的代码
您的设计携带的意图越多，生成的代码就越好：
- **在 Visily 中为屏幕和关键组命名语义** — 名称流入导出并进入链接匹配以“查找我的看板”。
- **依赖 Visily 的主题/设计系统** ，以便代理可以应用真正的令牌而不是猜测颜色和半径。
- **一次请求一个屏幕** 用于大型看板 — 更小的选择产生更可靠的结果。
## 工具
| 工具 | 用途 |
|---|---|
| `get_design_context` | **主要。** 返回一个元素的 `designData` + 主题 + 截图元数据。 |
| `get_screenshot` | 获取截图用于视觉验证。 |
| `get_board_theme` | 看板设计系统作为 shadcn 令牌（`JSON` / `CSS` / `Tailwind`）。 |
| `list_workspaces`、`list_projects`、`list_boards`、`list_elements` | 发现/查找看板。 |
| `get_workspace`、`get_project`、`get_board`、`get_element`、`get_element_export` | 高级 — 元数据和原始导出很少需要用于三种用例；请优先使用上面的工具。 |
服务器还提供 **提示** （例如 `find_visily_board`、`generate_code_from_element`、`apply_board_theme`）和 **资源** （`visily://docs/...`），您的代理按需读取。
## 自定义规则（可选）
设置项目级指导，以便输出保持一致 — 例如新团队成员的入职培训笔记。
**Cursor** （`.cursor/rules/visily-quality.mdc`）：
```yaml
---
description: Visily 代码生成规则
alwaysApply: false
---
- 将 Visily `designData` 视为参考，而不是最终代码 — 语义重建。
- 应用 Visily `theme` 令牌；永远不要硬编码十六进制、半径或间距。
- 重用 `src/components/ui` 中的现有组件，而不是重复。
- 在完成前使用 `get_screenshot` 验证 1:1 布局。
```
**Claude Code** (`CLAUDE.md`)：
```markdown
## Visily MCP 规则
- 将 Visily `designData` 视为参考，而不是最终代码 — 语义重建。
- 应用 Visily `theme` 令牌；永远不要硬编码十六进制、半径或间距。
- 重用现有组件而不是重复；使用 `get_screenshot` 验证。
```
## 此仓库的构建方式
`plugins/` 由单个共享源（`shared/`）使用 `scripts/build.mjs` 生成。要更改集成，请编辑 `shared/` 并运行 `npm run build` — 永远不要手动编辑 `plugins/`。请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
