kregyu

KPC组件库MCP服务

Community kregyu
Updated

KPC组件库MCP服务

KPC组件库MCP服务

基于官方 @modelcontextprotocol/sdk 开发的KPC组件库AI代码生成服务,彻底解决AI幻觉问题。

🎯 解决的问题

  1. AI幻觉问题: AI经常使用不存在的组件属性或错误的API
  2. 导入方式错误: AI使用错误的包名导入组件
  3. 嵌套关系错误: 如Form组件不使用FormItem包裹表单控件
  4. 依赖源码环境: 传统方案需要访问KPC源码

🚀 方案优势

特性 静态文档 官方SDK MCP服务
开发标准 自定义实现 官方TypeScript SDK
类型安全 无类型检查 完整TypeScript类型
错误处理 简单异常 标准MCP错误码
可维护性 手工维护 官方标准+自动化
Token消耗 ~50KB+ ~5KB 精确API
覆盖范围 部分组件 全部58个组件

📁 项目结构

mcp/
├── src/
│   ├── index.ts              # MCP服务器主入口
│   ├── types.ts              # TypeScript类型定义
│   ├── data-loader.ts        # 数据加载器
│   ├── validators.ts         # 组件使用验证器
│   ├── example-generator.ts  # 示例代码生成器
│   ├── formatters.ts         # 输出格式化器
│   └── test.ts              # 完整测试套件
├── data/                     # 组件API数据
│   ├── kpc-api-full.json     # 完整组件数据
│   ├── kpc-api-index.json    # 组件索引
│   └── kpc-api-*.json        # 分类数据文件
├── dist/                     # 编译输出
├── package.json              # 项目配置
├── tsconfig.json             # TypeScript配置
└── README.md                 # 项目文档

🛠️ 快速开始

1. 安装依赖

cd mcp
yarn install

2. 编译项目

yarn build

3. 运行测试

yarn test

4. 启动服务

yarn start

5. 配置Claude Desktop

编辑 Claude Desktop 配置文件:

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

{
  "mcpServers": {
    "kpc-components": {
      "command": "node",
      "args": ["/path/to/kpc/mcp/dist/index.js"],
      "cwd": "/path/to/kpc/mcp"
    }
  }
}

🔧 MCP工具列表

工具名 功能 参数
get_kpc_component 获取组件完整API component: 组件名
search_kpc_components 搜索相关组件 query: 搜索关键词category?: 分类筛选fuzzy?: 模糊搜索
list_kpc_components 列出所有组件 category?: 分类筛选summary?: 简要信息
validate_kpc_usage 验证组件使用 component: 组件名props: 属性对象context?: 上下文
get_kpc_usage_examples 获取使用示例 component: 组件名scenario?: 使用场景framework?: 目标框架
get_kpc_stats 获取统计信息 无参数

💡 实际使用示例

场景1: AI需要数字输入框

用户: "我需要一个数字输入框组件"

AI: [调用 search_kpc_components("数字输入")]
→ 找到: Spinner组件 - 数字输入框

AI: [调用 get_kpc_component("Spinner")]  
→ 获取: 完整的Spinner组件API

AI: 基于准确API生成代码:
<template>
  <Spinner 
    v-model="count"
    :min="0"
    :max="100" 
    :step="1"
    :precision="0"
    @change="handleChange"
  />
</template>

<script>
import { Spinner } from '@king-design/vue';

export default {
  components: { Spinner },
  data() {
    return { count: 0 };
  },
  methods: {
    handleChange(value, oldValue) {
      console.log('数值变化:', value);
    }
  }
};
</script>

场景2: 验证代码正确性

用户: "这样写对吗?<Form><Input /></Form>"

AI: [调用 validate_kpc_usage("Input", {}, "Form")]
→ 返回: ❌ Form组件内必须使用FormItem包裹表单控件

AI: 这样写是错误的,正确写法:
<Form>
  <FormItem label="输入框" :value="form.input" :rules="{required: true}">
    <Input v-model="form.input" />
  </FormItem>
</Form>

场景3: 获取使用示例

用户: "如何使用Table组件进行数据展示?"

AI: [调用 get_kpc_usage_examples("Table", "数据展示")]
→ 返回: 完整的Table使用示例代码

📊 API数据统计

运行 get_kpc_stats 工具查看最新统计:

  • 组件总数: 58个
  • 分类: 7大类(基础组件、表单组件、数据展示等)
  • API覆盖:
    • ✅ Props属性: 完整类型定义和默认值
    • ✅ Events事件: 参数类型和描述
    • ✅ Methods方法: 返回值类型和用途
    • ✅ Slots插槽: 参数定义和说明
    • ✅ 使用示例: 真实可用代码
    • ✅ 嵌套规则: 防止错误用法

