- Updated the README to clarify how to configure cua-mcp-server for Claude Desktop and other MCP clients.
- Fixed the example development configuration to use an absolute/expanded path rather than `~`, preventing issues with Claude’s sandboxed execution.
- Aligned instructions with the current start_mcp_server.sh behavior, ensuring the correct virtual environment and PYTHONPATH are always set.
- Improved wording for consistency across installation, development, and usage sections.
Changes
- Refactored `server.py`:
- Delayed server instantiation to avoid double-import issues and RuntimeWarning.
- Reworked `run_cua_task` and `run_multi_cua_tasks` to yield structured output
(text + screenshots) in a Pydantic-compatible format.
- Added helper functions for normalising message content, extracting text,
and serialising tool outputs.
- Improved logging and error handling for clearer debugging.
- Updated `start_mcp_server.sh`:
- Ensures Python path points to repo-local `.venv`.
- Sets `PYTHONPATH` correctly for all `libs/python/*` packages.
- Added clear debug output for python binary, repo dir, and PYTHONPATH.
Why
- Fixed `PydanticSchemaGenerationError` when returning `Image` objects from
tool functions.
- Prevented `FastMCP.__init__()` errors by aligning with supported arguments.
- Removed duplicate module loading at startup that triggered RuntimeWarnings.
- Improved clarity of server startup logs for easier integration with Claude Desktop.
Outcome
The MCP server now starts cleanly, registers all tools, and stays connected
with Claude Desktop without schema errors or double-import issues.
Adam