Peekaboo MCP

# peekaboo-mcp Minimal Model Context Protocol (MCP) server for read-only file system access. ## The Problem Claude Code (or any AI coding agent) often makes broader changes than intended. You ask it to fix a simple bug, and it refactors half your codebase. This happens because Claude Code has full read/write access to everything in your project directory. ## The Solution Peekaboo-mcp lets you isolate what Claude Code (or any AI agent) can modify while still giving it visibility into your entire codebase. Simply: 1. Open your editor in a small, dedicated workspace folder 2. Let peekaboo-mcp provide read-only access to your actual project. Now Claude Code can see all the context it needs but can only modify files in your controlled workspace. ## Quick Start 1. **Install peekaboo-mcp in your project root:** ```bash cd /path/to/your/project npm install peekaboo-mcp ``` 2. **Configure your AI tool:** **For Claude Desktop:** Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac): ```json { "mcpServers": { "peekaboo": { "command": "npx", "args": ["peekaboo-mcp"], "cwd": "/path/to/your/project" } } } ``` **For Claude Code (CLI):** ```bash # One-time setup: Navigate to your project and add peekaboo cd /path/to/your/project claude mcp add peekaboo npx peekaboo-mcp # From now on, just start Claude Code claude # Claude automatically launches peekaboo when it starts! # Optional: Check MCP server status > /mcp # Should show: peekaboo: connected ✓ ``` **For Cursor.AI:** Create `.cursor/mcp.json` in your home directory or project: ```json { "mcpServers": { "peekaboo": { "command": "npx", "args": ["-y", "peekaboo-mcp"], "cwd": "/path/to/your/project" } } } ``` Or use Cursor Settings UI: - Open Command Palette (Ctrl/Cmd + Shift + P) - Search for "Cursor Settings" - Navigate to MCP Servers section - Add peekaboo-mcp with the project path **Important**: You don't need to manually launch peekaboo! Claude Desktop, Claude Code, and Cursor all automatically start the MCP server when they need it. 3. **Open ONLY the folder you want AI to work on:** Instead of opening your entire project, open just the specific folder you want modified: ```bash # Example: You want AI to work on your React components cursor /path/to/your/project/src/components # Or: You want AI to refactor your API routes cursor /path/to/your/project/api/routes ``` **Result:** The AI can now: - ✅ Read your ENTIRE project (understands full context) - ✅ Only modify files in `/src/components` (or whatever folder you opened) - ❌ Cannot touch files outside the opened folder ## Features - List directory contents recursively by default - Read file contents with MIME type detection - Search files by name pattern (glob support) - Search content within files - Strict read-only access (no write/edit/delete operations) - Path traversal protection - Automatic project root detection (accesses only the project where installed) - Configurable recursion depth - Resource management (timeouts, file size limits) - Comprehensive test coverage ## Installation ```bash npm install peekaboo-mcp ``` ## Usage ### As a standalone server ```bash # Run from your project (automatically detects project root) npx peekaboo-mcp # Disable recursive listing PEEKABOO_RECURSIVE=false npx peekaboo-mcp # Set custom max depth (default: 10) PEEKABOO_MAX_DEPTH=5 npx peekaboo-mcp ``` **Note**: peekaboo-mcp automatically detects and uses the project root where it's installed. It cannot access files outside of this project for security reasons. ### As a module ```typescript import { createPeekabooServer, findProjectRoot } from 'peekaboo-mcp'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; // Automatically detect project root const rootDir = findProjectRoot(); // Default: recursive listing enabled, max depth 10 const server = createPeekabooServer(rootDir); // Or with custom config const server = createPeekabooServer(rootDir, { recursive: false, // Disable recursive listing maxDepth: 5, // Limit recursion depth timeout: 60000, // 60 second timeout (default: 30s) maxFileSize: 5 * 1024 * 1024, // 5MB max file size (default: 10MB) maxTotalSize: 50 * 1024 * 1024 // 50MB max total size (default: 100MB) }); const transport = new StdioServerTransport(); await server.connect(transport); ``` ### MCP Client Configuration Add to your MCP client configuration: ```json { "mcpServers": { "peekaboo": { "command": "npx", "args": ["peekaboo-mcp"] } } } ``` ## Security - All file access is strictly read-only - Automatic project root detection prevents access outside the installed project - Path traversal above the project root is blocked - No write, edit, or delete operations are supported - No user-configurable root directory (prevents manipulation by LLMs or malicious actors) ## API ### Resources 1. **List Resources**: Returns all files and directories from the root (recursive by default) 2. **Read Resource**: Returns the content of a specific file Resources are accessed via `file://` URIs relative to the configured root. ### Tools 1. **search_path**: Search for files and directories by name pattern - Supports wildcards: `*` (any characters), `**` (any directories), `?` (single character) - Examples: `*.ts`, `src/**/*.js`, `test-?.md` 2. **search_content**: Search for content within files - Optional file pattern filter - Case-insensitive by default - Returns matching lines with line numbers ## Configuration Environment variables: - `PEEKABOO_RECURSIVE`: Enable recursive listing (default: true, set to 'false' to disable) - `PEEKABOO_MAX_DEPTH`: Maximum recursion depth (default: 10) The root directory is automatically detected based on where peekaboo-mcp is installed and cannot be overridden. ## Resource Limits Default limits (configurable via ServerConfig): - **Timeout**: 30 seconds per operation - **Max file size**: 10MB per file - **Max total size**: 100MB for directory listings Operations that exceed these limits will fail with appropriate error messages. ## Testing Run the test suite: ```bash npm test ``` See [docs/TESTING.md](docs/TESTING.md) for detailed testing information. ## Example Client See [examples/test-client.js](examples/test-client.js) for a complete example of using peekaboo-mcp with the MCP SDK. ## Documentation - [Testing Guide](docs/TESTING.md) - How to run and write tests - [MCP Response Reference](docs/MCP-RESPONSES.md) - Expected server responses - [Example Client](examples/test-client.js) - Working client implementation - [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions - [Contributing](CONTRIBUTING.md) - Development guide ## FAQ **Q: Can I access files outside my project?** A: No, for security reasons peekaboo-mcp only accesses files within the project where it's installed. **Q: How do I search for files?** A: Use the `search_path` tool with glob patterns like `*.js` or `src/**/*.ts`. **Q: What file types are supported?** A: All text files are supported. Binary files are detected but content reading may be limited. **Q: How do I increase file size limits?** A: Configure the server with custom limits - see the API section above.