🧪 测试验证

# 运行完整测试套件
yarn test

# 输出示例:
📊 测试结果:
   总计: 25 个测试
   通过: 25 个  
   失败: 0 个
   成功率: 100%
   总耗时: 156ms
🎉 所有测试通过!

测试覆盖:

  • ✅ 数据加载和缓存
  • ✅ 组件检索和搜索
  • ✅ 使用验证和错误检查
  • ✅ 示例生成和格式化
  • ✅ 边界情况和异常处理

🏗️ 开发指南

项目结构

// types.ts - 核心类型定义
export interface ComponentAPI {
  name: string;
  description: string;
  category: string;
  props: PropDefinition[];
  events: EventDefinition[];
  // ...
}

// data-loader.ts - 数据管理
export class KPCDataLoader {
  async initialize(): Promise<void>
  getComponent(name: string): ComponentAPI | null
  searchComponents(query: string): ComponentSummary[]
  // ...
}

// validators.ts - 使用验证
export class KPCUsageValidator {
  validate(component: ComponentAPI, props: object): ValidationResult
  // ...
}

添加新功能

  1. 添加新的MCP工具
// 在 index.ts 中添加工具定义
{
  name: 'my_new_tool',
  description: '工具描述',
  inputSchema: {
    type: 'object',
    properties: {
      param1: { type: 'string', description: '参数描述' }
    },
    required: ['param1']
  }
}

// 添加处理器
case 'my_new_tool':
  return await this.handleMyNewTool(args?.param1 as string);
  1. 扩展验证规则
// 在 validators.ts 中添加新规则
private validateCustomRules(component: ComponentAPI): void {
  // 自定义验证逻辑
}
  1. 自定义示例生成
// 在 example-generator.ts 中添加
generateCustomExample(component: ComponentAPI): UsageExample {
  // 生成特定类型的示例
}

🔄 数据更新流程

当KPC组件库更新时:

  1. 重新提取API数据(在KPC源码环境中):

    cd ../tools
    node extract-api.js
    
  2. 更新MCP服务数据

    cp -r ../tools/api-data ./data
    
  3. 重新编译和测试

    yarn build
    yarn test
    
  4. 重启服务

    yarn start
    

🔐 安全性和性能

安全性

  • 只读操作: 服务只提供API查询,不修改任何代码
  • 数据验证: 严格的TypeScript类型检查
  • 错误处理: 完善的异常捕获和MCP标准错误码
  • 输入验证: 所有用户输入都经过验证

性能优化

  • 数据缓存: 组件数据加载后缓存在内存
  • 按需查询: 只返回请求的组件信息
  • 分类索引: 支持快速分类查找和筛选
  • 异步加载: 使用异步I/O避免阻塞

🎉 最终效果

100%消除AI幻觉: 基于真实API数据,确保属性、事件、方法都存在 ✅ 正确的导入方式: 明确使用 @king-design/vue 等正确包名 ✅ 准确的嵌套关系: Form → FormItem → 表单控件等规则自动验证 ✅ 完整的API覆盖: 58个组件的全部Props、Events、Methods、Slots ✅ 智能验证机制: 实时检查代码正确性并提供修复建议 ✅ 官方标准实现: 基于官方TypeScript SDK,类型安全,易维护

🚢 部署选项

开发环境

# 开发模式(自动重编译)
yarn dev

# 运行测试
yarn test

生产环境

# 构建生产版本
yarn build

# 启动服务
yarn start

Docker部署

FROM node:18-alpine
WORKDIR /app
COPY package.json yarn.lock ./
RUN yarn install --production
COPY dist/ ./dist/
COPY data/ ./data/
CMD ["yarn", "start"]

CI/CD集成

  • KPC更新时自动重新提取API
  • 自动运行测试套件
  • 版本化管理API数据
  • 自动部署新版本服务

tools说明

  • extract-api.js 用于kpc根目录下生成kpc-api-full.json相关json
  • supplement_kpc_api.py 用于补全extract-api.js生成组件丢失的属性等
  • generate_api.files.py 用于基于kpc-api-full.json生成其他分类压缩json

这个基于官方SDK的实现提供了更高的代码质量、类型安全和维护性,是企业级应用的最佳选择。

MCP Server · Populars

MCP Server · New