<p align="center">
  <img src="assets/easyar-icon.png" alt="EasyAR logo" width="96" height="96">
</p>

# mcp-easyar

[English](README.en.md) | [日本語](README.ja.md) | [Tiếng Việt](README.vi.md) | 简体中文

`mcp-easyar` 帮助 EasyAR 注册用户通过 Codex、Claude 等 AI 工具，安全地完成 EasyAR Unity Sample 的配置、构建、真机验证和项目编程辅助。

当前公开版本是 local-key MVP：用户在 EasyAR 官网注册、登录、下载官方插件并创建本地 license / CRS key；MCP 只做引导、检查和 Unity 自动化，不接触官网密码、验证码、license key、API Secret 或 appSecret。

`v0.1.0-local-key.41` 同时提供微信小程序 Sample 支持：先覆盖 `wechat-mega` 和 `wechat-crs`，提供项目结构检查、微信开发者工具 CLI 检测、本地配置表、官方本地包导入、DevTools 检查、日志分析、preflight、run sequence、真机验证清单、run result、completion report 和小程序 scope status。小程序路径仍走官方网页/官方工具 handoff，不自动登录、不绕过下载授权、不在聊天里收集密钥。

## 当前状态

- 当前 GitHub 预发布版：`v0.1.0-local-key.41`
- 官方中文文档快照：`2026-07-01`，当前官方版本见 [docs/zh-CN/OFFICIAL_DOCS_2026-07-01.md](docs/zh-CN/OFFICIAL_DOCS_2026-07-01.md)
- 当前已跑通并具备 safe release evidence 的 Sample：
  - Image Tracking
  - CRS / Cloud Recognition
  - Mega（已有 Unity 2022.3.62f3 Android 手机、PICO 4 Ultra Enterprise 和 XREAL Air 2 Ultra 真机证据；XREAL 路径已验证 Native Session Manager、企业相机授权、APK 安装启动与 Mega `Found` 定位）
- 暂缓目标：
  - Hello AR
  - Surface Tracking
  - 其他 EasyAR Sense Unity Plugin 官方 Sample
- 新增小程序目标：
  - WeChat Mini Program Mega（本地检查、本地官方包导入、DevTools 检查和 runbook）
  - WeChat Mini Program CRS / Cloud Recognition（本地检查、本地官方包导入、DevTools 检查和 runbook）
- Unity 验证基线：`2022.3.62f3`
- GitHub Release tarball、CI、安装 smoke、安全检查均已通过。

## 安装正版包

请从 GitHub Release 下载正版包：

```bash
npm install -g https://github.com/terri1982/mcp-easyar/releases/download/v0.1.0-local-key.41/mcp-easyar-0.1.0.tgz
easyar-mcp-check
```

安装检查通过后，把 MCP client 配到 `easyar-mcp` 这个 package binary 即可。

## 工具数量

`mcp-easyar` 默认使用 `core` 工具集，启用工具数约 70 个，低于常见 MCP 客户端 80 个工具的警告线。

如果维护仓库、调试官方 API 合同或需要全部工具，可以用 full profile：

```bash
MCP_EASYAR_TOOL_PROFILE=full easyar-mcp
```

日常给 Codex / Claude 使用时，建议保持默认 core profile。

## 推荐首次调用

```text
easyar_server_status
easyar_list_miniprogram_samples
easyar_check_client_setup client=codex entrypointMode=package-bin includeTokenPlaceholder=false
easyar_first_run_guide accountStage=not-registered sampleId=cloud-recognition platform=android
easyar_account_onboarding accountStage=not-registered sampleId=cloud-recognition platform=android
```

同时阅读 MCP resource：

```text
easyar://acceptance/fresh-project
easyar://acceptance/wechat-miniprogram
easyar://official/docs-2026-07-01
easyar://samples/wechat-miniprogram
easyar://roadmap/full-goal
easyar://workflow/programming
```

## 本地 key 路线

当前版本走 local-key 路线：

