PcGöz

PcGöz is a Model Context Protocol (MCP) server that lets Claude (Claude Code CLI, or the Code tab of the Claude desktop app) see and use the Windows desktop. It combines the Microsoft UI Automation accessibility tree, screenshots annotated with numbered boxes, and real mouse/keyboard input through Windows SendInput — all sharing one set of element numbers.

Notice: Unofficial community project. Not affiliated with, sponsored by, or endorsed by Anthropic.

English · Türkçe

English

Have Claude Review It First

Recommended Prompt (Copy & Paste to Claude)

Clone the repository locally, start a Claude Code session inside it, and run:

I am considering installing PcGöz as a desktop automation MCP server. Please inspect the source code in this repository and answer the following questions:
1. What is the security and safety model? Which operations are blocked, restricted, or sanitized?
2. Which tools send physical inputs (mouse/keyboard), and which tools are strictly read-only?
3. How can I, as the user, immediately stop execution if something goes wrong?
4. Exactly what data is written to the audit log, where is it stored, and does it store passwords or clipboard text?
5. Does this MCP server make any outbound network connections or communicate with external servers?
6. Generate step-by-step installation and MCP configuration commands tailored specifically for my Windows environment.

After installing PcGöz, also install the companion skill (skills/masaustu-kullanimi) into Claude so it understands desktop automation best practices across all sessions.

How It Works

PcGöz connects three pillars into a unified feedback loop:

flowchart TD
    subgraph S["1. Accessibility Tree (UIA)"]
        UIA["Microsoft UI Automation<br/>Role, Name, Value, State, Coordinates"]
    end
    subgraph V["2. Annotated Vision"]
        SHOT["Screen Capture<br/>Overlaid with numbered bounding boxes: Box [7]"]
    end
    subgraph A["3. Hardware Automation"]
        INP["SendInput / UIA Pattern<br/>Direct invocation or physical mouse/keyboard"]
    end

    UIA -->|Same identifier space: ref_7| SHOT
    SHOT -->|Visual confirmation| INP
    INP -->|Live state diff: 0.3-1.2s| UIA

1. Microsoft UI Automation: Reads deep accessibility hierarchies (CUIAutomation8) to retrieve element roles, states, texts, and exact screen coordinates in single-pass COM queries.

2. Annotated Screenshot: Captures a window, a region or the whole screen and draws labeled boxes for the detected elements.

3. SendInput Simulation: Drives mouse clicks, keyboard text injection, and window management with low-level Windows APIs.

Unified Reference Space: Element ref_7 in the accessibility tree matches box 7 drawn on the screenshot. Claude can visually identify a button on screen and immediately interact with ref_7 without calculating pixel offsets manually. Every action automatically inspects UI changes and reports new, modified, or closed elements.

Tools Reference

PcGöz exposes 13 tools. All tool descriptions and returned messages are formatted in clear Turkish (ASCII), which Claude understands natively and reliably.

Safety Model (Code-Verified)

PcGöz operates under a free execution + local audit log philosophy. Instead of interrupting Claude with interactive approval prompts for routine clicks, it enforces rigorous deterministic safety layers in code:

• Physical Input Lock (inputguard.py:9-35, 258-337):

  • Uses low-level Windows hooks (WH_KEYBOARD_LL, WH_MOUSE_LL). When an action begins, user keyboard presses and mouse movements are intercepted and swallowed. Injected automation events (LLKHF_INJECTED, LLMHF_INJECTED) pass through seamlessly.

  • Unlike Windows BlockInput, this hook does not drop release events (WM_KEYUP, mouse button releases pass through so held keys never get stuck) and preserves emergency shortcuts.

  • If the user holds modifier keys (Ctrl/Alt/Shift/Win) or mouse buttons when the lock begins, PcGöz waits up to 1.5 seconds (config.HELD_WAIT_S = 1.5). If still held, it emits synthetic releases with a dummy mask key (0xE8) to prevent accidental Start Menu or menu bar activation.

  • Safety timeout: Locks auto-release after 30 seconds for single actions or 60 seconds for batch jobs (BLOCK_MAX_S = 30.0, BLOCK_BATCH_MAX_S = 60.0). Can be disabled via PCGOZ_BLOCK_INPUT=0.

