peekaboo-mcp

peekaboo-mcp

Servidor minimalista do Model Context Protocol (MCP) para acesso somente leitura ao sistema de arquivos.

O Problema

O Claude Code (ou qualquer agente de codificação de IA) frequentemente faz alterações mais amplas do que o pretendido. Você pede para corrigir um bug simples e ele refatora metade do seu código. Isso acontece porque o Claude Code tem acesso total de leitura/escrita a tudo no seu diretório de projeto.

A Solução

O Peekaboo-mcp permite isolar o que o Claude Code (ou qualquer agente de IA) pode modificar, mantendo a visibilidade de todo o seu código. Simplesmente:

1. Abra seu editor em uma pasta de workspace pequena e dedicada
2. Deixe o peekaboo-mcp fornecer acesso somente leitura ao seu projeto real.

Agora o Claude Code pode ver todo o contexto de que precisa, mas só pode modificar arquivos no seu workspace controlado.

Início Rápido

1. Instale o peekaboo-mcp na raiz do seu projeto:

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

2. Configure sua ferramenta de IA:

   Para Claude Desktop: Adicione em ~/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: Crie .cursor/mcp.json no seu diretório inicial ou projeto:

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

   Ou use a interface de Configurações do Cursor:

   • Abra a Paleta de Comandos (Ctrl/Cmd + Shift + P)
   • Pesquise por "Cursor Settings"
   • Navegue até a seção de Servidores MCP
   • Adicione o peekaboo-mcp com o caminho do projeto

   Importante: Você não precisa iniciar o peekaboo manualmente! O Claude Desktop, o Claude Code e o Cursor iniciam automaticamente o servidor MCP quando precisam dele.

3. Abra SOMENTE a pasta em que você quer que a IA trabalhe:

   Em vez de abrir todo o seu projeto, abra apenas a pasta específica que você quer 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: A IA agora pode:

   • ✅ Ler todo o seu projeto (entende o contexto completo)
   • ✅ Modificar apenas arquivos em /src/components (ou qualquer pasta que você abriu)
   • ❌ Não pode tocar em arquivos fora da pasta aberta

Recursos

• Lista o conteúdo de diretórios recursivamente por padrão
• Lê o conteúdo de arquivos com detecção de tipo MIME
• Pesquisa arquivos por padrão de nome (suporte a glob)
• Pesquisa conteúdo dentro de arquivos
• Acesso estritamente somente leitura (sem operações de escrita/edição/exclusão)
• Proteção contra travessia de caminho
• Detecção automática da raiz do projeto (acessa apenas o projeto onde está instalado)
• Profundidade de recursão configurável
• Gerenciamento de recursos (timeouts, limites de tamanho de arquivo)
• Cobertura abrangente de testes

Instalação

npm install peekaboo-mcp

Uso

Como servidor autônomo

# 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: o peekaboo-mcp detecta e usa automaticamente a raiz do projeto onde está instalado. Ele não pode acessar arquivos fora deste projeto por motivos de segurança.

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

Configuração do Cliente MCP

Adicione à configuração do seu cliente MCP:

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

Segurança

• Todo acesso a arquivos é estritamente somente leitura
• A detecção automática da raiz do projeto impede o acesso fora do projeto instalado
• A travessia de caminho acima da raiz do projeto é bloqueada
• Nenhuma operação de escrita, edição ou exclusão é suportada
• Nenhum diretório raiz configurável pelo usuário (impede manipulação por LLMs ou agentes maliciosos)

API

Recursos

1. Listar Recursos: Retorna todos os arquivos e diretórios a partir da raiz (recursivo por padrão)
2. Ler Recurso: Retorna o conteúdo de um arquivo específico

Os recursos são acessados por meio de URIs file:// relativas à raiz configurada.

Ferramentas

1. search_path: Pesquisa arquivos e diretórios por padrão de nome

   • Suporta curingas: * (qualquer caractere), ** (qualquer diretório), ? (um único caractere)
   • Exemplos: *.ts, src/**/*.js, test-?.md

2. search_content: Pesquisa conteúdo dentro de arquivos

   • Filtro opcional de padrão de arquivo
   • Não diferencia maiúsculas de minúsculas por padrão
   • Retorna linhas correspondentes com números de linha

Configuração

Variáveis de ambiente:

• PEEKABOO_RECURSIVE: Ativa a listagem recursiva (padrão: true, defina como 'false' para desativar)
• PEEKABOO_MAX_DEPTH: Profundidade máxima de recursão (padrão: 10)

O diretório raiz é detectado automaticamente com base em onde o peekaboo-mcp está instalado e não pode ser substituído.

Limites de Recursos

Limites padrão (configuráveis via ServerConfig):

• Timeout: 30 segundos por operação
• Tamanho máximo de arquivo: 10MB por arquivo
• Tamanho total máximo: 100MB para listagens de diretórios

Operações que excederem esses limites falharão com mensagens de erro apropriadas.

Testes

Execute a suíte de testes:

npm test

Consulte docs/TESTING.md para informações detalhadas sobre testes.

Exemplo de Cliente

Consulte examples/test-client.js para um exemplo completo de uso do peekaboo-mcp com o SDK MCP.

Documentação

• Guia de Testes - Como executar e escrever testes
• Referência de Respostas MCP - Respostas esperadas do servidor
• Exemplo de Cliente - Implementação funcional de cliente
• Solução de Problemas - Problemas comuns e soluções
• Contribuindo - Guia de desenvolvimento

Perguntas Frequentes

P: Posso acessar arquivos fora do meu projeto?
R: Não, por motivos de segurança o peekaboo-mcp só acessa arquivos dentro do projeto onde está instalado.

P: Como pesquiso arquivos?
R: Use a ferramenta search_path com padrões glob como *.js ou src/**/*.ts.

P: Quais tipos de arquivo são suportados?
R: Todos os arquivos de texto são suportados. Arquivos binários são detectados, mas a leitura de conteúdo pode ser limitada.

P: Como aumento os limites de tamanho de arquivo?
R: Configure o servidor com limites personalizados - consulte a seção de API acima.