@yoka-ui/mcp

MCP Server for @yoka-ui/ui 与 @yoka-ui/vue · 当前版本 1.0.9
栈无关引擎：启动时绑定单一数据根。同一镜像两个 HTTP 实例：:3001 React / :3002 Vue。

运行环境

| 场景 | 环境 | 说明 | |------|------|------| | 生产 / 团队共享 | Linux liujixiang-dev-01 · 5.4.0-122-generic · x86_64 | HTTP 容器，镜像 linux/amd64，端口 3001 | | 本地开发 | macOS Apple Silicon M4 | stdio / HTTP 本机调试；推生产镜像须 --platform linux/amd64 |

| 产物 | 路径 | 命令 | |------|------|------| | 组件库 | 仓库根 dist/ | pnpm build | | 文档站 | 仓库根 docs-dist/ | pnpm build:docs | | MCP | ecosystem/yoka-ui-mcp/dist/ | npm run build / ./deploy.sh --type mcp |

统一部署入口：deploy.sh（--type docs|mcp|mcp-vue）。

Tools

| Tool | 作用 | 可不挂仓库 | |------|------|------------| | suggest_component | 意图 → 组件候选（routing） | 部分 | | explain_component_choice | 解释某组件是否适合给定意图 | 部分 | | get_component_ai_doc | 共置 <Name>.docs.md（写 Props 优先） | 包已发布时 | | get_component_props | 结构化 Props JSON（对齐 antd_info；可选 detail） | 包已发布时 | | get_yoka_token | YK 自有 token（YK_THEME / YK_CHAT_THEME / --yk-* / 局部主题）；antd 组件级请用 antd MCP | 需源码或包内 src | | get_yoka_design | YK Design Markdown（public/design.md / YK-DESIGN.md，可按章节切片） | 需源码仓或含设计文件的数据根 | | get_component_semantic | YK semantic 槽位；多数委托 antd_semantic | 是 | | get_yoka_changelog | 查询 CHANGELOG.md（version / component；无 API diff） | 需含 CHANGELOG 的数据根 | | get_yoka_document | 合成文档（优先附带 *.docs.md） | 部分 | | get_component_demo | 默认 basic.tsx / basic.vue；variant / listOnly / includeAll | 否 | | get_component_source | 源码（大文件截断函数体） | 否 | | get_component_file_list | 组件目录文件列表 | 否 | | get_yoka_exports | 导出表；mode=summary 轻量列表，默认 full | 包已发布时 | | get_stories | stories 示例（Vue 数据根不可用） | 否 |

Prompts：suggest-yoka-component、write-yoka-usage、review-yoka-import。

推荐取证顺序（写码）：suggest_component → get_component_props → get_component_ai_doc → get_component_demo。
主题 / 语义 / 设计：get_yoka_token（Chat 用 scope: "chat"）；get_yoka_design；槽位先 get_component_semantic，继承 antd 的再调 antd MCP antd_token / antd_semantic。
变更查询：get_yoka_changelog（以仓库 CHANGELOG.md 为准，内容较薄时空结果属正常）。

Resource：yoka://components。

数据源优先级：YOKA_UI_REPO_PATH → 自动探测源码仓 → YOKA_UI_PACKAGE_PATH / node_modules/@yoka-ui/{ui,vue} → npm CDN（CDN 包名跟随数据根）。

混栈仓库：只启用一个 MCP URL + 一个 Skill，与当前安装的包一致。引擎不根据业务仓 package.json 猜栈。

CLI 快捷方式：@yoka-ui/cli 的 yoka setup / yoka mcp / yoka doctor 等，见文档站 CLI。

快速上手

团队 HTTP 服务（推荐）

| 栈 | MCP 端点 | 健康检查 | |------|------|------| | React @yoka-ui/ui | http://10.191.80.222:3001/mcp | http://10.191.80.222:3001/health | | Vue @yoka-ui/vue | http://10.191.80.222:3002/mcp | http://10.191.80.222:3002/health |

/health 的 dataRootPackage 须与栈一致。/mcp 不是网页；浏览器打开会 406。

Cursor

.cursor/mcp.json：

{
  "mcpServers": {
    "yoka-ui-mcp": {
      "url": "http://10.191.80.222:3001/mcp"
    }
  }
}

Claude Desktop / Claude Code

Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code：项目 .mcp.json 或 claude mcp add --transport http yoka-ui-mcp http://10.191.80.222:3001/mcp

{
  "mcpServers": {
    "yoka-ui-mcp": {
      "type": "http",
      "url": "http://10.191.80.222:3001/mcp"
    }
  }
}

VS Code

.vscode/mcp.json（顶层键为 servers）：

