<!-- ---
!-- Timestamp: 2025-08-23 22:23:25
!-- Author: ywatanabe
!-- File: /home/ywatanabe/proj/sccpt/README.md
!-- --- -->
# SCCPT - Python Screen Capture with MCP Server Support
*- shared visual context between users and AI agents -*
A lightweight, efficient screen capture library with automatic error detection. **Features full MCP (Model Context Protocol) server integration for seamless AI assistant workflows.** Optimized for WSL2 to capture Windows host screens.
## Key Features
### 🤖 **MCP Server Integration**
- **AI Assistant Ready** - Built-in MCP server for Claude Code and other AI assistants
- **Direct Screenshot Control** - AI can capture, monitor, and analyze screenshots programmatically
- **Automated Workflows** - Perfect for debugging, documentation, and monitoring tasks
- **Real-time Interaction** - AI assistants can respond to visual changes instantly
### 📸 **Core Screen Capture**
- 🖼️ **Windows Host Capture from WSL** - Seamlessly capture Windows desktop from WSL with DPI awareness
- 🖥️ **Multi-Monitor Support** - Capture single monitor or all monitors combined
- 🚨 **Automatic Error Detection** - Automatically categorizes screenshots when called in exception handlers
- 🗜️ **JPEG Compression** - Reduce file sizes with configurable quality (~250KB JPEG vs ~2MB PNG)
### 🎬 **Advanced Features**
- ⏱️ **Continuous Monitoring** - Automatic captures at configurable intervals (WSL: ~1.5s minimum due to PowerShell overhead)
- 🎥 **GIF Summaries** - Create animated GIFs from monitoring sessions for easy sharing
- 📝 **Smart Filenames** - Timestamps + normalized messages + category indicators
- 🔄 **Thread-Safe** - Safe for concurrent operations
- 🎯 **Minimal Logging** - Clean, single-line output per screenshot
## Installation
```bash
pip install sccpt
# pip install sccpt[full] # For full features including mss and Pillow support:
```
## Quick Start
### 🐍 Python API - Beautiful Simplicity (Just 4 Functions)
```python
import sccpt
sccpt.cpt() # Capture single screenshot
sccpt.start() # Start monitoring
sccpt.stop() # Stop monitoring
sccpt.create_gif_from_latest_session() # Create GIF summary
```
### 🤖 MCP Server - AI Assistant Integration
```bash
# Start MCP server for Claude Code integration
python -m mcp_server_sccpt
```
*For complete setup instructions and available tools, see [MCP Server Integration](#-mcp-server-integration) section below.*
## Use Cases & Examples
### 📸 **Essential Use Cases**
- **Debug visually** - Capture before/after states during development
- **Monitor processes** - Continuous screenshots during long operations
- **Document workflows** - Step-by-step visual documentation
- **Error analysis** - Automatic error categorization and screenshots
- **AI-powered automation** - Let AI assistants capture and analyze screens via MCP integration
<details>
<summary><strong>📋 Detailed Python Examples</strong></summary>
### 🐛 Debug Your Code Visually
```python
import sccpt
def process_data(df):
sccpt.cpt("before transformation")
df = df.transform(complex_operation)
sccpt.cpt("after transformation")
return df
```
### 🚨 Automatic Error Screenshots
```python
import sccpt
try:
selenium_driver.click(button)
api_response = fetch_data()
except Exception as e:
sccpt.cpt() # Auto-adds -stderr suffix
raise
```
### 🔍 Monitor Long-Running Processes
```python
import sccpt
sccpt.start() # Start taking screenshots every second
train_model() # Your long operation
sccpt.stop()
```
### 🎬 Create GIF Summaries
```python
import sccpt
sccpt.start()
# ... your process ...
sccpt.stop()
sccpt.create_gif_from_latest_session()
# 📹 GIF created: ~/.cache/sccpt/20250823_104523_summary.gif
```
</details>
## Platform Support
| Platform | Support | Notes |
|----------|---------|-------|
| **WSL → Windows** | ✅ Full | Primary focus - DPI-aware, multi-monitor |
| Linux (X11) | ⚠️ Limited | Falls back to mss/scrot |
| macOS | ⚠️ Limited | Requires mss library |
| Windows Native | ❌ | Not implemented |
| Linux (Wayland) | ❌ | Not supported |
<details>
<summary><strong>⚙️ Technical Details & Configuration</strong></summary>
## Configuration
All configuration through function parameters - no config files needed!
```python
sccpt.start(
output_dir="~/screenshots", # Where to save
interval=2.0, # Seconds between captures
quality=85, # JPEG quality (1-100)
verbose=False # Silent mode
)
```
## File Structure
```
~/.cache/sccpt/
├── 20250823_104523-message-stdout.jpg # Normal capture
├── 20250823_104525-error-stderr.jpg # Error capture
└── 20250823_104530_0001_*.jpg # Monitoring mode
Cache automatically managed (1GB default limit, oldest files removed)
```
## Requirements
- Python 3.7+
- WSL environment (for Windows capture)
- PowerShell access to Windows host
Optional:
- `Pillow` - JPEG compression (recommended)
- `mss` - Cross-platform fallback
</details>
## 🤖 MCP Server Integration
**Transform your AI workflows** - SCCPT's MCP server enables Claude and other AI assistants to capture, monitor, and analyze screenshots directly as part of their reasoning process.
### AI-Powered Capabilities
- **Seamless Integration** - AI assistants can capture screenshots on demand
- **Automated Debugging** - AI captures error screens and analyzes issues
- **Documentation Generation** - AI creates visual step-by-step guides
- **Intelligent Monitoring** - AI watches for visual changes and responds
- **Error Analysis** - AI automatically categorizes and analyzes screenshots
<details>
<summary><strong>🔧 MCP Server Setup & Configuration</strong></summary>
### Setup
```json
// Add to your Claude Code settings
{
"mcpServers": {
"sccpt": {
"command": "python",
"args": ["/path/to/sccpt/mcp_server_sccpt.py"]
}
}
}
```
### Available MCP Tools
**Core Capture:**
- `capture_screenshot` - Take single screenshots with custom messages
- `start_monitoring` / `stop_monitoring` - Continuous monitoring at configurable intervals
- `get_monitoring_status` - Check current monitoring status
**Analysis & Management:**
- `analyze_screenshot` - AI-powered error detection and categorization
- `list_recent_screenshots` - Browse capture history by category (stdout/stderr)
- `clear_cache` - Manage screenshot cache size
**Advanced Features:**
- `create_gif` - Generate animated summaries from monitoring sessions
- `list_sessions` - List available sessions for GIF creation
</details>
## 🎬 Live Demos & Screenshots
### 📸 Single Screenshot Capture
*Example of SCCPT's single screenshot capture functionality with custom message*
### 🔄 Real Monitoring Session
*Real GIF created from an actual monitoring session showing SCCPT's continuous capture capabilities*
**Real Session Details:**
- **Duration**: 30 seconds monitoring interval
- **Screenshots**: 11 captures automatically taken
- **File Size**: 2.8MB optimized GIF
- **Quality**: Automatic JPEG compression for efficient storage
- **Features Demonstrated**:
- Automatic timestamp-based naming
- Session-based organization
- GIF creation from monitoring sessions
## 🎥 Professional Feature Demonstrations
### 📋 Complete Workflow Documentation
*Step-by-step workflow documentation showing how SCCPT captures each stage of a process (230KB, 7 frames)*
### 🖥️ Continuous Monitoring Visualization
*Professional demonstration of SCCPT's continuous monitoring with real-time progress tracking (429KB, 12 frames)*
### 🚨 Automatic Error Detection
*Shows how SCCPT automatically categorizes screenshots as stdout (normal) vs stderr (error) based on execution context (322KB, 5 frames)*
## License
MIT License
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Contact
Yusuke.Watanabe@scitex.ai
<!-- EOF -->
Raw data
{
"_id": null,
"home_page": "https://github.com/ywatanabe/sccpt",
"name": "sccpt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "screenshot screen-capture wsl windows monitoring automation",
"author": "Yusuke Watanabe",
"author_email": "Yusuke.Watanabe@scitex.ai",
"download_url": "https://files.pythonhosted.org/packages/07/98/7fcc0daf50127b5f2f2ab0173123f255126f0b10948ebdc017276da057c1/sccpt-0.1.0.tar.gz",
"platform": null,
"description": "<!-- ---\n!-- Timestamp: 2025-08-23 22:23:25\n!-- Author: ywatanabe\n!-- File: /home/ywatanabe/proj/sccpt/README.md\n!-- --- -->\n\n# SCCPT - Python Screen Capture with MCP Server Support\n*- shared visual context between users and AI agents -*\n\nA lightweight, efficient screen capture library with automatic error detection. **Features full MCP (Model Context Protocol) server integration for seamless AI assistant workflows.** Optimized for WSL2 to capture Windows host screens.\n\n## Key Features\n\n### \ud83e\udd16 **MCP Server Integration** \n- **AI Assistant Ready** - Built-in MCP server for Claude Code and other AI assistants\n- **Direct Screenshot Control** - AI can capture, monitor, and analyze screenshots programmatically\n- **Automated Workflows** - Perfect for debugging, documentation, and monitoring tasks\n- **Real-time Interaction** - AI assistants can respond to visual changes instantly\n\n### \ud83d\udcf8 **Core Screen Capture**\n- \ud83d\uddbc\ufe0f **Windows Host Capture from WSL** - Seamlessly capture Windows desktop from WSL with DPI awareness\n- \ud83d\udda5\ufe0f **Multi-Monitor Support** - Capture single monitor or all monitors combined\n- \ud83d\udea8 **Automatic Error Detection** - Automatically categorizes screenshots when called in exception handlers\n- \ud83d\udddc\ufe0f **JPEG Compression** - Reduce file sizes with configurable quality (~250KB JPEG vs ~2MB PNG)\n\n### \ud83c\udfac **Advanced Features**\n- \u23f1\ufe0f **Continuous Monitoring** - Automatic captures at configurable intervals (WSL: ~1.5s minimum due to PowerShell overhead) \n- \ud83c\udfa5 **GIF Summaries** - Create animated GIFs from monitoring sessions for easy sharing\n- \ud83d\udcdd **Smart Filenames** - Timestamps + normalized messages + category indicators\n- \ud83d\udd04 **Thread-Safe** - Safe for concurrent operations\n- \ud83c\udfaf **Minimal Logging** - Clean, single-line output per screenshot\n\n## Installation\n\n```bash\npip install sccpt\n# pip install sccpt[full] # For full features including mss and Pillow support:\n```\n\n## Quick Start\n\n### \ud83d\udc0d Python API - Beautiful Simplicity (Just 4 Functions)\n\n```python\nimport sccpt\n\nsccpt.cpt() # Capture single screenshot\nsccpt.start() # Start monitoring \nsccpt.stop() # Stop monitoring\nsccpt.create_gif_from_latest_session() # Create GIF summary\n```\n\n### \ud83e\udd16 MCP Server - AI Assistant Integration\n\n```bash\n# Start MCP server for Claude Code integration\npython -m mcp_server_sccpt\n```\n\n*For complete setup instructions and available tools, see [MCP Server Integration](#-mcp-server-integration) section below.*\n\n## Use Cases & Examples\n\n### \ud83d\udcf8 **Essential Use Cases**\n- **Debug visually** - Capture before/after states during development \n- **Monitor processes** - Continuous screenshots during long operations\n- **Document workflows** - Step-by-step visual documentation\n- **Error analysis** - Automatic error categorization and screenshots\n- **AI-powered automation** - Let AI assistants capture and analyze screens via MCP integration\n\n<details>\n<summary><strong>\ud83d\udccb Detailed Python Examples</strong></summary>\n\n### \ud83d\udc1b Debug Your Code Visually\n\n```python\nimport sccpt\n\ndef process_data(df):\n sccpt.cpt(\"before transformation\")\n df = df.transform(complex_operation)\n sccpt.cpt(\"after transformation\")\n return df\n```\n\n### \ud83d\udea8 Automatic Error Screenshots\n\n```python\nimport sccpt\n\ntry:\n selenium_driver.click(button)\n api_response = fetch_data()\nexcept Exception as e:\n sccpt.cpt() # Auto-adds -stderr suffix\n raise\n```\n\n### \ud83d\udd0d Monitor Long-Running Processes\n\n```python\nimport sccpt\n\nsccpt.start() # Start taking screenshots every second\ntrain_model() # Your long operation\nsccpt.stop()\n```\n\n### \ud83c\udfac Create GIF Summaries\n\n```python\nimport sccpt\n\nsccpt.start()\n# ... your process ... \nsccpt.stop()\nsccpt.create_gif_from_latest_session()\n# \ud83d\udcf9 GIF created: ~/.cache/sccpt/20250823_104523_summary.gif\n```\n\n</details>\n\n## Platform Support\n\n| Platform | Support | Notes |\n|----------|---------|-------|\n| **WSL \u2192 Windows** | \u2705 Full | Primary focus - DPI-aware, multi-monitor |\n| Linux (X11) | \u26a0\ufe0f Limited | Falls back to mss/scrot |\n| macOS | \u26a0\ufe0f Limited | Requires mss library |\n| Windows Native | \u274c | Not implemented |\n| Linux (Wayland) | \u274c | Not supported |\n\n<details>\n<summary><strong>\u2699\ufe0f Technical Details & Configuration</strong></summary>\n\n## Configuration\n\nAll configuration through function parameters - no config files needed!\n\n```python\nsccpt.start(\n output_dir=\"~/screenshots\", # Where to save\n interval=2.0, # Seconds between captures\n quality=85, # JPEG quality (1-100)\n verbose=False # Silent mode\n)\n```\n\n## File Structure\n\n```\n~/.cache/sccpt/\n\u251c\u2500\u2500 20250823_104523-message-stdout.jpg # Normal capture\n\u251c\u2500\u2500 20250823_104525-error-stderr.jpg # Error capture \n\u2514\u2500\u2500 20250823_104530_0001_*.jpg # Monitoring mode\n\nCache automatically managed (1GB default limit, oldest files removed)\n```\n\n## Requirements\n\n- Python 3.7+\n- WSL environment (for Windows capture)\n- PowerShell access to Windows host\n\nOptional:\n- `Pillow` - JPEG compression (recommended)\n- `mss` - Cross-platform fallback\n\n</details>\n\n## \ud83e\udd16 MCP Server Integration\n\n**Transform your AI workflows** - SCCPT's MCP server enables Claude and other AI assistants to capture, monitor, and analyze screenshots directly as part of their reasoning process.\n\n### AI-Powered Capabilities\n- **Seamless Integration** - AI assistants can capture screenshots on demand\n- **Automated Debugging** - AI captures error screens and analyzes issues \n- **Documentation Generation** - AI creates visual step-by-step guides\n- **Intelligent Monitoring** - AI watches for visual changes and responds\n- **Error Analysis** - AI automatically categorizes and analyzes screenshots\n\n<details>\n<summary><strong>\ud83d\udd27 MCP Server Setup & Configuration</strong></summary>\n\n### Setup\n\n```json\n// Add to your Claude Code settings\n{\n \"mcpServers\": {\n \"sccpt\": {\n \"command\": \"python\", \n \"args\": [\"/path/to/sccpt/mcp_server_sccpt.py\"]\n }\n }\n}\n```\n\n### Available MCP Tools\n\n**Core Capture:**\n- `capture_screenshot` - Take single screenshots with custom messages\n- `start_monitoring` / `stop_monitoring` - Continuous monitoring at configurable intervals\n- `get_monitoring_status` - Check current monitoring status\n\n**Analysis & Management:**\n- `analyze_screenshot` - AI-powered error detection and categorization\n- `list_recent_screenshots` - Browse capture history by category (stdout/stderr)\n- `clear_cache` - Manage screenshot cache size\n\n**Advanced Features:**\n- `create_gif` - Generate animated summaries from monitoring sessions\n- `list_sessions` - List available sessions for GIF creation\n\n</details>\n\n## \ud83c\udfac Live Demos & Screenshots\n\n### \ud83d\udcf8 Single Screenshot Capture\n\n*Example of SCCPT's single screenshot capture functionality with custom message*\n\n### \ud83d\udd04 Real Monitoring Session\n\n*Real GIF created from an actual monitoring session showing SCCPT's continuous capture capabilities*\n\n**Real Session Details:**\n- **Duration**: 30 seconds monitoring interval \n- **Screenshots**: 11 captures automatically taken\n- **File Size**: 2.8MB optimized GIF\n- **Quality**: Automatic JPEG compression for efficient storage\n- **Features Demonstrated**: \n - Automatic timestamp-based naming\n - Session-based organization\n - GIF creation from monitoring sessions\n\n## \ud83c\udfa5 Professional Feature Demonstrations\n\n### \ud83d\udccb Complete Workflow Documentation\n\n*Step-by-step workflow documentation showing how SCCPT captures each stage of a process (230KB, 7 frames)*\n\n### \ud83d\udda5\ufe0f Continuous Monitoring Visualization\n\n*Professional demonstration of SCCPT's continuous monitoring with real-time progress tracking (429KB, 12 frames)*\n\n### \ud83d\udea8 Automatic Error Detection\n\n*Shows how SCCPT automatically categorizes screenshots as stdout (normal) vs stderr (error) based on execution context (322KB, 5 frames)*\n\n## License\n\nMIT License\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Contact\nYusuke.Watanabe@scitex.ai\n\n<!-- EOF -->\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Lightweight screen capture library optimized for WSL and Windows",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/ywatanabe/sccpt"
},
"split_keywords": [
"screenshot",
"screen-capture",
"wsl",
"windows",
"monitoring",
"automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "da8134ac9b13cd160030ad1363dda9849cc40624562810de24b2e990672cbc65",
"md5": "e94d3831090e5d4e36e7794817cdc132",
"sha256": "1c53680df13e370e8d3fdd0bcb7f5dec28cb4a344ff30f6723750d4da64a1e9f"
},
"downloads": -1,
"filename": "sccpt-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e94d3831090e5d4e36e7794817cdc132",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19686,
"upload_time": "2025-08-23T12:55:45",
"upload_time_iso_8601": "2025-08-23T12:55:45.710637Z",
"url": "https://files.pythonhosted.org/packages/da/81/34ac9b13cd160030ad1363dda9849cc40624562810de24b2e990672cbc65/sccpt-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "07987fcc0daf50127b5f2f2ab0173123f255126f0b10948ebdc017276da057c1",
"md5": "b3fb525ad384c82050565a536e314887",
"sha256": "aef12992f87585395b467fa3570c90bbc8240359574e613475048eeebbf94a1a"
},
"downloads": -1,
"filename": "sccpt-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b3fb525ad384c82050565a536e314887",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 20851,
"upload_time": "2025-08-23T12:55:47",
"upload_time_iso_8601": "2025-08-23T12:55:47.456095Z",
"url": "https://files.pythonhosted.org/packages/07/98/7fcc0daf50127b5f2f2ab0173123f255126f0b10948ebdc017276da057c1/sccpt-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 12:55:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ywatanabe",
"github_project": "sccpt",
"github_not_found": true,
"lcname": "sccpt"
}
JSON
