| Name | computer-split-screen-mcp JSON |
| Version |
1.5.0
JSON |
| download |
| home_page | None |
| Summary | Model Context Protocol Server via Cross-Platform (Mac & Windows) Split Screen Functions |
| upload_time | 2025-08-25 04:16:05 |
| maintainer | None |
| docs_url | None |
| author | Beta |
| requires_python | >=3.9 |
| license | MIT License
Copyright (c) 2024 Computer Split Screen MCP
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 NONINFRECTION. 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. |
| keywords |
cross-platform
desktop-productivity
macos
mcp
pywin32
split-screen
tiling
window-management
windows
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Computer Split Screen MCP
A high-performance, cross-platform Model Context Protocol (MCP) server that provides reliable split-screen window management for both Windows and macOS. This server exposes 16 window manipulation tools through the MCP protocol, enabling AI assistants and other MCP clients to control desktop window layouts with precision.
## 🚀 Features
- **Cross-platform support**: Windows and macOS with native optimizations
- **16 window management tools**: Comprehensive split-screen layouts and controls
- **High performance**: Windows: 15-60ms, macOS: 50-150ms per operation
- **Reliability first**: Robust fallback mechanisms and error handling
- **MCP integration**: Full Model Context Protocol server support via stdio transport
- **Smart focus detection**: Advanced window focus detection with platform-specific optimizations
## 🛠️ Installation
### Prerequisites
- **Python**: 3.9 or higher
- **Package Manager**: `uvx` (recommended) or `pip`
### Install via uvx (Recommended)
```bash
uvx install computer-split-screen-mcp
```
### Install via pip
```bash
pip install computer-split-screen-mcp
```
## 🔧 MCP Client Configuration
Configure your MCP client with the following settings:
```json
{
"mcpServers": {
"computer-split-screen": {
"command": "uvx",
"args": ["computer-split-screen-mcp"],
"env": {}
}
}
}
```
### Alternative Configuration (if not using uvx)
```json
{
"mcpServers": {
"computer-split-screen": {
"command": "python",
"args": ["-m", "computer-split-screen-mcp"],
"env": {}
}
}
}
```
## 🎯 Available Tools
### Split-Screen Layouts
#### Halves (2-way splits)
- `left-half-screen` - Snap current window to left half
- `right-half-screen` - Snap current window to right half
- `top-half-screen` - Snap current window to top half
- `bottom-half-screen` - Snap current window to bottom half
#### Quadrants (4-way splits)
- `top-left-screen` - Top-left quadrant (1/4 screen)
- `top-right-screen` - Top-right quadrant (1/4 screen)
- `bottom-left-screen` - Bottom-left quadrant (1/4 screen)
- `bottom-right-screen` - Bottom-right quadrant (1/4 screen)
#### Thirds (3-way splits)
- `left-one-third-screen` - Left third (1/3 screen)
- `middle-one-third-screen` - Middle third (1/3 screen)
- `right-one-third-screen` - Right third (1/3 screen)
#### Two-Thirds (2/3 splits)
- `left-two-thirds-screen` - Left two-thirds (2/3 screen)
- `right-two-thirds-screen` - Right two-thirds (2/3 screen)
### Window Controls
- `maximize-screen` - OS maximize (bordered, taskbar visible)
- `fullscreen-screen` - Fullscreen mode (platform-specific behavior)
- `minimize-screen` - Minimize window to taskbar/dock
## ⚡ Performance Characteristics
### Windows Performance
- **Total time**: 15-60ms per operation
- **Detection**: 2-5ms (direct Win32 API)
- **Manipulation**: 10-47ms (SetWindowPos with corrections)
- **Best case**: 15-25ms for simple splits
- **Typical case**: 20-35ms for most operations
### macOS Performance
- **Total time**: 50-150ms per operation
- **Detection**: 20-50ms (AppleScript + Accessibility API)
- **Manipulation**: 15-55ms (AXUIElement operations)
- **Best case**: 50-80ms for simple splits
- **Typical case**: 80-120ms for most operations
## 🔍 Technical Architecture
### Windows Implementation
- **Direct Win32 API calls** via `pywin32`
- **DWM integration** for accurate frame bounds
- **DPI-aware positioning** for high-resolution displays
- **Two-pass positioning** for precise window placement
### macOS Implementation
- **AppleScript focus detection** for reliability
- **Accessibility API** for window manipulation
- **Fallback mechanisms** for edge cases
- **Screen-aware positioning** respecting menu bar and Dock
### Cross-Platform Features
- **Automatic platform detection**
- **Conditional dependency loading**
- **Unified API interface**
- **Error handling and recovery**
## 📋 Platform Dependencies
### Windows
- **Required**: `pywin32>=306`
- **Purpose**: Win32 API access, DWM integration, window manipulation
### macOS
- **Required**: `pyobjc-core>=10.1,<11`, `pyobjc-framework-Cocoa>=10.1,<11`, `pyobjc-framework-Quartz>=10.1,<11`, `pyobjc-framework-ApplicationServices>=10.1,<11`
- **Purpose**: Accessibility API, AppleScript integration, window management
## 🚨 Troubleshooting
### Common Issues
#### macOS Focus Detection Problems
- **Symptom**: Windows don't move or wrong windows are selected
- **Solution**: Ensure Terminal has Accessibility permissions in System Preferences > Security & Privacy > Privacy > Accessibility
#### Windows DPI Issues
- **Symptom**: Windows positioned incorrectly on high-DPI displays
- **Solution**: The server automatically handles DPI awareness, but ensure `pywin32>=306` is installed
#### MCP Client Connection Issues
- **Symptom**: Functions work when called directly but fail via MCP
- **Solution**: Check MCP client logs, ensure proper configuration, restart MCP client
### Performance Optimization
- **First run**: May be slower due to system warm-up
- **Subsequent runs**: Should be consistently fast
- **Complex apps**: Safari, Chrome may take longer due to window structure
## 🔧 Development
### Project Structure
```
computer-split-screen/
├── src/splitscreen_mcp/
│ ├── __init__.py # Package initialization
│ ├── __main__.py # MCP server entry point
│ └── window_actions.py # Core window management logic
├── pyproject.toml # Project configuration
├── README.md # This file
└── LICENSE # MIT License
```
### Building from Source
```bash
git clone https://github.com/Beta0415/computer-split-screen-mcp.git
cd computer-split-screen-mcp
uvx install -e .
```
### Running Tests
```bash
# Test window detection
python3 -c "from src.splitscreen_mcp.window_actions import left_half_window; left_half_window()"
# Test MCP server
uvx run computer-split-screen-mcp
```
### Contributing
- **Repository**: [https://github.com/Beta0415/computer-split-screen-mcp](https://github.com/Beta0415/computer-split-screen-mcp)
- **Issues**: [https://github.com/Beta0415/computer-split-screen-mcp/issues](https://github.com/Beta0415/computer-split-screen-mcp/issues)
- **Pull Requests**: Welcome! Please open an issue first for major changes.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
## 📊 Version History
- **v1.4.4** - Current stable release
- Cross-platform window management
- 16 comprehensive tools
- High-performance implementation
- Full MCP protocol support
## 🆘 Support
If you encounter any issues or have questions:
1. Check the troubleshooting section above
2. Review MCP client logs for errors
3. Test functions directly to isolate issues
4. Open an issue on the project repository
---
**Built with ❤️ for the MCP community**
Raw data
{
"_id": null,
"home_page": null,
"name": "computer-split-screen-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "cross-platform, desktop-productivity, macos, mcp, pywin32, split-screen, tiling, window-management, windows",
"author": "Beta",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/fb/59/4c7846c45b2b58d74b9e18a4b053dafd366bb5dc2935a1c9c95ce53ed668/computer_split_screen_mcp-1.5.0.tar.gz",
"platform": null,
"description": "# Computer Split Screen MCP\n\nA high-performance, cross-platform Model Context Protocol (MCP) server that provides reliable split-screen window management for both Windows and macOS. This server exposes 16 window manipulation tools through the MCP protocol, enabling AI assistants and other MCP clients to control desktop window layouts with precision.\n\n## \ud83d\ude80 Features\n\n- **Cross-platform support**: Windows and macOS with native optimizations\n- **16 window management tools**: Comprehensive split-screen layouts and controls\n- **High performance**: Windows: 15-60ms, macOS: 50-150ms per operation\n- **Reliability first**: Robust fallback mechanisms and error handling\n- **MCP integration**: Full Model Context Protocol server support via stdio transport\n- **Smart focus detection**: Advanced window focus detection with platform-specific optimizations\n\n## \ud83d\udee0\ufe0f Installation\n\n### Prerequisites\n\n- **Python**: 3.9 or higher\n- **Package Manager**: `uvx` (recommended) or `pip`\n\n### Install via uvx (Recommended)\n\n```bash\nuvx install computer-split-screen-mcp\n```\n\n### Install via pip\n\n```bash\npip install computer-split-screen-mcp\n```\n\n## \ud83d\udd27 MCP Client Configuration\n\nConfigure your MCP client with the following settings:\n\n```json\n{\n \"mcpServers\": {\n \"computer-split-screen\": {\n \"command\": \"uvx\",\n \"args\": [\"computer-split-screen-mcp\"],\n \"env\": {}\n }\n }\n}\n```\n\n### Alternative Configuration (if not using uvx)\n\n```json\n{\n \"mcpServers\": {\n \"computer-split-screen\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"computer-split-screen-mcp\"],\n \"env\": {}\n }\n }\n}\n```\n\n## \ud83c\udfaf Available Tools\n\n### Split-Screen Layouts\n\n#### Halves (2-way splits)\n- `left-half-screen` - Snap current window to left half\n- `right-half-screen` - Snap current window to right half\n- `top-half-screen` - Snap current window to top half\n- `bottom-half-screen` - Snap current window to bottom half\n\n#### Quadrants (4-way splits)\n- `top-left-screen` - Top-left quadrant (1/4 screen)\n- `top-right-screen` - Top-right quadrant (1/4 screen)\n- `bottom-left-screen` - Bottom-left quadrant (1/4 screen)\n- `bottom-right-screen` - Bottom-right quadrant (1/4 screen)\n\n#### Thirds (3-way splits)\n- `left-one-third-screen` - Left third (1/3 screen)\n- `middle-one-third-screen` - Middle third (1/3 screen)\n- `right-one-third-screen` - Right third (1/3 screen)\n\n#### Two-Thirds (2/3 splits)\n- `left-two-thirds-screen` - Left two-thirds (2/3 screen)\n- `right-two-thirds-screen` - Right two-thirds (2/3 screen)\n\n### Window Controls\n- `maximize-screen` - OS maximize (bordered, taskbar visible)\n- `fullscreen-screen` - Fullscreen mode (platform-specific behavior)\n- `minimize-screen` - Minimize window to taskbar/dock\n\n## \u26a1 Performance Characteristics\n\n### Windows Performance\n- **Total time**: 15-60ms per operation\n- **Detection**: 2-5ms (direct Win32 API)\n- **Manipulation**: 10-47ms (SetWindowPos with corrections)\n- **Best case**: 15-25ms for simple splits\n- **Typical case**: 20-35ms for most operations\n\n### macOS Performance\n- **Total time**: 50-150ms per operation\n- **Detection**: 20-50ms (AppleScript + Accessibility API)\n- **Manipulation**: 15-55ms (AXUIElement operations)\n- **Best case**: 50-80ms for simple splits\n- **Typical case**: 80-120ms for most operations\n\n## \ud83d\udd0d Technical Architecture\n\n### Windows Implementation\n- **Direct Win32 API calls** via `pywin32`\n- **DWM integration** for accurate frame bounds\n- **DPI-aware positioning** for high-resolution displays\n- **Two-pass positioning** for precise window placement\n\n### macOS Implementation\n- **AppleScript focus detection** for reliability\n- **Accessibility API** for window manipulation\n- **Fallback mechanisms** for edge cases\n- **Screen-aware positioning** respecting menu bar and Dock\n\n### Cross-Platform Features\n- **Automatic platform detection**\n- **Conditional dependency loading**\n- **Unified API interface**\n- **Error handling and recovery**\n\n## \ud83d\udccb Platform Dependencies\n\n### Windows\n- **Required**: `pywin32>=306`\n- **Purpose**: Win32 API access, DWM integration, window manipulation\n\n### macOS\n- **Required**: `pyobjc-core>=10.1,<11`, `pyobjc-framework-Cocoa>=10.1,<11`, `pyobjc-framework-Quartz>=10.1,<11`, `pyobjc-framework-ApplicationServices>=10.1,<11`\n- **Purpose**: Accessibility API, AppleScript integration, window management\n\n## \ud83d\udea8 Troubleshooting\n\n### Common Issues\n\n#### macOS Focus Detection Problems\n- **Symptom**: Windows don't move or wrong windows are selected\n- **Solution**: Ensure Terminal has Accessibility permissions in System Preferences > Security & Privacy > Privacy > Accessibility\n\n#### Windows DPI Issues\n- **Symptom**: Windows positioned incorrectly on high-DPI displays\n- **Solution**: The server automatically handles DPI awareness, but ensure `pywin32>=306` is installed\n\n#### MCP Client Connection Issues\n- **Symptom**: Functions work when called directly but fail via MCP\n- **Solution**: Check MCP client logs, ensure proper configuration, restart MCP client\n\n### Performance Optimization\n- **First run**: May be slower due to system warm-up\n- **Subsequent runs**: Should be consistently fast\n- **Complex apps**: Safari, Chrome may take longer due to window structure\n\n## \ud83d\udd27 Development\n\n### Project Structure\n```\ncomputer-split-screen/\n\u251c\u2500\u2500 src/splitscreen_mcp/\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 __main__.py # MCP server entry point\n\u2502 \u2514\u2500\u2500 window_actions.py # Core window management logic\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 README.md # This file\n\u2514\u2500\u2500 LICENSE # MIT License\n```\n\n### Building from Source\n```bash\ngit clone https://github.com/Beta0415/computer-split-screen-mcp.git\ncd computer-split-screen-mcp\nuvx install -e .\n```\n\n### Running Tests\n```bash\n# Test window detection\npython3 -c \"from src.splitscreen_mcp.window_actions import left_half_window; left_half_window()\"\n\n# Test MCP server\nuvx run computer-split-screen-mcp\n```\n\n### Contributing\n- **Repository**: [https://github.com/Beta0415/computer-split-screen-mcp](https://github.com/Beta0415/computer-split-screen-mcp)\n- **Issues**: [https://github.com/Beta0415/computer-split-screen-mcp/issues](https://github.com/Beta0415/computer-split-screen-mcp/issues)\n- **Pull Requests**: Welcome! Please open an issue first for major changes.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## \ud83d\udcca Version History\n\n- **v1.4.4** - Current stable release\n - Cross-platform window management\n - 16 comprehensive tools\n - High-performance implementation\n - Full MCP protocol support\n\n## \ud83c\udd98 Support\n\nIf you encounter any issues or have questions:\n\n1. Check the troubleshooting section above\n2. Review MCP client logs for errors\n3. Test functions directly to isolate issues\n4. Open an issue on the project repository\n\n---\n\n**Built with \u2764\ufe0f for the MCP community**\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2024 Computer Split Screen MCP\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRECTION. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Model Context Protocol Server via Cross-Platform (Mac & Windows) Split Screen Functions",
"version": "1.5.0",
"project_urls": {
"Documentation": "https://github.com/Beta0415/computer-split-screen-mcp#readme",
"Homepage": "https://github.com/Beta0415/computer-split-screen-mcp",
"Issues": "https://github.com/Beta0415/computer-split-screen-mcp/issues",
"Repository": "https://github.com/Beta0415/computer-split-screen-mcp"
},
"split_keywords": [
"cross-platform",
" desktop-productivity",
" macos",
" mcp",
" pywin32",
" split-screen",
" tiling",
" window-management",
" windows"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c96180537d05e3bed33747a05a8430619d5091e33656f5f9f1252a19014289e8",
"md5": "5d7e3b408ba00ee14e2ddad3536a1e7d",
"sha256": "63bf97ce95d4b5bfd5936a3906e1904ec4d9cbab6d52f98c7443a9cea3624d5b"
},
"downloads": -1,
"filename": "computer_split_screen_mcp-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5d7e3b408ba00ee14e2ddad3536a1e7d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13044,
"upload_time": "2025-08-25T04:16:04",
"upload_time_iso_8601": "2025-08-25T04:16:04.519748Z",
"url": "https://files.pythonhosted.org/packages/c9/61/80537d05e3bed33747a05a8430619d5091e33656f5f9f1252a19014289e8/computer_split_screen_mcp-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fb594c7846c45b2b58d74b9e18a4b053dafd366bb5dc2935a1c9c95ce53ed668",
"md5": "8d6109077269e332e0746025bb0db518",
"sha256": "393102737b80548c6d7d0fe5fc300f52aec608007a710d35a0c2ef8999255a3e"
},
"downloads": -1,
"filename": "computer_split_screen_mcp-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "8d6109077269e332e0746025bb0db518",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 11096,
"upload_time": "2025-08-25T04:16:05",
"upload_time_iso_8601": "2025-08-25T04:16:05.861996Z",
"url": "https://files.pythonhosted.org/packages/fb/59/4c7846c45b2b58d74b9e18a4b053dafd366bb5dc2935a1c9c95ce53ed668/computer_split_screen_mcp-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-25 04:16:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Beta0415",
"github_project": "computer-split-screen-mcp#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "computer-split-screen-mcp"
}