1. 用户在浏览器里打开 EasyAR 官网并注册/登录。
2. 用户下载官方 EasyAR Sense Unity Plugin。
3. 用户在官网开发中心创建或找到 license。
4. CRS / Cloud Recognition 用户创建或找到 AppId、识别服务地址、API KEY、API Secret；Mega 用户在已登录的 EasyAR 网页端或 Mega Studio 中找到云定位库、Mega Block storage、Block 名称和 Block ID。
5. Image Tracking / CRS 用户在本机填写 `ProjectSettings/EasyAR/easyar.local.json`；Mega 用户只在 `Assets/XR/Settings/EasyAR Settings.asset` 填写 package License 和 Global Mega Block 字段，不创建通用 JSON 配置。
6. MCP 只检查字段是否存在、是否像占位符，不输出 secret。
7. Unity 构建和真机验证使用本地配置运行，不需要在运行时登录官网。

## Mega 路径必须先区分

项目里有两个名字相近、但不能互相替代的 Mega Sample：

- `mega`：Unity Mega Sample。目标是 Android 手机、PICO、XREAL 或 visionOS，验收必须包含真实设备上的 Mega 定位/跟踪证据。
- `wechat-mega`：微信小程序 Mega Sample。目标是微信开发者工具预览和真实微信设备，Unity 工程、Android APK、PICO 或 XREAL 证据都不能替代它。

Unity Mega 推荐从 `easyar-run-mega` prompt 开始；微信小程序 Mega 使用 `easyar-run-wechat-miniprogram` 并传入 `sampleId=wechat-mega`。不要用一个路径的产物去声称另一个路径已完成。

Unity Mega 的完成门槛不是“生成了文档”或“APK 打包成功”，而是 `Onsite` 模式下真实设备启动并完成所选 Mega Block 的定位/跟踪，随后由 MCP 写入 `RUN_RESULT.md` 和 `COMPLETION_REPORT.md`，且报告中的 `runThroughComplete=true`。

运行 Unity batch 前，`EASYAR_UNITY_PATH` 必须指向真实 Unity Editor：macOS 为 `Unity.app/Contents/MacOS/Unity`，不能使用 `~/.unity/bin/Unity` 这类 Unity CLI。`easyar_write_unity_environment_report` 会检查可执行类型、软链接目标和工程版本；外置盘上的 Unity Hub 版本软链接失效时，应先挂载或恢复目标盘。

## 微信小程序 Sample

当前小程序支持先覆盖两类官方 Sample：

- `wechat-mega`：EasyAR Mega 微信小程序 Sample。
- `wechat-crs`：EasyAR CRS / Cloud Recognition 微信小程序 Sample。

推荐调用：

```text
easyar_list_miniprogram_samples
easyar_check_wechat_devtools
easyar_find_miniprogram_official_package sampleId=wechat-mega searchRoots='["/Users/you/Downloads","/Users/you/Documents"]'
easyar_write_miniprogram_official_package_search projectPath=/path/to/miniprogram sampleId=wechat-mega searchRoots='["/Users/you/Downloads","/Users/you/Documents"]'
easyar_create_miniprogram_sample_workspace projectPath=/path/to/miniprogram sampleId=wechat-mega appId=wx-your-appid
easyar_write_miniprogram_local_config_form projectPath=/path/to/miniprogram sampleId=wechat-mega
easyar_import_miniprogram_sample_from_local_package projectPath=/path/to/miniprogram sampleId=wechat-mega packagePath=/path/to/official/package-or.zip dryRun=true
easyar_inspect_miniprogram_project projectPath=/path/to/miniprogram sampleId=wechat-mega
easyar_write_miniprogram_run_through_status projectPath=/path/to/miniprogram sampleId=wechat-mega
easyar_write_miniprogram_preflight projectPath=/path/to/miniprogram sampleId=wechat-mega
easyar_run_miniprogram_devtools_check projectPath=/path/to/miniprogram sampleId=wechat-mega mode=open dryRun=true
easyar_run_miniprogram_devtools_check projectPath=/path/to/miniprogram sampleId=wechat-mega mode=preview dryRun=true
easyar_analyze_miniprogram_devtools_log projectPath=/path/to/miniprogram sampleId=wechat-mega logPath=easyar-generated/wechat-mega/DEVTOOLS_CHECK.log
easyar_write_miniprogram_run_sequence projectPath=/path/to/miniprogram sampleId=wechat-mega
easyar_write_miniprogram_device_validation_checklist projectPath=/path/to/miniprogram sampleId=wechat-mega
easyar_write_miniprogram_run_result_form projectPath=/path/to/miniprogram sampleId=wechat-mega
easyar_write_miniprogram_completion_report projectPath=/path/to/miniprogram sampleId=wechat-mega
easyar_write_miniprogram_scope_status projectPath=/path/to/miniprogram
```

