{"id":31035668,"url":"https://github.com/ooples/mcp-console-automation","last_synced_at":"2025-10-09T20:34:10.153Z","repository":{"id":312901995,"uuid":"1046333827","full_name":"ooples/mcp-console-automation","owner":"ooples","description":"MCP server for AI-driven console application automation and monitoring","archived":false,"fork":false,"pushed_at":"2025-10-02T20:10:09.000Z","size":3919,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-02T20:17:08.533Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ooples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-28T14:32:08.000Z","updated_at":"2025-09-27T19:13:03.000Z","dependencies_parsed_at":"2025-09-02T18:47:57.930Z","dependency_job_id":"63707a9d-0ebb-4473-87d4-406ba5dd294e","html_url":"https://github.com/ooples/mcp-console-automation","commit_stats":null,"previous_names":["ooples/mcp-console-automation"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/ooples/mcp-console-automation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooples%2Fmcp-console-automation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooples%2Fmcp-console-automation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooples%2Fmcp-console-automation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooples%2Fmcp-console-automation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ooples","download_url":"https://codeload.github.com/ooples/mcp-console-automation/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ooples%2Fmcp-console-automation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278981518,"owners_count":26079640,"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-10-08T02:00:06.501Z","response_time":56,"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":[],"created_at":"2025-09-14T03:46:32.045Z","updated_at":"2025-10-09T20:34:10.147Z","avatar_url":"https://github.com/ooples.png","language":"TypeScript","funding_links":[],"categories":["CLI Tools","📦 Other"],"sub_categories":["Playwright"],"readme":"# MCP Console Automation Server\n\n**Production-Ready** Model Context Protocol (MCP) server that enables AI assistants to fully interact with console applications, monitor output, detect errors, and automate terminal workflows - similar to how Playwright works for web browsers.\n\n[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/ooples/mcp-console-automation)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)\n\n## Production Status ✅\n\nThis server is **fully production-ready** with:\n- ✅ No native compilation required (removed node-pty dependency)\n- ✅ Full cross-platform support (Windows, macOS, Linux)\n- ✅ Streaming support for long-running processes\n- ✅ Multiple console type support (cmd, PowerShell, bash, zsh, sh)\n- ✅ Resource management and automatic cleanup\n- ✅ Comprehensive error handling and recovery\n- ✅ Easy installation scripts for all major MCP clients\n- ✅ All tests passing (see test-functionality.js)\n\n## Features\n\n### 🚀 Core Capabilities\n\n- **Full Terminal Control**: Create and manage up to 50 concurrent console sessions\n- **Multi-Protocol Support**: Local shells (cmd, PowerShell, pwsh, bash, zsh, sh) and remote SSH connections\n- **Interactive Input**: Send text input and special key sequences (Enter, Tab, Ctrl+C, etc.)\n- **Real-time Output Monitoring**: Capture, filter, and analyze console output with advanced search\n- **Streaming Support**: Efficient streaming for long-running processes with pattern matching\n- **Automatic Error Detection**: Built-in patterns to detect errors, exceptions, and stack traces across languages\n- **Cross-platform**: Works on Windows, macOS, and Linux without native dependencies\n\n### 🔐 SSH \u0026 Remote Connections\n\n- **Full SSH Support**: Password and key-based authentication with passphrase support\n- **SSH Options**: Custom ports, connection timeouts, keep-alive settings\n- **Connection Profiles**: Save and reuse SSH configurations for quick access\n- **Cloud Platform Support**: Azure, AWS, GCP, Kubernetes connections via saved profiles\n- **Container Support**: Docker and WSL integration for containerized workflows\n\n### ✅ Test Automation Framework\n\n- **Automated Test Cases**: Built-in assertion tools for console output validation\n- **Output Assertions**: Verify output contains, matches regex, or equals expected values\n- **Exit Code Validation**: Assert command exit codes for success/failure detection\n- **Error-Free Validation**: Automatically check for errors in command output\n- **State Snapshots**: Save and compare session states before/after operations\n- **Test Workflows**: Chain assertions for comprehensive testing scenarios\n\n### 🔄 Background Job Execution\n\n- **Async Command Execution**: Run long-running commands in background with full output capture\n- **Priority Queue System**: Prioritize jobs (1-10 scale) for optimal resource utilization\n- **Job Monitoring**: Track status, progress, and completion of background jobs\n- **Job Control**: Cancel, pause, or resume background operations\n- **Result Retrieval**: Get complete output and exit codes from completed jobs\n- **Resource Management**: Automatic cleanup of completed jobs with configurable retention\n\n### 📊 Enterprise Monitoring \u0026 Alerts\n\n- **System-Wide Metrics**: CPU, memory, disk, and network usage tracking\n- **Session Metrics**: Per-session performance monitoring and resource consumption\n- **Real-time Dashboards**: Live monitoring data with customizable views\n- **Alert System**: Performance, error, security, and anomaly alerts with severity levels\n- **Custom Monitoring**: Configure monitoring intervals, metrics, and thresholds per session\n- **Diagnostics**: Built-in error analysis and session health validation\n\n### 📁 Profile Management\n\n- **Connection Profiles**: Save SSH, Docker, WSL, and cloud platform connections\n- **Application Profiles**: Store common command configurations (Node.js, Python, .NET, Java, Go, Rust)\n- **Quick Connect**: Instantly connect using saved profiles with override support\n- **Environment Variables**: Store environment configurations per profile\n- **Working Directory Management**: Set default directories for each profile\n\n### 🔍 Advanced Output Processing\n\n- **Regex Filtering**: Search output with regular expressions (case-sensitive/insensitive)\n- **Multi-Pattern Search**: Combine multiple patterns with AND/OR logic\n- **Pagination**: Get specific line ranges, head, or tail of output\n- **Time-based Filtering**: Filter output by timestamp (absolute or relative: '5m', '1h', '2d')\n- **Output Streaming**: Real-time output capture for long-running processes\n- **Buffer Management**: Clear output buffers to reduce memory usage\n\n## Quick Installation\n\n### Windows (PowerShell as Administrator)\n```powershell\ngit clone https://github.com/ooples/mcp-console-automation.git\ncd mcp-console-automation\n.\\install.ps1 -Target claude  # or google, openai, custom, all\n```\n\n### macOS/Linux\n```bash\ngit clone https://github.com/ooples/mcp-console-automation.git\ncd mcp-console-automation\nchmod +x install.sh\n./install.sh --target claude  # or google, openai, custom, all\n```\n\n### Manual Installation\n```bash\ngit clone https://github.com/ooples/mcp-console-automation.git\ncd mcp-console-automation\nnpm install --production\nnpm run build\n```\n\n## Configuration\n\n### For Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"console-automation\": {\n      \"command\": \"npx\",\n      \"args\": [\"@mcp/console-automation\"],\n      \"env\": {\n        \"LOG_LEVEL\": \"info\"\n      }\n    }\n  }\n}\n```\n\n### For other MCP clients\n\n```bash\n# Start the server\nmcp-console --log-level info\n\n# Or with npx\nnpx @mcp/console-automation --log-level info\n```\n\n## Available Tools (40 Total)\n\nThis MCP server provides **40 comprehensive tools** organized into 6 categories:\n\n### 📚 Complete Documentation\n\n- **[Complete Tools Reference](docs/TOOLS.md)** - Detailed documentation for all 40 tools\n- **[Practical Examples](docs/EXAMPLES.md)** - Real-world usage examples and patterns\n- **[Publishing Guide](PUBLISHING.md)** - How to list this server in registries\n\n### Tool Categories\n\n#### 🖥️ Session Management (9 tools)\n- `console_create_session` - Create local or SSH console sessions\n- `console_send_input` - Send text input to sessions\n- `console_send_key` - Send special keys (Enter, Ctrl+C, etc.)\n- `console_get_output` - Get filtered/paginated output with advanced search\n- `console_get_stream` - Stream output from long-running processes\n- `console_wait_for_output` - Wait for specific patterns\n- `console_stop_session` - Stop sessions\n- `console_list_sessions` - List all active sessions\n- `console_cleanup_sessions` - Clean up inactive sessions\n\n#### ⚡ Command Execution (6 tools)\n- `console_execute_command` - Execute commands with output capture\n- `console_detect_errors` - Analyze output for errors\n- `console_get_resource_usage` - Get system resource stats\n- `console_clear_output` - Clear output buffers\n- `console_get_session_state` - Get session execution state\n- `console_get_command_history` - View command history\n\n#### 📊 Monitoring \u0026 Alerts (6 tools)\n- `console_get_system_metrics` - Comprehensive system metrics\n- `console_get_session_metrics` - Session-specific metrics\n- `console_get_alerts` - Active monitoring alerts\n- `console_get_monitoring_dashboard` - Real-time dashboard data\n- `console_start_monitoring` - Start custom monitoring\n- `console_stop_monitoring` - Stop monitoring\n\n#### 📁 Profile Management (4 tools)\n- `console_save_profile` - Save SSH/app connection profiles\n- `console_list_profiles` - List saved profiles\n- `console_remove_profile` - Remove profiles\n- `console_use_profile` - Quick connect with saved profiles\n\n#### 🔄 Background Jobs (9 tools)\n- `console_execute_async` - Execute commands asynchronously\n- `console_get_job_status` - Check job status\n- `console_get_job_output` - Get job output\n- `console_cancel_job` - Cancel running jobs\n- `console_list_jobs` - List all background jobs\n- `console_get_job_progress` - Monitor job progress\n- `console_get_job_result` - Get complete job results\n- `console_get_job_metrics` - Job execution statistics\n- `console_cleanup_jobs` - Clean up completed jobs\n\n#### ✅ Test Automation (6 tools)\n- `console_assert_output` - Assert output matches criteria\n- `console_assert_exit_code` - Assert exit codes\n- `console_assert_no_errors` - Verify no errors occurred\n- `console_save_snapshot` - Save session state snapshots\n- `console_compare_snapshots` - Compare state differences\n- `console_assert_state` - Assert session state\n\n### Quick Start Examples\n\n#### Create a Local Session\n```javascript\nconst session = await console_create_session({\n  command: \"npm\",\n  args: [\"run\", \"dev\"],\n  detectErrors: true\n});\n```\n\n#### Connect via SSH\n```javascript\nconst session = await console_create_session({\n  command: \"bash\",\n  consoleType: \"ssh\",\n  sshOptions: {\n    host: \"example.com\",\n    username: \"user\",\n    privateKeyPath: \"~/.ssh/id_rsa\"\n  }\n});\n```\n\n#### Run Tests with Assertions\n```javascript\nconst session = await console_create_session({\n  command: \"npm\",\n  args: [\"test\"]\n});\n\nawait console_assert_output({\n  sessionId: session.sessionId,\n  assertionType: \"contains\",\n  expected: \"All tests passed\"\n});\n```\n\n#### Background Job Execution\n```javascript\nconst job = await console_execute_async({\n  sessionId: session.sessionId,\n  command: \"npm run build\",\n  priority: 8\n});\n\nconst status = await console_get_job_status({\n  jobId: job.jobId\n});\n```\n\nFor more examples, see [docs/EXAMPLES.md](docs/EXAMPLES.md)\n\n## Use Cases\n\n### 1. Running and monitoring a development server\n```javascript\n// Create a session for the dev server\nconst session = await console_create_session({\n  command: \"npm\",\n  args: [\"run\", \"dev\"],\n  detectErrors: true\n});\n\n// Wait for server to start\nawait console_wait_for_output({\n  sessionId: session.sessionId,\n  pattern: \"Server running on\",\n  timeout: 10000\n});\n\n// Monitor for errors\nconst errors = await console_detect_errors({\n  sessionId: session.sessionId\n});\n```\n\n### 2. Interactive debugging session\n```javascript\n// Start a Python debugging session\nconst session = await console_create_session({\n  command: \"python\",\n  args: [\"-m\", \"pdb\", \"script.py\"]\n});\n\n// Set a breakpoint\nawait console_send_input({\n  sessionId: session.sessionId,\n  input: \"b main\\n\"\n});\n\n// Continue execution\nawait console_send_input({\n  sessionId: session.sessionId,\n  input: \"c\\n\"\n});\n\n// Step through code\nawait console_send_key({\n  sessionId: session.sessionId,\n  key: \"n\"\n});\n```\n\n### 3. Automated testing with error detection\n```javascript\n// Run tests\nconst result = await console_execute_command({\n  command: \"pytest\",\n  args: [\"tests/\"],\n  timeout: 30000\n});\n\n// Check for test failures\nconst errors = await console_detect_errors({\n  text: result.output\n});\n\nif (errors.hasErrors) {\n  console.log(\"Test failures detected:\", errors);\n}\n```\n\n### 4. Interactive CLI tool automation\n```javascript\n// Start an interactive CLI tool\nconst session = await console_create_session({\n  command: \"mysql\",\n  args: [\"-u\", \"root\", \"-p\"]\n});\n\n// Enter password\nawait console_wait_for_output({\n  sessionId: session.sessionId,\n  pattern: \"Enter password:\"\n});\n\nawait console_send_input({\n  sessionId: session.sessionId,\n  input: \"mypassword\\n\"\n});\n\n// Run SQL commands\nawait console_send_input({\n  sessionId: session.sessionId,\n  input: \"SHOW DATABASES;\\n\"\n});\n```\n\n## Error Detection Patterns\n\nThe server includes built-in patterns for detecting common error types:\n\n- Generic errors (error:, ERROR:, Error:)\n- Exceptions (Exception:, exception)\n- Warnings (Warning:, WARNING:)\n- Fatal errors\n- Failed operations\n- Permission/access denied\n- Timeouts\n- Stack traces (Python, Java, Node.js)\n- Compilation errors\n- Syntax errors\n- Memory errors\n- Connection errors\n\n## Development\n\n### Building from source\n```bash\nnpm install\nnpm run build\n```\n\n### Running in development mode\n```bash\nnpm run dev\n```\n\n### Running tests\n```bash\nnpm test\n```\n\n### Type checking\n```bash\nnpm run typecheck\n```\n\n### Linting\n```bash\nnpm run lint\n```\n\n## Architecture\n\nThe server is built with:\n- **node-pty**: For creating and managing pseudo-terminals\n- **@modelcontextprotocol/sdk**: MCP protocol implementation\n- **TypeScript**: For type safety and better developer experience\n- **Winston**: For structured logging\n\n### Core Components\n\n1. **ConsoleManager**: Manages terminal sessions, input/output, and lifecycle\n2. **ErrorDetector**: Analyzes output for errors and exceptions\n3. **MCP Server**: Exposes console functionality through MCP tools\n4. **Session Management**: Handles multiple concurrent console sessions\n\n## Requirements\n\n- Node.js \u003e= 18.0.0\n- Windows, macOS, or Linux operating system\n- No additional build tools required!\n\n## Testing\n\nRun the included test suite to verify functionality:\n```bash\nnode test-functionality.js\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Permission denied errors**: Ensure the server has permission to spawn processes\n2. **node-pty compilation errors**: Install build tools for your platform\n3. **Session not responding**: Check if the command requires TTY interaction\n4. **Output not captured**: Some applications may write directly to terminal, bypassing stdout\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Support\n\nFor issues, questions, or suggestions, please open an issue on GitHub:\nhttps://github.com/ooples/mcp-console-automation/issues\n\n## Roadmap\n\n- [ ] Add support for terminal recording and playback\n- [ ] Implement session persistence and recovery\n- [ ] Add more error detection patterns for specific languages\n- [ ] Support for terminal multiplexing (tmux/screen integration)\n- [ ] Web-based terminal viewer\n- [ ] Session sharing and collaboration features\n- [ ] Performance profiling tools\n- [ ] Integration with popular CI/CD systems\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fooples%2Fmcp-console-automation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fooples%2Fmcp-console-automation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fooples%2Fmcp-console-automation/lists"}