• Emergency Stop (safety.py:81-150, 269-324):

  • Global hotkey toggle: Ctrl+Alt+Shift+Esc.

  • Fallbacks if registered by another app: Ctrl+Alt+Shift+Pause, Ctrl+Alt+Shift+F12, Ctrl+Shift+Alt+Backspace.

  • If no hotkey can be registered, a prominent warning is prepended to all action responses (safety.hotkey_warning()).

  • Cross-process synchronization: All running PcGöz server instances share a named event (Local\PcGozAcilDurdurma). Triggering emergency stop in any session instantly freezes all sessions.

• On-Screen Visual HUD (overlay.py:8-20, 202-250):

  • A layered, semi-transparent top-left window (WS_EX_TRANSPARENT, WS_EX_NOACTIVATE, WS_EX_TOPMOST).

  • Click-through and unfocusable; marked with WDA_EXCLUDEFROMCAPTURE so it never appears in PcGöz's own screenshots or OCR.

  • Warns the user when input is locked and how to stop it. Lingers for 0.4 seconds after actions complete to eliminate visual flickering. Can be disabled with PCGOZ_OVERLAY=0.

• Inter-Session Mutex (inputguard.py:97, 200-216):

  • A named mutex (Local\PcGozGirdiKilidi) ensures multiple Claude sessions never fight over the physical keyboard or mouse queue simultaneously. Sessions queue up with a 20-second timeout (SESSION_WAIT_S = 20.0).

• Hard Credential Blocks (safety.py:470-523, config.py:138-144):

  • Text typing (pc_do type, pc_invoke value) is unconditionally rejected on elements with IsPassword=True and processes belonging to Windows credential interfaces (consent.exe, credentialuibroker.exe, logonui.exe, lsaiso.exe, winlogon.exe).

  • Key injection (pc_do key) into password targets is strictly whitelisted: only navigation and deletion keys (Tab, Enter, Esc, Backspace, Delete, Arrows, Home/End, PgUp/PgDn, Ctrl+A) are permitted. Typing character keys or pasting passwords is hard-blocked.

• Secure Desktop Detection (safety.py:155-172):

  • Detects when Windows switches to the secure desktop (UAC elevation prompts, lock screen, Ctrl+Alt+Del). Halts input immediately and returns an explicit SecureDesktop error rather than injecting invisible keystrokes.

• Stale Coordinate Protection (server.py:241, refs.py):

  • If a target element moves, closes, or is obscured after detection, stale coordinates are rejected instead of clicking blind pixels.

• Safe Clipboard Restoration (server.py:327-332, clipboard.py):

  • Large text blocks (>200 characters) are pasted via delayed rendering (WM_RENDERFORMAT). PcGöz backs up existing clipboard data (images, files, custom formats) and restores it once the target process reads the synthetic text.

  • Monitored via destination PIDs (windows.input_pids()) so background readers (such as Windows CrossDeviceService) do not trigger premature restoration. Does not pollute Win+V clipboard history.

• Dry Run Mode: Set PCGOZ_DRY_RUN=1 to run all vision and inspection tools normally while logging simulated inputs without executing them.

Privacy & Data Flow (Code-Verified)

• Audit Log File: Stored at ~/.pcgoz/actions.jsonl (or configured via PCGOZ_LOG_DIR). Automatically rotates to actions.1.jsonl when exceeding 5 MB (config.LOG_MAX_BYTES = 5 * 1024 * 1024).

• What is logged:

  • Timestamp, tool name, PID, correlation call ID, execution time (ms), success/error status.

  • pc_do type: The text string typed into applications is logged (safety.audit records text=text). Password fields are blocked from typing (see Safety Model), so passwords never reach this log through PcGöz.

  • pc_do key: The key or combo executed is logged (safety.audit records key=key).

  • pc_invoke: Target label, action name, and character count are logged (chars=len(value)).

  • Clipboard text: NEVER logged. Only character count (chars=len(...)) is recorded for clipboard read/write actions.

  • Screenshots: NEVER logged or saved to disk. Image buffers are held in memory and returned directly to the MCP protocol channel.

  • Vision read tools: Argument queries and document contents are not logged, only tool name, timing, and error outcomes.

