# m8-generator-mcp 开发指南
## 1. 项目概述
`m8-generator-mcp` 是一个基于 **Model Context Protocol (MCP)** 协议的智能辅助工具。旨在帮助 M8 框架开发者快速查阅组件文档、生成符合规范的代码结构，并提供工具函数检索功能。
### 核心能力
- **组件查询** (`get_component_usage`): 基于 RAG (检索增强生成) 提供 UI 组件的用法、Props 和示例。
- **结构生成** (`generate_module_structure`): 依据 M8 规范生成 Vue2/Vue3 页面目录结构。
- **工具、规范检索**: 提供 `Util` 工具函数和开发规范的快速查询。
---
## 2. 技术架构
### 2.1 技术栈
- **Runtime**: Node.js (>=18)
- **Language**: TypeScript
- **Protocol**: `@modelcontextprotocol/sdk` (MCP SDK)
- **Build Tool**: `tsc` (TypeScript Compiler)
### 2.2 目录结构
```bash
m8-generator-mcp/
├── data/ # 知识库数据源 (Markdown 文档)
│ ├── m8mpdoc/ # 组件库 & 工具库文档
│ └── standards/ # 开发规范文档
├── src/ # 源代码
│ ├── knowledge/ # RAG 检索引擎层
│ │ └── index.ts # 负责加载 data/ 下的 Markdown 并建立索引
│ ├── templates/ # 代码生成模板
│ │ ├── vue2.ts # Vue 2 模板 (页面, 路由, Store, Mock)
│ │ └── vue3.ts # Vue 3 模板
│ ├── tools/ # 工具逻辑实现
│ │ └── generate_module_structure.ts
│ └── index.ts # MCP Server 入口 & 工具注册
├── dist/ # 编译后输出目录 (发布用)
└── package.json # 依赖与脚本
```
---
## 3. 核心实现原理
### 3.1 知识库加载 system (RAG)
**位置**: `src/knowledge/index.ts`
- **加载机制**: 服务启动时，同步读取 `data/` 目录下的所有 Markdown 文件。
- **索引策略**:
- **组件**: 解析文件名 (如 `005-button按钮.md`) 提取组件名 `em-button`，并解析 Props、Events 和代码示例块。
- **规范**: 递归扫描 `standards/` 目录，按类别 (Project, Vue, CSS 等) 建立映射。
- **Util**: 扫描工具库文档，建立关键词索引。
### 3.2 代码生成 System
**位置**: `src/tools/` & `src/templates/`
- **逻辑分离**:
- `tools/generate_module_structure.ts` 负责接收参数、协调模板调用。
- `templates/*.ts` 存储纯文本模板字符串。
- **多版本支持**: 通过 `vueVersion` 参数区分调用 `vue2.ts` 或 `vue3.ts` 中的生成函数。
### 3.3 MCP Server & 工具注册
**位置**: `src/index.ts`
- 使用 `McpServer` 和 `StdioServerTransport` 创建服务。
- 通过 `server.tool()` 注册对外暴露的能力。
- 每个工具的回调函数中，通过调用 `knowledge` 模块的方法检索数据，或调用 `tools` 模块的方法生成代码。
---
## 4. 开发工作流
### 4.1 环境准备
```bash
# 安装依赖
npm install
```
### 4.2 本地调试
建议使用 TypeScript 监视模式进行开发：
```bash
# 启动编译监听
npm run dev
```
**调试方法**:
1. **使用 MCP Inspector (推荐)**:
可以使用 MCP 官方的调试工具来测试 Server。
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```
这会打开一个 Web 界面，你可以在里面列出工具并发送请求测试。
2. **命令行运行**:
直接运行编译后的文件，检查是否有启动报错。
```bash
node dist/index.js
```
_(注意: MCP Server 使用 Stdio 通信，直接运行不会有太多输出，除非有 console.error)_
### 4.3 编译构建
发布前需要进行完整构建：
```bash
npm run build:prod
```
此命令会执行 TSC 编译并进行代码压缩/混淆。
---
## 5. 扩展指南 (How-to)
### 场景 A: 添加新的组件文档
1. 将 Markdown 文档放入 `data/m8mpdoc/UI组件库/` 目录。
2. 命名格式建议: `XXX-组件名.md`。
3. 文档内容需包含 `### 介绍`, `#### Props`, `#### Events`, 和代码块示例。
4. **无需修改代码**，重启 Server 即可自动加载。
### 场景 B: 修改代码生成模板
1. 找到 `src/templates/` 目录下对应的 `vue2.ts` 或 `vue3.ts`。
2. 修改对应的模板函数 (如 `generateVue2Template`)。
3. 保持模板字符串中的变量插值 (`${moduleName}`) 正确。
### 场景 C: 新增一个 MCP 工具
1. 在 `src/tools/` 下新建逻辑文件 (可选)。
2. 在 `src/index.ts` 中引入逻辑。
3. 使用 `server.tool()` 注册新工具：
```typescript
server.tool(
"new_tool_name",
"工具描述",
{
param: z.string().describe("参数描述"),
},
async ({ param }) => {
// 实现逻辑
return { content: [{ type: "text", text: "结果" }] };
}
);
```
---
## 6. 常见问题 (FAQ)
**Q: 为什么生成的代码找不到 Util 工具?**
A: 请检查 `data/m8mpdoc/核心通用Util工具库` 下是否有对应的文档，且 Server 启动时是否成功加载 (可查看错误日志)。
**Q: 如何更新 M8 规范?**
A: 直接修改 `data/standards/` 下的 Markdown 文件即可，无需重新编译代码，但需要重启 Server 进程以重新加载文件。