{
  "servers": {
    "yoka-ui-mcp": {
      "type": "http",
      "url": "http://10.191.80.222:3001/mcp"
    }
  }
}

Codex

~/.codex/config.toml 或 codex mcp add yoka-ui-mcp --url http://10.191.80.222:3001/mcp：

[mcp_servers.yoka-ui-mcp]
url = "http://10.191.80.222:3001/mcp"

OpenCode

opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "yoka-ui-mcp": {
      "type": "remote",
      "url": "http://10.191.80.222:3001/mcp",
      "enabled": true,
      "oauth": false
    }
  }
}

stdio（本地 / 离线）

{
  "mcpServers": {
    "yoka-ui-mcp": {
      "command": "npx",
      "args": ["-y", "@yoka-ui/mcp"],
      "env": {
        "YOKA_UI_REPO_PATH": "/Users/liujilei/projects/yoka-ui"
      }
    }
  }
}

或全局安装后：

pnpm add -g @yoka-ui/mcp
YOKA_UI_REPO_PATH=/Users/liujilei/projects/yoka-ui yoka-ui-mcp

生产部署（liujixiang-dev-01）

cd /opt/yoka-ui   # 或实际克隆路径
git pull --ff-only
./deploy.sh rebuild --type mcp --yoka-ui-path /opt/yoka-ui

./deploy.sh status --type mcp
./deploy.sh logs --type mcp

• 宿主端口默认 3001；健康检查 GET /health
• 资源默认：内存 512m、CPU 0.5、NODE_OPTIONS=--max-old-space-size=384
• Compose 备选：cd ecosystem/yoka-ui-mcp && YOKA_UI_REPO_PATH=/opt/yoka-ui docker compose up -d --build
• 旧脚本 mcp-deploy.sh 已废弃，请用根目录 deploy.sh

macOS M4 构建生产镜像（勿推 arm64）：

./deploy.sh build --type mcp
# 或
docker build --platform linux/amd64 -t yoka-ui-mcp:latest \
  -f ecosystem/yoka-ui-mcp/Dockerfile ecosystem/yoka-ui-mcp

HTTP 端点：POST/GET /mcp、GET /health、GET /。

本地开发（macOS M4）

cd /Users/liujilei/projects/yoka-ui
pnpm install
cd ecosystem/yoka-ui-mcp
pnpm exec tsc --noEmit
pnpm build

# stdio
YOKA_UI_REPO_PATH=/Users/liujilei/projects/yoka-ui pnpm start

# HTTP
YOKA_UI_REPO_PATH=/Users/liujilei/projects/yoka-ui pnpm start:http

源码调试（无需先 build）：

YOKA_UI_REPO_PATH=/Users/liujilei/projects/yoka-ui \
  node --import tsx/esm src/http.ts --port 3100

新增 Tool：在 src/tools/ 实现后注册到 src/tools/index.ts；新增 Prompt：改 src/prompts/index.ts 并在 server.ts 已挂 prompts capability，再 pnpm build。

测试

pnpm test            # build + node:test（c8）
pnpm test:coverage   # statements / lines / functions ≥ 80%

用例在 tests/*.test.mjs。覆盖率配置见 .c8rc.json（排除 stdio/http 入口与 npm 磁盘缓存等难单测路径）。

目录

src/
  stdio.ts / http.ts   # 传输入口
  server.ts            # 注册 tools / resources / prompts
  tools/               # Tool 实现
  prompts/             # MCP prompts
  utils/               # 数据根、routing、AI docs、demos 路径、缓存
tests/                 # node:test + c8
Dockerfile             # linux/amd64
docker-compose.yml

发布

cd ecosystem/yoka-ui-mcp
npm login
npm publish --access public
# 开启 2FA：npm publish --access public --otp=XXXXXX

prepublishOnly 会执行 npm run build。发版前 bump package.json version。

配置

| 变量 | 说明 | |------|------| | YOKA_UI_REPO_PATH | 源码仓根。本地：/Users/liujilei/projects/yoka-ui；生产：/opt/yoka-ui | | YOKA_UI_PACKAGE_PATH | 可选，已安装 @yoka-ui/ui / @yoka-ui/vue 包根 | | YOKA_UI_PACKAGE_NAME | 可选，探测 node_modules 时只匹配该包名 | | YOKA_UI_DISABLE_REPO | 设为 1 时跳过源码仓探测（强制包路径；测试常用） | | PORT | HTTP 端口，默认 3001 | | TZ | 默认 Asia/Shanghai |

yoka-ui-mcp-http [--port 3001] [--host 0.0.0.0] [--stateless]

磁盘缓存（npm CDN）：macOS ~/.yoka-ui-mcp/cache/。

相关

• 文档站 MCP Server · CLI
• @yoka-ui/cli
• 消费方接入 ai/