astrax-mcp 0.2.0__tar.gz

astrax_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astrax
+
+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.

astrax_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.5
+Name: astrax-mcp
+Version: 0.2.0
+Summary: Agentic System Telemetry, Realtime Automation & X-control: servidor MCP que da ojos y manos a tu IA
+Project-URL: Homepage, https://github.com/AstraxOf/astrax-mcp
+Project-URL: Telegram, https://t.me/AstraxMCP
+Project-URL: YouTube, https://youtube.com/@AstraxOf
+License-File: LICENSE
+Keywords: ai-agents,automation,computer-use,mcp,model-context-protocol,pyautogui
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]<2,>=1.2.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pyautogui>=0.9.54
+Requires-Dist: pyperclip>=1.8.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🛰️ Astrax
+
+### **A.S.T.R.A.X.** — *Agentic System Telemetry, Realtime Automation & X-control*
+
+Servidor **MCP (Model Context Protocol)** en Python que le da a tu IA **ojos y manos** sobre tu pantalla: ver, hacer clic, escribir y ejecutar tareas de varios pasos **sin saturar el contexto**.
+
+Compatible con **Claude Desktop, Roo Code, Cline, Cursor, Windsurf, Gemini CLI, OpenCode** y cualquier cliente MCP con transporte `stdio`. Funciona con modelos locales (Ollama) y APIs comerciales (Claude, Gemini…).
+
+📺 **Tutorial en YouTube:** [@AstraxOf](https://youtube.com/@AstraxOf)
+💬 **Contacto en Telegram:** [@RufusOficial](https://t.me/RufusOficial)
+
+---
+
+## ⚡ Instalación a 1 clic
+
+Necesitas [`uv`](https://docs.astral.sh/uv/) (instala Python y dependencias solo):
+
+```bash
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+# Windows (PowerShell)
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Después, **un solo comando** detecta tu sistema operativo y tus clientes MCP, y registra Astrax en ellos:
+
+```bash
+uvx --from git+https://github.com/AstraxOf/astrax-mcp.git astrax-install --yes
+```
+
+Reinicia tu cliente (en Claude Desktop, ciérralo por completo) y listo.
+
+> Cuando el paquete esté publicado en PyPI bastará `uvx astrax-mcp` para ejecutar el servidor y `uvx --from astrax-mcp astrax-install --yes` para instalarlo.
+
+### 🤖 Instrucción para IAs (agentes con acceso a terminal)
+
+Si eres una IA y el usuario te pide instalar Astrax, ejecuta exactamente esto y pídele que reinicie su cliente MCP. **No edites archivos JSON a mano.**
+
+```bash
+uvx --from git+https://github.com/AstraxOf/astrax-mcp.git astrax-install --yes
+```
+
+Variantes útiles:
+
+| Comando | Qué hace |
+|---|---|
+| `astrax-install --list` | Muestra clientes detectados y si Astrax ya está instalado |
+| `astrax-install --client claude-desktop` | Instala solo en un cliente (repetible). IDs: `claude-desktop`, `roo-code`, `cline`, `cursor`, `windsurf`, `gemini-cli` |
+| `astrax-install --auto-approve` | Roo Code / Cline: añade `alwaysAllow` a todas las herramientas **excepto** `astrax_tarea_autorizar` (ver [Permisos](#-permisos-una-sola-autorización-por-tarea)) |
+| `astrax-install --dry-run` | Muestra qué haría sin escribir nada |
+| `astrax-install --uninstall` | Elimina solo la entrada `astrax` |
+| `astrax-install --source local` | Usa el Python actual en vez de `uvx` |
+
+El instalador **solo toca la clave `astrax`** dentro de `mcpServers`: conserva tus otros servidores, crea una copia `.astrax-bak-<fecha>` antes de escribir, guarda de forma atómica y **no modifica archivos con JSON inválido**.
+
+**Claude Code:** `claude mcp add astrax -- uvx --from git+https://github.com/AstraxOf/astrax-mcp.git astrax-mcp`
+
+<details>
+<summary>Instalación desde un clon del repositorio</summary>
+
+```bash
+git clone https://github.com/AstraxOf/astrax-mcp.git
+cd astrax-mcp
+python install.py          # asistente interactivo (equivale a astrax-install)
+```
+
+</details>
+
+---
+
+## 🧠 Motor paso a paso por estado temporal
+
+Los modelos ligeros (Ollama) se saturan y alucinan cuando el contexto crece con historial y capturas de pantalla viejas. Astrax lo evita **aislando el contexto en un archivo de estado local**: `.astrax_task_state.json`.
+
+1. **Desglose.** Ante una petición compleja (*"Redacta una carta para X con mis datos, prepárala y envíala a tal correo"*), la IA llama a `astrax_tarea_crear` y guarda el plan como pasos ordenados.
+2. **Lectura directa.** Para cada paso, la IA llama a `astrax_tarea_estado`: recibe solo el **paso actual, el siguiente y los datos guardados** (un JSON de unas pocas líneas) en lugar de releer toda la conversación, el prompt inicial o capturas pasadas.
+3. **Caché de salidas.** Al cerrar un paso con `astrax_tarea_completar_paso`, la IA guarda lo relevante, por ejemplo `{"pdf_generado": "/rutas/carta.pdf"}`. El paso siguiente (adjuntar al correo) consulta solo ese dato y usa la ruta exacta, sin adivinarla.
+4. **Cierre.** Al terminar el último paso la tarea queda `completada`, los permisos se **revocan** y se borran las capturas temporales. `astrax_tarea_limpiar` elimina el archivo.
+
+Detalles que protegen al modelo:
+
+- **Guarda rutas, no contenidos:** cada dato admite hasta 4000 caracteres; si es más, la herramienta pide guardarlo en un archivo y almacenar la ruta.
+- **Anti-bucles:** un paso que falla 3 veces pasa a `bloqueada` y la IA debe parar y explicar al usuario qué ocurrió.
+- **Sin imágenes pesadas en el historial:** las acciones devuelven texto corto; solo `astrax_ver_pantalla` devuelve imagen, cuando hace falta verificar.
+- **Ubicación:** carpeta privada del usuario (`~/.cache/astrax`, `~/Library/Caches/astrax` o `%LOCALAPPDATA%\astrax`), con permisos restringidos. Cámbiala con `ASTRAX_HOME`.
+
+---
+
+## 🔐 Permisos: una sola autorización por tarea
+
+Antes de ejecutar nada, la IA declara **todo lo que necesitará la tarea completa** en `astrax_tarea_crear`:
+
+| Permiso | Habilita |
+|---|---|
+| `pantalla` | `astrax_ver_pantalla`, `astrax_capturar_pantalla` |
+| `raton_teclado` | clic, doble clic, teclas, atajos, scroll, escribir |
+| `portapapeles` | `astrax_portapapeles` y escritura de texto no ASCII (ñ, tildes, emojis) |
+| `terminal` | `astrax_ejecutar_comando` |
+
+Después muestra el plan y los permisos, **pide tu confirmación una sola vez** y llama a `astrax_tarea_autorizar`. Desde ese momento puede trabajar de forma desatendida durante la sesión (60 min por defecto, `ASTRAX_SESSION_MINUTES`). Las herramientas de acción **rechazan** cualquier uso fuera de una tarea autorizada o de un permiso no solicitado.
+
+**Cómo evitar las confirmaciones por paso en tu cliente:** el servidor no puede saltarse las confirmaciones que muestra el cliente. Por eso `astrax-install --auto-approve` (Roo Code / Cline) marca como "permitir siempre" todas las herramientas *excepto* `astrax_tarea_autorizar`: tu cliente te pregunta **una vez**, justo en la autorización, y no durante la ejecución. En otros clientes (p. ej. Claude Desktop) elige "Permitir siempre" en esa herramienta o en el resto cuando te lo pida.
+
+Para volver al comportamiento anterior sin tareas ni sesiones: `ASTRAX_REQUIRE_SESSION=0`.
+
+---
+
+## ✨ ¿Qué puede hacer?
+
+| Herramienta | Descripción |
+|---|---|
+| `astrax_tarea_crear` | Guarda el plan por pasos y los permisos que necesita la tarea completa |
+| `astrax_tarea_autorizar` | Concede los permisos tras la confirmación del usuario |
+| `astrax_tarea_estado` | Lee el paso actual, el siguiente y los datos guardados |
+| `astrax_tarea_guardar` | Guarda un dato clave (rutas, ids…) |
+| `astrax_tarea_completar_paso` | Cierra el paso, guarda salidas y devuelve el siguiente |
+| `astrax_tarea_limpiar` | Borra el estado y las capturas temporales |
+| `astrax_ver_pantalla` | **La IA ve la pantalla**: captura como imagen (marca roja en el cursor) |
+| `astrax_capturar_pantalla` | Guarda un PNG y devuelve la ruta |
+| `astrax_info_pantalla` | Ancho y alto de la pantalla |
+| `astrax_clic` / `astrax_doble_clic` | Clic en `(x, y)` con validación de límites |
+| `astrax_escribir` | Teclea texto (soporta `ñ`, tildes y emojis vía portapapeles) |
+| `astrax_tecla` / `astrax_atajo` | Teclas sueltas y atajos (`["ctrl", "t"]`…) |
+| `astrax_scroll` | Rueda del ratón arriba/abajo |
+| `astrax_esperar` | Espera a que cargue una app o página |
+| `astrax_portapapeles` | Lee o escribe el portapapeles |
+| `astrax_ejecutar_comando` | Ejecuta un comando de shell con timeout y salida recortada |
+
+Ejemplo de prompt:
+
+> *"Usa Astrax: redacta una carta para Ana con mis datos, guárdala como PDF y envíala a ana@ejemplo.com con el asunto 'Propuesta'."*
+
+---
+
+## ⚙️ Configuración manual
+
+Si prefieres no usar el instalador, añade esto a tu `mcp_settings.json` (o al archivo equivalente de tu cliente):
+
+```json
+{
+  "mcpServers": {
+    "astrax": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/AstraxOf/astrax-mcp.git", "astrax-mcp"]
+    }
+  }
+}
+```
+
+> En clientes de escritorio que no heredan tu `PATH`, usa la ruta absoluta de `uvx` (`which uvx` / `where uvx`). El instalador ya lo hace por ti.
+
+---
+
+## 🛡️ Seguridad
+
+Astrax controla tu ratón, teclado y (si lo autorizas) tu terminal reales. Úsalo con cabeza:
+
+- **Fail-safe activo:** mueve el ratón a una esquina de la pantalla para abortar cualquier automatización.
+- **Permisos mínimos:** la IA solo recibe los permisos que declara y que tú confirmas; se revocan al terminar o al bloquearse la tarea.
+- Los clics fuera de los límites de la pantalla se rechazan.
+- `astrax_ejecutar_comando` bloquea patrones destructivos obvios (`rm -rf /`, `mkfs`, `format C:`, `shutdown`…). **Es una red de seguridad contra accidentes, no un sandbox.** Concede `terminal` solo si confías en la tarea y la supervisas.
+- Evita ejecutarlo mientras tengas abiertos datos sensibles (contraseñas, banca, etc.).
+
+---
+
+## 🖥️ Notas por sistema operativo
+
+- **Windows:** funciona sin configuración extra.
+- **macOS:** concede permisos de *Grabación de pantalla* y *Accesibilidad* a tu terminal o editor.
+- **Linux:** funciona en X11 (Wayland suele bloquear captura y control). Puede hacer falta `sudo apt install python3-tk python3-dev scrot xclip`.
+
+---
+
+## 🧩 Arquitectura
+
+```
+astrax-mcp/
+├── pyproject.toml          # entry points: astrax-mcp, astrax-install
+├── install.py              # atajo para quien clona el repo
+├── mcp_settings.json       # ejemplo (Roo Code / Cline)
+├── tests/
+└── src/astrax_mcp/
+    ├── server.py           # construye el servidor y registra los módulos
+    ├── config.py           # constantes, rutas y variables ASTRAX_*
+    ├── state.py            # motor del archivo de estado de tareas (sin dependencias de MCP)
+    ├── tasks.py            # herramientas MCP del gestor de tareas
+    ├── permissions.py      # verificación de permisos de sesión
+    ├── vision.py           # captura y visión de pantalla
+    ├── control.py          # ratón, teclado, scroll, esperas
+    ├── system.py           # terminal y portapapeles
+    ├── gui.py              # acceso perezoso a pyautogui + validaciones
+    ├── utils.py            # log a stderr, errores uniformes, truncado
+    ├── compat.py           # SDK MCP v1 (FastMCP) / v2 (MCPServer)
+    └── installer.py        # wizard de instalación multiplataforma
+```
+
+- Basado en el SDK oficial de MCP para Python. `compat.py` usa `MCPServer` (v2) y recurre a `FastMCP` (v1.x); `pyproject.toml` fija `mcp<2` como en la configuración original: quita el tope cuando pruebes el SDK v2.
+- Transporte `stdio`; todos los logs van a `stderr` para no corromper el flujo JSON-RPC.
+- Las capturas se normalizan al tamaño lógico de pantalla: las coordenadas de la imagen coinciden con las del clic, incluso en HiDPI/Retina. La calidad JPEG se ajusta con `ASTRAX_JPEG_QUALITY` (30-95, por defecto 65).
+- Tests: `pip install -e ".[dev]" && pytest`
+
+---
+
+## 🤝 Contribuciones / Community
+
+Astrax es **Open Source** y crece con la comunidad. Si quieres sumarte, eres bienvenido: puedes abrir *issues*, enviar *pull requests*, proponer ideas, probar Astrax en otros sistemas o clientes MCP y reportar errores.
+
+- 📧 **Correo de contacto:** [avpn497@gmail.com](mailto:avpn497@gmail.com)
+- 📢 **Canal oficial de Telegram:** [https://t.me/AstraxMCP](https://t.me/AstraxMCP) — únete al canal para aportar, hacer preguntas o reportar problemas.
+- 📺 **YouTube:** [@AstraxOf](https://youtube.com/@AstraxOf) — tutoriales y novedades
+- 💬 **Creador en Telegram:** [@RufusOficial](https://t.me/RufusOficial)
+
+Si te sirvió el proyecto, deja una ⭐ en el repositorio y suscríbete al canal.
+
+---
+
+<p align="center">Hecho con 💙 por <b>Rufus</b> · <a href="https://youtube.com/@AstraxOf">@AstraxOf</a></p>

astrax_mcp-0.2.0/README.md

@@ -0,0 +1,217 @@
+# 🛰️ Astrax
+
+### **A.S.T.R.A.X.** — *Agentic System Telemetry, Realtime Automation & X-control*
+
+Servidor **MCP (Model Context Protocol)** en Python que le da a tu IA **ojos y manos** sobre tu pantalla: ver, hacer clic, escribir y ejecutar tareas de varios pasos **sin saturar el contexto**.
+
+Compatible con **Claude Desktop, Roo Code, Cline, Cursor, Windsurf, Gemini CLI, OpenCode** y cualquier cliente MCP con transporte `stdio`. Funciona con modelos locales (Ollama) y APIs comerciales (Claude, Gemini…).
+
+📺 **Tutorial en YouTube:** [@AstraxOf](https://youtube.com/@AstraxOf)
+💬 **Contacto en Telegram:** [@RufusOficial](https://t.me/RufusOficial)
+
+---
+
+## ⚡ Instalación a 1 clic
+
+Necesitas [`uv`](https://docs.astral.sh/uv/) (instala Python y dependencias solo):
+
+```bash
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+# Windows (PowerShell)
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Después, **un solo comando** detecta tu sistema operativo y tus clientes MCP, y registra Astrax en ellos:
+
+```bash
+uvx --from git+https://github.com/AstraxOf/astrax-mcp.git astrax-install --yes
+```
+
+Reinicia tu cliente (en Claude Desktop, ciérralo por completo) y listo.
+
+> Cuando el paquete esté publicado en PyPI bastará `uvx astrax-mcp` para ejecutar el servidor y `uvx --from astrax-mcp astrax-install --yes` para instalarlo.
+
+### 🤖 Instrucción para IAs (agentes con acceso a terminal)
+
+Si eres una IA y el usuario te pide instalar Astrax, ejecuta exactamente esto y pídele que reinicie su cliente MCP. **No edites archivos JSON a mano.**
+
+```bash
+uvx --from git+https://github.com/AstraxOf/astrax-mcp.git astrax-install --yes
+```
+
+Variantes útiles:
+
+| Comando | Qué hace |
+|---|---|
+| `astrax-install --list` | Muestra clientes detectados y si Astrax ya está instalado |
+| `astrax-install --client claude-desktop` | Instala solo en un cliente (repetible). IDs: `claude-desktop`, `roo-code`, `cline`, `cursor`, `windsurf`, `gemini-cli` |
+| `astrax-install --auto-approve` | Roo Code / Cline: añade `alwaysAllow` a todas las herramientas **excepto** `astrax_tarea_autorizar` (ver [Permisos](#-permisos-una-sola-autorización-por-tarea)) |
+| `astrax-install --dry-run` | Muestra qué haría sin escribir nada |
+| `astrax-install --uninstall` | Elimina solo la entrada `astrax` |
+| `astrax-install --source local` | Usa el Python actual en vez de `uvx` |
+
+El instalador **solo toca la clave `astrax`** dentro de `mcpServers`: conserva tus otros servidores, crea una copia `.astrax-bak-<fecha>` antes de escribir, guarda de forma atómica y **no modifica archivos con JSON inválido**.
+
+**Claude Code:** `claude mcp add astrax -- uvx --from git+https://github.com/AstraxOf/astrax-mcp.git astrax-mcp`
+
+<details>
+<summary>Instalación desde un clon del repositorio</summary>
+
+```bash
+git clone https://github.com/AstraxOf/astrax-mcp.git
+cd astrax-mcp
+python install.py          # asistente interactivo (equivale a astrax-install)
+```
+
+</details>
+
+---
+
+## 🧠 Motor paso a paso por estado temporal
+
+Los modelos ligeros (Ollama) se saturan y alucinan cuando el contexto crece con historial y capturas de pantalla viejas. Astrax lo evita **aislando el contexto en un archivo de estado local**: `.astrax_task_state.json`.
+
+1. **Desglose.** Ante una petición compleja (*"Redacta una carta para X con mis datos, prepárala y envíala a tal correo"*), la IA llama a `astrax_tarea_crear` y guarda el plan como pasos ordenados.
+2. **Lectura directa.** Para cada paso, la IA llama a `astrax_tarea_estado`: recibe solo el **paso actual, el siguiente y los datos guardados** (un JSON de unas pocas líneas) en lugar de releer toda la conversación, el prompt inicial o capturas pasadas.
+3. **Caché de salidas.** Al cerrar un paso con `astrax_tarea_completar_paso`, la IA guarda lo relevante, por ejemplo `{"pdf_generado": "/rutas/carta.pdf"}`. El paso siguiente (adjuntar al correo) consulta solo ese dato y usa la ruta exacta, sin adivinarla.
+4. **Cierre.** Al terminar el último paso la tarea queda `completada`, los permisos se **revocan** y se borran las capturas temporales. `astrax_tarea_limpiar` elimina el archivo.
+
+Detalles que protegen al modelo:
+
+- **Guarda rutas, no contenidos:** cada dato admite hasta 4000 caracteres; si es más, la herramienta pide guardarlo en un archivo y almacenar la ruta.
+- **Anti-bucles:** un paso que falla 3 veces pasa a `bloqueada` y la IA debe parar y explicar al usuario qué ocurrió.
+- **Sin imágenes pesadas en el historial:** las acciones devuelven texto corto; solo `astrax_ver_pantalla` devuelve imagen, cuando hace falta verificar.
+- **Ubicación:** carpeta privada del usuario (`~/.cache/astrax`, `~/Library/Caches/astrax` o `%LOCALAPPDATA%\astrax`), con permisos restringidos. Cámbiala con `ASTRAX_HOME`.
+
+---
+
+## 🔐 Permisos: una sola autorización por tarea
+
+Antes de ejecutar nada, la IA declara **todo lo que necesitará la tarea completa** en `astrax_tarea_crear`:
+
+| Permiso | Habilita |
+|---|---|
+| `pantalla` | `astrax_ver_pantalla`, `astrax_capturar_pantalla` |
+| `raton_teclado` | clic, doble clic, teclas, atajos, scroll, escribir |
+| `portapapeles` | `astrax_portapapeles` y escritura de texto no ASCII (ñ, tildes, emojis) |
+| `terminal` | `astrax_ejecutar_comando` |
+
+Después muestra el plan y los permisos, **pide tu confirmación una sola vez** y llama a `astrax_tarea_autorizar`. Desde ese momento puede trabajar de forma desatendida durante la sesión (60 min por defecto, `ASTRAX_SESSION_MINUTES`). Las herramientas de acción **rechazan** cualquier uso fuera de una tarea autorizada o de un permiso no solicitado.
+
+**Cómo evitar las confirmaciones por paso en tu cliente:** el servidor no puede saltarse las confirmaciones que muestra el cliente. Por eso `astrax-install --auto-approve` (Roo Code / Cline) marca como "permitir siempre" todas las herramientas *excepto* `astrax_tarea_autorizar`: tu cliente te pregunta **una vez**, justo en la autorización, y no durante la ejecución. En otros clientes (p. ej. Claude Desktop) elige "Permitir siempre" en esa herramienta o en el resto cuando te lo pida.
+
+Para volver al comportamiento anterior sin tareas ni sesiones: `ASTRAX_REQUIRE_SESSION=0`.
+
+---
+
+## ✨ ¿Qué puede hacer?
+
+| Herramienta | Descripción |
+|---|---|
+| `astrax_tarea_crear` | Guarda el plan por pasos y los permisos que necesita la tarea completa |
+| `astrax_tarea_autorizar` | Concede los permisos tras la confirmación del usuario |
+| `astrax_tarea_estado` | Lee el paso actual, el siguiente y los datos guardados |
+| `astrax_tarea_guardar` | Guarda un dato clave (rutas, ids…) |
+| `astrax_tarea_completar_paso` | Cierra el paso, guarda salidas y devuelve el siguiente |
+| `astrax_tarea_limpiar` | Borra el estado y las capturas temporales |
+| `astrax_ver_pantalla` | **La IA ve la pantalla**: captura como imagen (marca roja en el cursor) |
+| `astrax_capturar_pantalla` | Guarda un PNG y devuelve la ruta |
+| `astrax_info_pantalla` | Ancho y alto de la pantalla |
+| `astrax_clic` / `astrax_doble_clic` | Clic en `(x, y)` con validación de límites |
+| `astrax_escribir` | Teclea texto (soporta `ñ`, tildes y emojis vía portapapeles) |
+| `astrax_tecla` / `astrax_atajo` | Teclas sueltas y atajos (`["ctrl", "t"]`…) |
+| `astrax_scroll` | Rueda del ratón arriba/abajo |
+| `astrax_esperar` | Espera a que cargue una app o página |
+| `astrax_portapapeles` | Lee o escribe el portapapeles |
+| `astrax_ejecutar_comando` | Ejecuta un comando de shell con timeout y salida recortada |
+
+Ejemplo de prompt:
+
+> *"Usa Astrax: redacta una carta para Ana con mis datos, guárdala como PDF y envíala a ana@ejemplo.com con el asunto 'Propuesta'."*
+
+---
+
+## ⚙️ Configuración manual
+
+Si prefieres no usar el instalador, añade esto a tu `mcp_settings.json` (o al archivo equivalente de tu cliente):
+
+```json
+{
+  "mcpServers": {
+    "astrax": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/AstraxOf/astrax-mcp.git", "astrax-mcp"]
+    }
+  }
+}
+```
+
+> En clientes de escritorio que no heredan tu `PATH`, usa la ruta absoluta de `uvx` (`which uvx` / `where uvx`). El instalador ya lo hace por ti.
+
+---
+
+## 🛡️ Seguridad
+
+Astrax controla tu ratón, teclado y (si lo autorizas) tu terminal reales. Úsalo con cabeza:
+
+- **Fail-safe activo:** mueve el ratón a una esquina de la pantalla para abortar cualquier automatización.
+- **Permisos mínimos:** la IA solo recibe los permisos que declara y que tú confirmas; se revocan al terminar o al bloquearse la tarea.
+- Los clics fuera de los límites de la pantalla se rechazan.
+- `astrax_ejecutar_comando` bloquea patrones destructivos obvios (`rm -rf /`, `mkfs`, `format C:`, `shutdown`…). **Es una red de seguridad contra accidentes, no un sandbox.** Concede `terminal` solo si confías en la tarea y la supervisas.
+- Evita ejecutarlo mientras tengas abiertos datos sensibles (contraseñas, banca, etc.).
+
+---
+
+## 🖥️ Notas por sistema operativo
+
+- **Windows:** funciona sin configuración extra.
+- **macOS:** concede permisos de *Grabación de pantalla* y *Accesibilidad* a tu terminal o editor.
+- **Linux:** funciona en X11 (Wayland suele bloquear captura y control). Puede hacer falta `sudo apt install python3-tk python3-dev scrot xclip`.
+
+---
+
+## 🧩 Arquitectura
+
+```
+astrax-mcp/
+├── pyproject.toml          # entry points: astrax-mcp, astrax-install
+├── install.py              # atajo para quien clona el repo
+├── mcp_settings.json       # ejemplo (Roo Code / Cline)
+├── tests/
+└── src/astrax_mcp/
+    ├── server.py           # construye el servidor y registra los módulos
+    ├── config.py           # constantes, rutas y variables ASTRAX_*
+    ├── state.py            # motor del archivo de estado de tareas (sin dependencias de MCP)
+    ├── tasks.py            # herramientas MCP del gestor de tareas
+    ├── permissions.py      # verificación de permisos de sesión
+    ├── vision.py           # captura y visión de pantalla
+    ├── control.py          # ratón, teclado, scroll, esperas
+    ├── system.py           # terminal y portapapeles
+    ├── gui.py              # acceso perezoso a pyautogui + validaciones
+    ├── utils.py            # log a stderr, errores uniformes, truncado
+    ├── compat.py           # SDK MCP v1 (FastMCP) / v2 (MCPServer)
+    └── installer.py        # wizard de instalación multiplataforma
+```
+
+- Basado en el SDK oficial de MCP para Python. `compat.py` usa `MCPServer` (v2) y recurre a `FastMCP` (v1.x); `pyproject.toml` fija `mcp<2` como en la configuración original: quita el tope cuando pruebes el SDK v2.
+- Transporte `stdio`; todos los logs van a `stderr` para no corromper el flujo JSON-RPC.
+- Las capturas se normalizan al tamaño lógico de pantalla: las coordenadas de la imagen coinciden con las del clic, incluso en HiDPI/Retina. La calidad JPEG se ajusta con `ASTRAX_JPEG_QUALITY` (30-95, por defecto 65).
+- Tests: `pip install -e ".[dev]" && pytest`
+
+---
+
+## 🤝 Contribuciones / Community
+
+Astrax es **Open Source** y crece con la comunidad. Si quieres sumarte, eres bienvenido: puedes abrir *issues*, enviar *pull requests*, proponer ideas, probar Astrax en otros sistemas o clientes MCP y reportar errores.
+
+- 📧 **Correo de contacto:** [avpn497@gmail.com](mailto:avpn497@gmail.com)
+- 📢 **Canal oficial de Telegram:** [https://t.me/AstraxMCP](https://t.me/AstraxMCP) — únete al canal para aportar, hacer preguntas o reportar problemas.
+- 📺 **YouTube:** [@AstraxOf](https://youtube.com/@AstraxOf) — tutoriales y novedades
+- 💬 **Creador en Telegram:** [@RufusOficial](https://t.me/RufusOficial)
+
+Si te sirvió el proyecto, deja una ⭐ en el repositorio y suscríbete al canal.
+
+---
+
+<p align="center">Hecho con 💙 por <b>Rufus</b> · <a href="https://youtube.com/@AstraxOf">@AstraxOf</a></p>

astrax_mcp-0.2.0/install.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""Instalador para quien clonó el repo:  python install.py  (equivale a `astrax-install`)."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent / "src"))
+
+from astrax_mcp.installer import main  # noqa: E402
+
+if __name__ == "__main__":
+    sys.exit(main())

astrax_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "astrax-mcp"
+dynamic = ["version"]
+description = "Agentic System Telemetry, Realtime Automation & X-control: servidor MCP que da ojos y manos a tu IA"
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["mcp", "model-context-protocol", "ai-agents", "automation", "pyautogui", "computer-use"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+]
+dependencies = [
+    # <2: misma restricción que usaba mcp_settings.json. El código ya es compatible con
+    # el SDK v2 (MCPServer); quita el tope cuando lo hayas probado.
+    "mcp[cli]>=1.2.0,<2",
+    "pyautogui>=0.9.54",
+    "Pillow>=10.0.0",
+    "pyperclip>=1.8.2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/AstraxOf/astrax-mcp"
+Telegram = "https://t.me/AstraxMCP"
+YouTube = "https://youtube.com/@AstraxOf"
+
+[project.scripts]
+astrax-mcp = "astrax_mcp:main"
+astrax-install = "astrax_mcp.installer:main"
+
+[tool.hatch.version]
+path = "src/astrax_mcp/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/astrax_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "install.py", "README.md", "pyproject.toml", "requirements.txt"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

astrax_mcp-0.2.0/requirements.txt

@@ -0,0 +1,14 @@
+# Astrax - Agentic System Telemetry, Realtime Automation & X-control
+# Recomendado: usa `uvx` (ver README). Alternativa: pip install -r requirements.txt
+
+# Servidor MCP (incluye FastMCP y la CLI `mcp dev`)
+mcp[cli]>=1.2.0,<2
+
+# Control de ratón/teclado y capturas de pantalla
+pyautogui>=0.9.54
+
+# Procesamiento de imágenes (captura y reescalado)
+Pillow>=10.0.0
+
+# Portapapeles: escribir caracteres no ASCII (ñ, tildes, emojis) y herramienta de portapapeles
+pyperclip>=1.8.2

astrax_mcp-0.2.0/src/astrax_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""Astrax - Agentic System Telemetry, Realtime Automation & X-control."""
+
+__version__ = "0.2.0"
+
+
+def main() -> None:
+    """Punto de entrada del servidor MCP (comando `astrax-mcp`)."""
+    from .server import run
+
+    run()

astrax_mcp-0.2.0/src/astrax_mcp/__main__.py

@@ -0,0 +1,4 @@
+from . import main
+
+if __name__ == "__main__":
+    main()

astrax_mcp-0.2.0/src/astrax_mcp/compat.py

@@ -0,0 +1,10 @@
+"""Compatibilidad con el SDK de MCP v1.x (FastMCP) y v2.x (MCPServer)."""
+
+try:  # SDK v2
+    from mcp.server.mcpserver import MCPServer
+    from mcp.server.mcpserver.utilities.types import Image as MCPImage
+except ImportError:  # SDK v1.x
+    from mcp.server.fastmcp import FastMCP as MCPServer  # type: ignore[assignment]
+    from mcp.server.fastmcp.utilities.types import Image as MCPImage  # type: ignore[assignment]
+
+__all__ = ["MCPServer", "MCPImage"]

astrax_mcp-0.2.0/src/astrax_mcp/config.py

@@ -0,0 +1,78 @@
+"""Constantes y configuración (sobrescribible con variables de entorno ASTRAX_*)."""
+
+import os
+import sys
+from pathlib import Path
+
+SERVER_NAME = "Astrax"
+
+
+def _env_int(nombre: str, defecto: int) -> int:
+    try:
+        return int(os.environ.get(nombre, defecto))
+    except ValueError:
+        return defecto
+
+
+def _directorio_astrax() -> Path:
+    """Directorio privado por usuario (no /tmp compartido): guarda estado y capturas."""
+    override = os.environ.get("ASTRAX_HOME")
+    if override:
+        return Path(override).expanduser()
+    if sys.platform == "win32":
+        base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
+    elif sys.platform == "darwin":
+        base = Path.home() / "Library" / "Caches"
+    else:
+        base = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache")
+    return base / "astrax"
+
+
+HOME_DIR = _directorio_astrax()
+STATE_FILE = HOME_DIR / ".astrax_task_state.json"
+SCREENSHOT_DIR = HOME_DIR / "screens"
+
+# --- Permisos de sesión (ámbitos) ---
+SCOPE_PANTALLA = "pantalla"            # ver / capturar la pantalla
+SCOPE_INPUT = "raton_teclado"          # clics, teclas, atajos, scroll
+SCOPE_PORTAPAPELES = "portapapeles"    # leer / escribir el portapapeles
+SCOPE_TERMINAL = "terminal"            # ejecutar comandos de shell
+SCOPES = (SCOPE_PANTALLA, SCOPE_INPUT, SCOPE_PORTAPAPELES, SCOPE_TERMINAL)
+
+# Si es "0", las herramientas de acción no exigen tarea autorizada (modo legado).
+REQUIRE_SESSION = os.environ.get("ASTRAX_REQUIRE_SESSION", "1") != "0"
+SESSION_MINUTES = _env_int("ASTRAX_SESSION_MINUTES", 60)
+
+# --- Límites (ahorro de tokens y anti-bucles) ---
+MAX_PASOS = 30
+MAX_INTENTOS = 3
+MAX_DATOS = 100
+MAX_DATO_CHARS = 4000
+MAX_SALIDA = 4000
+MAX_ESPERA_SEG = 15.0
+JPEG_QUALITY = max(30, min(_env_int("ASTRAX_JPEG_QUALITY", 65), 95))
+
+# --- Nombres de herramientas (el instalador los usa para `alwaysAllow`) ---
+TOOL_AUTORIZAR = "astrax_tarea_autorizar"
+TODAS_LAS_HERRAMIENTAS = (
+    "astrax_tarea_crear",
+    TOOL_AUTORIZAR,
+    "astrax_tarea_estado",
+    "astrax_tarea_guardar",
+    "astrax_tarea_completar_paso",
+    "astrax_tarea_limpiar",
+    "astrax_info_pantalla",
+    "astrax_ver_pantalla",
+    "astrax_capturar_pantalla",
+    "astrax_clic",
+    "astrax_doble_clic",
+    "astrax_escribir",
+    "astrax_tecla",
+    "astrax_atajo",
+    "astrax_scroll",
+    "astrax_esperar",
+    "astrax_portapapeles",
+    "astrax_ejecutar_comando",
+)
+# Todo menos la autorización: así el cliente pregunta UNA vez, justo ahí.
+AUTO_APROBABLES = tuple(t for t in TODAS_LAS_HERRAMIENTAS if t != TOOL_AUTORIZAR)