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的实现提供了更高的代码质量、类型安全和维护性，是企业级应用的最佳选择。