Orca — MCP-сервер для ATK-доступности

Захватывает дерево виджетов ATK (Accessibility Toolkit) из запущенных на Linux GTK-приложений, нормализует его к ролям/типам ARIA, применяет настраиваемую декларативную политику безопасности и предоставляет результат в виде инструментов MCP любому стандартному MCP-клиенту (Claude, Cursor, Windsurf и т.п.).

Быстрый старт

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

Конфигурация

Политика

Файлы политики загружаются в следующем порядке приоритета:

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: изоляция в подпроцессе предотвращает падение сервера из-за аварийного завершения GLib при отсутствии шины AT-SPI

• Для каждого узла сохраняются: 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

Ограничения

• Wayland-приложения без AT-SPI: Некоторые нативные Wayland GTK-приложения не раскрывают интерфейсы AT-SPI. Для таких приложений get_tree_for_app возвращает []. Ожидаемое поведение, а не ошибка.

• Без горячей перезагрузки: Политика загружается один раз при запуске.

• Требуется шина AT-SPI: без запущенной шины доступности (например, at-spi-bus-launcher) модуль ATK корректно возвращает [].

• Python 3.14+: без зависимости typing-extensions.

Лицензия

MIT