XYF Mobile Components MCP

一个用于查询 XYF Mobile 移动端组件库的 MCP (Model Context Protocol) 服务。

功能特性

• 组件列表查询: 获取所有可用的移动端组件列表
• 组件文档查询: 获取组件的详细文档、Props、Events 和 Slots 说明
• 代码示例: 提供完整的组件使用示例代码

MCP vs 直接喂文档

你可能会问："为什么不直接把组件文档复制粘贴给 AI，而是要用 MCP？"

以下是关键区别：

| 特性 | MCP | 直接喂文档 | |------|-----|-----------| | 上下文占用 | ✅ 按需查询，只加载需要的组件文档 | ❌ 需要一次性加载所有文档，占用大量上下文 | | Token 成本 | ✅ 节省 Token，只获取必要信息 | ❌ 文档越长，消耗的 Token 越多 | | 准确性 | ✅ 精确 API 调用，避免 AI 自行编造属性 | ❌ AI 可能遗漏文档细节或产生幻觉 | | 代码生成 | ✅ 标准化输出，提供一致的代码示例 | ❌ AI 生成的代码风格可能不一致 | | 维护成本 | ✅ 版本同步，文档随 npm 包自动更新 | ❌ 需要手动复制最新文档 | | 使用体验 | ✅ 对话流畅，AI 自动在需要时查询 | ❌ 需要反复手动提供文档 |

实际场景对比

场景 1：用户需要实现一个搜索功能

直接喂文档方式：

用户: 帮我实现一个搜索组件
AI: 好的，请提供 PostarSearch 组件的文档
用户: [复制粘贴 50 行文档]
AI: 好的，根据文档... [生成代码]

MCP 方式：

用户: 帮我实现一个搜索组件
AI: [自动调用 list-components 获取组件列表]
AI: [自动调用 get-component-docs 获取 PostarSearch 文档]
AI: 我找到了 PostarSearch 组件，让我为你生成代码...
[生成代码]

场景 2：项目中有 20 个组件，用户不确定用哪个

直接喂文档方式：

• 用户需要一次性粘贴 20 个组件的文档（数千 Token）
• AI 可能无法一次性处理这么多信息
• 需要分批提供，对话效率低

MCP 方式：

• AI 只查询一次组件列表（几十个 Token）
• 用户选择后，再查询具体组件文档
• Token 消耗极少，对话高效

什么时候不需要 MCP？

• ✅ 简单项目：只有 1-2 个组件，直接粘贴文档更快
• ✅ 快速原型：不需要精确的 API 定义
• ✅ 已有上下文：AI 已经记住了组件库的所有细节

什么时候必须使用 MCP？

• ✅ 大型组件库：组件数量多，文档量大
• ✅ 团队协作：需要确保代码生成的一致性
• ✅ 精确要求：需要准确的 Props、Events、Slots 定义
• ✅ 版本管理：文档需要随代码版本同步更新

支持的组件

• 基础组件: PostarBtn, PostarModal, PostarToast, PostarEmpty, PostarLoading
• 导航组件: PostarNavbar, PostarTabbar
• 表单组件: PostarField, PostarPicker, PostarDatetimePicker, PostarSearch, PostarNumberKeyboard
• 展示组件: PostarPopup, PostarActionSheet, PostarPopover, PostarCalendar, PostarSafeView
• 其他组件: PostarWeb, PostarVPopup, PostarWotPopup 等

安装

在 Claude Desktop 中使用

在 claude_desktop_config.json 中添加配置：

{
  "mcpServers": {
    "xyf-mobile-components": {
      "command": "npx",
      "args": ["-y", "@xyf-mobile/mcp"]
    }
  }
}

全局安装使用

npm install -g @xyf-mobile/mcp

### 本地开发使用

```json
{
  "mcpServers": {
    "xyf-mobile-components": {
      "command": "node",
      "args": [
        "/path/to/xyf-mobile/mcp/dist/cli.js"
      ]
    }
  }
}

文档同步

MCP 使用内置的 componentData/ 目录中的文档。当组件库文档更新时，需要同步：

# 在 xyf-mobile 根目录
pnpm sync:mcp-docs

# 或在 mcp 目录
cd mcp && pnpm sync-docs

提供的 Tools

1. list-components

列出所有可用的 XYF Mobile 组件。

2. get-component-docs

获取指定组件的详细文档。

参数:

• componentName: 组件名称，如 "Modal", "Navbar", "Search" 等

3. list-component-examples

获取指定组件的代码示例。

参数:

• componentName: 组件名称，如 "Modal", "Navbar", "Search" 等

发布流程

# 1. 更新组件文档后，同步到 MCP
pnpm sync:mcp-docs

# 2. 提交代码（包含 componentData/ 的变更）
git add mcp/componentData
git commit -m "docs: update component docs"

# 3. 创建 changeset
pnpm changeset:add

# 4. 提升版本
pnpm changeset:version

# 5. 发布
pnpm release

项目结构

mcp/
├── src/
│   ├── server.ts              # MCP 服务器入口
│   ├── cli.ts                 # CLI 入口
│   ├── tools/                 # 工具注册
│   │   ├── index.ts
│   │   ├── list-components.ts
│   │   ├── get-component-docs.ts
│   │   └── list-component-examples.ts
│   ├── utils/
│   │   └── components.ts      # 组件数据工具
│   └── constants/
│       └── path.ts            # 路径常量
├── componentData/             # 内置组件文档（由 sync-docs.js 生成）
│   ├── components-index.json
│   └── [component-name]/
│       └── docs.md
├── scripts/
│   └── sync-docs.js           # 文档同步脚本
├── package.json
├── tsconfig.json
└── tsup.config.ts

技术栈

• TypeScript
• MCP SDK (@modelcontextprotocol/sdk)
• Zod (参数校验)
• tsup (构建工具)

注意事项

1. XYF Mobile 是基于 Vue 3 + UniApp 的移动端组件库
2. 组件使用 rpx 作为单位，适配各种移动设备屏幕
3. 部分组件依赖于全局配置，请参考各组件的文档说明
4. MCP 默认使用内置的本地组件文档，无需网络连接

许可证

MIT