CRS 小程序把 `sampleId` 改成 `wechat-crs`。用户仍需自己在 EasyAR 官网和微信开发者工具中完成注册、登录、下载、license / CRS key 创建和真机预览。

官方包查找工具会按 EasyAR 官方文件名在本机目录里找用户已下载的包，并可把结果写到 `easyar-generated/<sampleId>/OFFICIAL_PACKAGE_SEARCH.json` 和 `.md`。例如 Mega 目标包是 `easyar-mega-wechat-miniprogram-plugin-2.0.3-1077.647aaae_samples.zip`；CRS 目标包是 `EasyAR-miniprogram-WebAR-Demo-tracking.zip`。如果没找到，用户仍需在自己的 EasyAR 官网登录会话里下载，MCP 不代下、不绕过授权。

支持 prompts 的 MCP 客户端可以从 `easyar-run-mega` 开始跑 Unity Mega，或从 `easyar-run-wechat-miniprogram` 开始跑微信小程序 Mega/CRS。两个 prompt 会先声明项目类型和完成边界，禁止在聊天里收集密钥，并要求对应的真实设备证据后才允许声明完成。

## Unity CLI 工作流

`easyar_unity_cli_status` 用于检查本机 Unity CLI、beta 通道最新版本和 Pipeline 状态；`easyar_unity_cli` 提供受限的 `preflight`、`import-sample`、`prepare`、`configure`、`validate` 和 `build-android` 流程，不接受任意命令或任意 C# 方法名。当前真机回归使用 Unity CLI `1.0.0-beta.3` 与 Unity `2022.3.62f3`。

Android 手机使用 `deviceProfile=android-phone`。XREAL 使用 `deviceProfile=xreal`，并要求官方 `com.xreal.xr` `3.1.0+` 与 XREAL Enterprise 授权文件；在 `prepare` 时通过 `xrealLicensePath=/local/path/nrsdk_license.bin` 指定授权文件。MCP 只把二进制授权复制为项目内 TextAsset，不读取或返回授权内容。`configure` 会按 EasyAR 官方 XREAL 配置要求开启 `Enable Native Session Manager`；`validate` 和 `build-android` 会在缺少 SDK、授权、Native Session Manager、XR Loader 或 OpenGL ES 3 配置时停止。EasyAR 文档没有要求另行下载 `com.xreal.xr.enterprise` Unity 包。

如果项目尚未安装 XREAL 包，可在 `prepare` 中传入 `xrealSdkPackagePath=/local/path/com.xreal.xr.tar.gz`。MCP 会校验包的 `package.json` 名称和最低版本，再安全写入 `Packages/manifest.json`。

## 安全边界

不要把以下内容发到聊天、提交到 GitHub 或写进公开日志：

- EasyAR 官网密码
- 邮箱/手机验证码
- license key
- Cloud Recognition API KEY / API Secret
- appKey / appSecret
- signing key
- APK、Unity package、含密钥的本地日志

MCP 不应绕过 EasyAR 登录、license 检查、下载授权、企业权限或限流规则。

## Mega PICO 4 Ultra Enterprise

