# 埋点 MCP 工具

基于 Model Context Protocol (MCP) 的专业埋点代码生成工具，自动生成符合企业级标准的跟踪代码。

## 🚀 快速开始

### 安装配置

在支持 MCP 的客户端中添加服务器配置：

```json
{
  "mcpServers": {
    "mcp-ai-track": {
      "command": "npx",
      "args": ["-y", "mcp-ai-track"],
      "env": {
        "ENVIRONMENT": "h5",
        "BUSINESS": "jk"
      }
    }
  }
}
```

### 本地配置

```json
{
  "mcpServers": {
    "mcp-ai-track": {
      "command": "node",
      "args": ["/path/to/mcp-ai-track/dist/server.js"],
      "env": {
        "ENVIRONMENT": "h5",
        "BUSINESS": "jk"
      }
    }
  }
}
```

### 不同环境配置示例

通过环境变量设置默认的 environment 和 business 参数：

**微信小程序**:

```json
{
  "mcpServers": {
    "mcp-ai-track": {
      "command": "node",
      "args": ["/path/to/mcp-ai-track/dist/server.js"],
      "env": {
        "ENVIRONMENT": "wxmp",
        "BUSINESS": "jk"
      }
    }
  }
}
```

**支付宝小程序**:

```json
{
  "mcpServers": {
    "mcp-ai-track": {
      "command": "node",
      "args": ["/path/to/mcp-ai-track/dist/server.js"],
      "env": {
        "ENVIRONMENT": "alipaymp",
        "BUSINESS": "bx"
      }
    }
  }
}
```

**原生应用**:

```json
{
  "mcpServers": {
    "mcp-ai-track": {
      "command": "node",
      "args": ["/path/to/mcp-ai-track/dist/server.js"],
      "env": {
        "ENVIRONMENT": "app",
        "BUSINESS": "jkyx"
      }
    }
  }
}
```

## 🛠️ 核心工具

### 1. api_data - API 调用埋点

- **事件类型**: api_data
- **参数**: state(pre/success/failed) + action(order/login/get 等) + description(自定义)
- **用途**: API 调用前后的状态跟踪

### 2. web_click - 页面点击埋点

- **事件类型**: $WebClick
- **参数**: subject(page/pop) + scene(order/banner 等) + description(submit/close 等)
- **用途**: 用户点击行为跟踪

### 3. popup - 弹窗显示埋点

- **事件类型**: Popup
- **参数**: scene(splash/collection 等) + description(自定义)
- **用途**: 弹窗展示事件跟踪

### 4. focus_related - 焦点事件埋点

- **事件类型**: focus_related
- **参数**: subject(page/pop) + focus(focus/blur) + description(input*/select*等)
- **用途**: 表单元素焦点跟踪

## 📋 参数规范

### 固定参数值

**环境 (environment)**: h5 | wxmp | alipaymp | ksmp | app
**业务 (business)**: jk | bx | wa | qsgy | jkyx | mg |

### API 埋点参数

**状态 (state)**: pre | success | failed
**动作 (action)**: order | login | imageupload | get | add | update | delete
**描述 (description)**: 自定义，如 phone、userinfo、gominepage

### 点击埋点参数

**主体 (subject)**: page | pop
**场景 (scene)**: order | condition | banner | promotion | progress | recomm | tabbar
**描述 (description)**: laststep | nextstep | continue | submit | receive | confirm | close

### 弹窗埋点参数

**场景 (scene)**: splash | collection | remind | confirmationmodal
**描述 (description)**: 自定义，描述弹窗用途

### 焦点埋点参数

**主体 (subject)**: page | pop
**焦点 (focus)**: focus | blur
**描述 (description)**: input* | select* | search\* + 上下文（如 inputname、selectcity）

## ⚙️ 高级功能

### 自动配置

- **环境、业务默认值**:环境：environment=h5,业务： business=jk （可手动指定 AI 更换）
- **JIRA 集成**: 自动从 git 分支提取 JIRA Key (格式: XXXX-1234) (分支名必须包含 XXXX-1234，也可手动指定 AI 更换)

### 可选参数

- `jiraKey`: JIRA 任务号
- `environment`: 环境
- `business`:业务

### 输出格式

```javascript
window.sa.track("事件类型", {
  jiraKey: "BASESERVER-2411222", // 可选
  fileName: "环境_业务_参数组合", // 必需
  chineseDesc:'中文描述' //必须
  fileValue: window.sa.fv(), // 可选，当前路由
});
```

## 🔧 本地开发

```bash
# 克隆项目
git clone <repository-url>
cd mcp-ai-track

# 安装依赖
npm install

# 构建项目
npm run build

# 启动服务器
npm start
```