alipay-mini-mcp

支付宝小程序 MCP Server — 让 Claude Code 直接编译、分析你的支付宝小程序项目，并捕获运行时日志。

工作原理

Claude Code ──STDIO──> MCP Server
                         │  ▪ build / analyze / log tools
                         │  ▪ HTTP log collector :5701
                         │      ▲
                         │      │ POST /api/v1/logs
                         │      │
支付宝 IDE 模拟器         │
  └── 小程序              │
       └── Logger ──> log-bridge.ts (monkey-patch)

• MCP Server：随 Claude Code 启动，提供构建、代码分析、日志收集三个域的工具
• log-bridge.ts：注入小程序的一小段 TypeScript，猴子补丁 Logger 单例，将运行时日志批量 POST 到 MCP Server
• 日志持久化：按天写入 JSONL 文件，默认保留 7 天

前置条件

| 依赖 | 最低版本 | 说明 | |------|----------|------| | Node.js | 16.12+ | top-level await 需要 | | Claude Code | 最新版 | 当前仅支持 Claude Code (STDIO transport) | | 支付宝开发者工具 | 最新稳定版 | 用于模拟器运行小程序 |

快速开始

1. 安装 MCP Server

npm install -g alipay-mini-mcp

如果尚未发布到 npm，可先用 npm link 本地调试，见下方本地开发。

2. 在项目中接入

cd your-alipay-miniprogram
npx alipay-mini-mcp init

init 会做以下事情：

• 写入 .mcp.json（Claude Code 自动发现 MCP Server）
• 复制 log-bridge.ts 到 src/utils/
• 修改 config/dev.js（将 ENABLE_REMOTE_LOG 改为 true，追加 LOG_BRIDGE_URL）
• 修改 global.d.ts、app.ts、.gitignore

所有改动都标记了 @alipay-mini-mcp，见 .gitignore 不会被提交到仓库。

3. 重启 Claude Code

.mcp.json 只在启动时加载，重启后生效。

4. 在支付宝开发者工具中开启域名白名单忽略

这是一个必须的步骤！ 支付宝小程序要求 my.request() 的域名在后台配置的白名单中，本地调试不会被允许访问 127.0.0.1:5701。

在支付宝开发者工具中：

1. 右上角 详情 → 域名信息
2. 勾选 「不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书」
3. 刷新模拟器

5. 开始调试

启动小程序 dev 构建、打开 IDE 模拟器后，在 Claude Code 对话中：

请启动日志收集

Claude Code 会自动调用 start_log_capture，然后你在模拟器中操作小程序，后续：

帮我查看最近的日志

Claude Code 会调用 get_captured_logs 返回运行时日志。

MCP Tools

构建类

| Tool | 说明 | |------|------| | build_miniprogram | 编译项目（env: "dev" 或 "prod"） | | get_last_build_result | 返回上次编译结果（含错误列表和耗时） | | get_build_status | 查询当前是否有编译正在进行 | | cancel_build | 终止正在进行的编译 |

分析类

| Tool | 说明 | |------|------| | read_project_structure | 返回 src/ 目录树 | | read_source_file | 读取 src/ 下的源文件（路径受校验，无法读取 src/ 外文件） | | list_pages | 解析 app.config.ts，列出所有页面和分包 | | list_api_endpoints | 扫描 src/apis/ 和 src/utils/ 汇总所有 API 调用及 BASE_URL | | find_issues | 检查 console.log 残留等代码问题 | | check_project_config | 项目配置快照（Taro 版本、页面数、API 数） | | search_code | 在 src/ 中正则搜索代码 |

日志捕获类

| Tool | 说明 | |------|------| | start_log_capture | 启动 HTTP 日志收集服务器（默认端口 5701） | | stop_log_capture | 停止收集器，返回统计摘要 | | get_captured_logs | 按 level/since/limit 条件检索日志 | | get_log_bridge_status | 查看收集器运行状态 | | clear_captured_logs | 清空内存缓冲区 |

CLI 命令

| 命令 | 说明 | |------|------| | npx alipay-mini-mcp init | 在当前项目一键接入 | | npx alipay-mini-mcp uninit | 从当前项目完全移除（按快照精确回滚） | | npx alipay-mini-mcp --version | 版本号 | | npx alipay-mini-mcp --help | 帮助 |

日志存储

运行时日志存储在当前工程的 .alipay-mini-mcp/logs/ 下，按天分文件：

your-project/
└── .alipay-mini-mcp/
    └── logs/
        ├── 2026-05-13.jsonl
        └── 2026-05-12.jsonl

每次 start_log_capture 时自动清理 7 天前的文件。路径可通过环境变量 LOGS_DIR 自定义。

故障排除

Claude Code 中看不到 alipay-mini-mcp

运行 /mcp 检查是否加载成功。如果未出现，确认：

1. 项目根目录存在 .mcp.json
2. 已重启 Claude Code
3. npx alipay-mini-mcp init 执行成功

日志收集没有数据

1. 确认 IDE 中已勾选 「不校验合法域名」
2. 检查 IDE 控制台中是否有 [LogBridge] 开头的日志
3. 如果有 Send failed 且错误信息包含 "未配置域名白名单"，说明步骤 4 没做
4. 确认 npm run dev 构建中包含 ENABLE_REMOTE_LOG: true

端口 5701 被占用

start_log_capture 会检测端口占用并返回明确错误。也可以指定其他端口：

请启动日志收集，端口 5702

但注意，log-bridge.ts 中默认也指向 5701。如果用其他端口，需要同步修改 LOG_BRIDGE_URL。

不想提交这些改动

init 生成的所有文件和改动已加入 .gitignore，不会被 commit。如果需要完全移除，运行 npx alipay-mini-mcp uninit。

适配范围

| 项目类型 | 构建类工具 | 分析类工具 | 运行时日志 | |----------|-----------|-----------|-----------| | Taro 3.x + Vue/React + TypeScript | ✅ | ✅ | ✅ | | Taro 3.x + JavaScript | ✅ | ✅ | ⚠️ 需手动改造 log-bridge.ts | | 原生支付宝小程序 | ⚠️ | ✅ | ❌ 暂不支持 | | uni-app 等其他跨端框架 | ⚠️ | ✅ | ❌ 暂不支持 |

日志捕获核心依赖：log-bridge.ts 需要 @tarojs/taro、Taro 的 @/ 路径别名、以及一个单例 Logger。如果你用的是其他技术栈，分析类和构建类工具仍然可用。

反馈与参与

有问题或建议？欢迎 提交 Issue。

想改造成适配自己的项目（比如原生支付宝小程序、JS 项目、其他框架），可以直接用 Claude Code 来改——本工程的代码结构清晰，改个 log-bridge.ts 模板、调几个 patcher 就能适配你的技术栈。

本地开发

git clone https://github.com/yssmiac7/alipay-mini-mcp
cd alipay-mini-mcp
npm install
npm run build      # 编译 TypeScript → dist/

# 本地联调
npm link
cd your-test-project
npm link alipay-mini-mcp
npx alipay-mini-mcp init

关于本项目

本项目由 Claude Code + DeepSeek V4 Pro 通过 Vibe Coding 方式生成，未经人工编码。有问题或想交流？欢迎 提交 Issue 讨论。

License

MIT