{"_id":"@birchcraft/mcp-weapp-cli","_rev":"3-14803b9e1c257fc8d7c4d48fef132825","name":"@birchcraft/mcp-weapp-cli","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@birchcraft/mcp-weapp-cli","version":"1.0.0","keywords":["mcp","weapp","miniprogram","wechat","devtools","cli","modelcontextprotocol"],"author":"","license":"MIT","_id":"@birchcraft/mcp-weapp-cli@1.0.0","maintainers":[{"name":"birchcraft","email":"15611310017@163.com"}],"homepage":"https://github.com/your-username/weapp-devtools-mcp#readme","bugs":{"url":"https://github.com/your-username/weapp-devtools-mcp/issues"},"bin":{"mcp-weapp-cli":"dist/index.js"},"dist":{"shasum":"45bb180538226f01360e0670722ab4a3e52714c0","tarball":"https://registry.npmjs.org/@birchcraft/mcp-weapp-cli/-/mcp-weapp-cli-1.0.0.tgz","fileCount":62,"integrity":"sha512-sooL2I3K9TBuBN2EPNkq00zT365bidERE9+2x1Qf3R+vDATRjBTGOcZEuPl9vsx2sF02ZaAfytG5tWUEJV2VeQ==","signatures":[{"sig":"MEQCIER9LybZREwo8O8EosgGwdf0CODQQU14MLMoljZHW9bWAiB4BHGgiObdmNoNKdAOiaQnd1W5gqng7LNQr0zT/8+BjA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":198588},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"e8a5f431eee5cad24e7b973417e4e1c635fef339","scripts":{"dev":"tsc --watch","lint":"eslint src/**/*.ts","test":"node --test dist/tests/**/*.test.js","build":"tsc","start":"node dist/index.js","format":"prettier --write src/**/*.ts","prepublishOnly":"npm run build"},"_npmUser":{"name":"birchcraft","email":"15611310017@163.com"},"repository":{"url":"git+https://github.com/your-username/weapp-devtools-mcp.git","type":"git"},"_npmVersion":"11.6.2","description":"微信小程序开发者工具 CLI 的 MCP 服务器实现","directories":{},"_nodeVersion":"24.13.0","dependencies":{"zod":"^3.22.4","@modelcontextprotocol/sdk":"^1.6.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.0","@types/node":"^20.10.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-weapp-cli_1.0.0_1771561107428_0.7542361656355592","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@birchcraft/mcp-weapp-cli","version":"1.0.1","keywords":["mcp","weapp","miniprogram","wechat","devtools","cli","modelcontextprotocol"],"author":{"name":"birchcraft","email":"you@example.com"},"license":"MIT","_id":"@birchcraft/mcp-weapp-cli@1.0.1","maintainers":[{"name":"birchcraft","email":"birchcraft@163.com"}],"homepage":"https://github.com/birchcraft/mcp-weapp-cli#readme","bugs":{"url":"https://github.com/birchcraft/mcp-weapp-cli/issues"},"bin":{"mcp-weapp-cli":"dist/index.js"},"dist":{"shasum":"0561e2ba7a7086c356542463415a5ad887882dda","tarball":"https://registry.npmjs.org/@birchcraft/mcp-weapp-cli/-/mcp-weapp-cli-1.0.1.tgz","fileCount":62,"integrity":"sha512-9jD4N3JvJhkuaHlWrgutOeflE9S9ySG3CG0vqxpOb2tb8UxAyDW7zoVYNCkREAql8jb7SPs4tY+ZzUgCu4T1vQ==","signatures":[{"sig":"MEUCIQD78BfM6WFtbDrserbVIZsg8/L0ukT2yl7i2kfDsa6o0gIgJ5fAegF2xykvsE5/KDEmFgRyGyZX/kXKRKIdaVGhGIw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":198592},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"1f494a410033618610bb3c65a333a3ede5aaddae","scripts":{"dev":"tsc --watch","lint":"eslint src/**/*.ts","test":"node --test dist/tests/**/*.test.js","build":"tsc","start":"node dist/index.js","format":"prettier --write src/**/*.ts","prepublishOnly":"npm run build"},"_npmUser":{"name":"birchcraft","email":"birchcraft@163.com"},"repository":{"url":"git+https://github.com/birchcraft/mcp-weapp-cli.git","type":"git"},"_npmVersion":"11.6.2","description":"微信小程序开发者工具 CLI 的 MCP 服务器实现","directories":{},"_nodeVersion":"24.13.0","dependencies":{"zod":"^3.22.4","@modelcontextprotocol/sdk":"^1.6.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.0","@types/node":"^20.10.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-weapp-cli_1.0.1_1771571054159_0.06984203750779772","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@birchcraft/mcp-weapp-cli","version":"1.1.0","description":"微信小程序开发者工具 CLI 的 MCP 服务器实现","main":"dist/index.js","type":"module","bin":{"mcp-weapp-cli":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsc --watch","start":"node dist/index.js","test":"node --test dist/tests/**/*.test.js","lint":"eslint src/**/*.ts","format":"prettier --write src/**/*.ts","prepublishOnly":"npm run build"},"keywords":["mcp","weapp","miniprogram","wechat","devtools","cli","modelcontextprotocol"],"author":{"name":"birchcraft","email":"you@example.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/birchcraft/mcp-weapp-cli.git"},"bugs":{"url":"https://github.com/birchcraft/mcp-weapp-cli/issues"},"homepage":"https://github.com/birchcraft/mcp-weapp-cli#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.6.0","zod":"^3.22.4"},"devDependencies":{"@types/node":"^20.10.0","typescript":"^5.3.0"},"engines":{"node":">=18.0.0"},"gitHead":"714ab3e86f332705c1741b95478323be98bbde71","types":"./dist/index.d.ts","_id":"@birchcraft/mcp-weapp-cli@1.1.0","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-4xr6Y9F/IQssUD1FJQXNsQFs5K6FOUtJ+hGvRaaymyUbJKrjbiiNIPnnIutSlaCAe9SUNp3NcbDmNmyxGOIjmw==","shasum":"0e49a7648a2b991c6cacc6d85b0bd0fa565a3812","tarball":"https://registry.npmjs.org/@birchcraft/mcp-weapp-cli/-/mcp-weapp-cli-1.1.0.tgz","fileCount":83,"unpackedSize":311426,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDbEVpd8ACJr5eqFglemld50hHEcpTfT5Di7wJbNSPAJAiEA9gg3b9d+RTrj7fG0sIAWL8iXZtJyNKlQZmd7q/RAmbM="}]},"_npmUser":{"name":"birchcraft","email":"birchcraft@163.com"},"directories":{},"maintainers":[{"name":"birchcraft","email":"birchcraft@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-weapp-cli_1.1.0_1771933488624_0.6225012190188692"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-20T04:18:27.346Z","modified":"2026-02-24T11:44:48.889Z","1.0.0":"2026-02-20T04:18:27.576Z","1.0.1":"2026-02-20T07:04:14.367Z","1.1.0":"2026-02-24T11:44:48.782Z"},"bugs":{"url":"https://github.com/birchcraft/mcp-weapp-cli/issues"},"author":{"name":"birchcraft","email":"you@example.com"},"license":"MIT","homepage":"https://github.com/birchcraft/mcp-weapp-cli#readme","keywords":["mcp","weapp","miniprogram","wechat","devtools","cli","modelcontextprotocol"],"repository":{"type":"git","url":"git+https://github.com/birchcraft/mcp-weapp-cli.git"},"description":"微信小程序开发者工具 CLI 的 MCP 服务器实现","maintainers":[{"name":"birchcraft","email":"birchcraft@163.com"}],"readme":"# 微信小程序开发者工具 MCP 服务器\r\n\r\n<p align=\"center\">\r\n  <strong>一个完整的 Model Context Protocol (MCP) 服务器实现</strong><br>\r\n  封装微信开发者工具 CLI 的全部功能，让 AI 助手能够调用小程序开发工具\r\n</p>\r\n\r\n<p align=\"center\">\r\n  <a href=\"https://www.npmjs.com/package/@birchcraft/mcp-weapp-cli\">\r\n    <img src=\"https://img.shields.io/npm/v/@birchcraft/mcp-weapp-cli.svg\" alt=\"npm version\">\r\n  </a>\r\n  <a href=\"https://nodejs.org/\">\r\n    <img src=\"https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg\" alt=\"node version\">\r\n  </a>\r\n  <a href=\"LICENSE\">\r\n    <img src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"license\">\r\n  </a>\r\n</p>\r\n\r\n---\r\n\r\n## 功能特性\r\n\r\n- 🔧 **完整 CLI 覆盖**: 支持微信开发者工具 CLI 的全部 20+ 个命令\r\n- 🌐 **HTTP API 支持**: 支持通过 HTTP API 调用开发者工具功能\r\n- 🤖 **AI 集成**: 让 AI 助手能够通过自然语言调用小程序开发工具\r\n- 📦 **类型安全**: 使用 TypeScript 开发，提供完整的类型定义\r\n- 🔒 **错误处理**: 完善的错误处理和参数验证\r\n- 📝 **资源与提示符**: 支持 MCP Resources 和 Prompts\r\n- 🌐 **跨平台**: 支持 Windows、macOS 和 Linux\r\n\r\n---\r\n\r\n## 目录\r\n\r\n- [功能特性](#功能特性)\r\n- [支持的工具](#支持的工具)\r\n- [快速开始](#快速开始)\r\n- [安装](#安装)\r\n- [配置](#配置)\r\n- [使用示例](#使用示例)\r\n- [项目结构](#项目结构)\r\n- [架构设计](#架构设计)\r\n- [开发指南](#开发指南)\r\n- [贡献指南](#贡献指南)\r\n- [文档](#文档)\r\n- [许可证](#许可证)\r\n\r\n---\r\n\r\n## 支持的工具\r\n\r\n### 登录管理\r\n| 工具名称 | 描述 |\r\n|---------|------|\r\n| `weapp_login` | 登录微信开发者工具（支持二维码终端显示/图片/Base64） |\r\n| `weapp_check_login` | 检查当前登录状态 |\r\n\r\n### 预览与上传\r\n| 工具名称 | 描述 |\r\n|---------|------|\r\n| `weapp_preview` | 生成预览二维码，用于在真机上预览小程序 |\r\n| `weapp_auto_preview` | 自动预览，自动打开 IDE 并生成二维码 |\r\n| `weapp_upload` | 上传代码到微信公众平台，用于提交审核或发布体验版 |\r\n\r\n### 项目管理\r\n| 工具名称 | 描述 |\r\n|---------|------|\r\n| `weapp_open_tool` | 启动微信开发者工具（不打开项目），返回 HTTP 端口号 |\r\n| `weapp_open_project` | 打开指定的小程序项目，返回 HTTP 端口号 |\r\n| `weapp_open_other` | 以独立窗口模式打开项目 |\r\n| `weapp_close` | 关闭指定项目或当前项目 |\r\n| `weapp_quit` | 完全退出微信开发者工具 |\r\n| `weapp_reset_fileutils` | 重置文件监听，解决文件监听失效问题 |\r\n| `weapp_http_detect_port` | 检测 HTTP 服务端口号（从 .ide 文件读取） |\r\n\r\n### 构建\r\n| 工具名称 | 描述 |\r\n|---------|------|\r\n| `weapp_build_npm` | 构建 npm 包，将 node_modules 构建为小程序可用模块 |\r\n| `weapp_clear_cache` | 清除开发者工具缓存（数据/文件/编译/授权/网络/会话） |\r\n\r\n### 自动化测试\r\n| 工具名称 | 描述 |\r\n|---------|------|\r\n| `weapp_auto` | 开启自动化功能，启用 WebSocket 控制接口 |\r\n| `weapp_auto_replay` | 执行自动化测试回放 |\r\n\r\n### 云开发\r\n| 工具名称 | 描述 |\r\n|---------|------|\r\n| `weapp_cloud_env_list` | 获取云开发环境列表 |\r\n| `weapp_cloud_functions_list` | 获取指定环境下的云函数列表 |\r\n| `weapp_cloud_functions_info` | 获取云函数详细信息 |\r\n| `weapp_cloud_functions_deploy` | 部署云函数到云端 |\r\n| `weapp_cloud_functions_inc_deploy` | 增量部署云函数（更快） |\r\n| `weapp_cloud_functions_download` | 从云端下载云函数代码 |\r\n\r\n### 状态检测\r\n| 工具名称 | 描述 |\r\n|---------|------|\r\n| `weapp_status` | 检测开发者工具运行状态、端口信息、进程情况 |\r\n| `weapp_kill_all` | 强制关闭所有开发者工具实例 |\r\n\r\n### HTTP API 工具\r\n| 工具名称 | 描述 |\r\n|---------|------|\r\n| `weapp_http_login` | HTTP 方式登录 |\r\n| `weapp_http_check_login` | HTTP 方式检查登录状态 |\r\n| `weapp_http_preview` | HTTP 方式预览 |\r\n| `weapp_http_upload` | HTTP 方式上传代码 |\r\n| `weapp_http_auto_preview` | HTTP 方式自动预览 |\r\n| `weapp_http_build_npm` | HTTP 方式构建 npm |\r\n| `weapp_http_clear_cache` | HTTP 方式清除缓存 |\r\n| `weapp_http_open` | HTTP 方式打开工具/项目 |\r\n| `weapp_http_close` | HTTP 方式关闭项目 |\r\n| `weapp_http_quit` | HTTP 方式退出工具 |\r\n| `weapp_http_reset_fileutils` | HTTP 方式重置文件监听 |\r\n| `weapp_http_cloud_env_list` | HTTP 方式获取云环境列表 |\r\n| `weapp_http_cloud_functions_list` | HTTP 方式获取云函数列表 |\r\n\r\n---\r\n\r\n## 快速开始\r\n\r\n### 前置要求\r\n\r\n- Node.js >= 18\r\n- 微信开发者工具（已安装并开启服务端口）\r\n\r\n### 使用 npx 运行（推荐）\r\n\r\n无需安装，直接在 MCP 客户端配置中使用：\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"weapp-devtools\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"@birchcraft/mcp-weapp-cli\"],\r\n      \"env\": {\r\n        \"WEAPP_PORT\": \"9420\",\r\n        \"WEAPP_LANG\": \"zh\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 安装\r\n\r\n### 全局安装\r\n\r\n```bash\r\nnpm install -g @birchcraft/mcp-weapp-cli\r\n```\r\n\r\n### 从源码安装\r\n\r\n```bash\r\n# 克隆仓库\r\ngit clone https://github.com/birchcraft/mcp-weapp-cli.git\r\ncd mcp-weapp-cli\r\n\r\n# 安装依赖\r\nnpm install\r\n\r\n# 编译\r\nnpm run build\r\n\r\n# 创建到源码的链接（可选）\r\nnpm link\r\n```\r\n\r\n---\r\n\r\n## ⚠️ 重要约束提醒\r\n\r\n### 1. HTTP 端口 vs 自动化端口\r\n\r\n**这是最常见的混淆点，请务必注意：**\r\n\r\n| 端口类型 | 参数/环境变量 | 用途 |\r\n|---------|--------------|------|\r\n| **HTTP 端口** | `--port` / `WEAPP_PORT` | CLI 和 HTTP API 通信端口 |\r\n| **自动化端口** | `--auto-port` | 自动化测试 WebSocket 端口 |\r\n\r\n- **`weapp_open_tool`** 和 **`weapp_open_project`** 中的 `httpPort` 参数指定的是 **HTTP 服务端口**\r\n- **`weapp_auto`** 中的 `autoPort` 参数指定的是 **自动化 WebSocket 端口**\r\n- 两者完全不同，不可混淆！\r\n\r\n### 2. 实例唯一性保证\r\n\r\n`weapp_open_tool` 和 `weapp_open_project` 会自动确保只有一个开发者工具实例运行：\r\n- 启动前会检测并关闭其他实例\r\n- 如果关闭失败，会返回错误提示\r\n\r\n### 3. 端口不匹配检测\r\n\r\n如果启动时指定的 HTTP 端口与实际启动的端口不同，工具会明确提示：\r\n\r\n```\r\n⚠️ 警告: HTTP 端口不匹配\r\n\r\n指定的端口: 9420\r\n实际的端口: 49283 (与指定端口不同！)\r\n\r\n建议: 先执行 weapp_quit 关闭工具，然后重新启动。\r\n```\r\n\r\n### 4. 自动化端口延迟\r\n\r\n自动化服务启动后可能有延迟，工具会：\r\n- 等待最多 8 秒检测端口\r\n- 明确告知实际监听状态是否符合预期\r\n- 提供排查建议\r\n\r\n### 5. CLI vs HTTP 使用建议\r\n\r\n| 场景 | 推荐方式 | 原因 |\r\n|------|----------|------|\r\n| 启动/关闭工具 | CLI | 更可靠，直接控制进程 |\r\n| 开启自动化 | CLI | 需要传递 auto-port 等参数 |\r\n| 预览/上传 | CLI (默认) | 更稳定 |\r\n| 清除缓存 | HTTP | 支持更精细的缓存类型控制 |\r\n\r\n---\r\n\r\n## 配置\r\n\r\n### 环境变量\r\n\r\n| 变量名 | 说明 | 默认值 |\r\n|--------|------|--------|\r\n| `WEAPP_CLI_PATH` | CLI 工具路径 | 自动检测 |\r\n| `WEAPP_PORT` | HTTP 服务端口 | 9420 |\r\n| `WEAPP_LANG` | 语言 (en/zh) | zh |\r\n| `WEAPP_DEBUG` | 调试模式 | false |\r\n\r\n### CLI 路径自动检测\r\n\r\n如果没有设置 `WEAPP_CLI_PATH`，服务器会自动检测以下常见路径：\r\n\r\n**Windows:**\r\n- `C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat`\r\n- `C:\\Program Files\\Tencent\\微信web开发者工具\\cli.bat`\r\n- `%USERPROFILE%\\AppData\\Local\\微信开发者工具\\cli.bat`\r\n\r\n**macOS:**\r\n- `/Applications/wechatwebdevtools.app/Contents/MacOS/cli`\r\n- `/Applications/微信开发者工具.app/Contents/MacOS/cli`\r\n\r\n### MCP 客户端配置\r\n\r\n#### Claude Desktop\r\n\r\n编辑配置文件：\r\n- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`\r\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"weapp-devtools\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"@birchcraft/mcp-weapp-cli\"],\r\n      \"env\": {\r\n        \"WEAPP_PORT\": \"9420\",\r\n        \"WEAPP_LANG\": \"zh\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n#### Cursor\r\n\r\n在 Cursor 设置中找到 MCP 配置，添加上述相同的配置。\r\n\r\n---\r\n\r\n## 使用示例\r\n\r\n### 登录开发者工具\r\n\r\n```\r\n使用 weapp_login 工具登录微信开发者工具\r\n```\r\n\r\n### 预览项目\r\n\r\n```\r\n使用 weapp_preview 工具为项目 D:\\Projects\\MyMiniApp 生成预览二维码\r\n```\r\n\r\n### 上传代码\r\n\r\n```\r\n使用 weapp_upload 工具上传项目 D:\\Projects\\MyMiniApp，版本 1.0.0，描述 \"初始版本\"\r\n```\r\n\r\n### 构建 npm\r\n\r\n```\r\n使用 weapp_build_npm 工具为项目 D:\\Projects\\MyMiniApp 构建 npm\r\n```\r\n\r\n---\r\n\r\n## 项目结构\r\n\r\n```\r\nmcp-weapp-cli/\r\n├── src/                          # 源代码目录\r\n│   ├── index.ts                  # 主入口，服务器启动\r\n│   ├── server.ts                 # MCP 服务器核心实现\r\n│   ├── cli-client.ts             # CLI 客户端，封装微信 CLI 调用\r\n│   ├── http-client.ts            # HTTP 客户端，封装 HTTP API 调用 (NEW)\r\n│   ├── config.ts                 # 配置管理（环境变量、自动检测）\r\n│   ├── types.ts                  # TypeScript 类型定义\r\n│   ├── tools/                    # 工具定义（按功能分类）\r\n│   │   ├── index.ts              # 工具注册中心，聚合所有工具\r\n│   │   ├── auth.ts               # 登录认证工具\r\n│   │   ├── preview.ts            # 预览上传工具\r\n│   │   ├── project.ts            # 项目管理工具（含 open_tool, open_project）\r\n│   │   ├── build.ts              # 构建工具\r\n│   │   ├── automation.ts         # 自动化测试工具\r\n│   │   ├── cloud.ts              # 云开发工具\r\n│   │   ├── status.ts             # 状态检测工具\r\n│   │   └── http.ts               # HTTP API 工具 (NEW)\r\n│   └── utils/                    # 工具函数\r\n│       ├── helpers.ts            # 辅助函数\r\n│       ├── logger.ts             # 日志模块\r\n│       ├── result-formatter.ts   # 结果格式化\r\n│       └── tool-wrapper.ts       # 工具包装器\r\n├── dist/                         # TypeScript 编译输出\r\n├── docs/                         # 文档目录\r\n│   └── meta/                     # 元文档\r\n│       ├── AGENT_WORKFLOW.md     # Agent 工作规范\r\n│       └── PROJECT_HANDOVER.md   # 项目交接本\r\n├── tests/                        # 测试目录（待补充）\r\n├── package.json                  # 包配置\r\n├── tsconfig.json                 # TypeScript 配置\r\n├── README.md                     # 本文件\r\n└── LICENSE                       # MIT 许可证\r\n```\r\n\r\n---\r\n\r\n## 架构设计\r\n\r\n### 整体架构\r\n\r\n```\r\n┌─────────────────────────────────────────────────────────────┐\r\n│                      MCP Client                             │\r\n│              (Claude Desktop / Cursor / etc.)               │\r\n└───────────────────────┬─────────────────────────────────────┘\r\n                        │ JSON-RPC / stdio\r\n┌───────────────────────▼─────────────────────────────────────┐\r\n│                   MCP Server                                │\r\n│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────┐ │\r\n│  │   Tools     │  │  Resources   │  │      Prompts        │ │\r\n│  │  (35 tools) │  │(CLI status,  │  │ (setup guide,       │ │\r\n│  │             │  │ config)      │  │  deploy checklist)  │ │\r\n│  └──────┬──────┘  └──────────────┘  └─────────────────────┘ │\r\n│         │                                                   │\r\n│  ┌──────▼────────────────────────────────────────────────┐  │\r\n│  │              CLI Client + HTTP Client                 │  │\r\n│  │  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  │  │\r\n│  │  │ ConfigMgr   │  │   CLIExec    │  │  HTTPReq     │  │  │\r\n│  │  │(env/args)   │  │(spawn proc)  │  │(fetch api)   │  │  │\r\n│  │  └─────────────┘  └──────────────┘  └──────────────┘  │  │\r\n│  └───────────────────────┬────────────────────┬──────────┘  │\r\n└──────────────────────────┼────────────────────┼─────────────┘\r\n                           │                    │\r\n              ┌────────────┘                    └──────────┐\r\n              ▼                                            ▼\r\n┌──────────────────────────┐                ┌────────────────┐\r\n│ WeChat DevTools CLI      │                │ HTTP Service   │\r\n│ (cli.bat / cli)          │                │ (port in .ide) │\r\n└──────────┬───────────────┘                └────────┬───────┘\r\n           │                                         │\r\n           └────────────────┬────────────────────────┘\r\n                           │\r\n┌──────────────────────────▼──────────────────────────────────┐\r\n│              WeChat DevTools IDE                            │\r\n└─────────────────────────────────────────────────────────────┘\r\n```\r\n\r\n### 核心模块说明\r\n\r\n| 模块 | 职责 | 关键文件 |\r\n|------|------|----------|\r\n| **MCP Server** | 处理 MCP 协议通信，管理 Tools/Resources/Prompts | `server.ts` |\r\n| **CLI Client** | 封装微信 CLI 调用，管理进程生命周期 | `cli-client.ts` |\r\n| **HTTP Client** | 封装 HTTP API 调用，端口检测 | `http-client.ts` |\r\n| **Config Manager** | 管理配置，自动检测 CLI 路径 | `config.ts` |\r\n| **Tools** | 实现具体工具逻辑，按功能分类 | `tools/*.ts` |\r\n| **Utils** | 辅助函数，日志、验证等 | `utils/*.ts` |\r\n\r\n### 工具分类架构\r\n\r\n```\r\ntools/\r\n├── auth.ts          # 认证类工具\r\n├── preview.ts       # 预览发布类工具\r\n├── project.ts       # 项目管理类工具（open_tool, open_project）\r\n├── build.ts         # 构建类工具\r\n├── automation.ts    # 自动化测试类工具\r\n├── cloud.ts         # 云开发类工具\r\n├── status.ts        # 状态检测类工具\r\n└── http.ts          # HTTP API 工具\r\n```\r\n\r\n---\r\n\r\n## 开发指南\r\n\r\n### 环境准备\r\n\r\n```bash\r\n# 克隆仓库\r\ngit clone https://github.com/birchcraft/mcp-weapp-cli.git\r\ncd mcp-weapp-cli\r\n\r\n# 安装依赖\r\nnpm install\r\n\r\n# 编译\r\nnpm run build\r\n```\r\n\r\n### 开发命令\r\n\r\n```bash\r\n# 开发模式（自动编译）\r\nnpm run dev\r\n\r\n# 运行测试\r\nnpm test\r\n\r\n# 代码格式化\r\nnpm run format\r\n\r\n# 代码检查\r\nnpm run lint\r\n\r\n# 构建发布\r\nnpm run build\r\n```\r\n\r\n### 添加新工具\r\n\r\n1. **阅读微信 CLI 文档**，确认命令参数\r\n2. **更新 `types.ts`**，添加相关类型定义\r\n3. **更新 `cli-client.ts`**，添加 CLI 调用方法\r\n4. **创建/修改工具文件**（`src/tools/xxx.ts`）\r\n5. **注册到 `tools/index.ts`**，导出工具定义\r\n6. **编译检查**：`npm run build`\r\n7. **本地测试**：启动服务器验证\r\n8. **更新文档**：README.md 等\r\n\r\n详细步骤参考 [Agent 工作规范](./docs/meta/AGENT_WORKFLOW.md)\r\n\r\n---\r\n\r\n## 贡献指南\r\n\r\n我们欢迎所有形式的贡献，无论是新功能、bug 修复还是文档改进。\r\n\r\n### 提交 Issue\r\n\r\n如果你发现了 bug 或有功能建议，请通过 GitHub Issues 提交：\r\n\r\n1. 检查是否已有相关 issue\r\n2. 使用清晰的标题描述问题\r\n3. 提供复现步骤（如果是 bug）\r\n4. 说明期望的行为\r\n\r\n### 提交 Pull Request\r\n\r\n1. **Fork 仓库** 并创建你的分支 (`git checkout -b feature/amazing-feature`)\r\n2. **提交修改** (`git commit -m 'feat: add amazing feature'`)\r\n3. **推送到分支** (`git push origin feature/amazing-feature`)\r\n4. **创建 Pull Request**\r\n\r\n### 提交信息规范\r\n\r\n我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：\r\n\r\n```\r\n<type>(<scope>): <subject>\r\n\r\n<body>\r\n\r\n<footer>\r\n```\r\n\r\n**Type 类型:**\r\n- `feat`: 新功能\r\n- `fix`: Bug 修复\r\n- `docs`: 文档更新\r\n- `style`: 代码格式\r\n- `refactor`: 重构\r\n- `test`: 测试相关\r\n- `chore`: 构建/工具相关\r\n\r\n**Scope 范围:**\r\n- `tools`: 工具相关\r\n- `cli`: CLI 客户端\r\n- `server`: MCP 服务器\r\n- `types`: 类型定义\r\n- `utils`: 工具函数\r\n\r\n### 代码规范\r\n\r\n- 使用 TypeScript 编写代码\r\n- 遵循现有代码风格\r\n- 为新功能添加类型定义\r\n- 确保 `npm run build` 编译通过\r\n\r\n---\r\n\r\n## 文档\r\n\r\n- [MCP 协议规范](https://modelcontextprotocol.io/)\r\n- [微信开发者工具 CLI 文档](https://developers.weixin.qq.com/minigame/dev/devtools/cli.html)\r\n- [Agent 工作规范](./docs/meta/AGENT_WORKFLOW.md) - 项目内部开发规范\r\n- [项目交接本](./docs/meta/PROJECT_HANDOVER.md) - 开发日志和遗留问题\r\n\r\n---\r\n\r\n## 路线图\r\n\r\n- [x] 完整的 CLI V2 命令支持\r\n- [x] 统一的错误处理和结果格式化\r\n- [x] 区分启动工具和启动项目\r\n- [x] HTTP API 支持\r\n- [x] HTTP 端口检测\r\n- [x] 自动化端口监听检测\r\n- [ ] 添加单元测试覆盖\r\n- [ ] 支持更多自动化测试功能\r\n- [ ] 完善中文/英文文档\r\n\r\n---\r\n\r\n## 许可证\r\n\r\n[MIT](LICENSE) License\r\n\r\nCopyright (c) 2024 birchcraft\r\n\r\n---\r\n\r\n<p align=\"center\">\r\n  如果这个项目对你有帮助，请给我们一个 ⭐️ Star！\r\n</p>\r\n","readmeFilename":"README.md"}