Skip to main content
Glama
Sign In
deenesjakoruzh
orca

orca

by sachin-sankar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Orca — ATK Accessibility MCP Server

実行中の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のデスクトップルートを再帰的に走査します

  • フェイルクローズ: サブプロセス分離により、AT-SPIバスが利用できない場合にGLibのabortがサーバーをクラッシュさせるのを防ぎます

  • 各ノードはobj_id、role (int)、role_name、name、description、state_set、attributes、child_count、index_in_parent、app_name、pidをキャプチャします

正規化

ロールマップはdocs/modify.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への依存はありません。

ライセンス

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