wince-use

WinCE Use

简体中文

WinCE Use is a local Model Context Protocol (MCP) toolkit for operating and debugging Windows CE devices. It enables AI assistants and MCP clients to interact with a Windows CE target through a lightweight native device agent—supporting file transfers, process control, registry editing, window inspection, screen capture, and touch/keyboard input. For legacy development tools, it uses dedicated 32-bit helper bridges to automate Microsoft CoreCon and Visual Studio 2008 Smart Device debugging without loading 32-bit COM components into the main server process.

Project Structure

• src/WinceMcp.Server: .NET Framework 4.7.2 stdio MCP server (wince-mcp) built with the official C# MCP SDK.
• src/WinceMcp.CoreConBridge: net472-x86 helper process for Microsoft CoreCon 9.0 connectivity.
• src/WinceMcp.VsBridge: net472-x86 helper process for Visual Studio 2008 DTE automation and source debugging.
• device/WinceMcp.Agent: Native agent that runs on the Windows CE device.
• device/WinceMcp.TestApp: Sample Windows CE application used for testing input, window inspection, process control, and debugging.

Using a Prebuilt Release

Use the packaged wince-use-<version>.zip release if you want to run the MCP server or install the local Codex plugin directly without compiling the project.

Runtime Prerequisites

• PC runtime: Windows with .NET Framework 4.7.2 or later (included with Windows 10 version 1809 and later, and Windows 11; earlier Windows 10 versions may require a Framework update).
• Target device: A Windows CE 5.0 or later device on compatible ARM hardware connected to an isolated development network. Runtime testing has covered Windows Embedded Compact 7 (7.0 build 2824, ARMV7).
• CoreCon & VS2008 automation (optional): Locally installed Microsoft CoreCon 1.0, Visual Studio 2008, and your target Windows CE SDK are only needed if you use CoreCon deployment/process tools, automatic Agent updates, or Visual Studio 2008 build and source-debugging tools (these proprietary SDK binaries are not redistributed in the release package). Standard device operations over the native Agent TCP channel work without them.

Security notice: The device agent TCP protocol does not encrypt traffic or authenticate clients. Only run the agent on an isolated development network, and never expose its port (32190 by default) to untrusted networks or the Internet.

Quick Start (Release Package)

1. Extract wince-use-<version>.zip.
2. Copy config.example.toml to ~/.wince-mcp/config.toml, add your device IP addresses under [devices.<name>], and set default_device. Every MCP tool accepts an optional device_name parameter and falls back to default_device when omitted. See Configuration for details.
3. Deploy device/agent/WinceMcp.Agent.exe to your Windows CE device (see Installing and Updating the Device Agent below).
4. Connect your MCP client:
   • Codex desktop app: Extract the release archive to %USERPROFILE%\.agents\plugins\wince-use, register it in %USERPROFILE%\.agents\plugins\marketplace.json, and install WinCE Use from the Personal plugins list. It bundles all 52 tools from wince-mcp together with the built-in usage skill, while keeping ~/.wince-mcp/config.toml in your user profile across updates. See the Local Codex Plugin Guide.
   • Other MCP clients: Configure your stdio MCP client to run server/WinceMcp.Server.exe (or launch scripts/Start-WinceMcpPlugin.ps1 as shown in .mcp.json).

Building from Source

Build from source if you are modifying the codebase, targeting a custom Windows CE SDK, or generating a new release archive.

Build Prerequisites

• PC MCP server (src/WinceMcp.Server): Windows with the .NET 8 SDK or later and .NET Framework 4.7.2 reference assemblies (Developer Pack).
• 32-bit CoreCon & VS2008 bridges (-IncludeBridges): Microsoft CoreCon 1.0 and Visual Studio 2008 PublicAssemblies.
• Windows CE device binaries (-IncludeDevice): Visual Studio 2008 and the Toradex_CE500 Windows CE 5.0 SDK with ARMV4I support for the checked-in device projects (or another Windows CE SDK passed via -DevicePlatform).

Build & Package Commands

Run scripts/Build-Release.ps1 from PowerShell:

# Build and unit-test the .NET Framework MCP server
.\scripts\Build-Release.ps1

# Include the 32-bit CoreCon and VS2008 bridges
.\scripts\Build-Release.ps1 -IncludeBridges

# Build everything (server, bridges, and Windows CE binaries) and create a release ZIP
.\scripts\Build-Release.ps1 -IncludeBridges -IncludeDevice -Package

The packaged ZIP (artifacts/release/wince-use-<version>.zip) includes only the project's own binaries, docs, skills, and scripts while automatically excluding proprietary Microsoft, CoreCon, Visual Studio, and device SDK files. See Building and Packaging Releases for script options.

Installing and Updating the Device Agent

First-Time Setup (Manual)

For the initial setup, copy device/agent/WinceMcp.Agent.exe and wince-mcp-agent.ini to a persistent folder on the Windows CE device and start WinceMcp.Agent.exe. For CoreCon over TCP, place ConmanClient2.exe and CMAccept.exe in the folder configured in the INI file. A working CoreCon USB connection can be used without manually placing these binaries for the Agent watchdog.

Automatic Updates

Once the agent is running on a device, the MCP server automatically checks its version once a minute whenever that device is used:

1. If your PC has a newer WinceMcp.Agent.exe binary, the server queries the running agent for its executable path on the device.
2. It backs up the existing .exe, uploads the new version over CoreCon, restarts the agent, and verifies the updated version over TCP.
3. If the update fails at any point, the server automatically restores and restarts the previous executable.

Automatic updates first try each CoreCon target's existing connection settings, including USB, then temporarily try TCP using the Agent address. They require a working CoreCon connection to the same physical device.

Tip: Registry changes made via MCP tools update the live registry in memory. If you need those changes to survive a reboot, call registry_flush on the modified hive when you finish editing.

Troubleshooting Tool Errors

When a tool fails, it returns isError=true along with an error category, a human-readable message, and an error_id.

• Pass that error_id to server_log to inspect the PC-side diagnostic record (which also logs background agent update failures).
• Call agent_log to inspect recent logs from the Windows CE device agent.

Server diagnostic logs are saved as rolling JSONL files in ~/.wince-mcp/logs and automatically cleaned up after 7 days. To keep logs safe to share, tool arguments, file payloads, and full stack traces are omitted from the JSONL files (full C# exception stack traces are written to standard error).

Hardware Integration Testing

With the WinceMcp.TestApp solution open in Visual Studio 2008, the agent running on your target device, and ~/.wince-mcp/config.toml configured, you can run the full hardware test suite:

.\scripts\Invoke-McpFullToolTest.ps1

This script connects to the server over stdio and tests all 52 MCP tools against the live device. You can also run targeted test suites:

• .\scripts\Invoke-McpRegistryTest.ps1 — registry operations only
• .\scripts\Invoke-McpWindowInspectionTest.ps1 — window listing and UI hierarchy inspection
• .\scripts\Invoke-McpErrorDiagnosticsTest.ps1 — error handling across all tools without modifying device state

Documentation

• Architecture and Control Flow · 中文
• Configuration Guide · 中文
• Device Protocol Specification · 中文
• Device Agent & CoreCon Watchdog · 中文
• Building and Packaging Releases · 中文
• Local Codex Plugin Guide · 中文
• Agent Tool-Usage Skill

License

WinCE Use is released under the MIT License. Third-party tools and SDKs remain under their respective licenses and are not distributed with this project.