• Zero Outbound Network Connections:

  • The PcGöz MCP server makes ZERO network connections (no telemetry, no tracking, no external API calls).

  • OCR and vision processing run entirely on your local CPU/GPU using Windows native APIs (Windows.Media.Ocr).

  • Honest Data Flow Note: Because pc_screenshot returns PNG image data over stdio to Claude Code, those screenshots are transmitted by the Claude client to Anthropic's model servers as part of your active chat session.

System Requirements

• Operating System: Windows 10 version 2004 (build 19041) or later, or Windows 11 (x64) — needed so the on-screen warning stays out of screenshots (WDA_EXCLUDEFROMCAPTURE)

• Python Runtime: Python 3.12 or newer

• Package Manager: uv recommended

• Client: Claude Code CLI or Claude Desktop (Code integration)

• OCR Support: Built-in Windows OCR (Language pack with Optical Character Recognition enabled in Windows Settings > Time & Language)

Step-by-Step Installation

1. Clone & Synchronize Dependencies

git clone https://github.com/emperorbug46/PcGoz
cd PcGoz
uv sync

2. Register with Claude Code

Option A — Via Claude Code CLI (Recommended):

claude mcp add pcgoz --scope user -- "C:\yol\PcGoz\.venv\Scripts\python.exe" -m pcgoz

Option B — Manual Registration in ~/.claude.json:

Add pcgoz to your user-level mcpServers object in ~/.claude.json:

{
  "mcpServers": {
    "pcgoz": {
      "type": "stdio",
      "command": "C:\\yol\\PcGoz\\.venv\\Scripts\\python.exe",
      "args": ["-m", "pcgoz"]
    }
  }
}

3. Install the Companion Desktop Skill

The skill directs Claude on when to use PcGöz versus shell tools, and teaches it how to handle focus and navigation quirks:

New-Item -ItemType Junction -Path "$HOME\.claude\skills\masaustu-kullanimi" -Target "C:\yol\PcGoz\skills\masaustu-kullanimi"

4. Verify the Installation

Restart Claude Code. In your terminal, run the diagnostic verification command:

.\.venv\Scripts\python.exe -m pcgoz --doctor

5. Plugin Distribution (Alternative)

This repository includes Claude plugin manifests (.claude-plugin/plugin.json, .mcp.json). You can install it as a plugin:

claude plugin install C:\yol\PcGoz

(Note: Plugin manifest packaging is implemented, but independent CLI verification is pending).

Example Prompts for Claude

Once PcGöz is active, you can give Claude real desktop tasks:

1. "Open Notepad, type a two-stanza poem, and verify that all characters were typed accurately."

2. "Look at the active error dialog on my screen, read the error message, and tell me what went wrong."

3. "Build and run my WinForms project, then check whether the main window opened with all buttons and fields intact."

4. "Open Windows Settings, navigate to Display, and read the recommended scaling percentage."

5. "Find the File Explorer window showing our project folder and tell me the size of README.md."

Command-Line Diagnostics

PcGöz provides built-in maintenance tools accessible via Python CLI:

Test Suite

The test suite under tests/ verifies edge cases and hardware integration:

• tests/smoke.py: End-to-end automation test using Notepad. Uses the mouse and keyboard for ~20 seconds and runs a series of checks (including Turkish Unicode round-trips and stale ref handling), and cleanly exits without killing processes.

• tests/kilit_canli.py: Interactive input guard verification. After a 5-second countdown it locks the keyboard and mouse for 8 seconds while you move/type, and reports the swallowed events.

• tests/kapsam.py: Validates UI Automation across open apps, UWP Settings navigation, cold browser launch, emergency freeze, and password blocking. (Brave browser tests are skipped if Brave is not installed).

• tests/agir_sayfa.py: Benchmarks cold and warm tree reading on heavy 1,500-row HTML pages (~9,000 UIA elements). (Requires Brave; exits if missing).

• tests/ocr_olcum.py: Evaluates Windows OCR accuracy and performance across 1×/2×/3× scaling and BICUBIC vs. LANCZOS resampling.

• tests/birim.py: Pure unit tests for coordinate normalization, shortcut parsing, password whitelisting, and lock decision logic (requires no input or windows).

• tests/pano.py: Validates delayed rendering clipboard exchange, background reader filtering, and format preservation.

