peekaboo-mcp

Un servidor MCP mínimo que proporciona acceso de solo lectura al sistema de archivos.

Documentación

peekaboo-mcp

Servidor mínimo del Protocolo de Contexto de Modelos (MCP) para acceso de solo lectura al sistema de archivos.

El Problema

Claude Code (o cualquier agente de IA de codificación) a menudo realiza cambios más amplios de lo previsto. Le pides que corrija un error simple y refactoriza la mitad de tu código. Esto ocurre porque Claude Code tiene acceso completo de lectura/escritura a todo en tu directorio de proyecto.

La Solución

Peekaboo-mcp te permite aislar lo que Claude Code (o cualquier agente de IA) puede modificar mientras aún le brinda visibilidad a todo tu código. Simplemente:

Abre tu editor en una carpeta de trabajo pequeña y dedicada
Deja que peekaboo-mcp proporcione acceso de solo lectura a tu proyecto real.

Ahora Claude Code puede ver todo el contexto que necesita pero solo puede modificar archivos en tu espacio de trabajo controlado.

Inicio Rápido

Instala peekaboo-mcp en la raíz de tu proyecto:

cd /path/to/your/project
npm install peekaboo-mcp

Configura tu herramienta de IA:

Para Claude Desktop: Agrega a ~/Library/Application Support/Claude/claude_desktop_config.json (Mac):

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": ["peekaboo-mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Para Claude Code (CLI):

# 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 ✓

Para Cursor.AI: Crea .cursor/mcp.json en tu directorio de inicio o proyecto:

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": ["-y", "peekaboo-mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

O usa la interfaz de Configuración de Cursor:

Abre la Paleta de Comandos (Ctrl/Cmd + Shift + P)
Busca "Cursor Settings"
Navega a la sección de Servidores MCP
Agrega peekaboo-mcp con la ruta del proyecto

Importante: ¡No necesitas iniciar peekaboo manualmente! Claude Desktop, Claude Code y Cursor inician automáticamente el servidor MCP cuando lo necesitan.

Abre SOLO la carpeta en la que quieres que la IA trabaje:

En lugar de abrir todo tu proyecto, abre solo la carpeta específica que deseas modificar:
```
# 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
```
Resultado: La IA ahora puede:
- ✅ Leer TODO tu proyecto (entiende el contexto completo)
- ✅ Solo modificar archivos en /src/components (o cualquier carpeta que hayas abierto)
- ❌ No puede tocar archivos fuera de la carpeta abierta

Características

Lista el contenido del directorio de forma recursiva por defecto
Lee el contenido de archivos con detección de tipo MIME
Busca archivos por patrón de nombre (soporte glob)
Busca contenido dentro de archivos
Acceso estrictamente de solo lectura (sin operaciones de escritura/edición/eliminación)
Protección contra recorrido de rutas
Detección automática de la raíz del proyecto (accede solo al proyecto donde está instalado)
Profundidad de recursión configurable
Gestión de recursos (tiempos de espera, límites de tamaño de archivo)
Cobertura integral de pruebas

Instalación

npm install peekaboo-mcp

Uso

Como servidor independiente

# 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

Nota: peekaboo-mcp detecta y usa automáticamente la raíz del proyecto donde está instalado. No puede acceder a archivos fuera de este proyecto por razones de seguridad.

Como módulo

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);

Configuración del Cliente MCP

Agrega a tu configuración de cliente MCP:

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": ["peekaboo-mcp"]
    }
  }
}

Seguridad

Todo acceso a archivos es estrictamente de solo lectura
La detección automática de la raíz del proyecto previene el acceso fuera del proyecto instalado
El recorrido de rutas por encima de la raíz del proyecto está bloqueado
No se admiten operaciones de escritura, edición o eliminación
Sin directorio raíz configurable por el usuario (previene manipulación por LLMs o actores maliciosos)

API

Recursos

Listar Recursos: Devuelve todos los archivos y directorios desde la raíz (recursivo por defecto)
Leer Recurso: Devuelve el contenido de un archivo específico

Los recursos se acceden mediante URIs file:// relativas a la raíz configurada.

Herramientas

search_path: Busca archivos y directorios por patrón de nombre
- Admite comodines: * (cualquier carácter), ** (cualquier directorio), ? (carácter único)
- Ejemplos: *.ts, src/**/*.js, test-?.md
search_content: Busca contenido dentro de archivos
- Filtro opcional de patrón de archivo
- No distingue entre mayúsculas y minúsculas por defecto
- Devuelve líneas coincidentes con números de línea

Configuración

Variables de entorno:

PEEKABOO_RECURSIVE: Habilita el listado recursivo (predeterminado: true, establece 'false' para deshabilitar)
PEEKABOO_MAX_DEPTH: Profundidad máxima de recursión (predeterminado: 10)

El directorio raíz se detecta automáticamente según dónde esté instalado peekaboo-mcp y no se puede anular.

Límites de Recursos

Límites predeterminados (configurables mediante ServerConfig):

Tiempo de espera: 30 segundos por operación
Tamaño máximo de archivo: 10MB por archivo
Tamaño total máximo: 100MB para listados de directorios

Las operaciones que excedan estos límites fallarán con mensajes de error apropiados.

Pruebas

Ejecuta el conjunto de pruebas:

npm test

Consulta docs/TESTING.md para información detallada sobre pruebas.

Cliente de Ejemplo

Consulta examples/test-client.js para un ejemplo completo de uso de peekaboo-mcp con el SDK de MCP.

Documentación

Guía de Pruebas - Cómo ejecutar y escribir pruebas
Referencia de Respuestas MCP - Respuestas esperadas del servidor
Cliente de Ejemplo - Implementación de cliente funcional
Solución de Problemas - Problemas comunes y soluciones
Contribuciones - Guía de desarrollo

Preguntas Frecuentes

P: ¿Puedo acceder a archivos fuera de mi proyecto?
R: No, por razones de seguridad peekaboo-mcp solo accede a archivos dentro del proyecto donde está instalado.

P: ¿Cómo busco archivos?
R: Usa la herramienta search_path con patrones glob como *.js o src/**/*.ts.

P: ¿Qué tipos de archivo son compatibles?
R: Todos los archivos de texto son compatibles. Los archivos binarios se detectan pero la lectura de contenido puede ser limitada.

P: ¿Cómo aumento los límites de tamaño de archivo?
R: Configura el servidor con límites personalizados - consulta la sección de API anterior.