bmall-mcp

MCP Server for bmall development rules and tools.

Features

• 📋 从 Git 同步 bmall Rules 到 IDE 目录
• 🔄 支持 Kiro、Cursor、Windsurf、JoyCode
• 📦 支持 iOS、Android、Harmony、Common 四种规则类型
• 🚀 规范化 Git 提交
• 📊 埋点文档生成（从京东流式平台提取）
• 🔧 埋点代码生成和业务集成

Installation

npx -y bmall-mcp

Usage

在 Kiro 中配置

添加到 ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "bmall": {
      "command": "npx",
      "args": ["-y", "--registry", "https://registry.npmjs.org/", "bmall-mcp"],
      "env": {
        "MCP_IDE": "kiro"
      }
    }
  }
}

💡 --registry https://registry.npmjs.org/ 确保从 npm 官方源获取最新版本 💡 MCP_IDE 指定当前 IDE，所有工具自动使用，无需每次指定

可用工具

| 工具 | 说明 | 示例 | |------|------|------| | pull_rules | 下载 Rules 到 IDE | 同步 bmall iOS 的 rules | | push_rules | 上传本地 Rules 到 Git | 上传修改的 iOS rules | | standard_git_commit | 规范化 Git 提交 | 提交代码，需求名称是语音转写SDK | | mta_read | 从流式平台提取埋点需求 | 提取埋点需求 https://stream.jd.com/ddrx/#/requirement/29582 | | mta_implementation | 生成埋点管理类代码 | 生成埋点代码 34747 | | mta_integration | 埋点业务集成指导 | 集成埋点 34747 | | analyze_appfreeze | 鸿蒙AppFreeze分析 | 分析AppFreeze日志 /path/to/freeze.log | | generate_requirements | 需求文档生成 | 生成需求文档 |

工具详情

从 Git 仓库下载 bmall Rules 到 IDE 目录。

参数：

• ide: 目标 IDE（可选，默认从 MCP_IDE 环境变量读取）- kiro | cursor | windsurf | joycode
• rulesType: Rules 类型（可选，自动检测）- ios | android | harmony | common

将本地修改的 Rules 上传到 Git 仓库。会自动创建以项目名命名的分支。

参数：

• ide: 目标 IDE（可选，默认从 MCP_IDE 环境变量读取）- kiro | cursor | windsurf | joycode
• message: 提交信息（可选）
• rulesType: Rules 类型（可选，自动检测）- ios | android | harmony | common

自动分析改动内容，生成符合约定式提交规范的 commit message 并推送。

参数：

• scope: 需求名称（必填），如：语音转写SDK、购物车、登录模块

从京东流式平台提取埋点需求，生成结构化埋点文档。

参数：

• requirementUrl: 埋点需求文档URL（必填）
• platform: 目标端（可选，自动检测）- iOS | Android | H5 | Web | 鸿蒙

根据埋点需求文档生成埋点管理类代码。

参数：

• requirementId: 埋点需求ID（必填）
• moduleName: 模块名称（可选）

指导在业务代码中集成埋点调用。

参数：

• requirementId: 埋点需求ID（必填）
• businessCodePath: 业务代码路径（可选）

根据AppFreeze日志文件生成详细的分析提示词，指导AI按照标准流程诊断应用冻屏问题。

参数：

• logFilePath: AppFreeze日志文件路径（必填），如：/path/to/appfreeze.log
• outputPath: 分析报告输出路径（可选，默认为当前目录）

支持的项目类型：

• HarmonyOS (鸿蒙)

分析内容：

• 提取基本信息（Pid、Reason、Fault time、Foreground）
• 分析freeze栈（对比3S和6S栈）
• 分析EventHandler信息
• 分析Binder信息
• 结合trace和HiLog
• 问题分类（应用/调度/系统库/IO）
• 提供针对性解决方案

参考文档：

• 项目根目录下的 harmonyos-appfreeze-guide.md 包含完整的分析规则和典型案例

