KPC组件库MCP服务
基于官方 @modelcontextprotocol/sdk 开发的KPC组件库AI代码生成服务,彻底解决AI幻觉问题。
🎯 解决的问题
- AI幻觉问题: AI经常使用不存在的组件属性或错误的API
- 导入方式错误: AI使用错误的包名导入组件
- 嵌套关系错误: 如Form组件不使用FormItem包裹表单控件
- 依赖源码环境: 传统方案需要访问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
// ...
}
添加新功能
- 添加新的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);
- 扩展验证规则:
// 在 validators.ts 中添加新规则
private validateCustomRules(component: ComponentAPI): void {
// 自定义验证逻辑
}
- 自定义示例生成:
// 在 example-generator.ts 中添加
generateCustomExample(component: ComponentAPI): UsageExample {
// 生成特定类型的示例
}
🔄 数据更新流程
当KPC组件库更新时:
重新提取API数据(在KPC源码环境中):
cd ../tools node extract-api.js
更新MCP服务数据:
cp -r ../tools/api-data ./data
重新编译和测试:
yarn build yarn test
重启服务:
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的实现提供了更高的代码质量、类型安全和维护性,是企业级应用的最佳选择。