Skip to main content
Glama
Sign In
deenesjakoruzh
orca

orca

by sachin-sankar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Orca — ATK Accessibility MCP Server

捕获 Linux 上运行的 GTK 应用程序的 ATK（Accessibility Toolkit）控件树，将其规范化为 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 工具

工具

参数

说明

get_tree

无

完整 ARIA 规范化树，按策略过滤

get_tree_for_app

app_name: str

限定某个应用的树（fnmatch 通配符）

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 和空的用户规则启动。

策略只在启动时加载一次——重启服务器后才能生效变更。

完整 schema 和示例参见 docs/policy.md。

Nix 环境

依赖全部由 shell.nix 管理。没有 uv，没有 virtualenv。

主要软件包：

  • python313 — 运行时

  • python313Packages.pyatspi — ATK 树访问

  • python313Packages.pygobject3 — GI 内省

  • python313Packages.mcp — MCP SDK v2

  • python313Packages.pydantic-settings — 策略配置

  • python313Packages.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）。

开发

开发指南参见 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 返回 []。这是预期行为，不是 bug。

  • 不支持热重载：策略只在启动时加载一次。

  • 需要 AT-SPI 统线：如果没有运行中的无障碍总线（例如 at-spi-bus-launcher），该 ATK 组件会优雅地返回 []。

  • Python 3.14+：不依赖 typing-extensions。

许可证

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