最新官方文档快照：2026-07-01，EasyAR Sense Unity Plugin / for Mega `4003.0.0`，EasyAR Mega 支持包与 Mega Studio `2.13.0`，XR 设备扩展包 `4000.0.1`。详见 [docs/zh-CN/OFFICIAL_DOCS_2026-07-01.md](docs/zh-CN/OFFICIAL_DOCS_2026-07-01.md)。

PICO 4 Ultra Enterprise sample 已验证的基线：

- Unity `2022.3.62f3`
- 包名 `com.easyar.mega.xrtest`
- EasyAR Sense Unity Plugin `4002.0.0`
- EasyAR Mega `2.12.6`
- EasyAR Unity XR 设备扩展包 `4000.0.0`
- PICO Unity Integration SDK `3.4.0`（EasyAR 文档要求 `3.1.0` 或更新版本）
- 官网 license 类型：`4.x XR正式版`

注意：PICO 和 XREAL 的 Mega 头显验收包也应使用 `LocationInputMode=Onsite`。如果眼镜中出现 EasyAR Simulator diagnostics caution，说明场景仍处于 Simulator/非现场输入模式，需要先切到 Onsite 后重新打包。验收以眼镜内 VST 实景可见、Mega 返回 `Found`、并定位到对应办公室 block 为准。`adb screencap` 可能抓不到 PICO 的透视合成层。

使用 `4003.0.0` 或更新版本新建 Mega 工程时，优先按官方 `MegaBlockController` 流程处理；旧 Mega Studio 生成节点组、多 block 配置选项和 BlockRoot 中心化流程不应作为新的默认路径。

## 中文文档目录

- [中文文档索引](docs/zh-CN/README.md)
- [快速开始](docs/zh-CN/quickstart.md)
- [从 GitHub Release 安装](docs/zh-CN/install-from-github-release.md)
- [客户端配置](docs/zh-CN/client-setup.md)
- [新 Unity 项目验收](docs/zh-CN/FRESH_PROJECT_ACCEPTANCE.md)
- [微信小程序 Sample 验收](docs/zh-CN/wechat-miniprogram-sample-acceptance.md)
- [Mega MCP 干净环境验收](docs/zh-CN/MEGA_CLEAN_ACCEPTANCE.md)
- [当前状态](docs/zh-CN/STATUS.md)
- [剩余工作](docs/zh-CN/REMAINING_WORK.md)
- [完整目标计划](docs/zh-CN/FULL_GOAL_PLAN.md)
- [路线图](docs/zh-CN/ROADMAP.md)
- [问题排查](docs/zh-CN/troubleshooting.md)
- [客户端验收清单](docs/zh-CN/CLIENT_ACCEPTANCE.md)
- [Release Manifest](docs/zh-CN/RELEASE_MANIFEST.md)
- [local-key MVP 发布说明](docs/zh-CN/release-notes/local-key-mvp.md)
- [官方 API 合同](docs/zh-CN/OFFICIAL_API_CONTRACT.md)
- [官方 API 接入交接](docs/zh-CN/OFFICIAL_API_HANDOFF.md)
- [EasyAR Mega 微信小程序 MCP 设计](docs/zh-CN/easyar-mega-wechat-miniprogram-mcp.md)
- [微信小程序 Sample 验收](docs/zh-CN/wechat-miniprogram-sample-acceptance.md)

## 英文文档

- [新项目验收](docs/FRESH_PROJECT_ACCEPTANCE.md)
- [WeChat Mini Program sample acceptance](docs/wechat-miniprogram-sample-acceptance.md)
- [当前状态](docs/STATUS.md)
- [剩余工作](docs/REMAINING_WORK.md)
- [完整目标计划](docs/FULL_GOAL_PLAN.md)
- [从 GitHub Release 安装](docs/install-from-github-release.md)
- [客户端配置](docs/client-setup.md)

## 当前结论

Image Tracking 和 CRS / Cloud Recognition 的 local-key MVP 已经跑通并发布。后续扩展 Sample 时，先调用：

```text
easyar_generate_sample_expansion_plan sampleId=hello-ar platform=android unityVersion=2022.3.62f3
```

然后按生成的验收清单补 import、build、真机 evidence 和 completion report。