SoftAuto

SoftAuto란 무엇인가

SoftAuto는 AI Agent를 위한 오픈소스 Windows RPA 및 MCP Server입니다. Microsoft UI Automation(UIA)으로 데스크톱 소프트웨어 요소를 찾고, Chrome DOM으로 웹 요소를 찾은 다음, 클릭, 입력, 읽기, 하이라이트, 검증 등의 작업을 Model Context Protocol(MCP) 도구로 노출합니다. ERP 자동화, 데스크톱 소프트웨어 자동화, 웹 업무 시스템 자동화, GUI 테스트 및 반복적인 사무 업무에 적합합니다.

스크린샷과 좌표에 의존하는 기존 매크로 도구가 아니라, Computer Use의 결정적 실행 계층입니다. 요소는 한 번만拾取하고 검증하면 되며, 이후 Agent는 이름으로 호출할 수 있어 반복적인 스크린샷, 시각적 추론, 좌표 클릭을 줄일 수 있습니다.

Related MCP server: Browser[X]MCP

해결하는 핵심 문제점

Computer Use는 거의 모든 소프트웨어를 조작할 수 있지만, 매 단계마다 "스크린샷 → 시각적 추론 → 좌표 클릭 → 다시 스크린샷"을 반복하면 속도가 느리고, 창 이동, 해상도, UI 변경에 취약합니다.

SoftAuto는 이 실행 체인을 분리합니다. 처음에는 사람이 RPA처럼 요소를拾取하고 검증하여 저장합니다. 이후 Agent는 MCP를 통해 요소 이름으로 직접 Windows UIA 또는 브라우저 DOM 작업을 호출합니다. 에이전트는 계속해서 이해와 의사 결정을 담당하고, 반복적인 소프트웨어 조작은 결정적인 요소 자동화 경로를 따릅니다.

flowchart LR
    A[首次拾取并验证元素] --> B[(项目元素库)]
    B --> C[SoftAuto MCP]
    D[Agent 理解任务并决策] --> C
    C --> E[Windows UIA]
    C --> F[Browser DOM]
    E --> G[桌面软件]
    F --> H[网页系统]

주요 기능

• Ctrl + 왼쪽 클릭으로 데스크톱 또는 웹 요소를拾取하고 하이라이트하며, 프로젝트와 폴더별로 요소 라이브러리를 관리합니다.

• 시스템이 안정적인 속성을 추천하며, 속성 값, 와일드카드, ${variable} 동적 변수를 직접 편집할 수 있습니다.

• 창을 다시 열거나 이동한 후에도 창 앵커, 컨트롤 경로, 대상 특징을 기준으로 다시 위치를 찾을 수 있습니다.

• MCP는 찾기, 하이라이트, 클릭, 입력, 포커스, 읽기 등 19개의 쿼리 및 작업 도구를 제공합니다.

• Windows UIA와 브라우저 DOM 이중 채널; 웹 확장 프로그램은 소프트웨어에서 한 번의 클릭으로 설치 절차를 열 수 있습니다.

• 프로젝트 요소 라이브러리는 가져오기, 내보내기 및 다른 Windows 컴퓨터로 마이그레이션할 수 있습니다.

• 간체 중국어 / English 즉시 전환; 인터페이스는 해상도와 Windows DPI에 맞게 조정됩니다.

• 임의 명령 실행을 제공하지 않으며, MCP가 요소 라이브러리를 우회하여 임의로 좌표 클릭하는 것도 허용하지 않습니다.

5분 빠른 시작

설치 버전(권장)

1. Releases에서 Lingheyi-SoftAuto-Setup-*.exe를 다운로드합니다.

2. SoftAuto를 설치하고 실행한 후, 새 프로젝트와 폴더를 만듭니다.

3. "데스크톱 요소拾取" 또는 "웹 요소拾取"을 클릭하고 대상 컨트롤로 이동한 후 Ctrl + 왼쪽 클릭으로 저장합니다.

4. 오른쪽에서 위치 속성을 조정하고 "검증"을 클릭합니다.

5. "MCP 구성"을 클릭하고 복사된 구성을 MCP를 지원하는 Agent에 붙여넣습니다.

소스 코드에서 실행

uv sync --extra dev
uv run softauto-inspector

작업 흐름:

1. 상단에서 현재 프로젝트를 선택합니다. "새 프로젝트"를 클릭하면 완전히 독립된 빈 요소 라이브러리가 생성됩니다.

