Orca — ATK Accessibility MCP Server

Erfasst den ATK-Widget-Baum (Accessibility Toolkit) von laufenden GTK-Anwendungen unter Linux, normalisiert ihn zu ARIA-Rollen/Typen, wendet eine konfigurierbare deklarative Sicherheitsrichtlinie an und stellt die Ergebnisse als MCP-Tools für jeden Standard-MCP-Client (Claude, Cursor, Windsurf usw.) bereit.

Schnellstart

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

Oder manuell:

nix-shell
PYTHONPATH=src python3 -m src

Related MCP server: claude-workman

Architektur

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-Tools

Konfiguration

Policy

Richtliniendateien werden in diesem Prioritätsverfahren geladen:

1. ~/.config/atk-mcp/policy.yaml (Benutzerüberschreibung)

2. src/default_policy.yaml (mitgelieferte Standardrichtlinie)

Wenn keine der Dateien existiert oder eine davon nicht analysieren lässt, startet der Server mit default_action: allow und ohne Benutzerregeln.

Die Richtlinie wird einmal beim Start geladen. Starten Sie den Server neu, um Änderungen zu übernehmen.

Siehe docs/policy.md für das vollständige Schema und Beispiele.

Nix-Umgebung

Alle Abhängigkeiten werden über shell.nix verwaltet. Kein uv, kein virtualenv.

Wichtige Pakete:

• python314 – Laufzeit

• python314Packages.pyatspi – ATK-Baumzugriff

• python314Packages.pygobject3 – GI-Introspektion

• python314Packages.mcp – MCP SDK v2

• python314Packages.pydantic-settings – Richtlinienkonfiguration

• python314Packages.pyyaml – Policy-Analyse

• at-spi2-core, at-spi2-atk, atk, gtk3 – Laufzeitbibliotheken

Verwendung

Mit Cursor

Fügen Sie zu ~/.cursor/mcp.json hinzu:

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

Mit Claude Desktop

Fügen Sie zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

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

Mit Windsurf

Fügen Sie zu .mcp.json in Ihrem Projekt hinzu:

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

Von der Befehlszeile (interaktiver Test)

just shell
python -m src    # runs indefinitely on stdio

Leiten Sie eine rohe MCP-Anfrage weiter, um einzelne Tools zu testen:

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

Richtlinien-Engine

Siehe docs/policy.md für die vollständige Referenz.

Kurzes Beispiel – alle heading-Knoten ablehnen und textbox-Namen schwärzen:

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-Erfassung

Für Details siehe docs/atk.md. Wichtige Punkte:

• Durchläuft Rekursiv den Desktop-Root gi.repository.Atspi

• Fail-closed: Die Subprozess-Isolation verhindert, dass ein GLib-Abort der Servers Absturz , wenn kein AT-SPI-Bus verfügbar ist.

• Jeder Knoten erfasst: obj_id, role (int), role_name, name, description ,state_set, attributes, child_count, index_in_parent, app_name, pid

Normalisierung

Für die Rollenzuordnung siehe docs/normalize.md.

Ganzzahlige ATK-Rollen (0–132) werden auf ARIA-Rollenstrings abgebildet. Nicht zugeordnete Rollen werden unverändert als ihr role_name-String durchgereicht. Zustandsnamen werden übersetzt (z. B. FOCUSED → focused, CHECKED → checked).

Entwicklung

Siehe docs/contribute.md für den Entwicklungsleitfaden.

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

Einschränkungen

• Wayland-Apps ohne AT-SPI: Manche Wayland-native GTK-Apps stellen keine AT-SPI-Schnittstellen bereit. get_tree_for_app p-

• Kein heißen Reload: Die Richtlinie wird einmal beim Start geladen.

• Erforderlicher AT-SPI-Bus: Ohne einen laufenden Accessibility-Bus (z. B. at-spi-bus-launcher) gibt das ATK-Modul sauber [] zurück.

• Python 3.14+: Keine typing-extensions-Abhängigkeit.

Lizenz

MIT