Skip to main content
Glama
Sign In
deenesjakoruzh
orca

orca

by sachin-sankar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Orca — ATK 접근성 MCP 서버

실행 중인 GTK 애플리케이션에서 ATK(Accessibility Toolkit) 위젯 트리를 캡처하여 ARIA 역할/유형으로 정규화하고, 구성 가능한 선언적 보안 정책을 적용한 다음, 결과를 모든 표준 MCP 클라이언트(Claude, Cursor, Windsurf 등)에 MCP 도구로 노출합니다.

빠른 시작

cd orca
just shell        # enter nix-shell with all dependencies
just server       # start the MCP server on stdio

또는 수동으로:

nix-shell
PYTHONPATH=src python3 -m src

Related MCP server: claude-workman

아키텍처

orca/
├── shell.nix                 # nix-shell environment
├── pyproject.toml            # package config
├── Justfile                  # task runner
├── docs/
│   ├── README.md             # this file
│   ├── usage.md              # client integration guide
│   ├── policy.md             # policy engine reference
│   ├── atk.md                # ATK capture internals
│   └── contribute.md         # development guide
└── src/
    ├── __init__.py
    ├── __main__.py           # entry point
    ├── atk.py                # ATK tree capture
    ├── normalize.py          # ATK→ARIA normalization
    ├── policy.py             # declarative security policy
    ├── server.py             # MCP server
    └── default_policy.yaml   # ship-default policy

MCP 도구

도구

매개변수

설명

get_tree

없음

정책이 적용된 전체 ARIA 정규화 트리

get_tree_for_app

app_name: str

앱 범위로 한정된 트리(fnmatch glob)

get_node_info

node_id: str

obj_id로 단일 노드 조회

list_apps

없음

최상위 앱 객체(name, pid, role)

구성

정책

정책 파일은 다음 우선순위로 로드됩니다.

  1. ~/.config/atk-mcp/policy.yaml (사용자 재정의)

  2. src/default_policy.yaml (번들 기본값)

두 파일이 모두 없거나 파싱에 실패하면 서버는 default_action: allow 및 사용자 규칙 없이 시작됩니다.

정책은 시작 시 한 번만 로드됩니다. 변경 사항을 적용하려면 서버를 재시작하세요.

전체 스키마와 예시는 docs/policy.md를 참조하세요.

Nix 환경

모든 의존성은 shell.nix로 관리됩니다. uv도 virtualenv도 없습니다. 주요 패키지:

  • python314 — 런타임

  • python314Packages.pyatspi — ATK 트리 접근

  • python314Packages.pygobject3 — GI 인트로스펙션

  • python314Packages.mcp — MCP SDK v2

  • python314Packages.pydantic-settings — 정책 구성

  • python314Packages.pyyaml — 정책 파싱

  • at-spi2-core, at-spi2-atk, atk, gtk3 — 런타임 라이브러리

사용 방법

Cursor와 함께

~/.cursor/mcp.json에 추가:

{
  "mcpServers": {
    "atk-accessibility": {
      "command": "nix-shell",
      "args": ["--run", "python -m src"],
      "cwd": "/path/to/orca"
    }
  }
}

Claude Desktop에서

~/Library/Application Support/Claude/claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "atk-accessibility": {
      "command": "nix-shell",
      "args": ["--run", "python -m src"],
      "cwd": "/path/to/orca"
    }
  }
}

Windsurf에서

프로젝트의 .mcp.json에 추가:

{
  "mcpServers": {
    "atk-accessibility": {
      "command": "nix-shell",
      "args": ["--run", "python -m src"],
      "cwd": "/path/to/orca"
    }
  }
}

명령줄에서 (대화형 테스트)

just shell
python -m src    # runs indefinitely on stdio

개별 도구를 테스트하려면 원시 MCP 요청을 파이프로 전달합니다:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | python -m src

정책 엔진

전체 참조는 docs/policy.md를 참조하세요.

빠른 예제 — 모든 heading 노드를 거부하고 textbox 이름을 수정합니다:

default_action: allow
built_in_deny:
  aria_roles:
    - "password"
  state_keywords:
    - "hidden"
    - "invisible"
rules:
  - id: deny-headings
    conditions:
      role: "heading"
    action: deny
  - id: redact-forms
    conditions:
      role: "textbox"
    action: redact
    redact_fields:
      - "name"
      - "description"

ATK 캡처

내부 구조는 docs/atk.md를 참조하세요. 핵심 사항:

  • gi.repository.Atspi 데스크톱 루트를 재귀적으로 탐색합니다.

  • Fail-closed: 하위 프로세스 격리를 통해 AT-SPI 버스를 사용할 수 없을 때 GLib abort가 서버를 충돌시키지 않습니다.

  • 각 노드가 캡처하는 것: obj_id, role (int), role_name, name, description, state_set, attributes, child_count, index_in_parent, app_name, pid

정규화

역할 매핑은 docs/normalize.md를 참조하세요.

ATK 정수 역할(0–132)은 ARIA 역할 문자열로 매핑됩니다. 매핑되지 않은 역할은 role_name 문자열로 통과합니다. 상태 이름도 변환됩니다(예: FOCUSED → focused, CHECKED → checked).

개발

개발 가이드는 docs/contribute.md를 참조하세요.

just shell        # enter dev environment
just test         # run verification suite
just compile      # syntax check
just lint         # import + smoke check
just server       # start server for manual testing

제한 사항

  • AT-SPI가 없는 Wayland 앱: 일부 Wayland 네이티브 GTK 앱은 AT-SPI 인터페이스를 노출하지 않습니다. get_tree_for_app은 이러한 앱에 대해 []를 반환합니다. 예상된 동작이며 버그가 아닙니다.

  • 핫 리로드 불가: 정책은 시작 시 한 번만 로드됩니다.

  • AT-SPI 버스 필요: 실행 중인 접근성 버스(예: at-spi-bus-launcher)가 없으면 ATK 모듈은 오류 없이 빈 []를 반환합니다.

  • Python 3.14+: typing-extensions 의존성이 없습니다.

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Resources

Related MCP Connectors

Related MCP Servers

  • claude-workman

    AdvisorAGI
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables MCP clients to control a Linux/X11 desktop like a human: see the screen, move the mouse, click UI elements via the accessibility tree, type text, and manage windows.
    MIT

  • dsh-computer-use-mcp

    huiliyi37
    -
    license
    Not graded
    quality
    C
    maintenance
    Standalone MCP server for desktop GUI automation on macOS and Windows, exposing a unified tool for accessibility-tree snapshots, input, app control, and browser CDP fast path, driven by any MCP host.
    -