2. 웹 모드를 처음 사용할 때 "웹 확장 프로그램 설치"를 클릭합니다. 소프트웨어가 Chrome 확장 프로그램 페이지를 열고, 확장 프로그램 디렉터리를 열며 경로를 복사합니다. 안내에 따라 개발자 모드를 켜고 "압축 해제된 확장 프로그램 로드"를 선택합니다.

3. "새 폴더"를 클릭하여 애플리케이션, 페이지, 모듈 등의 계층을 만듭니다. 폴더 안에 하위 폴더를 계속 만들 수 있습니다.

4. 대상 폴더를 선택하고 "데스크톱 요소拾取" 또는 "웹 요소拾取"을 클릭합니다.

5. 마우스를 이동하면 대상 요소에 주황색 실시간 테두리가 표시됩니다.

6. Ctrl + 마우스 왼쪽 버튼을 누르면 클릭이 차단되어 대상 소프트웨어로 전달되지 않습니다.

7. 사용자 지정 이름을 입력하고 현재 폴더에 저장합니다.

8. 요소 라이브러리에서 요소를 선택한 후, 오른쪽 "요소 상세"에서 위치 확인에 참여할 속성을 체크합니다.

9. 시스템은 ★가 표시된 안정적인 속성을 미리 선택합니다. 동적 텍스트는 기본적으로 NamePrefix를 선택하며, 업무 값이 포함된 전체 Name은 선택하지 않습니다. 사용자가 속성을 직접 추가/삭제하고 "속성 저장" 또는 "검증"을 클릭할 수 있습니다.

10. 요소 라이브러리에서 요소를 선택하고 "검증"을 클릭하면 시스템이 요소를 다시 찾아 하이라이트합니다.

11. 폴더와 요소는 모두 더블 클릭으로 이름을 바꿀 수 있으며, 다른 폴더로 직접 끌어다 놓을 수도 있습니다. 비어 있지 않은 폴더는 실수로 삭제되지 않습니다.

12. "프로젝트 내보내기"를 클릭하면 휴대용 JSON이 생성됩니다. 다른 컴퓨터에 SoftAuto를 설치한 후 "프로젝트 가져오기"를 클릭하면 모든 폴더, 요소, 로케이터를 마이그레이션할 수 있습니다.

13. "MCP 구성 복사"를 클릭하면 설치된 SoftAutoMCP.exe의 전체 Agent 구성을 얻을 수 있습니다.

프로젝트 레지스트리는 data/projects.json에 저장되며, 각 프로젝트의 요소 라이브러리는 data/projects/<프로젝트ID>/elements.json에 독립적으로 저장됩니다. 이전 버전의 data/elements.json은 처음 생성된 "기본 프로젝트"로 복사되며 원본 파일은 계속 유지됩니다. MCP는 기본적으로拾取기의 현재 프로젝트를 따릅니다. SOFTAUTO_ELEMENT_LIBRARY로 "MCP에 내보내기"로 생성된 JSON을 가리킬 수도 있습니다. MCP는 안정적인 ID, 고유 이름 또는 전체 경로(예: Training System/登录/账号)로 요소를 가져올 수 있습니다.

속성 값은 직접 편집할 수 있으며 다음을 지원합니다:

• 와일드카드: Please take note of your order reference: *

• 단일 문자 와일드카드: Order ?

• MCP 변수: Order reference: ${reference}

${reference}가 포함된 Locator는 get_element, validate_saved_element, highlight_element 또는 작업 도구를 호출할 때 variables로 값을 전달합니다:

{
  "variables": {
    "reference": "842"
  }
}

심층 검사

일반拾取으로 복잡한 컨트롤을 구분할 수 없을 때 "심층 검사"를 클릭하면 성숙한 FlaUInspect가 시작됩니다.

uv run softauto-flauinspect

프로젝트에는 SHA-256 검증을 거친 FlaUInspect 3.1.0 공식 Release가 포함되어 있습니다.

다운로드 패키지 체크섬: a3e571e783af1cf84661332e5229714b7ac81f908ea44b454e5c1aa0398e20d5.

Windows 설치 패키지 빌드

PyInstaller와 Inno Setup 6을 설치한 후 실행합니다:

uv sync --extra packaging
.\packaging\build_installer.ps1

빌드 결과는 Lingheyi-SoftAuto-Setup-0.5.3.exe입니다. 설치 버전에는 다음이 포함됩니다:

• SoftAuto.exe: 요소拾取기 및 프로젝트 요소 라이브러리 인터페이스.

• mcp/SoftAutoMCP.exe: Agent가 직접 연결할 수 있는 stdio MCP 서비스.

• FlaUInspect: GUI와 함께 설치되는 심층 요소 검사 도구.