从产品 PRD 文档（支持 Markdown/PDF/网页）、可选的设计稿（Figma/文件）和后端文档（文件/网页）生成结构化的前端需求文档。

参数：

• requirementSource: 需求文档来源（必填）
  • type: "file" | "url"
  • path: 文件路径（.md/.pdf），type=file 时必填
  • url: 网页 URL，type=url 时必填
• featureName: 功能名称（必填），用于生成输出路径
• designSource: 设计稿来源（可选）
  • type: "figma" | "file"
  • url: Figma 链接，type=figma 时必填
  • path: 设计稿文件路径，type=file 时必填
• backendSource: 后端文档来源（可选）
  • type: "file" | "url"
  • path: 后端文档路径（.md/.pdf），type=file 时必填
  • url: 后端文档网页 URL，type=url 时必填

输出文档结构：

1. 介绍：功能概述、核心价值、涉及范围、核心指标、术语表
2. 功能需求：用户故事 + 验收标准（3-6 条）
3. 交互细节：视觉反馈、动画效果、错误处理、确认弹窗
4. 技术要求与限制：性能需求、可用性需求、兼容性需求、限制说明

核心约束：

• 从用户视角描述功能，避免技术细节
• 必须覆盖 10 个前端开发重点
• 验收标准必须可测试、具体明确

项目架构

src/
├── index.ts              # 服务器入口
├── server/
│   ├── tools.ts          # Tool 定义
│   └── handlers.ts       # Tool 处理器
├── tools/
│   ├── appfreeze/
│   │   ├── index.ts      # AppFreeze 分析入口（端识别）
│   │   └── harmony.ts    # 鸿蒙 AppFreeze 分析
│   ├── git/
│   │   └── commit.ts     # Git 提交规范
│   ├── mta/
│   │   ├── read/         # 埋点文档生成
│   │   ├── implementation/  # 埋点代码生成
│   │   └── integration/  # 埋点业务集成
│   └── rules/
│       ├── utils.ts      # Rules 专用工具
│       ├── pull.ts       # 下载 Rules
│       └── push.ts       # 上传 Rules
└── utils/
    ├── index.ts          # 统一导出 + 常量
    ├── project.ts        # 项目相关（类型检测、项目名、根目录）
    ├── ide.ts            # IDE 相关（检测、路径）
    ├── file.ts           # 文件操作（复制 Markdown）
    └── git.ts            # Git 操作（初始化、分支、提交）

Changelog

v1.10.9 (2026-03-17)

• ✅ 强化 Figma 设计稿处理提示：添加"只处理当前这一个 Figma 设计稿"的强调
• ✅ 与 PDF 处理保持一致：明确指出当前要处理的文件，避免 AI 处理其他文件
• ✅ 添加"立即停止并重新调用工具"的提示

v1.10.8 (2026-03-17)

• ✅ 精简提示词：所有文档处理返回消息统一为"只处理了XX文档"
• ✅ 删除冗余内容：移除"当前任务"、"立即重新调用工具"、"重要"等重复强调
• ✅ 简化 Figma 提示：删除"不处理后端文档"等列举其他文档类型的内容
• ✅ 提升清晰度：每次只说明当前处理的文档，不列举其他文档

v1.10.7 (2026-03-17)

• 🐛 修复关键 bug：handler 层面没有传递 designSource 和 backendSource 参数
• ✅ 在 generate_requirements handler 中提取并传递 designSource 和 backendSource
• ✅ 这是导致参数丢失的真正原因（不是 AI 的问题，是代码的问题）

v1.10.6 (2026-03-17)

• ✅ 修复参数传递问题：在返回消息中直接提供完整的 JSON 参数
• ✅ 使用代码块格式：展示完整参数，确保 AI 能正确复制
• ✅ 强调参数完整性：明确提示"必须包含所有参数，不要遗漏"
• ✅ 解决 AI 第二次调用时丢失 designSource 和 backendSource 的问题

