agentic-windows-mcp 0.8.8__tar.gz

agentic_windows_mcp-0.8.8/LICENSE.md

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Vu Manh Ruy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Portions of this software are derived from the windows-mcp project.
+Copyright (c) 2025 JEOMON GEORGE. Retained in accordance with the MIT License
+terms above.

agentic_windows_mcp-0.8.8/PKG-INFO

@@ -0,0 +1,337 @@
+Metadata-Version: 2.4
+Name: agentic-windows-mcp
+Version: 0.8.8
+Summary: Agentic Windows MCP - an MCP server that gives AI agents full, safe control of a Windows PC: desktop automation, remote computer control, browser DevTools inspection, and remote software development.
+Author: Vu Manh Ruy
+License: MIT License
+        
+        Copyright (c) 2026 Vu Manh Ruy
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+        ---
+        
+        Portions of this software are derived from the windows-mcp project.
+        Copyright (c) 2025 JEOMON GEORGE. Retained in accordance with the MIT License
+        terms above.
+        
+Project-URL: Homepage, https://github.com/homenewstar
+Project-URL: Repository, https://github.com/homenewstar/agentic-agentic-windows-mcp
+Project-URL: Issues, https://github.com/homenewstar/agentic-agentic-windows-mcp/issues
+Keywords: windows,mcp,ai,desktop,ai agent
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Desktop Environment
+Classifier: Topic :: System :: Shells
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: click>=8.2.1
+Requires-Dist: comtypes>=1.4.15
+Requires-Dist: dxcam>=0.3.0
+Requires-Dist: fastmcp>=3.0
+Requires-Dist: fuzzywuzzy>=0.18.0
+Requires-Dist: markdownify>=1.1.0
+Requires-Dist: pillow>=11.2.1
+Requires-Dist: platformdirs>=4.3.8
+Requires-Dist: posthog>=7.4.0
+Requires-Dist: psutil>=7.0.0
+Requires-Dist: pygments>=2.20.0
+Requires-Dist: python-levenshtein>=0.27.1
+Requires-Dist: pywin32>=311
+Requires-Dist: requests>=2.33.0
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: thefuzz>=0.22.1
+Requires-Dist: uuid7>=0.1.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.9.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# Agentic Windows MCP
+
+**Biến mọi AI Agent — dù đang chạy trên web, trên app, hay ở bất cứ đâu — thành đôi tay điều khiển chiếc máy tính Windows của bạn.**
+
+Điều khiển máy tính từ xa toàn diện · Tự động hóa mọi thao tác · Lập trình trực tiếp trên máy của bạn, từ bất cứ nơi nào
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md)
+![Platform](https://img.shields.io/badge/Platform-Windows%2010%20%7C%2011-blue)
+![Python](https://img.shields.io/badge/Python-3.14%2B-yellow)
+![Protocol](https://img.shields.io/badge/Protocol-MCP-purple)
+![Tools](https://img.shields.io/badge/Tools-40-orange)
+
+</div>
+
+---
+
+## 💡 Ý tưởng cốt lõi — Ba trụ cột
+
+Một mình, AI Agent chỉ "nói" được. Một mình, chiếc PC của bạn chỉ "ngồi" đó. **Agentic Windows MCP** là cầu nối khiến cả hai — cộng với GitHub — tạo thành một bộ máy làm việc hoàn chỉnh:
+
+| Trụ cột | Vai trò | Nằm ở đâu? |
+|---|---|---|
+| **1. GitHub** | Kho mã nguồn trung tâm: đồng bộ, lịch sử phiên bản, điểm gặp gỡ của mọi thay đổi | Trên cloud của GitHub |
+| **2. AI Agent** | "Bộ não": Muse, ChatGPT, Claude, Gemini, DeepSeek... phân tích, ra quyết định, viết code, ra lệnh | Web, app điện thoại, máy khác — bất cứ đâu |
+| **3. Máy tính / Server của bạn** | "Đôi tay + nơi làm việc thật": dự án nằm đây, code chạy ở đây, ứng dụng thật mở ở đây — Agentic Windows MCP được cài tại đây để thi hành | PC ở nhà, máy ở công ty, VPS Windows... |
+
+**Ba trụ cột hoàn toàn độc lập về vị trí địa lý**, chỉ kết hợp qua hai đường ống: giao thức **MCP** (Agent ⇄ máy của bạn) và **Git** (máy của bạn ⇄ GitHub). Nhờ vậy:
+
+- Bạn ngồi quán cà phê, mở ChatGPT trên điện thoại → ra lệnh → Agent điều khiển chiếc PC ở nhà: mở dự án, sửa code, chạy test, commit và push lên GitHub. Về đến nhà, mọi thứ đã xong.
+- Hoặc gộp cả ba vào **một máy duy nhất**: Agent chạy app trên chính PC, code nằm trên chính PC — Agentic Windows MCP cho phép Agent tự thao tác như một lập trình viên ngồi trước máy.
+
+```
+                    ┌─────────────────────────────┐
+                    │           GITHUB            │
+                    │  mã nguồn · đồng bộ · bản sao │
+                    └──────────────┬──────────────┘
+                          git push/pull
+                    ┌──────────────▼──────────────┐
+   ┌─────────────┐  │   MÁY TÍNH CỦA BẠN          │      ┌──────────────────┐
+   │  AI AGENT   │  │   ┌───────────────────────┐  │      │  NGƯỜI DÙNG      │
+   │ Muse ·     ├──┼──►│  AGENTIC WINDOWS MCP  │◄─┼──────┤  giám sát · xem  │
+   │ ChatGPT ·   │MCP│   │  40 công cụ điều khiển │  │ nhìn │  viền phát sáng  │
+   │ Claude ·    │◄──┼──┤  chuột · phím · app   │  │ thấy │  · bảng cảnh báo │
+   │ Gemini ·    │  │   │  PowerShell · file    │  │      │  · phím Space*   │
+   │ DeepSeek... │  │   │  DevTools trình duyệt│  │      └──────────────────┘
+   └─────────────┘  │   └───────────────────────┘  │
+   (web / app /     │   Windows 10 / 11          │
+    máy khác)       └─────────────────────────────┘
+                     *phím tắt lấy lại quyền điều khiển:
+                      Ctrl + Alt + Shift + Space
+```
+
+---
+
+## ✨ Chức năng chính
+
+### 🖥️ Điều khiển máy tính toàn diện
+- **Chuột & bàn phím như người thật**: click, double/right-click, kéo–thả theo đường nhiều đoạn, giữ chuột, vuốt/cào, gõ văn bản Unicode, tổ hợp phím tắt, cuộn — kể cả thao tác kéo chính xác từng điểm ảnh.
+- **Đọc màn hình bằng cây UI (UI Automation)**: chụp "Snapshot" toàn bộ cây phần tử của cửa sổ đang mở (nút bấm, ô nhập, nhãn...) kèm ảnh chụp có đánh số — Agent hiểu giao diện **không cần mô hình thị giác**.
+- **Quản lý cửa sổ & ứng dụng**: mở app, chuyển/đóng cửa sổ, thay đổi kích thước, nhiều màn hình, virtual desktop, chụp ảnh màn hình từng vùng.
+- **Clipboard, thông báo, hiển thị**: đọc/ghi clipboard, gửi thông báo hệ thống, quản lý màn hình.
+
+### ⚙️ Tự động hóa hệ thống
+- **PowerShell** không giới hạn: chạy lệnh, cài đặt phần mềm, quản trị hệ thống.
+- **FileSystem**: đọc/ghi/liệt kê/di chuyển file & thư mục — đọc và sửa mã nguồn trực tiếp.
+- **Registry & Process**: đọc/sửa registry, liệt kê & dừng tiến trình.
+- **Scrape**: tải và trích xuất nội dung trang web.
+
+### 🌐 Kiểm tra trình duyệt như DevTools (F12) thật
+Bộ công cụ Browser kết nối vào Chrome/Edge/Brave đang mở của bạn qua **CDP (Chrome DevTools Protocol)**:
+- Điều hướng, quản lý tab, snapshot DOM, truy vấn phần tử, highlight trực quan, thực thi JavaScript tùy ý.
+- CSS chuyên sâu: computed styles, **matched rules** (rule nào thắng, từ stylesheet nào), `::before`/`::after`, animation — và **cây Accessibility**.
+- **Network chuyên sâu**: response body, request payload, timing từng pha (DNS/TCP/TLS/TTFB), kích thước truyền, redirect chain, request lỗi, frame WebSocket, chi tiết chứng chỉ TLS.
+- **Application storage**: cookies (kể cả **HttpOnly**), local/session storage, IndexedDB, Cache Storage, Service Workers.
+- **Sources**: liệt kê & đọc nguyên văn source của mọi script/stylesheet.
+
+### 👨‍💻 Lập trình từ xa trên chính máy của bạn
+Kết hợp các nhóm công cụ trên, Agent có thể làm trọn vòng đời của một tác vụ lập trình ngay trên PC của bạn: mở IDE/thư mục dự án → đọc code → sửa file → chạy build/test bằng PowerShell → mở trình duyệt kiểm tra kết quả bằng DevTools → sửa tiếp → `git commit` & `git push` lên GitHub. Bạn chỉ cần ra lệnh và giám sát — từ điện thoại cũng được.
+
+### 🛡️ An toàn & quyền kiểm soát thuộc về bạn
+- **Chỉ báo trực quan luôn bật**: khi AI đang điều khiển, màn hình có **viền phát sáng** + bảng báo ở cạnh trên + quầng sáng quanh con trỏ — không bao giờ điều khiển "lén".
+- **Phím lấy lại quyền**: nhấn **`Ctrl + Alt + Shift + Space`** để giành lại quyền điều khiển ngay lập tức; Agent chỉ tiếp tục khi bạn đã nhàn rỗi đủ lâu.
+- **Chính sách kiểm soát 3 mức** (`relaxed` / `balanced` / `strict`): ở mức strict, *mọi* thao tác đều phải qua cổng kiểm soát và hiện chỉ báo.
+- **Chế độ ưu tiên Agent** (tùy chọn): Agent không bị ngắt bởi di chuột/gõ phím thông thường — chỉ phím tắt trên mới takeover được.
+- **Xác thực bắt buộc**: API key qua header `Authorization: Bearer <token>` hoặc OAuth; chỉ nên phơi endpoint qua mạng riêng (Tailscale/WireGuard) hoặc HTTPS.
+- **Không telemetry mặc định**: mã nguồn không chứa sẵn khóa theo dõi; phân tích sử dụng chỉ bật khi bạn tự đặt biến môi trường `POSTHOG_API_KEY`.
+
+---
+
+## 🚀 Cài đặt (trên máy Windows sẽ bị điều khiển)
+
+**Yêu cầu**: Windows 10/11 · Python 3.14+ · [uv](https://docs.astral.sh/uv/) · Git.
+
+```powershell
+git clone https://github.com/homenewstar/agentic-windows-mcp.git
+cd agentic-windows-mcp
+uv sync
+uv pip install playwright   # cần cho bộ công cụ Browser/DevTools
+```
+
+### Chạy server
+
+**Chế độ HTTP (cho Agent ở xa / qua mạng)** — kèm khóa xác thực:
+
+```powershell
+# Tạo / đổi khóa xác thực (lưu tại ~/.agentic-windows-mcp/)
+uv run agentic-windows-mcp auth
+
+# Khởi động server MCP qua HTTP
+uv run agentic-windows-mcp serve --transport streamable-http --host 0.0.0.0 --port 8000
+# Endpoint: http://<IP-máy-bạn>:8000/mcp
+```
+
+**Chế độ stdio (cho Agent chạy cùng máy**, ví dụ Claude Desktop, Cursor, VS Code): xem cấu hình ở mục kết nối bên dưới — client sẽ tự khởi động server qua `uvx`.
+
+### Tự khởi động cùng Windows
+
+```powershell
+uv run agentic-windows-mcp install   # tạo Scheduled Task "agentic-windows-mcp-server"
+uv run agentic-windows-mcp uninstall # gỡ task và dừng server
+```
+
+### Phơi endpoint ra ngoài an toàn
+
+Đừng mở port trực tiếp ra Internet. Hãy dùng một trong các cách:
+
+- **Tailscale** (khuyên dùng): cài Tailscale trên cả PC và thiết bị của bạn, rồi `tailscale serve --bg --https=443 http://127.0.0.1:8000` — endpoint chỉ xuất hiện trong tailnet riêng của bạn.
+- **WireGuard / VPN** tự host, hoặc reverse proxy HTTPS (Caddy/Nginx) có xác thực.
+
+### Cấu hình
+
+File cấu hình đặt tại `~/.agentic-windows-mcp/config.toml`:
+
+```toml
+[server]
+# host / port / transport mặc định...
+
+[control]
+enabled = true
+policy = "strict"        # relaxed | balanced | strict
+idle_timeout_seconds = 10
+```
+
+---
+
+## 🔌 Kết nối các AI Agent
+
+Nguyên tắc chung: **bất kỳ ứng dụng nào hỗ trợ giao thức MCP (Model Context Protocol) đều kết nối được**, qua stdio (cùng máy) hoặc Streamable HTTP (qua mạng, kèm header `Authorization: Bearer <API_KEY>`).
+
+### Muse (muse.ai) & các agent dạng web/app
+Các agent chạy trên nền web không tự cài phần mềm lên máy bạn — chúng kết nối tới endpoint HTTP của Agentic Windows MCP:
+
+1. Chạy server ở chế độ HTTP như trên và phơi qua Tailscale/HTTPS.
+2. Trong agent, thêm **custom connector / MCP server** với URL `https://<máy-của-bạn>/mcp` và khóa xác thực.
+3. Agent sẽ thấy toàn bộ 40 công cụ và bắt đầu điều khiển được PC của bạn — kể cả việc mở dự án, sửa code và đẩy lên GitHub.
+
+### ChatGPT
+ChatGPT hỗ trợ MCP qua **Developer mode / Connectors**:
+
+1. Settings → Connectors → bật Developer mode → *Create* một connector mới.
+2. Nhập URL MCP (`https://<máy-của-bạn>/mcp`) và khóa API.
+3. Trong cuộc trò chuyện, bật connector và ra lệnh, ví dụ: *"Mở thư mục dự án X trên máy tôi, chạy test và sửa các lỗi đang fail."*
+
+### Claude (Claude Desktop & Claude Code)
+Cùng máy — dùng stdio, Claude tự khởi động server:
+
+```json
+{
+  "mcpServers": {
+    "agentic-windows-mcp": {
+      "command": "uvx",
+      "args": ["agentic-windows-mcp"]
+    }
+  }
+}
+```
+
+Khác máy — trỏ tới endpoint HTTP:
+
+```json
+{
+  "mcpServers": {
+    "agentic-windows-mcp": {
+      "url": "http://<IP-máy-bạn>:8000/mcp",
+      "headers": { "Authorization": "Bearer <API_KEY>" }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add --transport http agentic-windows-mcp http://<IP-máy-bạn>:8000/mcp --header "Authorization: Bearer <API_KEY>"`.
+
+### Gemini
+- **Gemini CLI**: thêm vào `~/.gemini/settings.json` đúng định dạng `mcpServers` như ví dụ của Claude ở trên (stdio hoặc `httpUrl` + `headers`).
+- **Google AI Studio / Gemini API**: dùng MCP client tích hợp trong ứng dụng của bạn và trỏ tới cùng endpoint HTTP.
+
+### DeepSeek & mọi agent khác
+DeepSeek (và các mô hình khác) kết nối được theo hai cách:
+
+- **Qua một MCP host** có sẵn: Cursor, VS Code (Copilot agent mode), Cline, Continue, Windsurf... — chỉ cần thêm khối `mcpServers` ở trên; mô hình phía sau là gì không quan trọng, kể cả DeepSeek.
+- **Qua HTTP trực tiếp**: bất kỳ framework agent nào (LangChain, LlamaIndex, code tự viết...) gọi JSON-RPC tới `POST /mcp` với header xác thực đều dùng được.
+
+### Bảng tra nhanh
+
+| Agent / Client | Cách kết nối | Ghi chú |
+|---|---|---|
+| Muse (web/app) | HTTP connector | Agent ở xa, điều khiển PC qua Tailscale/HTTPS |
+| ChatGPT | HTTP connector (Developer mode) | Cần bật Developer mode |
+| Claude Desktop / Code | stdio hoặc HTTP | stdio khi cùng máy |
+| Gemini CLI | stdio hoặc HTTP | Cấu hình `mcpServers` |
+| DeepSeek | Qua MCP host (Cursor/Cline/VS Code...) | Mô hình thay thế linh hoạt |
+| Cursor / VS Code / Windsurf | stdio hoặc HTTP | Thêm khối `mcpServers` |
+
+---
+
+## 🧰 Bộ công cụ (40 tools)
+
+| Nhóm | Công cụ |
+|---|---|
+| **Điều khiển desktop** | `Click`, `Type`, `Move`, `Scroll`, `Shortcut`, `MultiSelect`, `MultiEdit`, `Snapshot`, `Screenshot`, `Wait`, `WaitFor` |
+| **Ứng dụng & hệ thống** | `App`, `PowerShell`, `FileSystem`, `Registry`, `Process`, `Clipboard`, `Notification`, `DisplayInventory`, `Scrape` |
+| **Cổng kiểm soát** | `ControlStatus` (xem ai đang giữ quyền điều khiển, chính sách đang áp dụng) |
+| **Trình duyệt (CDP)** | `Browser_Connect`, `Browser_Navigate`, `Browser_ManageTabs`, `Browser_GetPageSnapshot`, `Browser_QueryElements`, `Browser_Interact`, `Browser_TakeScreenshot`, `Browser_Highlight`, `Browser_EvaluateScript` |
+| **DevTools chuyên sâu** | `Browser_GetCssStyles`, `Browser_GetComputedStyle`, `Browser_GetMatchedStyles`, `Browser_GetAccessibilityTree`, `Browser_ListConsoleMessages`, `Browser_ListNetworkRequests`, `Browser_GetNetworkDetails`, `Browser_GetStorage`, `Browser_ListPageSources`, `Browser_GetSourceText` |
+
+---
+
+## 💬 Ví dụ ra lệnh cho Agent
+
+- *"Mở dự án `D:\code\shop-web` trên máy tôi, chạy test, sửa hết lỗi đang fail rồi commit và push lên GitHub."*
+- *"Trang chủ web của tôi tải chậm — mở nó trong Chrome, kiểm tra tab Network xem request nào chậm và vì sao."*
+- *"Đọc file Excel báo cáo trong thư mục Downloads, tổng hợp doanh thu theo tháng và lưu thành file mới."*
+- *"Cài đặt Node.js và VS Code lên máy này, cấu hình git với tên và email của tôi."*
+- *"Mở ứng dụng ghi chú, chép nội dung cuộc họp hôm nay từ clipboard vào và lưu lại."*
+
+---
+
+## 🏗️ Kiến trúc
+
+```
+Agent (MCP client)
+   │  JSON-RPC: stdio / Streamable HTTP (+ Bearer auth / OAuth)
+   ▼
+Agentic Windows MCP (FastMCP, Python)
+   ├── Desktop layer .... Win32 API + UI Automation (cây phần tử, ảnh chụp)
+   ├── Control plane .... cổng kiểm soát: viền phát sáng, bảng báo, chính sách
+   │                      relaxed/balanced/strict, phím takeover, hàng đợi lease
+   ├── System layer ..... PowerShell, FileSystem, Registry, Process
+   └── Browser layer .... Playwright + CDP trực tiếp (Network/CSS/DOM/
+                          Accessibility/Debugger/Storage domains)
+   ▼
+Windows 10 / 11
+```
+
+Mã nguồn chính nằm trong `src/agentic_windows_mcp/` (`desktop/`, `browser/`, `tools/`, `infrastructure/`, `filesystem/`, `powershell/`, `registry/`, `uia/`...).
+
+---
+
+## 🤝 Đóng góp
+
+Mọi đóng góp đều được hoan nghênh — mở issue hoặc pull request tại [github.com/homenewstar/agentic-windows-mcp](https://github.com/homenewstar/agentic-windows-mcp). Khi phát triển, chạy kiểm thử bằng `uv run pytest`.
+
+## 📄 Giấy phép
+
+Phát hành theo giấy phép **MIT** — © 2026 **Vu Manh Ruy**. Xem chi tiết trong [LICENSE.md](LICENSE.md).

agentic_windows_mcp-0.8.8/README.md

@@ -0,0 +1,267 @@
+<div align="center">
+
+# Agentic Windows MCP
+
+**Biến mọi AI Agent — dù đang chạy trên web, trên app, hay ở bất cứ đâu — thành đôi tay điều khiển chiếc máy tính Windows của bạn.**
+
+Điều khiển máy tính từ xa toàn diện · Tự động hóa mọi thao tác · Lập trình trực tiếp trên máy của bạn, từ bất cứ nơi nào
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md)
+![Platform](https://img.shields.io/badge/Platform-Windows%2010%20%7C%2011-blue)
+![Python](https://img.shields.io/badge/Python-3.14%2B-yellow)
+![Protocol](https://img.shields.io/badge/Protocol-MCP-purple)
+![Tools](https://img.shields.io/badge/Tools-40-orange)
+
+</div>
+
+---
+
+## 💡 Ý tưởng cốt lõi — Ba trụ cột
+
+Một mình, AI Agent chỉ "nói" được. Một mình, chiếc PC của bạn chỉ "ngồi" đó. **Agentic Windows MCP** là cầu nối khiến cả hai — cộng với GitHub — tạo thành một bộ máy làm việc hoàn chỉnh:
+
+| Trụ cột | Vai trò | Nằm ở đâu? |
+|---|---|---|
+| **1. GitHub** | Kho mã nguồn trung tâm: đồng bộ, lịch sử phiên bản, điểm gặp gỡ của mọi thay đổi | Trên cloud của GitHub |
+| **2. AI Agent** | "Bộ não": Muse, ChatGPT, Claude, Gemini, DeepSeek... phân tích, ra quyết định, viết code, ra lệnh | Web, app điện thoại, máy khác — bất cứ đâu |
+| **3. Máy tính / Server của bạn** | "Đôi tay + nơi làm việc thật": dự án nằm đây, code chạy ở đây, ứng dụng thật mở ở đây — Agentic Windows MCP được cài tại đây để thi hành | PC ở nhà, máy ở công ty, VPS Windows... |
+
+**Ba trụ cột hoàn toàn độc lập về vị trí địa lý**, chỉ kết hợp qua hai đường ống: giao thức **MCP** (Agent ⇄ máy của bạn) và **Git** (máy của bạn ⇄ GitHub). Nhờ vậy:
+
+- Bạn ngồi quán cà phê, mở ChatGPT trên điện thoại → ra lệnh → Agent điều khiển chiếc PC ở nhà: mở dự án, sửa code, chạy test, commit và push lên GitHub. Về đến nhà, mọi thứ đã xong.
+- Hoặc gộp cả ba vào **một máy duy nhất**: Agent chạy app trên chính PC, code nằm trên chính PC — Agentic Windows MCP cho phép Agent tự thao tác như một lập trình viên ngồi trước máy.
+
+```
+                    ┌─────────────────────────────┐
+                    │           GITHUB            │
+                    │  mã nguồn · đồng bộ · bản sao │
+                    └──────────────┬──────────────┘
+                          git push/pull
+                    ┌──────────────▼──────────────┐
+   ┌─────────────┐  │   MÁY TÍNH CỦA BẠN          │      ┌──────────────────┐
+   │  AI AGENT   │  │   ┌───────────────────────┐  │      │  NGƯỜI DÙNG      │
+   │ Muse ·     ├──┼──►│  AGENTIC WINDOWS MCP  │◄─┼──────┤  giám sát · xem  │
+   │ ChatGPT ·   │MCP│   │  40 công cụ điều khiển │  │ nhìn │  viền phát sáng  │
+   │ Claude ·    │◄──┼──┤  chuột · phím · app   │  │ thấy │  · bảng cảnh báo │
+   │ Gemini ·    │  │   │  PowerShell · file    │  │      │  · phím Space*   │
+   │ DeepSeek... │  │   │  DevTools trình duyệt│  │      └──────────────────┘
+   └─────────────┘  │   └───────────────────────┘  │
+   (web / app /     │   Windows 10 / 11          │
+    máy khác)       └─────────────────────────────┘
+                     *phím tắt lấy lại quyền điều khiển:
+                      Ctrl + Alt + Shift + Space
+```
+
+---
+
+## ✨ Chức năng chính
+
+### 🖥️ Điều khiển máy tính toàn diện
+- **Chuột & bàn phím như người thật**: click, double/right-click, kéo–thả theo đường nhiều đoạn, giữ chuột, vuốt/cào, gõ văn bản Unicode, tổ hợp phím tắt, cuộn — kể cả thao tác kéo chính xác từng điểm ảnh.
+- **Đọc màn hình bằng cây UI (UI Automation)**: chụp "Snapshot" toàn bộ cây phần tử của cửa sổ đang mở (nút bấm, ô nhập, nhãn...) kèm ảnh chụp có đánh số — Agent hiểu giao diện **không cần mô hình thị giác**.
+- **Quản lý cửa sổ & ứng dụng**: mở app, chuyển/đóng cửa sổ, thay đổi kích thước, nhiều màn hình, virtual desktop, chụp ảnh màn hình từng vùng.
+- **Clipboard, thông báo, hiển thị**: đọc/ghi clipboard, gửi thông báo hệ thống, quản lý màn hình.
+
+### ⚙️ Tự động hóa hệ thống
+- **PowerShell** không giới hạn: chạy lệnh, cài đặt phần mềm, quản trị hệ thống.
+- **FileSystem**: đọc/ghi/liệt kê/di chuyển file & thư mục — đọc và sửa mã nguồn trực tiếp.
+- **Registry & Process**: đọc/sửa registry, liệt kê & dừng tiến trình.
+- **Scrape**: tải và trích xuất nội dung trang web.
+
+### 🌐 Kiểm tra trình duyệt như DevTools (F12) thật
+Bộ công cụ Browser kết nối vào Chrome/Edge/Brave đang mở của bạn qua **CDP (Chrome DevTools Protocol)**:
+- Điều hướng, quản lý tab, snapshot DOM, truy vấn phần tử, highlight trực quan, thực thi JavaScript tùy ý.
+- CSS chuyên sâu: computed styles, **matched rules** (rule nào thắng, từ stylesheet nào), `::before`/`::after`, animation — và **cây Accessibility**.
+- **Network chuyên sâu**: response body, request payload, timing từng pha (DNS/TCP/TLS/TTFB), kích thước truyền, redirect chain, request lỗi, frame WebSocket, chi tiết chứng chỉ TLS.
+- **Application storage**: cookies (kể cả **HttpOnly**), local/session storage, IndexedDB, Cache Storage, Service Workers.
+- **Sources**: liệt kê & đọc nguyên văn source của mọi script/stylesheet.
+
+### 👨‍💻 Lập trình từ xa trên chính máy của bạn
+Kết hợp các nhóm công cụ trên, Agent có thể làm trọn vòng đời của một tác vụ lập trình ngay trên PC của bạn: mở IDE/thư mục dự án → đọc code → sửa file → chạy build/test bằng PowerShell → mở trình duyệt kiểm tra kết quả bằng DevTools → sửa tiếp → `git commit` & `git push` lên GitHub. Bạn chỉ cần ra lệnh và giám sát — từ điện thoại cũng được.
+
+### 🛡️ An toàn & quyền kiểm soát thuộc về bạn
+- **Chỉ báo trực quan luôn bật**: khi AI đang điều khiển, màn hình có **viền phát sáng** + bảng báo ở cạnh trên + quầng sáng quanh con trỏ — không bao giờ điều khiển "lén".
+- **Phím lấy lại quyền**: nhấn **`Ctrl + Alt + Shift + Space`** để giành lại quyền điều khiển ngay lập tức; Agent chỉ tiếp tục khi bạn đã nhàn rỗi đủ lâu.
+- **Chính sách kiểm soát 3 mức** (`relaxed` / `balanced` / `strict`): ở mức strict, *mọi* thao tác đều phải qua cổng kiểm soát và hiện chỉ báo.
+- **Chế độ ưu tiên Agent** (tùy chọn): Agent không bị ngắt bởi di chuột/gõ phím thông thường — chỉ phím tắt trên mới takeover được.
+- **Xác thực bắt buộc**: API key qua header `Authorization: Bearer <token>` hoặc OAuth; chỉ nên phơi endpoint qua mạng riêng (Tailscale/WireGuard) hoặc HTTPS.
+- **Không telemetry mặc định**: mã nguồn không chứa sẵn khóa theo dõi; phân tích sử dụng chỉ bật khi bạn tự đặt biến môi trường `POSTHOG_API_KEY`.
+
+---
+
+## 🚀 Cài đặt (trên máy Windows sẽ bị điều khiển)
+
+**Yêu cầu**: Windows 10/11 · Python 3.14+ · [uv](https://docs.astral.sh/uv/) · Git.
+
+```powershell
+git clone https://github.com/homenewstar/agentic-windows-mcp.git
+cd agentic-windows-mcp
+uv sync
+uv pip install playwright   # cần cho bộ công cụ Browser/DevTools
+```
+
+### Chạy server
+
+**Chế độ HTTP (cho Agent ở xa / qua mạng)** — kèm khóa xác thực:
+
+```powershell
+# Tạo / đổi khóa xác thực (lưu tại ~/.agentic-windows-mcp/)
+uv run agentic-windows-mcp auth
+
+# Khởi động server MCP qua HTTP
+uv run agentic-windows-mcp serve --transport streamable-http --host 0.0.0.0 --port 8000
+# Endpoint: http://<IP-máy-bạn>:8000/mcp
+```
+
+**Chế độ stdio (cho Agent chạy cùng máy**, ví dụ Claude Desktop, Cursor, VS Code): xem cấu hình ở mục kết nối bên dưới — client sẽ tự khởi động server qua `uvx`.
+
+### Tự khởi động cùng Windows
+
+```powershell
+uv run agentic-windows-mcp install   # tạo Scheduled Task "agentic-windows-mcp-server"
+uv run agentic-windows-mcp uninstall # gỡ task và dừng server
+```
+
+### Phơi endpoint ra ngoài an toàn
+
+Đừng mở port trực tiếp ra Internet. Hãy dùng một trong các cách:
+
+- **Tailscale** (khuyên dùng): cài Tailscale trên cả PC và thiết bị của bạn, rồi `tailscale serve --bg --https=443 http://127.0.0.1:8000` — endpoint chỉ xuất hiện trong tailnet riêng của bạn.
+- **WireGuard / VPN** tự host, hoặc reverse proxy HTTPS (Caddy/Nginx) có xác thực.
+
+### Cấu hình
+
+File cấu hình đặt tại `~/.agentic-windows-mcp/config.toml`:
+
+```toml
+[server]
+# host / port / transport mặc định...
+
+[control]
+enabled = true
+policy = "strict"        # relaxed | balanced | strict
+idle_timeout_seconds = 10
+```
+
+---
+
+## 🔌 Kết nối các AI Agent
+
+Nguyên tắc chung: **bất kỳ ứng dụng nào hỗ trợ giao thức MCP (Model Context Protocol) đều kết nối được**, qua stdio (cùng máy) hoặc Streamable HTTP (qua mạng, kèm header `Authorization: Bearer <API_KEY>`).
+
+### Muse (muse.ai) & các agent dạng web/app
+Các agent chạy trên nền web không tự cài phần mềm lên máy bạn — chúng kết nối tới endpoint HTTP của Agentic Windows MCP:
+
+1. Chạy server ở chế độ HTTP như trên và phơi qua Tailscale/HTTPS.
+2. Trong agent, thêm **custom connector / MCP server** với URL `https://<máy-của-bạn>/mcp` và khóa xác thực.
+3. Agent sẽ thấy toàn bộ 40 công cụ và bắt đầu điều khiển được PC của bạn — kể cả việc mở dự án, sửa code và đẩy lên GitHub.
+
+### ChatGPT
+ChatGPT hỗ trợ MCP qua **Developer mode / Connectors**:
+
+1. Settings → Connectors → bật Developer mode → *Create* một connector mới.
+2. Nhập URL MCP (`https://<máy-của-bạn>/mcp`) và khóa API.
+3. Trong cuộc trò chuyện, bật connector và ra lệnh, ví dụ: *"Mở thư mục dự án X trên máy tôi, chạy test và sửa các lỗi đang fail."*
+
+### Claude (Claude Desktop & Claude Code)
+Cùng máy — dùng stdio, Claude tự khởi động server:
+
+```json
+{
+  "mcpServers": {
+    "agentic-windows-mcp": {
+      "command": "uvx",
+      "args": ["agentic-windows-mcp"]
+    }
+  }
+}
+```
+
+Khác máy — trỏ tới endpoint HTTP:
+
+```json
+{
+  "mcpServers": {
+    "agentic-windows-mcp": {
+      "url": "http://<IP-máy-bạn>:8000/mcp",
+      "headers": { "Authorization": "Bearer <API_KEY>" }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add --transport http agentic-windows-mcp http://<IP-máy-bạn>:8000/mcp --header "Authorization: Bearer <API_KEY>"`.
+
+### Gemini
+- **Gemini CLI**: thêm vào `~/.gemini/settings.json` đúng định dạng `mcpServers` như ví dụ của Claude ở trên (stdio hoặc `httpUrl` + `headers`).
+- **Google AI Studio / Gemini API**: dùng MCP client tích hợp trong ứng dụng của bạn và trỏ tới cùng endpoint HTTP.
+
+### DeepSeek & mọi agent khác
+DeepSeek (và các mô hình khác) kết nối được theo hai cách:
+
+- **Qua một MCP host** có sẵn: Cursor, VS Code (Copilot agent mode), Cline, Continue, Windsurf... — chỉ cần thêm khối `mcpServers` ở trên; mô hình phía sau là gì không quan trọng, kể cả DeepSeek.
+- **Qua HTTP trực tiếp**: bất kỳ framework agent nào (LangChain, LlamaIndex, code tự viết...) gọi JSON-RPC tới `POST /mcp` với header xác thực đều dùng được.
+
+### Bảng tra nhanh
+
+| Agent / Client | Cách kết nối | Ghi chú |
+|---|---|---|
+| Muse (web/app) | HTTP connector | Agent ở xa, điều khiển PC qua Tailscale/HTTPS |
+| ChatGPT | HTTP connector (Developer mode) | Cần bật Developer mode |
+| Claude Desktop / Code | stdio hoặc HTTP | stdio khi cùng máy |
+| Gemini CLI | stdio hoặc HTTP | Cấu hình `mcpServers` |
+| DeepSeek | Qua MCP host (Cursor/Cline/VS Code...) | Mô hình thay thế linh hoạt |
+| Cursor / VS Code / Windsurf | stdio hoặc HTTP | Thêm khối `mcpServers` |
+
+---
+
+## 🧰 Bộ công cụ (40 tools)
+
+| Nhóm | Công cụ |
+|---|---|
+| **Điều khiển desktop** | `Click`, `Type`, `Move`, `Scroll`, `Shortcut`, `MultiSelect`, `MultiEdit`, `Snapshot`, `Screenshot`, `Wait`, `WaitFor` |
+| **Ứng dụng & hệ thống** | `App`, `PowerShell`, `FileSystem`, `Registry`, `Process`, `Clipboard`, `Notification`, `DisplayInventory`, `Scrape` |
+| **Cổng kiểm soát** | `ControlStatus` (xem ai đang giữ quyền điều khiển, chính sách đang áp dụng) |
+| **Trình duyệt (CDP)** | `Browser_Connect`, `Browser_Navigate`, `Browser_ManageTabs`, `Browser_GetPageSnapshot`, `Browser_QueryElements`, `Browser_Interact`, `Browser_TakeScreenshot`, `Browser_Highlight`, `Browser_EvaluateScript` |
+| **DevTools chuyên sâu** | `Browser_GetCssStyles`, `Browser_GetComputedStyle`, `Browser_GetMatchedStyles`, `Browser_GetAccessibilityTree`, `Browser_ListConsoleMessages`, `Browser_ListNetworkRequests`, `Browser_GetNetworkDetails`, `Browser_GetStorage`, `Browser_ListPageSources`, `Browser_GetSourceText` |
+
+---
+
+## 💬 Ví dụ ra lệnh cho Agent
+
+- *"Mở dự án `D:\code\shop-web` trên máy tôi, chạy test, sửa hết lỗi đang fail rồi commit và push lên GitHub."*
+- *"Trang chủ web của tôi tải chậm — mở nó trong Chrome, kiểm tra tab Network xem request nào chậm và vì sao."*
+- *"Đọc file Excel báo cáo trong thư mục Downloads, tổng hợp doanh thu theo tháng và lưu thành file mới."*
+- *"Cài đặt Node.js và VS Code lên máy này, cấu hình git với tên và email của tôi."*
+- *"Mở ứng dụng ghi chú, chép nội dung cuộc họp hôm nay từ clipboard vào và lưu lại."*
+
+---
+
+## 🏗️ Kiến trúc
+
+```
+Agent (MCP client)
+   │  JSON-RPC: stdio / Streamable HTTP (+ Bearer auth / OAuth)
+   ▼
+Agentic Windows MCP (FastMCP, Python)
+   ├── Desktop layer .... Win32 API + UI Automation (cây phần tử, ảnh chụp)
+   ├── Control plane .... cổng kiểm soát: viền phát sáng, bảng báo, chính sách
+   │                      relaxed/balanced/strict, phím takeover, hàng đợi lease
+   ├── System layer ..... PowerShell, FileSystem, Registry, Process
+   └── Browser layer .... Playwright + CDP trực tiếp (Network/CSS/DOM/
+                          Accessibility/Debugger/Storage domains)
+   ▼
+Windows 10 / 11
+```
+
+Mã nguồn chính nằm trong `src/agentic_windows_mcp/` (`desktop/`, `browser/`, `tools/`, `infrastructure/`, `filesystem/`, `powershell/`, `registry/`, `uia/`...).
+
+---
+
+## 🤝 Đóng góp
+
+Mọi đóng góp đều được hoan nghênh — mở issue hoặc pull request tại [github.com/homenewstar/agentic-windows-mcp](https://github.com/homenewstar/agentic-windows-mcp). Khi phát triển, chạy kiểm thử bằng `uv run pytest`.
+
+## 📄 Giấy phép
+
+Phát hành theo giấy phép **MIT** — © 2026 **Vu Manh Ruy**. Xem chi tiết trong [LICENSE.md](LICENSE.md).