mirror of
https://github.com/samsonjs/Peekaboo.git
synced 2026-03-25 09:25:47 +00:00
🎃 Transform README into spooky Halloween theme
- Add ghost emojis and supernatural terminology throughout - Rename sections with mystical themes (Installation → Summoning, etc.) - Transform technical terms into magical concepts - Update all LOG_LEVEL references to lowercase format - Maintain technical accuracy while adding Halloween personality 👻 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Peter Steinberger
parent
fd380f3c58
commit
d4263d7fe5
1 changed files with 90 additions and 90 deletions
180
README.md
180
README.md
|
|
@ -1,4 +1,4 @@
|
|||
# Peekaboo MCP Server
|
||||
# 👻 Peekaboo MCP Server
|
||||
|
||||
|
||||
|
||||
|
|
@ -7,18 +7,18 @@
|
|||
[](https://www.apple.com/macos/)
|
||||
[](https://nodejs.org/)
|
||||
|
||||
A macOS utility exposed via Node.js MCP server for advanced screen captures, image analysis, and window management.
|
||||
A ghostly macOS utility that haunts your screen, capturing spectral snapshots and peering into windows with supernatural AI vision. 🎃
|
||||
|
||||
## 🚀 Installation
|
||||
## 🦇 Summoning Peekaboo
|
||||
|
||||
### Prerequisites
|
||||
### Ritual Requirements
|
||||
|
||||
- **macOS 12.0+** (Monterey or later)
|
||||
- **Node.js 18.0+**
|
||||
|
||||
### Quick Start
|
||||
### 🕯️ Quick Summoning Ritual
|
||||
|
||||
Add Peekaboo to your Claude Desktop configuration:
|
||||
Summon Peekaboo into your Claude Desktop realm:
|
||||
|
||||
1. Open Claude Desktop settings
|
||||
2. Go to the Developer tab
|
||||
|
|
@ -40,13 +40,13 @@ Add Peekaboo to your Claude Desktop configuration:
|
|||
|
||||
4. Restart Claude Desktop
|
||||
|
||||
That's it! Peekaboo will be automatically installed and available.
|
||||
That's it! Peekaboo will materialize from the digital ether, ready to haunt your screen! 👻
|
||||
|
||||
### 🔧 Configuration
|
||||
### 🔮 Mystical Configuration
|
||||
|
||||
#### Environment Variables
|
||||
#### Enchantment Variables
|
||||
|
||||
You can configure Peekaboo with environment variables in your Claude Desktop configuration:
|
||||
Cast powerful spells upon Peekaboo using mystical environment variables:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -70,7 +70,7 @@ You can configure Peekaboo with environment variables in your Claude Desktop con
|
|||
}
|
||||
```
|
||||
|
||||
#### Available Environment Variables
|
||||
#### 🎭 Available Enchantments
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
|
|
@ -81,9 +81,9 @@ You can configure Peekaboo with environment variables in your Claude Desktop con
|
|||
| `CONSOLE_LOGGING` | Boolean (`"true"`/`"false"`) for dev console logs. | `"false"` |
|
||||
| `CLI_PATH` | Optional override for Swift `peekaboo` CLI path. | (bundled CLI) |
|
||||
|
||||
#### AI Provider Configuration
|
||||
#### 🧙 AI Spirit Guide Configuration
|
||||
|
||||
Configure AI providers for image analysis:
|
||||
Summon AI spirit guides to divine the meaning of captured visions:
|
||||
|
||||
```json
|
||||
[
|
||||
|
|
@ -102,50 +102,50 @@ Configure AI providers for image analysis:
|
|||
]
|
||||
```
|
||||
|
||||
### 🔐 Permissions Setup
|
||||
### 🕰️ Granting Mystical Permissions
|
||||
|
||||
Peekaboo requires specific macOS permissions to function properly:
|
||||
Peekaboo requires ancient macOS rites to manifest its powers:
|
||||
|
||||
#### 1. Screen Recording Permission
|
||||
#### 1. 👁️ The All-Seeing Eye Permission
|
||||
|
||||
**Grant permission via System Preferences:**
|
||||
**Perform the permission ritual:**
|
||||
1. Open **System Preferences** → **Security & Privacy** → **Privacy**
|
||||
2. Select **Screen Recording** from the left sidebar
|
||||
3. Click the **lock icon** and enter your password
|
||||
4. Click **+** and add your terminal application or MCP client
|
||||
5. Restart the application
|
||||
|
||||
**For common applications:**
|
||||
**Known vessels that can channel Peekaboo:**
|
||||
- **Terminal.app**: `/Applications/Utilities/Terminal.app`
|
||||
- **Claude Desktop**: `/Applications/Claude.app`
|
||||
- **VS Code**: `/Applications/Visual Studio Code.app`
|
||||
|
||||
#### 2. Accessibility Permission (Optional)
|
||||
#### 2. 🪄 Window Whisperer Permission (Optional)
|
||||
|
||||
For advanced window management features:
|
||||
To whisper commands to windows and make them dance:
|
||||
1. Open **System Preferences** → **Security & Privacy** → **Privacy**
|
||||
2. Select **Accessibility** from the left sidebar
|
||||
3. Add your terminal/MCP client application
|
||||
|
||||
### ✅ Verification
|
||||
### 🕯️ Séance Verification
|
||||
|
||||
Test your installation:
|
||||
Verify that Peekaboo has successfully crossed over:
|
||||
|
||||
```bash
|
||||
# Test the Swift CLI directly
|
||||
# Commune with the Swift spirit directly
|
||||
./peekaboo --help
|
||||
|
||||
# Test server status
|
||||
# Check the spectral server's pulse
|
||||
./peekaboo list server_status --json-output
|
||||
|
||||
# Test screen capture (requires permissions)
|
||||
# Capture a soul (requires permission wards)
|
||||
./peekaboo image --mode screen --format png
|
||||
|
||||
# Start the MCP server for testing
|
||||
# Open the portal for testing
|
||||
peekaboo-mcp
|
||||
```
|
||||
|
||||
**Expected output for server status:**
|
||||
**Expected ghostly whispers:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
|
|
@ -161,83 +161,83 @@ peekaboo-mcp
|
|||
}
|
||||
```
|
||||
|
||||
### 🎯 Quick Start
|
||||
### 🎙 Channeling Peekaboo
|
||||
|
||||
Once installed and configured:
|
||||
Once the portal is open and Peekaboo lurks in the shadows:
|
||||
|
||||
1. **Capture Screenshot:**
|
||||
1. **🖼️ Capture Ghostly Visions:**
|
||||
```bash
|
||||
peekaboo-mcp
|
||||
# In your MCP client: "Take a screenshot of my screen"
|
||||
# Whisper: "Capture the essence of my screen"
|
||||
```
|
||||
|
||||
2. **List Applications:**
|
||||
2. **💀 Reveal Hidden Spirits:**
|
||||
```bash
|
||||
# In your MCP client: "Show me all running applications"
|
||||
# Whisper: "Reveal all digital spirits dwelling here"
|
||||
```
|
||||
|
||||
3. **Analyze Screenshot:**
|
||||
3. **🔮 Divine the Captured Essence:**
|
||||
```bash
|
||||
# In your MCP client: "Take a screenshot and tell me what's on my screen"
|
||||
# Whisper: "Divine the visions upon my ethereal display"
|
||||
```
|
||||
|
||||
### 🐛 Troubleshooting
|
||||
### 🕸️ Exorcising Demons
|
||||
|
||||
**Common Issues:**
|
||||
**Common Hauntings:**
|
||||
|
||||
| Issue | Solution |
|
||||
| Haunting | Exorcism |
|
||||
|-------|----------|
|
||||
| `Permission denied` errors | Grant Screen Recording permission in System Preferences |
|
||||
| `Swift CLI unavailable` | Rebuild Swift CLI: `cd swift-cli && swift build -c release` |
|
||||
| `AI analysis failed` | Check AI provider configuration and network connectivity |
|
||||
| `Command not found: peekaboo-mcp` | Run `npm link` or check global npm installation |
|
||||
|
||||
**Debug Mode:**
|
||||
**Ghost Hunter Mode:**
|
||||
```bash
|
||||
# Enable verbose logging
|
||||
# Unleash the ghost hunters
|
||||
LOG_LEVEL=debug peekaboo-mcp
|
||||
|
||||
# Check permissions
|
||||
# Divine the permission wards
|
||||
./peekaboo list server_status --json-output
|
||||
```
|
||||
|
||||
**Get Help:**
|
||||
**Summon the Spirit Guides:**
|
||||
- 📚 [Documentation](./docs/)
|
||||
- 🐛 [Issues](https://github.com/yourusername/peekaboo/issues)
|
||||
- 💬 [Discussions](https://github.com/yourusername/peekaboo/discussions)
|
||||
|
||||
## 📦 Alternative Installation Methods
|
||||
## 🧿 Alternative Summoning Rituals
|
||||
|
||||
### From Source
|
||||
### 🧪 From the Ancient Scrolls
|
||||
|
||||
If you want to build from source or contribute to development:
|
||||
If you dare to invoke Peekaboo from the ancient source grimoires:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
# Clone the cursed repository
|
||||
git clone https://github.com/steipete/peekaboo.git
|
||||
cd peekaboo
|
||||
|
||||
# Install Node.js dependencies
|
||||
# Gather spectral dependencies
|
||||
npm install
|
||||
|
||||
# Build the TypeScript server
|
||||
# Forge the TypeScript vessel
|
||||
npm run build
|
||||
|
||||
# Build the Swift CLI component
|
||||
# Craft the Swift talisman
|
||||
cd swift-cli
|
||||
swift build -c release
|
||||
|
||||
# Copy the binary to the project root
|
||||
# Transport the enchanted binary
|
||||
cp .build/release/peekaboo ../peekaboo
|
||||
|
||||
# Return to project root
|
||||
# Return to the haunted grounds
|
||||
cd ..
|
||||
|
||||
# Optional: Link for global access
|
||||
# Optional: Cast a global summoning spell
|
||||
npm link
|
||||
```
|
||||
|
||||
Then configure Claude Desktop (or a similar MCP client) to use your local installation. If you used `npm link`, the command `peekaboo-mcp` should be globally available. If you prefer to run directly via `node`:
|
||||
Then bind Peekaboo to Claude Desktop (or another MCP vessel) using your local incantations. If you performed `npm link`, the spell `peekaboo-mcp` echoes through the command realm. Alternatively, summon directly through `node`:
|
||||
|
||||
**Example MCP Client Configuration (using local build):**
|
||||
|
||||
|
|
@ -277,9 +277,9 @@ Alternatively, running directly with `node`:
|
|||
Remember to replace `/Users/steipete/Projects/Peekaboo/dist/index.js` with the actual absolute path to the `dist/index.js` in your cloned project if it differs.
|
||||
Also, when using these local configurations, ensure you use a distinct key (like "peekaboo_local" or "peekaboo_local_node") in your MCP client's server list to avoid conflicts if you also have the npx-based "peekaboo" server configured.
|
||||
|
||||
### Using AppleScript
|
||||
### 🍎 Ancient AppleScript Ritual
|
||||
|
||||
For basic screen capture without the full MCP server, you can use the included AppleScript:
|
||||
For those who seek a simpler conjuring without the full spectral server, invoke the ancient AppleScript:
|
||||
|
||||
```bash
|
||||
# Run the AppleScript directly
|
||||
|
|
@ -306,11 +306,11 @@ For MCP clients other than Claude Desktop:
|
|||
|
||||
---
|
||||
|
||||
## 🛠️ Available Tools
|
||||
## 🎭 Spectral Powers
|
||||
|
||||
Once installed, Peekaboo provides three powerful MCP tools:
|
||||
Once summoned, Peekaboo grants you three supernatural abilities:
|
||||
|
||||
### 📸 `image` - Screen Capture
|
||||
### 🖼️ `image` - Soul Capture
|
||||
|
||||
**Parameters:**
|
||||
- `mode`: `"screen"` | `"window"` | `"multi"` (default: "screen")
|
||||
|
|
@ -328,7 +328,7 @@ Once installed, Peekaboo provides three powerful MCP tools:
|
|||
}
|
||||
```
|
||||
|
||||
### 📋 `list` - Application Listing
|
||||
### 👻 `list` - Spirit Detection
|
||||
|
||||
**Parameters:**
|
||||
- `item_type`: `"running_applications"` | `"application_windows"` | `"server_status"`
|
||||
|
|
@ -344,7 +344,7 @@ Once installed, Peekaboo provides three powerful MCP tools:
|
|||
}
|
||||
```
|
||||
|
||||
### 🧩 `analyze` - AI Analysis
|
||||
### 🔮 `analyze` - Vision Divination
|
||||
|
||||
**Parameters:**
|
||||
- `image_path`: Absolute path to image file
|
||||
|
|
@ -361,27 +361,27 @@ Once installed, Peekaboo provides three powerful MCP tools:
|
|||
}
|
||||
```
|
||||
|
||||
## 🎯 Key Features
|
||||
## 🌙 Supernatural Abilities
|
||||
|
||||
### Screen Capture
|
||||
- **Multi-display support**: Captures each display separately
|
||||
- **Window targeting**: Intelligent app/window matching with fuzzy search
|
||||
- **Format flexibility**: PNG, JPEG, WebP, HEIF support
|
||||
- **Automatic naming**: Timestamps and descriptive filenames
|
||||
- **Permission handling**: Automatic screen recording permission checks
|
||||
### 🖼️ Ethereal Vision Capture
|
||||
- **Multi-realm vision**: Captures each spectral display separately
|
||||
- **Soul targeting**: Supernatural app/window divination with ethereal matching
|
||||
- **Essence preservation**: PNG, JPEG, WebP, HEIF soul containers
|
||||
- **Mystical naming**: Temporal runes and descriptive incantations
|
||||
- **Ward detection**: Automatic permission ward verification
|
||||
|
||||
### Application Management
|
||||
- **Running app enumeration**: Complete system application listing
|
||||
- **Window discovery**: Per-app window enumeration with metadata
|
||||
- **Fuzzy matching**: Find apps by partial name, bundle ID, or PID
|
||||
- **Real-time status**: Active/background status, window counts
|
||||
### 👻 Spirit Management
|
||||
- **Spirit census**: Complete digital ghost registry
|
||||
- **Portal detection**: Per-spirit window scrying with ethereal metadata
|
||||
- **Spectral matching**: Divine apps by partial essence, soul ID, or spirit number
|
||||
- **Life force monitoring**: Active/slumbering status, portal counts
|
||||
|
||||
### AI Integration
|
||||
- **Provider agnostic**: Support for Ollama, OpenAI, and other providers
|
||||
### 🧿 Oracle Integration
|
||||
- **Oracle agnostic**: Channels Ollama, OpenAI, and other mystical seers
|
||||
- **Image analysis**: Natural language querying of captured content
|
||||
- **Configurable**: Environment-based provider selection
|
||||
|
||||
## 🏛️ Project Structure
|
||||
## 🏩 Haunted Architecture
|
||||
|
||||
```
|
||||
Peekaboo/
|
||||
|
|
@ -411,9 +411,9 @@ Peekaboo/
|
|||
└── README.md # This file
|
||||
```
|
||||
|
||||
## 🔧 Technical Details
|
||||
## 🔬 Arcane Knowledge
|
||||
|
||||
### Swift CLI JSON Output
|
||||
### 📜 Ancient Runes (JSON Output)
|
||||
The Swift CLI outputs structured JSON when called with `--json-output`:
|
||||
|
||||
```json
|
||||
|
|
@ -434,34 +434,34 @@ The Swift CLI outputs structured JSON when called with `--json-output`:
|
|||
}
|
||||
```
|
||||
|
||||
### MCP Integration
|
||||
### 🌌 Portal Integration
|
||||
The Node.js server translates between MCP's JSON-RPC protocol and the Swift CLI's JSON output, providing:
|
||||
- **Schema validation** via Zod
|
||||
- **Error handling** with proper MCP error codes
|
||||
- **Logging** via Pino logger
|
||||
- **Type safety** throughout the TypeScript codebase
|
||||
|
||||
### Permission Model
|
||||
### 🚪 Permission Wards
|
||||
Peekaboo respects macOS security by:
|
||||
- **Checking screen recording permissions** before capture operations
|
||||
- **Graceful degradation** when permissions are missing
|
||||
- **Clear error messages** guiding users to grant required permissions
|
||||
|
||||
## 🧪 Testing
|
||||
## 🧿 Ghost Hunting
|
||||
|
||||
### Manual Testing
|
||||
### 🕯️ Manual Séances
|
||||
```bash
|
||||
# Test Swift CLI directly
|
||||
# Channel the Swift spirit
|
||||
./peekaboo list apps --json-output | head -20
|
||||
|
||||
# Test MCP integration
|
||||
# Test the spectral portal
|
||||
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js
|
||||
|
||||
# Test image capture
|
||||
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "image", "arguments": {"mode": "screen"}}}' | node dist/index.js
|
||||
```
|
||||
|
||||
### Automated Testing
|
||||
### 🤖 Automated Exorcisms
|
||||
```bash
|
||||
# TypeScript compilation
|
||||
npm run build
|
||||
|
|
@ -470,12 +470,12 @@ npm run build
|
|||
cd swift-cli && swift build
|
||||
```
|
||||
|
||||
## 🐛 Known Issues
|
||||
## 🕸️ Known Curses
|
||||
|
||||
- **FileHandle warning**: Non-critical Swift warning about TextOutputStream conformance
|
||||
- **AI Provider Config**: Requires `AI_PROVIDERS` environment variable for analysis features
|
||||
|
||||
## 🚀 Future Enhancements
|
||||
## 🌀 Future Hauntings
|
||||
|
||||
- [ ] **OCR Integration**: Built-in text extraction from screenshots
|
||||
- [ ] **Video Capture**: Screen recording capabilities
|
||||
|
|
@ -483,11 +483,11 @@ cd swift-cli && swift build
|
|||
- [ ] **Cloud Storage**: Direct upload to cloud providers
|
||||
- [ ] **Hotkey Support**: System-wide keyboard shortcuts
|
||||
|
||||
## 📄 License
|
||||
## 📜 Ancient Pact
|
||||
|
||||
MIT License - see LICENSE file for details.
|
||||
MIT License - bound by the ancient pact in the LICENSE grimoire.
|
||||
|
||||
## 🤝 Contributing
|
||||
## 🧛 Join the Coven
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||
|
|
@ -497,4 +497,4 @@ MIT License - see LICENSE file for details.
|
|||
|
||||
---
|
||||
|
||||
**🎉 Peekaboo is ready to use!** The project successfully combines the power of native macOS APIs with modern Node.js tooling to create a comprehensive screen capture and analysis solution.
|
||||
**🎃 Peekaboo awaits your command!** This spectral servant bridges the veil between macOS's forbidden APIs and the ethereal realm of Node.js, granting you powers to capture souls and divine their secrets. Happy haunting! 👻
|
||||
Loading…
Reference in a new issue