v1.10.5 (2026-03-17)

• ✅ 添加详细的参数日志：在函数开头输出完整的 params、hasDesignSource、hasBackendSource 信息
• ✅ 诊断参数传递问题：帮助定位 AI 第二次调用时参数丢失的原因

v1.10.4 (2026-03-17)

• ✅ 修复 PDF 处理流程：强调只处理当前一个文件，不处理其他文件
• ✅ 优化提示词：明确说明"立即停止并重新调用工具"
• ✅ 添加多处强调：确保 AI 理解正确的流程

v1.10.3 (2026-03-17)

• ✅ 修复 generate_requirements 流程问题：每处理完一个文档后返回并提示重新调用
• ✅ 优化 PDF 读取提示词：使用通用描述让 AI 自己查找正确的工具名称
• ✅ 添加详细调试日志：帮助定位问题（步骤 3.2、3.3、步骤 4）
• ✅ 确保按顺序处理：PRD → 设计稿 → 后端文档 → 最终分析

v1.10.2 (2026-03-16)

• ✅ 修复 PDF OCR 调用问题：明确说明需要分别调用两个工具（文本读取 + OCR）
• ✅ 优化提示词：分 5 个步骤说明（读取文本层 → OCR 识别 → 合并 → 保存 → 重新调用）
• ✅ 强调必须调用两个工具，缺一不可

v1.10.1 (2026-03-16)

• ✅ 修复 PDF OCR 问题：明确说明 include_images: true 用于 OCR 识别图片和表格
• ✅ 修复中间文件保存问题：优化提示词，分步骤说明读取→保存→重新调用
• ✅ 确保 AI 明确知道要保存中间文件（origin-requirement.md、design-doc.md、backend-doc.md）到本地

v1.10.0 (2026-03-16)

• ✅ 优化 generate_requirements 工具流程：精简提示词，提升效率
• ✅ 优化 PDF 处理：删除冗余的步骤化格式和重复强调
• ✅ 优化 Figma 处理：删除 nodeId 提取和语言/框架指定
• ✅ 优化分析提示词：保留前端开发 10 个重点，确保需求文档完整性
• ✅ 明确路径要求：工具参数描述中明确说明必须使用绝对路径
• ✅ 提供路径示例：/Users/xxx/Documents/prd.pdf

v1.9.2 (2026-03-16)

• ✅ 添加绝对路径检测：自动检测文件路径是否为绝对路径
• ✅ 明确路径要求：相对路径时提示AI使用绝对路径
• ✅ 提供路径示例：/Users/xxx/Documents/prd.pdf
• ✅ 避免路径错误：确保pdf-reader工具正确读取文件

v1.9.1 (2026-03-16)

• ✅ 修复提示词歧义：移除每个任务中的"重新调用工具"指令
• ✅ 明确统一调用：所有任务完成后统一调用一次工具
• ✅ 避免误解：AI 不会误以为每个任务都要调用
• ✅ 提升效率：减少不必要的工具调用次数

v1.9.0 (2026-03-16)

• ✅ 优化提示词：明确推荐并行处理多个任务
• ✅ 说明自动检查机制：工具会自动跳过已完成的任务
• ✅ 避免重复执行：每次调用都会检查文件存在性
• ✅ 提升处理效率：同时处理多个文档，减少总耗时

v1.8.9 (2026-03-16)

• ✅ 优化工作流输出：一次性返回所有需要处理的文档任务
• ✅ 支持并行处理：AI可以同时处理多个文档，提高效率
• ✅ 减少交互次数：从多次返回改为一次返回完整任务列表
• ✅ 完善Figma提示：像PDF一样提供具体的工具调用步骤
• ✅ 统一提示格式：所有文档都有清晰的操作指引

v1.8.8 (2026-03-16)