• 링허이 지능 Web Connector: GUI와 함께 설치되는 Manifest V3 Chrome 확장 프로그램 디렉터리.

설치 버전의 사용자 데이터는 기본적으로 %LOCALAPPDATA%\SoftAuto\data에 저장되며, 제거하거나 덮어써서 업그레이드해도 프로젝트 요소는 삭제되지 않습니다. 설치 디렉터리 내의 安装与MCP配置.txt에 MCP 구성 예시가 제공됩니다.

전체 MCP 스택 동시 연결

mcp-stack.json에는 다음이 구성되어 있습니다:

• 이 프로젝트의 Windows UIA MCP

• Microsoft Playwright MCP 0.0.79

• Ui.Vision MCP Bridge 1.1.1

이 파일의 mcpServers를 Agent의 MCP 구성에 병합하면 됩니다. Playwright는 브라우저 Accessibility Snapshot과 작업 도구를 Agent에 직접 제공합니다. Ui.Vision은 먼저 브라우저 확장 프로그램을 설치하고 로컬 페어링을 완료해야 합니다.

OpenAdapt는 사용자 고유의 workflow bundle이 필요하므로 mcp-openadapt.example.json을 별도로 제공하며, bundle 디렉터리를 입력한 후 병합합니다.

Windows UIA MCP 단독 실행

읽기 전용 모드:

uv run mcp run src/softauto/server.py:mcp

UI 변경을 명시적으로 허용:

$env:SOFTAUTO_ALLOW_ACTIONS = "1"
uv run mcp run src/softauto/server.py:mcp

MCP 클라이언트 구성:

{
  "mcpServers": {
    "software-automation": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/absolute/path/to/software-automation-mcp",
        "mcp",
        "run",
        "src/softauto/server.py:mcp"
      ]
    }
  }
}

MCP 도구

읽기 전용 도구:

• automation_status

• integration_catalog

• list_saved_elements

• list_element_tree

• list_element_projects

• get_active_element_project

• get_saved_element

• validate_saved_element

• list_windows

• inspect_point

• get_element

• get_children

• find_elements

• highlight_element

작업 도구:

• focus_element

• click_element

• invoke_element

• set_element_value

• send_element_keys

작업 도구는 서버가 SOFTAUTO_ALLOW_ACTIONS=1로 시작되어야 합니다. Click, Invoke, SetValue, SendKeys는 또한 매 호출마다 confirm=true를 명시적으로 전달해야 합니다.

Locator 예시

{
  "backend": "windows-uia",
  "version": 1,
  "window": {
    "name": "业务系统",
    "class_name": "MainWindow",
    "control_type": "WindowControl"
  },
  "path": [
    {
      "automation_id": "orderPanel",
      "control_type": "PaneControl",
      "sibling_index": 0
    },
    {
      "automation_id": "saveButton",
      "name": "保存",
      "control_type": "ButtonControl",
      "sibling_index": 0
    }
  ],
  "target": {
    "automation_id": "saveButton",
    "name": "保存",
    "control_type": "ButtonControl"
  }
}

위치 확인은 AutomationId를 우선 사용하고, 이름, ClassName, ControlType, FrameworkId, 구조 경로를 결합합니다. 프로세스 ID와 창 핸들은 소프트웨어가 재시작되면 변경되므로 약한 힌트로만 사용합니다.

백엔드 라우팅 원칙

Agent는 다음 순서로 선택해야 합니다:

1. 브라우저 페이지: Playwright MCP.

2. Windows 네이티브 소프트웨어: Windows UIA MCP, FlaUInspect는 수동 탐색용.

3. 요소 트리가 보이지 않음: Ui.Vision OCR/이미지 위치 확인.

4. 안정적인 반복 업무 프로세스: OpenAdapt workflow로 컴파일한 후 OpenAdapt Agent MCP로 호출.

알려진 한계

표준 Win32, WPF, WinForms, UWP/Electron의 접근성 품질은 일반적으로 양호합니다. 다음 인터페이스는 의미 있는 요소 트리를 반환하지 못할 수 있습니다:

• 자체 그리기 Canvas, DirectX/OpenGL 인터페이스

• 게임 및 일부 산업용 소프트웨어

• Citrix, RDP 또는 비디오 스트림의 원격 애플리케이션

• Accessibility를 구현하지 않은 구형 컨트롤

• Inspector/MCP 프로세스보다 권한이 높은 소프트웨어

이러한 시나리오는 이미 연결된 Ui.Vision/OpenAdapt 백엔드에 맡기며, 이 프로젝트에서 비전 엔진을 중복 구현하지 않습니다.