{"id":30307225,"url":"https://github.com/angrysky56/textualize-mcp","last_synced_at":"2025-08-17T10:44:23.249Z","repository":{"id":307175479,"uuid":"1028607242","full_name":"angrysky56/textualize-mcp","owner":"angrysky56","description":"A MCP for an AI development environment orchestrator that can coordinate complex multi-service workflows, manage dependencies automatically, and provide visual process management.","archived":false,"fork":false,"pushed_at":"2025-07-29T19:46:08.000Z","size":110,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-29T22:02:22.900Z","etag":null,"topics":["ai","mcp-server","multiplex","orchestrator","textualize"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/angrysky56.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-29T19:31:22.000Z","updated_at":"2025-07-29T19:46:12.000Z","dependencies_parsed_at":"2025-07-29T22:02:45.321Z","dependency_job_id":"f59882af-4429-46b9-9544-4b35f5dbf90b","html_url":"https://github.com/angrysky56/textualize-mcp","commit_stats":null,"previous_names":["angrysky56/textualize-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/angrysky56/textualize-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angrysky56%2Ftextualize-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angrysky56%2Ftextualize-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angrysky56%2Ftextualize-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angrysky56%2Ftextualize-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/angrysky56","download_url":"https://codeload.github.com/angrysky56/textualize-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/angrysky56%2Ftextualize-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270837451,"owners_count":24654386,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","mcp-server","multiplex","orchestrator","textualize"],"created_at":"2025-08-17T10:44:21.615Z","updated_at":"2025-08-17T10:44:23.105Z","avatar_url":"https://github.com/angrysky56.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Textualize-MCP Server\n\nA Model Context Protocol (MCP) server that provides a library of useful Textual terminal applications and sophisticated development environment orchestration using [textualize/textual](https://github.com/Textualize/textual) and [multiplex](https://github.com/sebastien/multiplex)\n\n## Features\n\n- **Pre-built Application Library**: Collection of production-ready terminal applications\n- **Environment Orchestration**: Coordinated multi-service development environments with dependencies\n- **Process Coordination**: Automatic timing, sequencing, and dependency management\n- **MCP Interface**: Control apps and environments via AI assistants through standardized function calls\n- **Live Development**: Real-time editing and hot-reload capabilities\n- **Web Deployment**: Run terminal apps in browsers via textual-web\n- **Visual Process Management**: Color-coded outputs and status monitoring\n- **Cross-platform**: Works on Linux, macOS, and Windows\n\n## Available Textualize MCP Tools\n\n### 🎯 Core App Management\n- **list_apps()** - List all available Textual applications with metadata\n- **launch_app()** - **UNIFIED** launch method with comprehensive mode support:\n  - `launch_mode=\"background\"` - Standard background execution  \n  - `launch_mode=\"web\"` - Web browser deployment with custom port\n  - `launch_mode=\"terminal\"` - Visible terminal window (VS Code context)\n  - `launch_mode=\"collaborative\"` - Full AI-app interaction features\n- **get_app_info()** - Get detailed application information and capabilities\n- **terminate_app()** - Terminate specific running applications\n- **get_app_status()** - Get current application status and process info\n- **list_running_apps()** - List all currently running applications\n\n### 🤝 Interactive \u0026 Collaborative Features  \n- **capture_app_screen()** - Get real-time visual state and layout of running apps\n- **send_input_to_app()** - Send keystrokes, text, commands, or actions to apps\n- **get_app_state()** - Get detailed UI state, data, and context information\n- **create_interactive_session()** - Start shared real-time collaboration sessions\n- **read_app_output()** - Read recent output and logs from applications\n- **capture_terminal_output()** - Capture actual terminal content and visual output\n\n### 🏗️ Environment Orchestration (Multiplex Integration)\n- **list_environment_templates()** - List predefined development environment templates\n- **launch_development_environment()** - Launch coordinated multi-service environments\n- **create_custom_workflow()** - Create custom workflows with process dependencies  \n- **get_environment_status()** - Get comprehensive environment status and process info\n- **terminate_environment()** - Gracefully shutdown entire environments\n- **list_active_environments()** - List all running environments with details\n\n### 🔧 System Management \u0026 Debugging\n- **debug_running_apps()** - Debug tool for troubleshooting app tracking issues\n- **terminate_all_apps()** - Emergency shutdown of all running apps and environments\n- **get_all_running_processes()** - Get detailed info about all processes for debugging\n- **cleanup_dead_processes()** - Clean up orphaned process references\n\n## 🎪 What This Enables\n\n### 🎯 Individual App Control\n**👀 Visible Terminal Launch**\n```\nAI: \"I'll launch the process monitor in a visible terminal window\"\n→ Opens gnome-terminal/xterm with the app running\n→ You see exactly what I'm doing in real-time\n→ Both AI and user can interact with the same interface\n```\n\n**🌐 Web Browser Mode**\n```\nAI: \"Let me launch the file browser in your web browser\"\n→ Starts app at http://localhost:8000\n→ You open the URL and see the full interface\n→ Perfect for graphs, charts, visual data\n→ Works on any device with a web browser\n```\n\n### 🚀 Environment Orchestration (NEW!)\n\n**🏗️ Development Stack Coordination**\n```\nAI: \"Launch a full development environment\"\n→ Starts database, API server, file browser, and monitor in sequence\n→ Color-coded outputs distinguish each service (#green, #blue, #yellow)\n→ Automatic dependency management and timing (+2, +API, etc.)\n→ Single command shuts down entire environment gracefully\n```\n\n**🧪 Testing Pipeline Automation**\n```\nAI: \"Run the complete testing pipeline\"\n→ Executes: LINT#yellow → TYPE#blue → TEST#green → COVERAGE → CLEANUP\n→ Each step waits for previous to complete (+LINT, +TYPE dependencies)\n→ Automatic cleanup and summary reporting (|end action)\n→ Graceful failure handling and timeout management\n```\n\n**🎨 Custom Workflow Creation**\n```json\nAI: \"Create a custom workflow with process dependencies\"\n→ Define complex multi-step processes:\n[\n  \"DEMO#green=echo 'Starting custom workflow demo'\",\n  \"STEP1#blue+1=echo 'Step 1: Processing...'\",\n  \"STEP2#yellow+STEP1=echo 'Step 2: Finalizing...'\",\n  \"DONE+STEP2|end=echo '✅ Custom workflow completed!'\"\n]\n→ Built-in timing, dependencies, and coordination\n→ Color-coded process identification\n→ Automatic timeout and cleanup handling\n```\n\n## 📚 Environment Templates Available\n\n### 1. `textual_dev` - Single App Development\nPerfect for developing a single Textual application with live reload and debugging.\n\n**What it includes:**\n- APP#green: Textual serve with specified app and port\n- CONSOLE#blue: Development console for debugging  \n- DEV: Live reload development mode\n- BROWSER: Automatic browser opening\n\n**Template Commands:**\n```bash\nAPP#green=textual serve textualize_mcp.apps.{app_name}:{app_name}App --port {port}\nCONSOLE#blue+1=textual console\nDEV+2=textual run --dev textualize_mcp.apps.{app_name}:{app_name}App\nBROWSER+3=xdg-open http://localhost:{port}\n```\n\n**Usage:**\n```python\n# Launch with customizations\nawait launch_development_environment(\"textual_dev\", '{\"app_name\": \"calculator\", \"port\": \"8000\"}')\n```\n\n### 2. `full_stack` - Complete Development Stack\nFor complex applications requiring databases, multiple services, and monitoring.\n\n**What it includes:**\n- DB#blue: MongoDB with quiet logging (background)\n- REDIS#red: Redis server on custom port (background)  \n- API#green: API tester service on port 8001\n- MONITOR#yellow: Process monitor on port 8002\n- FILE_BROWSER#cyan: File browser on port 8003\n- DASHBOARD: Opens browser to main service\n\n**Template Commands:**\n```bash\nDB#blue|silent=mongod --quiet --dbpath /tmp/textual_db\nREDIS#red|silent=redis-server --port 6380\nAPI#green+2=textual serve textualize_mcp.apps.api_tester:APITesterApp --port 8001\nMONITOR#yellow+API=textual serve textualize_mcp.apps.process_monitor:ProcessMonitorApp --port 8002\nFILE_BROWSER#cyan+API=textual serve textualize_mcp.apps.file_browser:FileBrowserApp --port 8003\nDASHBOARD+5=xdg-open http://localhost:8001\n```\n\n### 3. `testing_pipeline` - Automated Testing Workflow\nComprehensive testing pipeline with proper dependency sequencing.\n\n**What it includes:**\n- LINT#yellow: Code linting with ruff\n- TYPE#blue: Type checking with mypy (waits for lint)\n- TEST#green: Test execution with pytest (waits for type check)  \n- COVERAGE: Coverage report generation (waits for tests)\n- CLEANUP: Success notification and cleanup (auto-terminates)\n\n**Template Commands:**\n```bash\nLINT#yellow=ruff check textualize_mcp/\nTYPE#blue+LINT=mypy textualize_mcp/\nTEST#green+TYPE=pytest tests/ -v\nCOVERAGE+TEST=coverage report --show-missing\nCLEANUP+COVERAGE|end=echo 'Testing pipeline completed successfully'\n```\n\n### 4. `development_stack` - Multi-Service Coordination\nCoordinate multiple Textual services for complex application development.\n\n**What it includes:**\n- API#green: API tester service on port 8001\n- FILE_MGR#cyan: File browser on port 8002\n- PROC_MON#yellow: Process monitor on port 8003  \n- GATEWAY: Status message when all services are ready\n\n**Template Commands:**\n```bash\nAPI#green=textual serve textualize_mcp.apps.api_tester:APITesterApp --port 8001\nFILE_MGR#cyan+1=textual serve textualize_mcp.apps.file_browser:FileBrowserApp --port 8002\nPROC_MON#yellow+1=textual serve textualize_mcp.apps.process_monitor:ProcessMonitorApp --port 8003\nGATEWAY+3=echo 'All services running - API:8001 Files:8002 Monitor:8003'\n```\n\n## 🎯 Real-World Usage Examples\n\n### Example 1: Web Browser Collaboration\n```python\n# Launch calculator in web browser for shared collaboration\nawait launch_app(\"calculator\", launch_mode=\"web\", port=8000)\n# → Calculator available at http://localhost:8000\n# → Both AI and user can interact with same interface\n```\n\n### Example 2: Multi-Service Development Environment  \n```python\n# Launch coordinated development stack\nenv_id = await launch_development_environment(\"development_stack\")\n# → API tester on port 8001\n# → File browser on port 8002  \n# → Process monitor on port 8003\n# → Color-coded coordination with timing dependencies\n\n# Check environment status\nstatus = await get_environment_status(env_id)\n# → Shows process coordination and service health\n\n# Graceful shutdown when complete\nawait terminate_environment(env_id)\n```\n\n### Example 3: Testing Pipeline Automation\n```python\n# Run complete automated testing workflow\nawait launch_development_environment(\"testing_pipeline\")\n# → LINT#yellow → TYPE#blue → TEST#green → COVERAGE → CLEANUP\n# → Each step waits for previous completion\n# → Automatic reporting and cleanup\n```\n\n### Example 4: Custom Workflow Creation\n```python\n# Create custom workflow with process dependencies\nworkflow = [\n    \"BUILD#yellow=npm run build\",\n    \"TEST#green+BUILD=pytest tests/ -v\", \n    \"DOCKER#blue+TEST=docker build -t app .\",\n    \"DEPLOY#red+DOCKER=kubectl apply -f deployment.yaml\",\n    \"NOTIFY+DEPLOY|end=echo '🚀 Deployment complete!'\"\n]\n\nawait create_custom_workflow(json.dumps(workflow), timeout=300)\n# → Custom deployment pipeline with color-coded stages\n# → Built-in dependency management and timeout handling\n```\n\n### Example 5: Interactive App Control\n```python\n# Launch app in collaborative mode for AI interaction\napp_id = await launch_app(\"api_tester\", launch_mode=\"collaborative\")\n\n# Capture current screen state\nscreen_data = await capture_app_screen(app_id)\n\n# Send input to the running app\nawait send_input_to_app(app_id, \"key\", \"Enter\")\n\n# Get detailed app state\nstate = await get_app_state(app_id) \n```\n\n🎪 What This Enables:\n\n### 🎯 Individual App Control\n👀 Visible Terminal Launch\nAI: \"I'll launch the process monitor in a visible terminal window\"\n→ Opens gnome-terminal/xterm with the app running\n→ You see exactly what I'm doing in real-time\n→ Both AI and user can interact with the same interface\n\n🌐 Web Browser Mode\nAI: \"Let me launch the file browser in your web browser\"\n→ Starts app at http://localhost:8000\n→ You open the URL and see the full interface\n→ Perfect for graphs, charts, visual data\n→ Works on any device with a web browser\n\n### 🚀 Environment Orchestration (NEW!)\n🏗️ Development Stack Coordination\nAI: \"Let me launch a full development environment\"\n→ Starts database, API server, file browser, and monitor in sequence\n→ Color-coded outputs distinguish each service\n→ Automatic dependency management and timing\n→ Single command shuts down entire environment\n\n🧪 Testing Pipeline Automation\nAI: \"Run the complete testing pipeline\"\n→ Executes linting, type checking, tests, and coverage in order\n→ Each step waits for previous to complete\n→ Automatic cleanup and summary reporting\n→ Graceful failure handling\n\n🎨 Custom Workflow Creation\nAI: \"Create a custom workflow with process dependencies\"\n→ Define complex multi-step processes with JSON configuration\n→ Built-in timing, dependencies, and coordination\n→ Color-coded process identification\n→ Automatic timeout and cleanup handling\n\n### 📸 Real-Time Monitoring\n\n📸 Real Terminal Screenshots\nAI: \"Let me capture what's currently on the terminal screen\"\n→ Gets actual terminal output and visual state\n→ Can describe what's happening visually\n→ Perfect for debugging and assistance\n\n🤝 One-Command Collaboration\nAI: \"Let's open a collaborative session with the API tester\"\n→ Launches in both terminal AND web browser\n→ You choose how you want to interact\n→ AI can control while you watch or vice versa\n\n\n### 📊 Unified Launch Method\n\nThe `launch_app()` method is the **single, consolidated** way to launch applications in any mode:\n\n```python\n# Basic syntax\nawait launch_app(\n    app_name: str,           # Required: \"calculator\", \"file_browser\", \"api_tester\", \"process_monitor\"\n    args: str = None,        # Optional: JSON string of arguments  \n    launch_mode: str = \"background\",  # Mode: \"background\", \"web\", \"terminal\", \"collaborative\"\n    port: int = 8000,        # Port for web mode\n    terminal_type: str = \"gnome-terminal\"  # Terminal type for terminal mode\n)\n\n# Launch modes explained:\n# \"background\"     → Standard execution (default)\n# \"web\"           → Browser deployment at http://localhost:PORT\n# \"terminal\"      → Visible terminal window (VS Code context only)  \n# \"collaborative\" → Full AI-app interaction features\n```\n\n**Previous redundant methods removed for architectural clarity:**\n- ~~`launch_app_in_terminal()`~~ → Use `launch_mode=\"terminal\"`\n- ~~`launch_app_in_web_browser()`~~ → Use `launch_mode=\"web\"`  \n- ~~`open_collaborative_session()`~~ → Use `launch_mode=\"collaborative\"`\n\nYou can say:\n\n\"Launch the file browser in a terminal window so I can see it\"\n\"Open the process monitor in my web browser\"\n\"Create a collaborative session with the API tester\"\n\"Show me what's currently on the terminal screen\"\n\n🖱️ Send Keystrokes: AI can press any key in the apps (r for refresh, q to quit, etc.)\n💬 Send Commands: AI can execute app-specific commands\n📸 Screen Capture: AI can see the current state of running apps\n🔄 Real-Time Interaction: Both you and AI can control the same app simultaneously\n📊 Monitor \u0026 Automate: AI can run automated testing and monitoring\n\n## Applications Library\n\n### 📊 Current Available Applications\n\n#### **Calculator** (v1.1.0)\n- **Description**: Calculator with basic arithmetic and scientific functions\n- **Tags**: calculator, math, utility, scientific\n- **Features**: Standard mathematical operations, scientific functions\n- **Launch**: `launch_app(\"calculator\", launch_mode=\"web\", port=8000)`\n\n#### **File Browser** (v1.0.0)  \n- **Description**: Advanced dual-pane file manager with syntax highlighting and file preview\n- **Tags**: file-management, preview, utility\n- **Features**: Dual-pane interface, syntax highlighting, file preview capabilities\n- **Launch**: `launch_app(\"file_browser\", launch_mode=\"web\", port=8001)`\n\n#### **Process Monitor** (v1.0.0)\n- **Description**: Real-time system and process monitoring with management capabilities\n- **Tags**: system, monitoring, processes, performance  \n- **Features**: Real-time monitoring, process management, performance metrics\n- **Launch**: `launch_app(\"process_monitor\", launch_mode=\"web\", port=8002)`\n\n#### **API Tester** (v1.0.0)\n- **Description**: REST API testing tool with request builder and response viewer\n- **Tags**: api, testing, development, http\n- **Features**: Request building, response viewing, HTTP testing capabilities\n- **Launch**: `launch_app(\"api_tester\", launch_mode=\"web\", port=8003)`\n\n## Installation\n\n### Prerequisites\n```bash\n# Install multiplex (required for environment orchestration)\nuv tool install multiplex-sh\n\n# Verify multiplex is available\nmultiplex --help\n```\n\n### Setup\n```bash\n# Navigate to the project directory\ncd /textualize-mcp\n\n# Create and activate virtual environment using uv (recommended)\nuv venv --python 3.12 --seed\nsource .venv/bin/activate\n\n# Install dependencies (now includes multiplex-sh)\nuv pip install -r pyproject.toml\n\n# Alternatively, install directly with uv\n# uv pip install -e .\n```\n\n## Usage\n\n### As MCP Server with Claude Desktop\n\n1. **Copy the example configuration:**\n   ```bash\n   cp example_mcp_config.json claude_desktop_config.json\n   ```\n\n2. **Edit paths in the configuration file to match your system:**\n   ```json\n   {\n     \"mcpServers\": {\n       \"textualize-mcp\": {\n         \"command\": \"uv\",\n         \"args\": [\n           \"--directory\",\n           \"/your/path/to/textualize-mcp\",\n           \"run\",\n           \"server.py\"\n         ]\n       }\n     }\n   }\n   ```\n\n3. **Add to your Claude Desktop configuration:**\n   - Location: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\n   - Or: `~/.config/claude/claude_desktop_config.json` (Linux)\n\n4. **Restart Claude Desktop** to load the MCP server\n\n### Standalone Applications\n```bash\n# Run any app directly\npython -m textualize_mcp.apps.file_browser\npython -m textualize_mcp.apps.process_monitor\npython -m textualize_mcp.apps.api_tester\n```\n\n### Web Interface\n```bash\n# Serve any app in browser\ntextual serve textualize_mcp.apps.file_browser:FileBrowserApp\n```\n\n## 🎯 Key Multiplex Integration Features\n\n### Process Coordination Syntax\nThe multiplex integration uses a powerful syntax for coordinating processes:\n\n- **Named Processes**: `API=textual serve app.py` (creates referenceable process)\n- **Colors**: `API#green=command` (color-codes output for visual distinction)\n- **Time Delays**: `+5=command` (wait 5 seconds before starting)\n- **Process Dependencies**: `+API=command` (wait for API process to complete)\n- **Actions**:\n  - `|silent` - suppress all output\n  - `|end` - terminate all processes when this one ends\n  - `|noout` - suppress stdout only\n  - `|noerr` - suppress stderr only\n\n### Example Multiplex Configuration\n```json\n[\n  \"DB#blue|silent=mongod --quiet --dbpath /tmp/dev_db\",\n  \"API#green+2=textual serve api_tester.py --port 8001\",\n  \"MONITOR#yellow+API=textual serve process_monitor.py --port 8002\",\n  \"BROWSER+5=xdg-open http://localhost:8001\"\n]\n```\nThis creates a coordinated environment where:\n1. Database starts silently in background (blue output)\n2. API server waits 2 seconds, then starts (green output)\n3. Monitor waits for API to be ready, then starts (yellow output)\n4. Browser opens after 5 seconds total\n\n### Benefits Over Manual Process Management\n\n| Feature | Manual Subprocess | Multiplex Integration |\n|---------|------------------|----------------------|\n| **Process Dependencies** | Manual coordination | Natural syntax (`+PROCESS=command`) |\n| **Timing Control** | Manual delays | Built-in timing (`+5=command`) |\n| **Output Management** | Complex pipe handling | Color-coded streams (`#color`) |\n| **Cleanup** | Manual termination | Automatic graceful shutdown |\n| **Visual Distinction** | All processes look same | Color-coded identification |\n| **Error Handling** | Custom error logic | Built-in failure handling |\n| **Scalability** | Complex to extend | Simple template addition |\n\n## Architecture\n\n```\ntextualize-mcp/\n├── apps/           # Individual Textual applications\n├── server/         # MCP server implementation\n├── core/           # Shared utilities and base classes\n├── templates/      # App generation templates\n└── web/           # Web deployment configurations\n```\n\n## Development\n\n```bash\n\n# Run tests\npytest\n\n# Start MCP server in development mode\npython server.py --dev\n\n# Create new application\npython -m textualize_mcp.create_app MyNewApp\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangrysky56%2Ftextualize-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fangrysky56%2Ftextualize-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangrysky56%2Ftextualize-mcp/lists"}