• ✅ 优化PDF读取流程：同时使用read_pdf_text和read_by_ocr两个工具
• ✅ 简化流程：不再输出中间文件，直接合并到origin-requirement.md
• ✅ 提升效率：一次调用完成两个工具读取，减少交互次数
• ✅ 确保完整性：文本层+OCR内容合并，不遗漏任何信息

v1.8.7 (2026-03-16)

• ✅ 优化PDF处理指令：明确指示AI调用mcp_execute_tool工具
• ✅ 完善PDF读取提示：提供完整的工具调用参数和格式
• ✅ 确保AI理解需要调用MCP工具并保存结果

v1.8.6 (2026-03-16)

• ✅ 修复 TypeScript 编译错误：删除多余的 } 语法错误
• ✅ 修复设计稿处理逻辑中的代码结构问题
• ✅ 确保代码正确编译和运行

v1.8.5 (2026-03-16)

• ✅ 优化逐个文档处理：PRD、设计稿、后端文档一次只处理一个
• ✅ 避免上下文累积：每读取成功一个文档就立即返回，重新调用工具
• ✅ 统一处理流程：所有文档都应用相同的增量处理逻辑
• ✅ 智能状态检查：自动检测已保存的文档，跳过已完成的步骤
• ✅ 明确指令提示：每次都强调"立即保存，不要把内容放在上下文中"

v1.8.4 (2026-03-16)

• ✅ 优化增量处理流程：支持逐个文档处理，避免上下文累积过长
• ✅ 完善 PDF 分步读取：text 和 OCR 分别处理，每次立即保存不放入上下文
• ✅ 统一文档处理逻辑：PRD、设计稿、后端文档都应用同样的分步处理
• ✅ 智能文件检查：自动检测已完成的步骤，避免重复处理
• ✅ 明确处理指令：每次都提示"立即保存，不要把内容放在上下文中"

v1.8.3 (2026-03-16)

• ✅ 优化 PDF 读取策略：采用分两步读取策略（text + OCR）
• ✅ 新增 PDF 语言自动检测：根据文件名自动识别中文/英文文档
• ✅ 完善 PDF 读取提示：建议先读文本层，再用 OCR 提取图片表格
• ✅ 避免内容遗漏：结合两种方式确保内容完整准确

v1.8.2 (2026-03-16)

• ✅ 修复工作目录问题：MCP 在根目录 / 运行时无法创建 .specs 目录
• ✅ 新增项目根目录自动识别：从输入文件的绝对路径智能提取项目根目录
• ✅ 优化路径处理：所有输出路径使用绝对路径，避免相对路径的依赖问题
• ✅ 完善 getProjectRoot 函数：支持从 .specs 路径自动识别项目根目录
• ✅ 更新所有文件操作函数：使用 buildOutputPath 生成绝对路径

v1.8.1 (2026-03-16)

• ✅ 新增 generate_requirements 工具详细调试日志
• ✅ 添加环境信息输出（工作目录、平台、主目录）
• ✅ 添加文件路径解析日志（绝对路径/相对路径）
• ✅ 添加文件操作日志（读取、目录创建、写入）
• ✅ 添加完整错误堆栈信息
• ✅ 优化错误诊断能力

v1.8.0 (2026-03-16)

• ✅ 完善后端文档处理逻辑：添加智能缓存机制
• ✅ 新增后端文档缓存函数：saveBackendDocument、tryReadSavedBackend
• ✅ 优化后端文档处理流程：支持文件和网页两种形式的缓存
• ✅ 统一文档管理：所有输入材料（PRD、设计稿、后端文档）都支持智能缓存
• ✅ 更新使用文档：明确后端文档缓存机制和处理流程

v1.7.0 (2026-03-16)

