poco-mcp

Small local stdio MCP server for live Unity Poco automation.

The server exposes seven tools:

• observe: compact visible UI snapshot with stable refs and locators; use query to narrow candidates and include_world=true for buildings and map HUDs
• tap: click one explicit ref, locator, text, or normalized position; optionally wait for text or page scope evidence
• swipe: scroll a view by direction and normalized anchor; observe again after each swipe to find an off-screen target
• wait: wait for a text or node name to appear or disappear
• exists: cheap remote Poco existence check
• input_text: type into a focused input
• run_steps: execute a previously verified sequence of stable selectors in one MCP call; page and text checks use Poco selectors rather than hierarchy dumps

observe and tap return timings_ms for MCP-side latency. Model tokens and API cost must be recorded by the model host, not this local MCP.

Install

pip install poco-mcp
poco-mcp

Claude Code Skills

The package includes the verified live-flow and script-export skills, but Claude Code discovers skills from the current project rather than from Python's site-packages. Install them once in the user's project:

cd <project-directory>
poco-mcp-init

This creates .claude/skills/live-script-builder and .claude/skills/poco-script-export. Existing skills are left untouched. Use poco-mcp-init --force to update only the files managed by this package.

For a source checkout, install the development extras before running tests:

pip install -e ".[dev]"
pytest -q

Shareable Allure Report

Install the optional reporting dependencies on the machine that executes generated regression scripts:

pip install -e ".[report]"

Install Allure 2 Commandline with --single-file support, or point the runner at an existing allure.cmd. Generate one self-contained Allure HTML file that can be sent directly to another person. The report keeps Allure cases, semantic steps, failure attachments, and captured START/PASS/FAIL execution logs.

$allureCli = "D:\qa_tools\qa_tools\ai_test_skill\allure\node_modules\.bin\allure.cmd"
poco-mcp-test "outputs\scripts\游戏\个人主页\头像框装扮\test_启用头像框.py" --allure-single-report --allure-command $allureCli --clean

For a single script, the default output is <script-directory>/reports/<timestamp>/allure-html-single/index.html; that index.html is the only file that needs to be shared. Runs containing multiple input paths use outputs/reports/<timestamp>/ instead. Pass a directory after --allure-single-report when a fixed output location is preferred.

Pytest continues with later independent tests after a failed test; each individual business flow stops at its first failed step.

常用执行命令

推荐直接使用一键入口。批量执行装扮目录并生成一份汇总 Allure 报告：

.\run-report.cmd "outputs\scripts\游戏\个人主页\装扮"

批量执行装扮目录、但排除工厂装扮脚本：

.\run-report.cmd "outputs\scripts\游戏\个人主页\装扮" --ignore "outputs\scripts\游戏\个人主页\装扮\test_工厂装扮启用.py"

执行单个脚本：

.\run-report.cmd "outputs\scripts\游戏\个人主页\Boss装备\test_帽子装备强化.py"

首次使用时安装项目和报告依赖：

pip install -e ".[report]"

执行 Boss 装备的帽子强化脚本，并生成可直接发送的 Allure 单文件报告：

python -m poco_mcp.test_runner "outputs\scripts\游戏\个人主页\Boss装备\test_帽子装备强化.py" --allure-single-report --allure-command "D:\qa_tools\qa_tools\ai_test_skill\allure\node_modules\.bin\allure.cmd"

执行其他脚本时，只需替换命令中的 .py 路径：

python -m poco_mcp.test_runner "<脚本路径.py>" --allure-single-report --allure-command "D:\qa_tools\qa_tools\ai_test_skill\allure\node_modules\.bin\allure.cmd"

单脚本报告默认生成在：

<脚本所在目录>\reports\<时间戳>\allure-html-single\index.html

批量报告默认生成在被执行目录的 reports\<时间戳>\allure-html-single\index.html。每个脚本是一个独立用例； 某个用例失败后，pytest 会继续执行后续用例，并在同一份报告中汇总结果。

速度说明

• 导出的 pytest 脚本直接使用已验证选择器，不再执行探索和整树观察。
• wait(timeout=10) 是最长等待时间，节点提前出现就立即继续，并非固定等待10秒。
• 同一批次复用一个 Unity Poco 连接，避免每个脚本重复查找窗口和握手。
• Allure 单文件只在整批结束后生成一次；本机验证通常约需10到15秒，批量运行时由全部用例共同分摊。
• 总执行时间主要取决于游戏页面切换、脚本中明确要求的等待和用例数量。

Allure Reports

Use the regular multi-file Allure report only when local allure open browsing or history assets are needed.

# One semantic test script
poco-mcp-test outputs\scripts\游戏\个人主页\Boss装备\test_帽子宝石升级.py --allure-report outputs\allure-report --clean

# A suite directory
poco-mcp-test outputs\scripts\商业化\商店 --allure-report outputs\allure-report --clean

Raw results are written to outputs/allure-results/. The generated HTML is in outputs/allure-report/. Future exported scripts use semantic Allure steps and attach a screenshot only when a step fails.

License

This project is licensed under CC BY-NC 4.0. Commercial use is not permitted.

Run it with the configured Python environment:

$env:PYTHONPATH = "$PWD\src"
python -m poco_mcp.server

Set POCO_MCP_HOST and POCO_MCP_PORT when the target is not the default 127.0.0.1:5001. Install pocoui and airtest in the same environment.