• tests/tus_probu.py: Tests key stroke injection and cursor placement inside a sandboxed test window (~2s of isolated input).

• tests/mcp_istemci.py: Spawns the MCP server over stdio to test protocol handshakes and fallback diagnostic modes.

Limitations & Known Quirks

• Elevated Windows (UIPI): If an application runs as Administrator while Claude Code runs un-elevated, Windows User Interface Privilege Isolation (UIPI) blocks messages and clicks. Launch Claude Code with administrative privileges if you need to automate elevated utilities (like Task Manager).

• Secure Desktop: UAC prompts, lock screens, and Ctrl+Alt+Del run on the isolated Winlogon desktop. No standard process can access it. PcGöz halts input and returns a SecureDesktop error.

• Non-Standard Frameworks: Custom rendering engines (Qt, canvas, video games, remote desktops) do not populate accessibility trees. Use pc_ocr and pc_screenshot as fallbacks.

• Hung Applications: Unresponsive windows are probed via a 500ms WM_NULL ping, and COM calls use CUIAutomation8 timeouts (2s connection / 10s operation) so a frozen program never deadlocks the agent.

• Focus Stealing Lock: If Windows blocks SetForegroundWindow, pc_focus automatically clicks an unoccluded coordinate on the target's caption bar (HTCAPTION).

• Deep Architecture Details: For technical measurements and history, see docs/GELISTIRICI-NOTLARI.md.

Troubleshooting

• Server Enters Fallback Mode: If an import fails, the server does not crash with a silent CONNECTION_CLOSED. It starts in fallback mode, offering all 13 tools with detailed instructions to run --repair.

• Broken Accessibility Cache: Run python -m pcgoz --repair to rebuild comtypes wrappers.

• Moved Folder or Missing Tools: If Claude cannot find PcGöz tools, run python -m pcgoz --doctor to check if ~/.claude.json points to a moved directory.

License & Disclaimer

• License: Distributed under the MIT License.

• Disclaimer: PcGöz simulates real mouse and keyboard inputs and directly manipulates desktop windows. Use it responsibly and review automated workflows before execution.

Related MCP server: screenmcp-claude-plugin

Türkçe

English · Türkçe

Kurmadan Önce Claude'a İnceletin

