Metadata-Version: 2.5
Name: autogenesis-windows-mcp
Version: 0.3.0
Summary: AutoGenesis Windows desktop MCP runtime
Project-URL: Repository, https://github.com/FSQ-lab/AutoGenesis
License-Expression: MIT
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.10
Requires-Dist: anyio<5,>=4.9
Requires-Dist: autogenesis-agent-contract==1.2.0
Requires-Dist: behave==1.2.6
Requires-Dist: jsonschema<5,>=4.20
Requires-Dist: langchain-core<2,>=0.2
Requires-Dist: langchain-openai<2,>=0.1
Requires-Dist: mcp<2,>=1.23.0
Requires-Dist: pillow<13,>=10
Requires-Dist: psutil<8,>=5.9
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: pympler==1.1
Requires-Dist: python-dotenv<2,>=1
Requires-Dist: pywinauto<0.7,>=0.6.9; sys_platform == 'win32'
Requires-Dist: requests<3,>=2.32
Provides-Extra: test
Requires-Dist: packaging<27,>=24; extra == 'test'
Requires-Dist: pytest<9,>=8.3; extra == 'test'
Description-Content-Type: text/markdown

# AutoGenesis Windows MCP package

Issue #8 evolves the Windows runtime as **autogenesis-windows-mcp**
(version 0.3.0), importable as **autogenesis_windows_mcp**, with the console
command **autogenesis-windows-mcp**. Python 3.10+ and Windows are required for
serving automation tools. Linux CI checks package metadata/imports only.

<!-- mcp-name: io.github.fsq-lab/autogenesis-windows -->

## Install in a business project

Build artifacts must contain both the Windows runtime wheel and the merged
Agent Contract 1.2.0 wheel. From any Windows business directory, without a
checkout of AutoGenesis:

```powershell
python -m venv .venv
.venv/Scripts/python -m pip install C:/artifacts/autogenesis_agent_contract-1.2.0-py3-none-any.whl C:/artifacts/autogenesis_windows_mcp-0.3.0-py3-none-any.whl
.venv/Scripts/autogenesis-windows-mcp --config ./apps.json --app notepad --project-root .
```

The installed command defaults to **stdio**. MCP clients must own stdin/stdout;
stdout contains JSON-RPC only. Diagnostics contain metadata on stderr; startup
does not create log files or write into the installed package. Close client
stdin or send SIGINT (Ctrl+C) to stop the server. Disconnecting does not invoke
the app_close automation tool or terminate the user's application.

With uv installed, isolated execution from local artifacts is also supported:

```powershell
uvx --with C:/artifacts/autogenesis_agent_contract-1.2.0-py3-none-any.whl --from C:/artifacts/autogenesis_windows_mcp-0.3.0-py3-none-any.whl autogenesis-windows-mcp --config ./apps.json --app notepad --project-root .
```

After these versions are published to the configured package index:

```powershell
uvx --from autogenesis-windows-mcp==0.3.0 autogenesis-windows-mcp --config ./apps.json --app notepad --project-root .
```

The runtime depends exactly on autogenesis-agent-contract==1.2.0 and requires
manifest SHA-256
e655f773ac723cf29610364e60f733121740f4701eccdc144cc5001e1bd67d36.
Missing, corrupt or incompatible contract assets fail startup.

Standard MCP Registry metadata is `pywinauto-mcp-server/server.json`. From a
source checkout, render the equivalent shell-free generic descriptor with:

```powershell
python tools/render_mcp_descriptor.py --server windows --config C:/business/apps.json --app notepad --project-root C:/business
```

## Application profiles

The schema is **PYWINAUTO_CONFIG.apps_config**, a nonempty object mapping
profile names to application configurations:

```json
{
  "PYWINAUTO_CONFIG": {
    "apps_config": {
      "notepad": {
        "app_name": "Notepad",
        "exe": "%WINDIR%/System32/notepad.exe",
        "window_title_re": ".*Notepad.*",
        "launch_args": []
      },
      "business-app": {
        "app_name": "Business application",
        "exe": "$AUTOGENESIS_APP_EXE",
        "window_title_re": ".*Business Application.*",
        "launch_args": ["--token", "$AUTOGENESIS_APP_TOKEN"]
      }
    }
  }
}
```

The packaged Notepad template is used when --config is omitted. A public
example is also in conf/pywinauto_conf.example.json. Copy it to a private business
configuration and select a profile with --app. Without --app, the first profile
in JSON insertion order is selected. Unknown profile names fail clearly.

Each profile requires nonempty string exe and window_title_re fields.
window_title_re must compile as a regular expression. Optional app_name is a
string; launch_args is an array of strings and defaults to an empty array.
Existing additional project/profile fields remain supported. All profiles are
schema-validated before startup; only the selected profile has environment
variables expanded. Unused profiles may reference unset variables.

Expansion supports $NAME, dollar-braced NAME, and Windows %NAME% recursively
through values in dictionaries and lists. Unset variables or empty required
values fail startup. Environment variables take precedence over a private .env
file in the current business directory. Keep credentials in environment
variables or that untracked file; configurations should contain references.
Profile values, launch arguments, entered text, keystrokes, tool results and
exception bodies are excluded from diagnostic logs. No MCP config readback tool
is exposed. Schema and argument errors do not echo supplied values.

Executable paths and launch arguments are quoted with Windows command-line
rules and passed to pywinauto's CreateProcess path without a shell.