• ✅ 优化设计稿处理逻辑：统一保存设计稿内容到 design-doc.md
• ✅ 添加设计稿智能缓存：自动检测已保存的设计稿，避免重复读取
• ✅ 完善 Figma 设计稿处理流程：AI 先读取并保存，再重新调用工具使用缓存
• ✅ 更新使用文档：明确设计稿文档保存路径和缓存机制
• ✅ 统一文件管理：origin-requirement.md、design-doc.md、backend-doc.md、requirements.md

v1.6.0 (2026-03-16)

• ✅ 优化 generate_requirements 工具 Prompt 模板
• ✅ 新增设计稿支持（Figma 链接和本地文件）
• ✅ 新增后端文档支持（文件和网页 URL）
• ✅ 完善输出文档结构（4 个章节：介绍、功能需求、交互细节、技术要求与限制）
• ✅ 强化核心约束：用户视角、10 个前端开发重点、可测试的验收标准
• ✅ 支持多输入源：PRD + 设计稿 + 后端文档组合生成
• ✅ 更新使用文档：新增完整流程示例和最佳实践

v1.5.0 (2026-02-12)

• ✅ 新增 generate_requirements 工具：从需求文档生成结构化的 requirements.md
• ✅ 支持 Markdown、PDF、网页 URL 三种输入格式
• ✅ 智能缓存机制：自动读取已保存的原始文档
• ✅ 分步执行流程：PDF/URL 先读取，再分析生成
• ✅ 精简提示词：移除冗余指导，聚焦核心原则
• ✅ 完善文档：使用指南和工作流程文档

v1.4.3 (2026-02-11)

• ✅ 新增 standard_git_commit 触发词：提交代码、规范提交、标准提交、git提交
• ✅ standard_git_commit 的 scope 参数改为可选，未提供时提示用户输入
• ✅ 新增发布指南文档（.kiro/steering/发布指南.md）

v1.4.2 (2026-02-11)

• ✅ 修复版本号不一致问题，改为从 package.json 动态读取

v1.4.1 (2026-02-11)

• ✅ 优化埋点工具触发词，提升识别准确率
  • mta_read: 提取埋点、读取埋点、埋点需求
  • mta_implementation: 生成埋点代码、埋点代码生成、生成埋点类
  • mta_integration: 集成埋点、埋点集成、调用埋点
• ✅ 统一埋点文档路径为 .spec/requirements/mta/mta_${requirementId}.md
• ✅ 强化埋点代码生成的现有类检测逻辑
  • 优先使用标识代码检测（bm_clickMTAWithEventsID 等）
  • 不限定命名规则，支持任意命名的埋点类
• ✅ 修正埋点基类 import 路径为 <JDBMUtilsModule/NSObject+BMMTA.h>
• ✅ 修复埋点集成逻辑漏洞，增加埋点管理类存在性检查

v1.4.0 (2026-02-11)

• ✅ 优化埋点提取 Prompt 结构（必须提取/提取条件/必须过滤）
• ✅ 优化埋点代码生成 Prompt，强化检测现有类逻辑
• ✅ 优化埋点集成 Prompt，精简冗余内容
• ✅ 清理未使用的导入和代码

v1.3.1 (2026-01-26)

• ✅ 去除dist中多余的文件

v1.3.0 (2026-01-21)

• ✅ 新增 analyze_appfreeze 鸿蒙AppFreeze分析工具
• ✅ 支持端识别，根据项目类型返回不同的分析提示词
• ✅ 完整的AppFreeze分析流程（freeze栈、EventHandler、Binder、trace、HiLog）
• ✅ 提供针对性的问题分类和解决方案

v1.2.8 (2026-01-15)

• ✅ 修复本地分支已存在时创建失败的问题

v1.2.7 (2026-01-15)

• ✅ 修复 Git remote 地址不一致问题，自动更新 remote URL

v1.2.6 (2026-01-15)

• ✅ 增加 git status 日志输出，排查推送问题

v1.2.5 (2026-01-15)

• ✅ 修复 iOS 项目名检测，排除 _Pods.xcodeproj 和 Pods.xcodeproj