Kopyalanabilir İstem (Claude'a Verilecek Prompt)

Depoyu bilgisayarınıza klonlayın, Claude Code oturumu açın ve şu istemi iletin:

PcGöz'ü masaüstü kontrolü ve görsel otomasyon için bir MCP sunucusu olarak kurmayı düşünüyorum. Lütfen bu depodaki kaynak kodları incele ve şu soruları yanıtla:
1. Güvenlik modeli nedir? Hangi eylemler engellenir, denetlenir veya filtrelenir?
2. Hangi araçlar fiziksel girdi (fare/klavye) gönderir, hangileri tamamen salt okunurdur?
3. Bir sorun olursa kullanıcı olarak eylemleri anında nasıl durdurabilirim?
4. Denetim günlüğüne tam olarak neler yazılır, nerede tutulur; parola veya pano metinleri kaydedilir mi?
5. Bu MCP sunucusunun internete veya harici bir ağa erişimi var mı?
6. Benim Windows ortamıma göre adım adım kurulum ve MCP kayıt komutlarını çıkar.

PcGöz'ü kurduktan sonra skills/masaustu-kullanimi becerisini de Claude'a yükletin; böylece Claude oturumlar boyunca yönlendirme ve kullanım kurallarını kalıcı olarak hatırlar.

Nasıl Çalışır?

PcGöz, masaüstü otomasyonunu üç temel ayak üzerinde birleştirir:

flowchart TD
    subgraph S["1. Erişilebilirlik Ağacı (UIA)"]
        UIA["Microsoft UI Automation<br/>Rol, Metin, Değer, Durum, Tam Koordinat"]
    end
    subgraph V["2. Numaralandırılmış Görsel"]
        SHOT["Ekran Görüntüsü<br/>Öğelerin üzerine çizilmiş kutular: Kutu [7]"]
    end
    subgraph A["3. Donanım Seviyesi Eylem"]
        INP["SendInput / UIA Deseni<br/>Desensel tetikleme veya gerçek fare/klavye"]
    end

    UIA -->|Aynı numara uzayı: ref_7| SHOT
    SHOT -->|Görsel doğrulama| INP
    INP -->|Canlı durum farkı: 0.3-1.2 sn| UIA

1. Microsoft UI Automation: Ekrandaki tüm pencerelerin ve bileşenlerin rollerini, durumlarını, metinlerini ve koordinatlarını CUIAutomation8 üzerinden tek COM çağrısıyla çeker.

2. Numaralandırılmış Ekran Görüntüsü: Alınan ekran görüntüsünün üzerine tespit edilen öğelerin sınır kutularını ve referans numaralarını çizer.

3. SendInput Sürüşü: Fare tıklamalarını, metin yazımını ve pencere işlemlerini gerçek Windows donanım mesajlarıyla yürütür.

Ortak Numara Uzayı: Erişilebilirlik ağacında ref_7 olarak görünen buton, ekran görüntüsünde 7 etiketli kutudur. Claude ekrandaki kutuyu görüp doğrudan ref_7 ile eyleme geçebilir; piksel hesabı yapmasına gerek kalmaz. Her eylemden sonra ekran otomatik olarak izlenir ve neyin değiştiği raporlanır.

Araçlar Tablosu

PcGöz toplam 13 araç sunar. Araç açıklamaları ve dönen mesajlar Türkçe (ASCII) olarak kodlanmıştır; Claude bu metinleri sorunsuz bir şekilde anlar.

Güvenlik Modeli (Koddan Doğrulanmış)

PcGöz, onay sormayan serbest çalışma + eksiksiz yerel denetim günlüğü modelini benimser. Güvenliği kod seviyesindeki sıkı kurallarla sağlar:

• Fiziksel Girdi Kilidi (inputguard.py:9-35, 258-337):

  • Düşük seviye Windows kancaları (WH_KEYBOARD_LL, WH_MOUSE_LL) kullanılır. Eylem başladığı anda kullanıcının fiziksel fare ve klavye hareketleri yutulur; PcGöz'ün gönderdiği sentetik olaylar (LLKHF_INJECTED, LLMHF_INJECTED) engelsiz geçer.

  • Windows BlockInput fonksiyonundan farklı olarak tuş bırakma (WM_KEYUP, fare düğmesi bırakma) olayları kilitlenmez; böylece basılı tuşlar takılı kalmaz ve acil durdurma kısayolu çalışır.

  • Kilit anında kullanıcı Ctrl/Alt/Shift/Win veya fare düğmesini basılı tutuyorsa 1,5 saniye bırakması beklenir (config.HELD_WAIT_S = 1.5). Süre dolarsa atanmamış maske tuşuyla (0xE8) sentetik bırakma gönderilir (Başlat menüsü veya menü çubuğunun açılması önlenir).

  • Zaman aşımı: Kilit tek eylemde en fazla 30 saniye, toplu işlerde 60 saniye sürer (BLOCK_MAX_S = 30.0, BLOCK_BATCH_MAX_S = 60.0). PCGOZ_BLOCK_INPUT=0 ile kapatılabilir.

• Acil Durdurma (safety.py:81-150, 269-324):

  • Genel kısayol: Ctrl+Alt+Shift+Esc (aç/kapa).

  • Kısayol başka uygulama tarafından tutuluyorsa sırayla Pause, F12, Backspace kombinasyonları denenir.

  • Hiçbiri alınamazsa girdi üreten tüm araçların çıktılarına acil durdurmanın çalışmadığına dair belirgin bir uyarı eklenir (safety.hotkey_warning()).

  • Süreçler arası ortaklık: Tüm PcGöz sunucuları adlandırılmış bir olay nesnesi (Local\PcGozAcilDurdurma) paylaşır. Herhangi bir oturumda kısayola basıldığında çalışan tüm PcGöz oturumları anında dondurulur.

• Sol Üst Görsel Uyarı Penceresi (overlay.py:8-20, 202-250):

  • Yarı saydam (%80), koyu zeminli, tıklama geçiren (WS_EX_TRANSPARENT), odak çalmayan (WS_EX_NOACTIVATE) ve en üstte duran (WS_EX_TOPMOST) penceredir.

  • WDA_EXCLUDEFROMCAPTURE bayrağı sayesinde PcGöz'ün kendi ekran görüntülerine ve OCR taramasına asla girmez.

  • Kullanıcıya klavye/farenin kilitli olduğunu ve durdurma kısayolunu gösterir. Kilit bittikten 0,4 saniye sonra kaybolur (LINGER_S = 0.4). PCGOZ_OVERLAY=0 ile devre dışı bırakılabilir.

• Oturumlar Arası Sıra Mutex'i (inputguard.py:97, 200-216):

  • Adlandırılmış mutex (Local\PcGozGirdiKilidi) ile aynı anda yalnızca tek bir Claude oturumunun masaüstüne girdi göndermesine izin verilir. Diğer oturumlar 20 saniyeye kadar sırada bekler (SESSION_WAIT_S = 20.0).

• Sert Kimlik ve Parola Engelleri (safety.py:470-523, config.py:138-144):

  • IsPassword=True olan alanlara ve Windows kimlik süreçlerine (consent.exe, credentialuibroker.exe, logonui.exe, lsaiso.exe, winlogon.exe) metin yazma (pc_do type, pc_invoke value) koşulsuz olarak reddedilir (Refused).

  • Parola alanlarına tuş gönderme (pc_do key) izin listesiyle sınırlandırılmıştır: Yalnızca gezinme ve silme tuşlarına (Tab, Enter, Esc, Oklar, Backspace, Delete, Home/End, PgUp/PgDn, Ctrl+A) izin verilir; karakter tuşları ve yapıştırma sert şekilde engellenir.

• Güvenli Masaüstü Kontrolü (safety.py:155-172):

  • Girdi masaüstü Default dışında olduğunda (UAC yükseltme ekranı, Ctrl+Alt+Del ekranı, kilit ekranı) girdi gönderilmez; açıkça SecureDesktop hatası döndürülür.

• Bayat Koordinat Koruması (server.py:241, refs.py):

  • Hedef pencere kapandıysa ya da hedef öğenin üstü başka bir pencereyle örtüldüyse eski koordinata tıklanmaz, hata verilir.

• Güvenli Pano Yapıştırması (server.py:327-332, clipboard.py):

  • 200 karakterden uzun metinler gecikmeli sunumla (WM_RENDERFORMAT) pano üzerinden yapıştırılır. Kullanıcının mevcut panosu (resim, dosya, biçimlendirilmiş veri) hafızaya alınır ve hedef uygulama veriyi okuduktan sonra panoya geri yüklenir.

  • Yalnızca hedef sürecin PID'leri (windows.input_pids()) okuyucu sayılır; Windows Cihazlar Arası Pano servisinin erken okuması filtrelenir. Win+V pano geçmişine girmez.

• Dry Run Kipi: PCGOZ_DRY_RUN=1 ile tüm görme araçları normal çalışırken girdi araçları fiziksel eylem yapmaz, sadece günlüğe yazar.

Gizlilik ve Veri Akışı (Koddan Doğrulanmış)

• Denetim Günlüğü Yolu: %USERPROFILE%\.pcgoz\actions.jsonl (veya PCGOZ_LOG_DIR değişkeni). 5 MB'ı aştığında otomatik olarak actions.1.jsonl adına yedeklenerek döndürülür (config.LOG_MAX_BYTES = 5 * 1024 * 1024). Eski %LOCALAPPDATA%\PcGoz kayıtları otomatik aktarılır.

• Günlüğe Neler Yazılır:

  • Zaman damgası, araç adı, süreç kimliği (PID), çağrı ID'si, milisaniye cinsinden süre, başarı/hata durumu.

  • pc_do type: Yazılan metin günlüğe yazılır (safety.audit kaydında text=text yer alır). Parola alanlarına yazma engelli olduğu için (bkz. Güvenlik Modeli) parolalar PcGöz üzerinden bu günlüğe girmez.

  • pc_do key: Gönderilen tuş kombinasyonu günlüğe yazılır (key=key).

  • pc_invoke: Hedef öğe, desen adı ve değer uzunluğu günlüğe yazılır (chars=len(value)).

  • Pano içeriği: ASLA günlüğe yazılmaz. Pano işlemlerinde yalnızca karakter sayısı (chars=len(...)) kaydedilir.

  • Ekran görüntüleri: ASLA diske veya günlüğe kaydedilmez. PNG verisi sadece bellekte tutulur ve MCP kanalıyla istemciye iletilir.

  • Görme/okuma araçları: Arama terimleri veya okunan belge içerikleri günlüğe yazılmaz; sadece araç adı, süre ve başarı durumu yazılır.

• Ağ Erişimi Yoktur:

  • PcGöz sunucusu internete veya herhangi bir harici ağa asla bağlanmaz (sıfır ağ çağrısı, yerel stdio MCP).

  • Ekran görüntüleri ve OCR işlemleri tamamen yerel işlemcinizde (Windows.Media.Ocr) çalışır.

  • Veri Akışı Notu: pc_screenshot aracı MCP üzerinden ekran görüntüsü baytlarını Claude Code istemcisine döndürdüğü için, bu görüntüler sohbet bağlamınızın parçası olarak Anthropic model sunucularına iletilir.

Gereksinimler

• İşletim Sistemi: Windows 10 sürüm 2004 (derleme 19041) veya üstü ya da Windows 11 (x64) — ekrandaki uyarının ekran görüntülerine girmemesi için (WDA_EXCLUDEFROMCAPTURE)

• Python: Python 3.12 veya üzeri

• Paket Yöneticisi: uv

• İstemci: Claude Code (CLI veya Claude Masaüstü uygulamasının Code sekmesi)

• OCR Bileşeni: Windows'un yerleşik OCR motoru (Ayarlar > Zaman ve dil > Dil ve bölge üzerinden kurulu dil için Optik Karakter Tanıma bileşeni)

Kurulum Adımları

1. Depoyu Klonlayın ve Bağımlılıkları Kurun

git clone https://github.com/emperorbug46/PcGoz
cd PcGoz
uv sync

2. Claude Code'a MCP Sunucusu Olarak Kaydedin

Yol 1 — Claude Code CLI ile (Önerilen):

claude mcp add pcgoz --scope user -- "C:\yol\PcGoz\.venv\Scripts\python.exe" -m pcgoz

Yol 2 — ~/.claude.json Dosyasına Elle Kayıt:

Kullanıcı profilinizdeki ~/.claude.json dosyasında mcpServers bölümüne ekleyin:

{
  "mcpServers": {
    "pcgoz": {
      "type": "stdio",
      "command": "C:\\yol\\PcGoz\\.venv\\Scripts\\python.exe",
      "args": ["-m", "pcgoz"]
    }
  }
}

3. Kullanım Becerisini (Skill) Bağlayın

Beceriyi bağlamak, Claude'un oturumlar boyunca PcGöz'ü hangi durumlarda ve nasıl kullanacağını bilmesini sağlar:

New-Item -ItemType Junction -Path "$HOME\.claude\skills\masaustu-kullanimi" -Target "C:\yol\PcGoz\skills\masaustu-kullanimi"

4. Kurulumu Doğrulayın

Claude Code'u yeniden başlatın. Terminalinizden teşhis aracını çalıştırın:

.\.venv\Scripts\python.exe -m pcgoz --doctor

5. Eklenti Olarak Kurulum (Alternatif)

Depo Claude Code eklenti manifestlerini içerir (.claude-plugin/plugin.json, .mcp.json):

claude plugin install C:\yol\PcGoz

(Not: Eklenti dosyaları hazırdır; CLI üzerinden doğrudan doğrulanması henüz tamamlanmamıştır).

Kullanım Örnekleri

Claude'a verebileceğiniz gerçek senaryo örnekleri:

1. "Not Defteri'ni aç, iki kıtalık bir şiir yaz ve metnin doğru yazıldığını doğrula."

2. "Ekranda açık olan hata penceresini incele, hata mesajını oku ve ne yapmam gerektiğini söyle."

3. "Geliştirdiğim WinForms uygulamasını derle, çalıştır ve ana pencerenin tüm düğmelerle birlikte açıldığını doğrula."

4. "Windows Ayarlar > Ekran sayfasına git ve önerilen ölçekleme oranını oku."

5. "Açık belgedeki 'Kaydet' düğmesine tıkla ve ekranda neyin değiştiğini kontrol et."

Komut Satırı Araçları

PcGöz bakım ve teşhis için dahili CLI bayrakları sunar:

Test Paketi

tests/ dizinindeki testler tüm otomasyon ve güvenlik sınırlarını doğrular:

• tests/smoke.py: Not Defteri ile uçtan uca otomasyon testi (~20 saniye fareyi ve klavyeyi kullanır, Türkçe karakter ve bayat ref dahil bir dizi kontrol yapar, kaydetmeden kapatır).

• tests/kilit_canli.py: Canlı kilit denemesi (5 sn geri sayımdan sonra fare ve klavyeyi 8 saniye kilitler, fiziksel hareketlerin yutulduğunu doğrular).

• tests/kapsam.py: Erişilebilirlik kapsamı, UWP Ayarlar penceresi, soğuk tarayıcı açılışı, acil durdurma ve parola engelleme kontrolleri. (Brave kurulu değilse tarayıcı testi atlanır).

• tests/agir_sayfa.py: 1500 satırlık (~9000 UIA öğesi) ağır sayfada okuma performansı ve kaydırma doğruluğu testi. (Brave gerektirir; yoksa çalışmaz).

• tests/ocr_olcum.py: Windows OCR ölçekleme ve yeniden örnekleme ölçümleri (BICUBIC vs. LANCZOS).

• tests/birim.py: Pencere açmayan ve girdi göndermeyen saf birim testleri (koordinat dönüşümleri, kısayol çözümlemeleri, kilit mantığı).

• tests/pano.py: Gecikmeli sunumlu pano kopyalama, arka plan okuyucusu filtreleme ve veri kurtarma testi.

• tests/tus_probu.py: Tuş gönderimi ve imleç konumlandırma doğrulaması (~2 saniye test penceresinde çalışır).

• tests/mcp_istemci.py: Sunucunun stdio üzerinden MCP protokolüyle konuşmasını ve yedek modu test eder.

Sınırlamalar ve Bilinen Durumlar

• Yönetici Pencereleri (UIPI): Claude Code standart kullanıcı haklarıyla çalışıyorsa yönetici yetkisiyle çalışan pencerelere tıklayamaz ve okuyamaz. Gerekirse Claude Code yönetici olarak başlatılmalıdır.

• Güvenli Masaüstü: UAC istemleri, kilit ekranı ve Ctrl+Alt+Del ekranı Winlogon masaüstünde çizilir. Hiçbir kullanıcı süreci erişemez; PcGöz bu durumda SecureDesktop hatası verir.

• Erişilebilirlik Vermeyen Uygulamalar: Qt, canvas veya oyun arayüzleri UIA ağacı üretmezse pc_ocr ve pc_screenshot kullanılmalıdır.

• Donmuş Uygulamalar: 500 ms WM_NULL yoklaması ve CUIAutomation8 zaman aşımları sayesinde donan uygulamalar sunucuyu kilitlemez.

• Odak Kilidi: Windows SetForegroundWindow çağrısını engellerse pc_focus başlık çubuğunun güvenli bir noktasına tıklar.

• Ayrıntılı Ölçümler ve Mimari Notlar: Geçmiş ölçümler ve tasarım kararları için docs/GELISTIRICI-NOTLARI.md belgesine bakın.

Sorun Giderme

• Sunucu Yedek Modda Açılıyor: Bir kütüphane veya COM hatası olduğunda sunucu çökmez; 13 aracın tümüyle yedek modda açılıp hatanın sebebini ve --repair komutunu bildirir.

• UIA Önbellek Bozulması: python -m pcgoz --repair çalıştırarak önbelleği temizleyin.

• Klasör Taşıma Sonrası Araçların Görünmemesi: python -m pcgoz --doctor çalıştırarak ~/.claude.json kaydının güncel Python yolunu gösterdiğinden emin olun.

Lisans ve Sorumluluk Reddi

• Lisans: Bu proje MIT Lisansı ile lisanslanmıştır.

• Sorumluluk Reddi: PcGöz gerçek donanım seviyesinde fare ve klavye girdisi gönderir. Kendi sorumluluğunuzda kullanın; kritik sistemlerde çalıştırmadan önce güvenlik modelini inceleyin.