## Source execution

From the pywinauto-mcp-server directory, with the contract wheel in C:/artifacts:

```powershell
uv sync --find-links C:/artifacts
uv run --no-sync python simple_server.py --transport stdio --config C:/business/apps.json --app notepad
```

simple_server.py is a thin launcher for the same synchronous stdio main and
prefers a local conf/pywinauto_conf.json when present. When absent, it uses the
packaged template. The ignored local configuration is never copied into the
wheel. Remote HTTP/SSE transport is intentionally not exposed by this runtime.

## MCP client example

A client can launch the installed command with an argument array:

```json
{
  "mcpServers": {
    "autogenesis-windows": {
      "command": "C:/business/.venv/Scripts/autogenesis-windows-mcp.exe",
      "args": ["--config", "C:/business/apps.json", "--app", "notepad", "--project-root", "C:/business"]
    }
  }
}
```

The client initializes with the canonical Core Policy instructions. The merged
Agent Contract adapter publishes these official prompts:

- execute_scenario(scenario_text, feature_file_path?)
- generate_scenario_test(scenario_text, feature_file_path)
- execute_natural_language_task(task_text)

The read-only resource autogenesis://agent-contract/identity reports contract
identity and appendix metadata. The startup-only `--project-root` fixes the
business-project write scope; generated destinations cannot escape it. The
canonical adapter currently registers an empty project appendix.

The **22 existing Windows tool names and complete input schemas** are frozen in
tests/fixtures/legacy_tool_schemas.json, including their required fields,
defaults, array items and types:

- app_launch, app_close, app_screenshot, app_wait
- element_click, right_click, enter_text, send_keystrokes, select_item, open_folder
- mouse_drag_drop, mouse_hover, mouse_scroll
- verify_element_exists, verify_element_not_exist, verify_checkbox_state,
  verify_element_value, verify_elements_order, verify_visual_task
- before_gen_code, preview_code_changes, confirm_code_changes

Generated replay continues to use Behave and the business project's
features.environment helpers. Default generation paths are relative to the
business working directory under features/steps, never inside site-packages.
Preview returns the complete payload, identity, and digest. Confirmation must
echo that identity and digest with `approved=true`; the runtime rejects stale
base files, escaping paths and symlinks, then atomically replaces the target.
Prefer explicit feature_file or step_file paths inside the project root.
Visual verification retains the Azure OpenAI and local provider paths;
AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT are read from the environment.
No provider implementation needs credential edits.

## Clean wheel verification

From the repository root, build both artifacts and verify them in a clean
Windows temporary business project:

```powershell
python -m pip install 'build>=1.2,<2'
python -m build --wheel --outdir C:/artifacts agent-contract
python -m build --wheel --outdir C:/artifacts pywinauto-mcp-server
python pywinauto-mcp-server/scripts/verify_wheel.py --wheel-dir C:/artifacts --mcp-version 1.23.0 --evidence-dir C:/evidence/windows-mcp-1.23
python pywinauto-mcp-server/scripts/verify_wheel.py --wheel-dir C:/artifacts --mcp-version 1.29.1 --evidence-dir C:/evidence/windows-mcp-1.29
```

Use a new artifacts directory with exactly one wheel per distribution. The
verifier creates a new venv and business directory, installs both local wheels,
copies only the acceptance harness and thin source launcher, and runs from that
business directory with isolated Python imports. It records wheel hashes,
runner image/version, installed module locations, install log, test report,
full protocol responses, the 22-tool snapshot, canonical prompts/identity,
EOF shutdown, SIGINT shutdown, and secret-canary results. Canary-bearing output
is rejected before protocol evidence is written. On Linux, only metadata,
package-data and import tests are selected; this is not Windows acceptance.
Pytest entry-point autoload is disabled, inherited PYTEST_PLUGINS/ADDOPTS are
cleared, and AnyIO is explicitly loaded. A synthetic installed plugin verifies
that third-party entry points cannot affect acceptance.

The SHA-pinned windows-package workflow covers Windows Server 2022 and Ubuntu
24.04, Python 3.10/3.12 and MCP SDK 1.23.0/1.29.1. Windows UI interaction still
requires an interactive desktop and a configured real application; hosted CI
proves installation and protocol behavior without launching user applications.
Independent code/security review and clean Windows acceptance remain required.

## Compatibility limits and rollback

The transport uses one private FastMCP server handle to supply cancellable
stdin and sanitized wire errors; both supported SDK versions have explicit
protocol coverage. Windows pipes use readiness polling and read only reported
available bytes, so SIGINT/EOF cancellation leaves no blocked reader worker.

Credential configuration must use `${NAME}`, `$NAME`, or `%NAME%` references;
plaintext credential fields are rejected. Coding Agents may pass
`{"$secret":"env:NAME"}` to secret-aware text tools. Recording, preview,
confirmation, and generated files retain that reference and resolve it only at
execution. Plaintext secure-control input becomes an unbound requirement, and
preview fails until the Coding Agent supplies an explicit SecretRef binding.
Generated code contains literals and references only—never plaintext credentials
or executable `[REDACTED]` placeholders.

Uninstall the runtime from the business venv to roll back:

```powershell
.venv/Scripts/python -m pip uninstall autogenesis-windows-mcp
```

Remove the client's server entry separately. Business configurations and
generated test files remain in the business project.