v1.2.4 (2026-01-15)

• ✅ 启动时输出版本号

v1.2.3 (2026-01-15)

• ✅ 修复 Cursor/JoyCode 中项目目录获取问题，使用 MCP roots API
• ✅ 修复 MTA 文档输出路径问题
• ✅ 移除 Flutter 相关冗余代码
• ✅ 提取通用方法到 utils（detectProjectName、copyMarkdownFiles）
• ✅ 新增 src/utils/file.ts 文件操作工具
• ✅ 新增 src/utils/git.ts Git 操作工具，提取通用 Git 方法
• ✅ 优化项目名称检测，根据项目类型选择检测方式（iOS/Android/Harmony/Web）
• ✅ Rules 操作增加详细日志输出

v1.2.2 (2026-01-15)

• ✅ 添加 roots/list 测试代码

v1.2.1 (2026-01-14)

• ✅ 修复 IDE Rules 路径计算问题，改为运行时动态获取
• ✅ 添加调试日志，输出当前工作目录

v1.2.0 (2026-01-14)

• ✅ 重构项目结构，新增 src/utils/ 目录

v1.1.6 (2026-01-14)

• ✅ 新增 Harmony (鸿蒙) Rules 类型支持
• ✅ 新增 MCP_IDE 环境变量，配置一次自动识别 IDE
• ✅ ide 参数改回可选，优先用参数，否则读环境变量
• ✅ 重构项目类型检测，抽离为独立方法
• ✅ 移除 Flutter 支持
• ✅ 修复 harmony 别名 "h" 冲突问题，改为 "hm"
• ✅ 重构项目结构，新增 src/utils/ 目录

v1.1.5 (2026-01-14)

• ✅ 更新 Changelog 记录

v1.1.4 (2026-01-14)

• ✅ pull_rules 和 push_rules 的 ide 参数改为必填
• ✅ 未指定 IDE 时返回明确提示信息

v1.1.3 (2026-01-14)

• ✅ 优化 README 工具列表展示（表格 + 折叠详情）
• ✅ push_rules 说明自动创建项目分支

v1.1.2 (2026-01-14)

• ✅ README 添加官方源配置说明

v1.1.1 (2026-01-14)

• ✅ 更新 RulesManager 仓库地址

v1.1.0 (2026-01-13)

• ✅ 新增 mta_implementation 埋点代码生成工具
• ✅ 新增 mta_integration 埋点业务集成工具
• ✅ 新增 JoyCode IDE 支持
• ✅ 重构项目架构，拆分 server/tools/handlers
• ✅ Rules 类型精简为 iOS/Android/Common

v1.0.6 (2026-01-13)

• ✅ 修正 page_code 为页面编号（非页面名称）

v1.0.5 (2026-01-13)

• ✅ 支持用户指定目标端（platform 参数），未指定时自动检测
• ✅ 支持一个模块多个页面，按页面分组显示埋点
• ✅ 状态筛选支持"新增"和"修改"
• ✅ 精简 Prompt 输出格式

v1.0.4 (2026-01-13)

• ✅ 优化 mta_read Prompt，精简输出格式
• ✅ 过滤通用参数（bPin、buId 等），只输出业务参数
• ✅ 添加端名称映射（苹果→iOS、安卓→Android）
• ✅ 不绑定特定浏览器 MCP，支持多种浏览器工具

v1.0.3 (2026-01-13)

• ✅ 新增 mta_read 埋点文档生成工具
• ✅ 新增 H5 项目类型识别（Taro 项目）
• ✅ 优化项目类型检测逻辑

v1.0.2 (2026-01-12)

• ✅ 新增 common 规则类型支持
• ✅ 更新 README 文档

v1.0.0

• ✅ 初始版本
• ✅ pull_rules / push_rules / standard_git_commit 三个工具
• ✅ 支持 iOS/Android/Web/Flutter 四种规则类型

License

MIT