MCP Personal

Uma coleção de servidores MCP para diversas ferramentas e utilitários de produtividade pessoal.

Documentação

MCP Personal - Coleção de Servidores MCP Pessoais

Uma coleção de servidores Model Context Protocol (MCP) para diversas ferramentas e utilitários de produtividade pessoal.

Servidores MCP Disponíveis

1. Servidor de Busca de Arquivos (`mcp_fd_server.py`)

Capacidades de busca difusa por NOME de arquivo usando fd e fzf:

Busca rápida por nome de arquivo usando fd (busca nomes/caminhos de arquivos, NÃO conteúdos)
Filtragem difusa de nomes de arquivos com fzf para correspondência inteligente de nomes
Correspondência de padrões com suporte a regex e glob para nomes de arquivos
Limitação de resultados com o parâmetro limit para restringir o número de correspondências
Tratamento adequado de erros para códigos de saída do fzf (distingue "sem correspondências" de erros)
Modo multilinha (avançado): também pode buscar conteúdos de arquivos quando habilitado
CLI independente para testes e uso direto
Ponto-chave: O objetivo principal é encontrar arquivos por NOME, não buscar conteúdos

2. Servidor de Busca Difusa (`mcp_fuzzy_search.py`)

Busca avançada com capacidades tanto de nome de arquivo quanto de conteúdo usando ripgrep e fzf:

Busca difusa por nome de arquivo - encontre arquivos por nomes parciais/difusos
Busca de conteúdo usando ripgrep para buscar texto dentro de arquivos
Filtragem difusa de resultados usando fzf --filter
Tratamento adequado de erros para códigos de saída do fzf (distingue "sem correspondências" de erros)
Dois modos distintos:
- fuzzy_search_files: Busca NOMES/caminhos de arquivos
- fuzzy_search_content: Busca CONTEÚDOS de arquivos com correspondência de caminho+conteúdo por padrão
Busca em PDF e documentos (opcional) - busque em PDFs, documentos Office e arquivos usando ripgrep-all
Extração de páginas de PDF (opcional) - extraia páginas específicas de PDFs usando PyMuPDF com suporte a rótulos de página
Ferramentas de informações de PDF (opcional) - obtenha rótulos de página, contagem de páginas e sumário de arquivos PDF:
- get_pdf_page_labels: Obtenha todos os rótulos de página de um arquivo PDF
- get_pdf_page_count: Obtenha o número total de páginas de um arquivo PDF
- get_pdf_outline: Extraia sumário/marcadores de um arquivo PDF
Interface simplificada - basta fornecer termos de busca difusa (SEM suporte a regex)
Processamento de registros multilinha para correspondência de padrões complexos
CLI independente para testes e uso direto

3. Servidor SQLite (`mcp_sqlite_server.py`)

Operações de banco de dados SQLite com permissões configuráveis de leitura/escrita:

Somente leitura por padrão - Operações de escrita desabilitadas a menos que explicitamente habilitadas
Amigável para agentes - Descrições claras de ferramentas e exemplos para fácil uso por agentes de IA
Suporte a banco de dados em memória - Use :memory: para bancos de dados temporários
Operações abrangentes - Consultar, executar, listar tabelas, descrever esquema, criar tabelas
Recursos de segurança - Validação de consultas, restrições de operações de escrita, mensagens de erro claras
CLI independente para testes e uso direto

4. Servidor de Pensamento Sequencial (`mcp_sequential_thinking.py`)

Resolução de problemas dinâmica e reflexiva através de uma cadeia estruturada de pensamentos — um port em Python do servidor oficial @modelcontextprotocol/server-sequential-thinking:

Resolução dinâmica de problemas — divida problemas complexos em etapas de pensamento discretas e ajustáveis
Revisão de pensamentos — revise pensamentos anteriores quando a compreensão se aprofunda (isRevision / revisesThought)
Ramificação — explore caminhos alternativos de raciocínio a partir de qualquer pensamento anterior (branchFromThought / branchId)
Totais ajustáveis — dimensione totalThoughts para cima ou para baixo durante o processo, ou estenda além da estimativa inicial com needsMoreThoughts
Geração e verificação de hipóteses — gere soluções candidatas e verifique-as contra a cadeia de pensamento
Correção de coerção de strings — aceita entradas de string para campos numéricos (thoughtNumber, totalThoughts) e booleanos (nextThoughtNeeded, isRevision, needsMoreThoughts), funcionando com Claude Code imediatamente. Inclui a correção de modelcontextprotocol/servers#3856, que ainda não foi publicada na versão npm (2025.12.18)
Registro de pensamentos opcional — pensamentos formatados vão para stderr por padrão; defina DISABLE_THOUGHT_LOGGING=true para silenciá-los
Ferramenta única: sequentialthinking

Pré-requisitos

Requisitos Gerais

Python 3.10 ou superior
uv (recomendado) ou pip

Para instalar o uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip (if you already have Python)
pip install uv

Nota sobre Recursos Opcionais

As ferramentas de busca e extração de PDF no Servidor de Busca Difusa são opcionais. O servidor funcionará sem esses binários instalados - apenas as ferramentas específicas de PDF ficarão indisponíveis. Isso permite usar a funcionalidade principal de busca difusa sem exigir todas as dependências.

Requisitos do Servidor de Busca de Arquivos

O servidor de busca de arquivos requer as seguintes ferramentas de linha de comando:

macOS

brew install fd fzf

Ubuntu/Debian

sudo apt install fd-find fzf
# Note: On Debian/Ubuntu, fd is installed as 'fdfind'

Outros Sistemas

Requisitos do Servidor de Busca Difusa

O servidor de busca difusa requer:

macOS

brew install ripgrep fzf

# For PDF search capabilities (optional)
brew install ripgrep-all pandoc
pip install PyMuPDF  # Or: uv pip install PyMuPDF

Ubuntu/Debian

sudo apt install ripgrep fzf

# For PDF search capabilities (optional)
# Install ripgrep-all
cargo install ripgrep-all  # Requires Rust/cargo

# Install PyMuPDF
pip install PyMuPDF  # Or: uv pip install PyMuPDF

# Install pandoc
sudo apt install pandoc

Outros Sistemas

Guia de instalação do ripgrep
Guia de instalação do fzf
Instalação do ripgrep-all (opcional, para busca em PDF)
Instalação do pandoc (opcional, para extração de PDF)

Instalação

Clonar o Repositório

git clone https://github.com/yourusername/mcp-personal.git
cd mcp-personal

Configurar Servidores MCP

Usando a CLI do Claude Code

A maneira mais fácil de adicionar servidores MCP ao Claude Code é usando a CLI:

# Add custom Python servers from this repository
# IMPORTANT: Use -s user for personal tools you want available across all projects
# Without -s flag, servers are only available in current directory and are temporary

# Easy method: Use $(pwd) when in the project directory
cd /path/to/mcp-personal
claude mcp add file-search -s user -- $(pwd)/mcp_fd_server.py
claude mcp add fuzzy-search -s user -- $(pwd)/mcp_fuzzy_search.py
claude mcp add sqlite -s user -- $(pwd)/mcp_sqlite_server.py
claude mcp add sequential-thinking -s user -- $(pwd)/mcp_sequential_thinking.py

# Or use relative paths (also from project directory)
claude mcp add file-search -s user -- ./mcp_fd_server.py
claude mcp add fuzzy-search -s user -- ./mcp_fuzzy_search.py
claude mcp add sqlite -s user -- ./mcp_sqlite_server.py
claude mcp add sequential-thinking -s user -- ./mcp_sequential_thinking.py

# Using absolute paths (works from anywhere)
claude mcp add file-search -s user -- /path/to/mcp-personal/mcp_fd_server.py
claude mcp add fuzzy-search -s user -- /path/to/mcp-personal/mcp_fuzzy_search.py
claude mcp add sqlite -s user -- /path/to/mcp-personal/mcp_sqlite_server.py
claude mcp add sequential-thinking -s user -- /path/to/mcp-personal/mcp_sequential_thinking.py

# Disable thought logging for the sequential thinking server
claude mcp add sequential-thinking -s user -e DISABLE_THOUGHT_LOGGING=true -- /path/to/mcp-personal/mcp_sequential_thinking.py

# Add SQLite server with write permissions enabled
claude mcp add sqlite -s user -- /path/to/mcp-personal/mcp_sqlite_server.py --allow-writes

# Or using environment variable
claude mcp add sqlite -s user -e MCP_SQLITE_ALLOW_WRITES=true -- /path/to/mcp-personal/mcp_sqlite_server.py

# Add Python servers with Python interpreter explicitly
claude mcp add my-server -s user -- python /path/to/my_mcp_server.py

# Add servers with arguments
claude mcp add my-server -s user -- python /path/to/server.py arg1 arg2

# Add servers with environment variables
claude mcp add my-server -s user -e API_KEY=your_key -e DEBUG=true -- python /path/to/server.py

# Scope options:
# -s local (default): Temporary, only in current directory
# -s project: Shared with team via .mcp.json file
# -s user: Personal, available across all your projects (recommended)

Nota:

O separador -- é importante antes do comando e seus argumentos
Variáveis de ambiente usam a sintaxe -e KEY=value
Use -s user para servidores pessoais disponíveis em todos os projetos
Tanto caminhos relativos quanto absolutos funcionam

Configuração Manual (Claude Desktop)

Para Claude Desktop, adicione manualmente os servidores ao ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "file-search": {
      "command": "/path/to/mcp-personal/mcp_fd_server.py"
    },
    "fuzzy-search": {
      "command": "/path/to/mcp-personal/mcp_fuzzy_search.py"
    },
    "sqlite": {
      "command": "/path/to/mcp-personal/mcp_sqlite_server.py",
      "args": ["--allow-writes"],
      "env": {
        "MCP_SQLITE_ALLOW_WRITES": "true"
      }
    },
    "sequential-thinking": {
      "command": "/path/to/mcp-personal/mcp_sequential_thinking.py",
      "env": {
        "DISABLE_THOUGHT_LOGGING": "false"
      }
    }
  }
}

Tornar Scripts Executáveis

# Make all Python scripts executable
chmod +x *.py

Para Desenvolvimento

# Install with development dependencies
uv sync --dev

# Or use make
make setup

Testes e Desenvolvimento

MCP Inspector

O MCP Inspector é uma ferramenta interativa de desenvolvimento para testar e depurar servidores MCP. Ele fornece uma interface baseada na web que permite:

Testar visualmente seus servidores MCP com uma interface interativa
Depurar implementações de servidores examinando fluxos de requisição/resposta
Testar ferramentas, recursos e prompts com diferentes argumentos
Validar o comportamento do servidor antes da implantação

Teste Rápido

Teste qualquer servidor MCP usando o inspector:

# Test the file search server
npx @modelcontextprotocol/inspector ./mcp_fd_server.py

# Test the fuzzy search server  
npx @modelcontextprotocol/inspector ./mcp_fuzzy_search.py

# Test the SQLite server (read-only mode)
npx @modelcontextprotocol/inspector ./mcp_sqlite_server.py

# Test the SQLite server with write permissions
npx @modelcontextprotocol/inspector ./mcp_sqlite_server.py -- --allow-writes

# Test the sequential thinking server
npx @modelcontextprotocol/inspector ./mcp_sequential_thinking.py

# Test the sequential thinking server with thought logging disabled
npx @modelcontextprotocol/inspector -e "DISABLE_THOUGHT_LOGGING=true" ./mcp_sequential_thinking.py

Isso irá:

Iniciar o servidor proxy do MCP Inspector (porta padrão 6277)
Iniciar uma interface web (porta padrão 6274)
Conectar ao seu servidor MCP via transporte stdio
Abrir seu navegador na interface do inspector

Usando o Inspector

Uma vez que o inspector esteja em execução:

Navegue até a interface web (geralmente http://localhost:6274)
Explore as abas:
- Ferramentas: Teste search_files, filter_files, fuzzy_search_files, fuzzy_search_content, fuzzy_search_documents, extract_pdf_pages
- Recursos: Visualize quaisquer recursos expostos (se implementados)
- Prompts: Teste quaisquer prompts expostos (se implementados)
Teste diferentes cenários:
- Experimente vários padrões de busca e filtros
- Teste a funcionalidade multilinha
- Experimente com diferentes caminhos de arquivo e flags
- Teste a busca em PDF com fuzzy_search_documents (se os binários estiverem instalados)
- Teste a extração de páginas de PDF com extract_pdf_pages (se os binários estiverem instalados)
- Valide o tratamento de erros com entradas inválidas

Configuração Avançada

Você também pode usar arquivos de configuração para setups complexos:

# Using a config file
npx @modelcontextprotocol/inspector --config config.json

# Passing environment variables
npx @modelcontextprotocol/inspector -e "DEBUG=1" ./mcp_fuzzy_search.py

# Custom ports
npx @modelcontextprotocol/inspector --mcpp-port 3001 --mcpi-port 3002 ./mcp_fd_server.py

O MCP Inspector é particularmente valioso para:

Prototipagem rápida - teste rapidamente novas funcionalidades
Depuração - identifique problemas antes da integração com Claude
Documentação - entenda exatamente o que seu servidor expõe
Validação - garanta tratamento adequado de erros e casos extremos

Uso

Servidor de Busca de Arquivos

Como Servidor MCP

Uma vez configurado no Claude Desktop, você pode usar linguagem natural para buscar arquivos por NOME:

"Encontre todos os arquivos Python no diretório src" (busca nomes de arquivos terminando em .py)
"Busque arquivos com 'config' no nome" (correspondência difusa de nomes de arquivos)
"Encontre arquivos de teste por nome" (busca arquivos com 'test' no nome)
"Use busca difusa para encontrar 'mainpy'" (encontra main.py, main_py.txt, etc.)

Uso via CLI

O servidor de busca de arquivos também funciona como ferramenta CLI independente:

# Search for files by name pattern
./mcp_fd_server.py search "\.py$" /path/to/search  # Find Python files by name
./mcp_fd_server.py search "\.py$" . --limit 10  # Limit to first 10 results

# Search with additional fd flags
./mcp_fd_server.py search "\.js$" . --flags "--hidden --no-ignore"

# Fuzzy filter file names/paths
./mcp_fd_server.py filter "main" "\.py$" /path/to/search  # Fuzzy search for 'main' in Python file names
./mcp_fd_server.py filter "test" "" . --limit 20  # Find up to 20 test-related files

# Get the best fuzzy match by name
./mcp_fd_server.py filter "app" "" . --first  # Find file with name most similar to 'app'

# Multiline mode - search file CONTENTS (not just names)
./mcp_fd_server.py filter "class function" "" src --multiline  # Find files containing both terms
./mcp_fd_server.py filter "TODO" "" . --multiline --limit 5  # Find first 5 files with TODOs

Servidor de Busca Difusa

Como Servidor MCP

Uma vez configurado no Claude Desktop, você pode usar linguagem natural para buscas avançadas:

"Busque comentários TODO que mencionem 'implement'"
"Encontre todos os arquivos com 'test' no nome usando busca difusa"
"Procure código de tratamento de erros em arquivos Python"
"Busque arquivos de configuração contendo configurações de banco de dados"
"Encontre definições de métodos chamadas 'update_ondemand_max_spend'"
"Busque funções assíncronas com tratamento de erros"
"Busque 'update' apenas em arquivos test.py" (funciona porque o modo padrão também corresponde a caminhos!)
"Busque 'async' apenas no conteúdo, ignore caminhos de arquivos" (use o modo content_only)
"Busque 'vector' em documentos PDF" (requer ripgrep-all)
"Encontre todas as referências a 'machine learning' em PDFs e documentos Word"
"Extraia as páginas 5-10 do PDF do manual do usuário"
"Obtenha o sumário do PDF do artigo de pesquisa"
"Mostre-me o esboço dos capítulos no manual do usuário"

Uso via CLI

O servidor de busca difusa também funciona como ferramenta CLI independente:

# Fuzzy search for file NAMES/PATHS
./mcp_fuzzy_search.py search-files "main" /path/to/search  # Find files with 'main' in the name
./mcp_fuzzy_search.py search-files "test" . --hidden --limit 10  # Find test files by name
./mcp_fuzzy_search.py search-files "config" / --confirm-root  # Search from root (requires explicit confirmation)

# Search file CONTENTS and filter with fzf (NO regex support)
# Default: Matches on BOTH file paths AND content
# Works with both directories and individual files
./mcp_fuzzy_search.py search-content "TODO implement" .  # Find lines containing both terms
./mcp_fuzzy_search.py search-content "test.py: update" .  # Find 'update' in test.py files
./mcp_fuzzy_search.py search-content "function" specific_file.py  # Search within a single file
./mcp_fuzzy_search.py search-content "error handle" src --rg-flags "-i"  # Case insensitive
./mcp_fuzzy_search.py search-content "config" / --confirm-root  # Search from root (requires explicit confirmation)

# Content-only mode: Match ONLY on content, ignore file paths
./mcp_fuzzy_search.py search-content "TODO implement" . --content-only  # Pure content search
./mcp_fuzzy_search.py search-content "async await" src --content-only  # Won't match file paths

# Multiline mode - changes behavior:
# search-files --multiline: Searches file CONTENTS instead of names
./mcp_fuzzy_search.py search-files "class constructor" src --multiline  # Find files CONTAINING these terms

# search-content --multiline: Treats whole files as searchable units
./mcp_fuzzy_search.py search-content "async await" . --multiline  # Find files with both terms anywhere
./mcp_fuzzy_search.py search-content "try catch" . --multiline --content-only  # Content-only + multiline

# PDF and document search (requires optional binaries)
./mcp_fuzzy_search.py search-documents "machine learning" .  # Search PDFs and docs
./mcp_fuzzy_search.py search-documents "invoice total" invoices/ --file-types "pdf"  # PDFs only
./mcp_fuzzy_search.py search-documents "contract" . --file-types "pdf,docx" --limit 5
./mcp_fuzzy_search.py search-documents "report" / --confirm-root  # Search from root (requires explicit confirmation)

# Extract specific pages from PDFs (using PyMuPDF)
./mcp_fuzzy_search.py extract-pdf manual.pdf "1,3,5-7"  # Extract pages 1, 3, 5, 6, 7
./mcp_fuzzy_search.py extract-pdf report.pdf "v-vii,1,ToC"  # Use page labels
./mcp_fuzzy_search.py extract-pdf report.pdf "10-20" --format html  # Extract as HTML
./mcp_fuzzy_search.py extract-pdf thesis.pdf "100-105" --preserve-layout  # Keep layout
./mcp_fuzzy_search.py extract-pdf book.pdf "1-50" --fuzzy-hint "neural network"  # Filter by content
./mcp_fuzzy_search.py extract-pdf book.pdf "0,266-273" --zero-based  # 0-based indices (pages 1, 267-274)
./mcp_fuzzy_search.py extract-pdf book.pdf "1-50" --one-based  # 1-based indices (pages 1-50)

# Get PDF information
./mcp_fuzzy_search.py page-labels manual.pdf  # List all page labels
./mcp_fuzzy_search.py page-labels manual.pdf --start 100 --limit 20  # Get labels for pages 100-119
./mcp_fuzzy_search.py page-count manual.pdf  # Get total page count
./mcp_fuzzy_search.py pdf-outline manual.pdf  # Get table of contents
./mcp_fuzzy_search.py pdf-outline manual.pdf --max-depth 2  # Limit to 2 levels
./mcp_fuzzy_search.py pdf-outline manual.pdf --fuzzy-filter "chapter"  # Filter by title
./mcp_fuzzy_search.py pdf-outline manual.pdf --no-simple  # Detailed output with links

Servidor SQLite

Como Servidor MCP

Uma vez configurado no Claude Desktop, você pode usar linguagem natural para operações de banco de dados:

"Liste todas as tabelas no banco de dados"
"Mostre-me o esquema da tabela de usuários"
"Consulte os últimos 10 pedidos da tabela de pedidos"
"Conte usuários ativos no banco de dados"
"Atualize o status do usuário para inativo para usuários que não fizeram login há um ano" (requer permissões de escrita)
"Crie uma nova tabela para armazenar dados de sessão" (requer permissões de escrita)

Uso via CLI

O servidor SQLite também funciona como ferramenta CLI independente:

# Query database (read-only operations)
./mcp_sqlite_server.py query "SELECT * FROM users" database.db
./mcp_sqlite_server.py query "SELECT COUNT(*) as total FROM orders WHERE status = 'active'" sales.db

# List all tables
./mcp_sqlite_server.py list-tables database.db

# Describe table schema
./mcp_sqlite_server.py describe-table users database.db

# Execute write operations (requires --allow-writes flag)
./mcp_sqlite_server.py execute "INSERT INTO users (name, email) VALUES ('John', 'john@example.com')" database.db --allow-writes
./mcp_sqlite_server.py execute "UPDATE users SET active = 0 WHERE last_login < date('now', '-1 year')" database.db --allow-writes

# Use in-memory database for testing
./mcp_sqlite_server.py query "SELECT sqlite_version()" :memory:

Servidor de Pensamento Sequencial

Como Servidor MCP

Uma vez configurado, Claude pode invocar sequentialthinking para trabalhar em problemas em etapas explícitas e revisáveis. Prompts em linguagem natural que o acionam:

"Pense passo a passo sobre como projetar esta camada de cache"
"Use pensamento sequencial para depurar por que este teste é instável"
"Divida esta refatoração em pensamentos e revise conforme avança"
"Planeje a migração com a ferramenta de pensamento sequencial, ramificando se você vir alternativas"

Cada chamada registra um pensamento e retorna o estado atual (thoughtNumber, totalThoughts, nextThoughtNeeded, branches ativo e thoughtHistoryLength). Claude continua chamando a ferramenta — revisando, ramificando ou estendendo o total conforme necessário — até que nextThoughtNeeded seja falso.

Registro

Por padrão, pensamentos formatados são impressos em stderr conforme chegam (útil ao executar o servidor interativamente ou através do MCP Inspector). Defina DISABLE_THOUGHT_LOGGING=true no ambiente para silenciar o registro mantendo a saída estruturada da ferramenta intacta.

# Run with thought logging disabled
DISABLE_THOUGHT_LOGGING=true ./mcp_sequential_thinking.py

Modo de Busca Multilinha

Ambos os servidores MCP suportam modo de busca multilinha que altera o comportamento da busca:

O que é o Modo Multilinha?

Comportamento padrão (multiline=false):

Servidor de Busca de Arquivos: Busca apenas NOMES/CAMINHOS de arquivos
Servidor de Busca Difusa: Busca linha por linha dentro dos conteúdos dos arquivos

Com modo multilinha (multiline=true):

Servidor de Busca de Arquivos: Muda para buscar CONTEÚDOS de arquivos em vez de nomes
Servidor de Busca Difusa: Trata o conteúdo inteiro do arquivo como unidades únicas de busca

Quando Usar o Modo Multilinha

O modo multilinha serve para pesquisar o CONTEÚDO de arquivos (não os nomes):

Encontrar definições de classes com seus métodos: "class UserService authenticate" (correspondência difusa no conteúdo)
Localizar implementações de funções: "async function await fetch" (todos os termos em um arquivo)
Pesquisar blocos de configuração: "database host port" (encontra arquivos contendo todos os termos)
Encontrar estruturas de código entre linhas: "try catch finally" (correspondências difusas entre linhas)
Importante: Isso pesquisa o CONTEÚDO, não os nomes de arquivos!

Exemplos de Multilinha

Servidor de Pesquisa de Arquivos Multilinha (Pesquisa de Conteúdo)

# With --multiline, searches file CONTENTS instead of names
# Find files CONTAINING these terms (not in file names)
./mcp_fd_server.py filter "class constructor method" "" src --multiline

# Find Python files CONTAINING specific patterns  
./mcp_fd_server.py filter "class def return" "" . --multiline

# Find files CONTAINING database configuration
./mcp_fd_server.py filter "database host password" "" config --multiline

Servidor de Pesquisa Difusa Multilinha

# search-files with --multiline searches file CONTENTS (not names)
./mcp_fuzzy_search.py search-files "async function await" src --multiline

# search-content with --multiline treats files as single units
./mcp_fuzzy_search.py search-content "try catch finally" . --multiline

# Find files CONTAINING class definitions with specific methods
./mcp_fuzzy_search.py search-content "class constructor render" src --multiline

Considerações de Desempenho

Tamanho do arquivo: O modo multilinha lê arquivos inteiros na memória; melhor para arquivos de código-fonte típicos
Tamanho do resultado: Resultados multilinha incluem o conteúdo completo do arquivo, que pode ser truncado para exibição
Complexidade do padrão: Padrões difusos simples funcionam bem; consultas complexas podem ser mais lentas

Dicas para Consultas Multilinha

Use termos específicos: "class MyClass def method" é melhor do que apenas "class def" (sem regex!)
Combine estrutura e conteúdo: "import React export default" encontra componentes React
Atenção à saída: Os resultados mostram o conteúdo completo do arquivo correspondente
Teste incrementalmente: Comece com padrões simples e refine

Guia de Sintaxe de Pesquisa fzf

Ambos os servidores MCP usam a sintaxe de pesquisa estendida do fzf para filtragem difusa poderosa. Entender essa sintaxe ajudará você a construir consultas precisas.

IMPORTANTE: O parâmetro fuzzy_filter em fuzzy_search_content NÃO suporta expressões regulares. Ele usa a sintaxe de correspondência difusa do fzf, conforme descrito abaixo. Se você precisar de padrões semelhantes a regex, use as âncoras de posição e os recursos de correspondência exata da sintaxe do fzf.

Sintaxe Básica

Padrão	Descrição	Exemplo
`term`	Correspondência difusa (padrão)	`config` corresponde a "configuration"
`term1 term2`	Lógica E (todos os termos devem corresponder)	`main config` exige ambos os termos
`term1 \| term2`	Lógica OU (qualquer termo pode corresponder)	`py$ \| js$ \| go$` corresponde a arquivos terminando em qualquer um

Correspondência Exata

Padrão	Descrição	Exemplo
`'term`	Correspondência exata parcial	`'main` corresponde exatamente à substring "main"
`'term'`	Correspondência exata de limite	`'main.py'` corresponde exatamente nos limites de palavras

Âncoras de Posição

Padrão	Descrição	Exemplo
`^term`	Correspondência de prefixo (começa com)	`^src` corresponde a "src/file.py"
`term$`	Correspondência de sufixo (termina com)	`.json$` corresponde a "config.json"
`^term$`	Correspondência exata (string inteira)	`^README$` corresponde apenas a "README"

Negação (Exclusão)

Padrão	Descrição	Exemplo
`!term`	Excluir correspondências difusas	`config !test` exclui arquivos de teste
`!'term`	Excluir correspondências exatas	`!'backup'` exclui arquivos com "backup" exato
`!^term`	Excluir correspondências de prefixo	`!^.` exclui arquivos ocultos
`!term$`	Excluir correspondências de sufixo	`!.tmp$` exclui arquivos temporários

Exemplos Avançados

Nota: Estes exemplos mostram como obter filtragem semelhante a regex SEM usar expressões regulares, já que fuzzy_filter não suporta regex.

# Find Python configuration files, excluding tests
config .py$ !test

# Find main files in src directory with multiple extensions  
^src/ main py$ | js$ | go$

# Find exact package manager files
'package.json' | 'yarn.lock' | 'Pipfile'

# Find TODO comments in code files, excluding documentation
TODO .py$ | .js$ | .go$ !README !docs/

# Find function definitions, excluding test files
'def ' .py$ !test !spec

# Find configuration files with specific extensions, excluding backups
config .json$ | .yaml$ | .toml$ !.bak$ !.old$

Padrões Específicos de Pesquisa de Conteúdo

Ao usar fuzzy_search_content, as consultas funcionam no formato file:line:content:

Modo Padrão (corresponde a caminhos de arquivo E conteúdo):

# Find implementation TODOs in specific file types
TODO implement .py: | .js:  # Matches TODO in .py or .js files

# Find error handling in specific files
error 'main.py:' | 'app.js:'  # Matches 'error' in main.py or app.js

# Find updates in test files
test.py: update  # Matches 'update' in files named test.py

# Find async functions with error handling
'async def' error .py$  # Matches in Python files

Modo Somente Conteúdo (ignora caminhos de arquivo):

# With --content-only flag or content_only=true parameter
# These will ONLY match the content, not file names:

# Find TODO comments regardless of filename
TODO implement  # Won't match files named 'TODO.txt'

# Find async/await patterns
async await catch  # Pure content search

# Find class definitions
'class ' 'def __init__'  # Won't match 'class.py' filename

Referência de Flags do ripgrep (rg)

A ferramenta fuzzy_search_content aceita rg_flags para pesquisa aprimorada. Aqui estão as flags mais úteis:

Sensibilidade a Maiúsculas/Minúsculas

Flag	Descrição	Exemplo
`-i, --ignore-case`	Pesquisa sem diferenciar maiúsculas/minúsculas	`rg -i "todo"` corresponde a TODO, Todo, todo
`-S, --smart-case`	Sem diferenciar se minúsculas, diferenciar se misturado	`rg -S "Todo"` diferencia maiúsculas/minúsculas
`-s, --case-sensitive`	Forçar diferenciação de maiúsculas/minúsculas (padrão)	`rg -s "TODO"` corresponde apenas a TODO

Filtragem por Tipo de Arquivo

Flag	Descrição	Exemplo
`-t TYPE`	Pesquisar apenas tipos de arquivo específicos	`-t py` pesquisa apenas arquivos Python
`-T TYPE`	Excluir tipos de arquivo específicos	`-T test` exclui arquivos de teste
`--type-list`	Mostrar todos os tipos de arquivo suportados	`rg --type-list`

Linhas de Contexto

Flag	Descrição	Exemplo
`-A NUM`	Mostrar NUM linhas após a correspondência	`-A 3` mostra 3 linhas depois
`-B NUM`	Mostrar NUM linhas antes da correspondência	`-B 2` mostra 2 linhas antes
`-C NUM`	Mostrar NUM linhas antes e depois	`-C 3` mostra 3 linhas de ambos os lados

Manipulação de Arquivos

Flag	Descrição	Exemplo
`--hidden`	Pesquisar arquivos/diretórios ocultos	`--hidden` inclui arquivos .hidden
`--no-ignore`	Ignorar regras do .gitignore	`--no-ignore` pesquisa arquivos ignorados
`-u`	Reduzir filtragem (1-3 vezes)	`-uu` = `--no-ignore --hidden`

Correspondência de Padrões

Flag	Descrição	Exemplo
`-F`	Pesquisa de string literal (sem regex)	`-F` pesquisa texto exato
`-w`	Corresponder apenas palavras inteiras	`-w` não corresponde palavras parciais
`-v`	Inverter correspondência (mostrar não correspondências)	`-v` mostra linhas sem correspondências
`-x`	Corresponder apenas linhas inteiras	`-x` corresponde linha exata

Recursos Avançados

Flag	Descrição	Exemplo
`-U`	Habilitar correspondência multilinha	`-U` (nota: use o parâmetro multilinha em vez disso)
`-P`	Usar mecanismo regex PCRE2	`-P` para recursos avançados de regex
`-o`	Mostrar apenas partes correspondentes	`-o` mostra apenas o texto correspondente

Controle de Saída

Flag	Descrição	Exemplo
`-c`	Contar correspondências por arquivo	`-c` mostra apenas a contagem
`-l`	Mostrar apenas nomes de arquivos com correspondências	`-l` lista arquivos com correspondências
`--column`	Mostrar números de coluna	`--column` inclui informações de coluna

Combinações Práticas

# Case-insensitive search with context in Python files
rg_flags: "-i -C 3 -t py"

# Search all files including hidden and ignored, with context
rg_flags: "-uu -C 2"

# Find exact function signatures in code files
rg_flags: "-F -w -t py -t js -t go"

# Search for TODOs with file types, case insensitive, show context
rg_flags: "-i -C 1 -t py -t js --no-ignore"

# Multi-line class definitions with context
rg_flags: "-U -C 3 -t py"

# Literal string search in all text files
rg_flags: "-F --no-ignore -t txt -t md -t rst"

Documentação das Ferramentas MCP

Ferramentas do Servidor de Pesquisa de Arquivos

`search_files`

Encontre arquivos por NOME usando fd com padrões regex ou glob.

Propósito: Pesquisar arquivos quando você conhece padrões exatos, extensões ou regex para NOMES de arquivos.

Parâmetros:

pattern (obrigatório): Padrão regex ou glob para corresponder nomes de arquivos
path (opcional): Diretório para pesquisar (padrão: diretório atual)
limit (opcional): Número máximo de resultados a retornar (padrão: 0 = sem limite)
flags (opcional): Flags adicionais para passar ao fd

Exemplo:

{
  "pattern": r"\.py$",  # Find files with names ending in .py
  "path": "/home/user/projects",
  "flags": "--hidden --no-ignore"
}

`filter_files`

Pesquisa difusa por NOME de arquivos usando a correspondência difusa do fzf.

Propósito: Encontrar arquivos quando você conhece apenas NOMES parciais ou aproximados.

Parâmetros:

filter (obrigatório): String de pesquisa difusa para corresponder a nomes/caminhos de arquivos
pattern (opcional): Padrão inicial para fd pré-filtrar
path (opcional): Diretório para pesquisar
first (opcional): Retornar apenas a melhor correspondência
limit (opcional): Número máximo de resultados a retornar (padrão: 0 = sem limite)
fd_flags (opcional): Flags extras para fd
fzf_flags (opcional): Flags extras para fzf
multiline (opcional): Quando verdadeiro, pesquisa o CONTEÚDO dos arquivos em vez dos nomes (padrão: falso)

Nota: Quando ambos first e limit são fornecidos, first tem precedência e retorna apenas a melhor correspondência.

Exemplo (Pesquisa por Nome de Arquivo):

{
  "filter": "test",  # Fuzzy match 'test' in file names
  "pattern": r"\.py$",  # Only Python files
  "path": "./src",
  "first": true
}

Exemplo Multilinha (Pesquisa de Conteúdo):

{
  "filter": "class function return",  # Find files containing all these terms
  "pattern": "",
  "path": "./src",
  "multiline": true  # Search CONTENTS, not names
}

Ferramentas do Servidor de Pesquisa Difusa

`fuzzy_search_files`

Pesquise NOMES/CAMINHOS de arquivos usando correspondência difusa.

Propósito: Encontrar arquivos por NOME quando você conhece apenas nomes parciais (ex.: "mainpy" encontra "main.py").

Parâmetros:

fuzzy_filter (obrigatório): String de pesquisa difusa para nomes/caminhos de arquivos
path (opcional): Diretório para pesquisar (padrão: diretório atual)
hidden (opcional): Incluir arquivos ocultos (padrão: falso)
limit (opcional): Máximo de resultados a retornar (padrão: 20)
multiline (opcional): Quando verdadeiro, pesquisa o CONTEÚDO dos arquivos em vez dos nomes (padrão: falso)
confirm_root (opcional): Permitir pesquisa a partir do diretório raiz (/) (padrão: falso)

Exemplo (Pesquisa por Nome de Arquivo):

{
  "fuzzy_filter": "main",  # Finds main.py, main.js, domain.py, etc.
  "path": "/home/user/projects",
  "hidden": true,
  "limit": 10
}

Exemplo Multilinha (Pesquisa de Conteúdo):

{
  "fuzzy_filter": "import export",  # Find files containing both terms
  "path": "./src",
  "multiline": true,  # Search CONTENTS, not names
  "limit": 5
}

`fuzzy_search_content`

Pesquise conteúdos de arquivos com filtragem difusa, correspondendo a AMBOS caminhos de arquivo E conteúdo por padrão.

Propósito: Encontrar texto/código específico usando pesquisa difusa que considera tanto onde está (caminho) quanto o que é (conteúdo). Funciona consistentemente com diretórios e arquivos individuais.

Parâmetros:

fuzzy_filter (obrigatório): Consulta de pesquisa difusa para filtragem (NÃO suporta regex - use sintaxe fzf)
path (opcional): Diretório/arquivo para pesquisar (padrão: diretório atual)
- Suporte aprimorado a caminhos de arquivo: Agora pode pesquisar diretórios e arquivos individuais
- Inclui automaticamente o nome do arquivo na saída ao pesquisar um único arquivo para resultados consistentes
hidden (opcional): Pesquisar arquivos ocultos (padrão: falso)
limit (opcional): Máximo de resultados a retornar (padrão: 20)
rg_flags (opcional): Flags extras para ripgrep (veja a referência de flags do ripgrep)
multiline (opcional): Habilitar processamento de registros multilinha (padrão: falso)
content_only (opcional): Corresponder APENAS no conteúdo, ignorar caminhos de arquivo (padrão: falso)
confirm_root (opcional): Permitir pesquisa a partir do diretório raiz (/) (padrão: falso)

Comportamento de Correspondência:

Padrão (content_only=false): Corresponde a AMBOS caminhos de arquivo E conteúdo (ignora números de linha)
- É por isso que "test.py: update" encontra "update" em arquivos test.py - corresponde ao caminho!
- Pesquisar "src TODO" encontra comentários TODO em arquivos sob o diretório src/
- Até mesmo apenas "update" corresponderá a arquivos chamados "update.py" OU contendo "update"
Com content_only=true: Corresponde APENAS no conteúdo, ignorando completamente caminhos de arquivo
- Pesquisa de conteúdo puro - "update" não corresponderá ao nome de arquivo "update.py", apenas ao conteúdo

Exemplo (Padrão - Caminho + Conteúdo):

{
  "fuzzy_filter": "test.py: TODO implement",  # Find TODOs in test.py files
  "path": "./src",
  "rg_flags": "-i",
  "limit": 15
}

Exemplo (Pesquisa em Arquivo Único):

{
  "fuzzy_filter": "function async",  # Find async functions in a specific file
  "path": "./src/main.py",  # Search within a single file
  "limit": 10
}

Exemplo (Somente Conteúdo):

{
  "fuzzy_filter": "async await catch",  # Find these terms in content only
  "path": "./src",
  "content_only": true,  # Ignore file paths in matching
  "limit": 10
}

`fuzzy_search_documents`

Pesquise em PDFs e outros formatos de documentos usando ripgrep-all (requer binários opcionais).

Propósito: Pesquisar PDFs, documentos do Office, arquivos compactados e outros formatos binários que a pesquisa de texto regular não consegue manipular.

Parâmetros:

fuzzy_filter (obrigatório): Consulta de pesquisa difusa para conteúdo de documentos
path (opcional): Diretório/arquivo para pesquisar (padrão: diretório atual)
file_types (opcional): Tipos de arquivo separados por vírgula para pesquisar (ex.: "pdf,docx,epub")
preview (opcional): Incluir contexto de pré-visualização (padrão: verdadeiro)
limit (opcional): Máximo de resultados a retornar (padrão: 20)
confirm_root (opcional): Permitir pesquisa a partir do diretório raiz (/) (padrão: falso)

Exemplo:

{
  "fuzzy_filter": "machine learning algorithm",
  "path": "./research",
  "file_types": "pdf,epub",
  "limit": 10
}

Retorna:

{
  "matches": [
    {
      "file": "/path/to/document.pdf",
      "line": 0,
      "content": "topology.",  # Content without "Page N: " prefix
      "match_text": "topology",
      "page": 542,  # 1-based page number (from ripgrep-all)
      "page_index_0based": 541,  # 0-based page index for programmatic access
      "page_label": "19"  # Actual PDF page label (only for PDFs with PyMuPDF)
    }
  ]
}

Nota: Para arquivos PDF, a ferramenta retorna:

page: O número da página baseado em 1 do ripgrep-all (ex.: 542 significa a 542ª página)
page_index_0based: O índice da página baseado em 0 para acesso programático (ex.: 541 para a página 542)
page_label: O rótulo real da página como exibido nos leitores de PDF (ex.: "vii", "ToC", "19")

O campo de conteúdo não inclui mais o prefixo "Página N: " para uma saída mais limpa.

`extract_pdf_pages`

Extraia páginas específicas de um PDF e converta para vários formatos usando PyMuPDF.

Propósito: Extrair páginas individuais ou intervalos de páginas de PDFs com suporte a rótulos/aliases de página como aparecem nos leitores de PDF.

Parâmetros:

file (obrigatório): Caminho para o arquivo PDF
pages (obrigatório): Especificações de página separadas por vírgula - suporta:
- Rótulos de página: "v", "vii", "ToC", "Introdução" (como exibido nos leitores de PDF)
- Intervalos de páginas: "v-vii", "1-5"
- Páginas físicas: "1", "14" (baseado em 1 se não encontrado como rótulo)
- Misto: "v,vii,1,5-8,ToC"
format (opcional): Formato de saída - markdown, html, plain (padrão: markdown)
preserve_layout (opcional): Tentar preservar o layout original (padrão: false)
clean_html (opcional): Remover tags de estilo HTML como <span style="..."> (padrão: true)
fuzzy_hint (opcional): String de busca difusa para filtrar páginas extraídas por conteúdo
zero_based (opcional): Interpretar números de página como índices baseados em 0 (padrão: false)
- Quando true, todos os números são tratados como índices de página diretos baseados em 0
- "0" = primeira página, "266" = 267ª página, "0-4" = primeiras 5 páginas
- Nenhuma busca por rótulo de página é realizada quando isso é true
- Não pode ser usado junto com one_based
one_based (opcional): Interpretar números de página como índices baseados em 1 (padrão: false)
- Quando true, todos os números são tratados como índices de página diretos baseados em 1
- "1" = primeira página, "267" = 267ª página, "1-5" = primeiras 5 páginas
- Nenhuma busca por rótulo de página é realizada quando isso é true
- Não pode ser usado junto com zero_based

Exemplo:

{
  "file": "research_paper.pdf",
  "pages": "v-vii,1,5-10,ToC",  # Mix of page labels and numbers
  "format": "markdown",
  "clean_html": true,
  "fuzzy_hint": "neural network"  # Only include pages mentioning this
}

# Example with zero_based=true
{
  "file": "research_paper.pdf",
  "pages": "0,266-273",  # Direct 0-based indices: page 1 and pages 267-274
  "zero_based": true
}

# Example with one_based=true
{
  "file": "research_paper.pdf",
  "pages": "1,267-274",  # Direct 1-based indices: pages 1, 267-274
  "one_based": true
}

`get_pdf_page_labels`

Obtenha todos os rótulos de página de um arquivo PDF.

Propósito: Retorna um mapeamento de índices de página para seus rótulos/aliases como exibido nos leitores de PDF, útil para entender os rótulos de página disponíveis antes da extração.

Parâmetros:

file (obrigatório): Caminho para o arquivo PDF
start (opcional): Índice inicial baseado em 0 para fatiar resultados (padrão: 0)
limit (opcional): Número máximo de rótulos a retornar (padrão: todas as páginas)

Exemplo:

{
  "file": "research_paper.pdf"
}

# Returns something like:
{
  "page_labels": {
    "0": "Cover",
    "1": "i",
    "2": "ii", 
    "3": "iii",
    "4": "iv",
    "5": "v",
    "6": "vi",
    "7": "vii",
    "8": "viii",
    "9": "1",
    "10": "2",
    "11": "3"
  },
  "page_count": 150
}

# Example with slicing:
{
  "file": "research_paper.pdf",
  "start": 100,
  "limit": 20
}

# Returns subset like:
{
  "page_labels": {
    "100": "87",
    "101": "88",
    "102": "89",
    "103": "90",
    "104": "91"
    # ... up to 20 entries
  },
  "page_count": 150
}

`get_pdf_page_count`

Obtenha o número total de páginas em um arquivo PDF.

Propósito: Retorna a contagem total de páginas, útil para entender o tamanho do documento antes da extração.

Parâmetros:

file (obrigatório): Caminho para o arquivo PDF

Exemplo:

{
  "file": "research_paper.pdf"
}

# Returns:
{
  "page_count": 150
}

`get_pdf_outline`

Extraia o sumário (estrutura/marcadores) de um arquivo PDF.

Propósito: Retorna a estrutura hierárquica do sumário com níveis, títulos, números de página e rótulos de página, útil para navegar em PDFs complexos e entender a estrutura do documento.

Parâmetros:

file (obrigatório): Caminho para o arquivo PDF
simple (opcional): Retornar informações básicas (padrão: true) ou informações detalhadas com dados de link (false)
max_depth (opcional): Profundidade máxima para percorrer na hierarquia do sumário (padrão: ilimitado)
fuzzy_filter (opcional): String de busca difusa para filtrar entradas do sumário por título usando fzf

Exemplo:

{
  "file": "research_paper.pdf"
}

# Returns (simple mode):
{
  "outline": [
    [1, "Introduction", 1, "i"],
    [1, "Chapter 1: Background", 5, "1"],
    [2, "1.1 History", 6, "2"],
    [2, "1.2 Related Work", 10, "6"],
    [1, "Chapter 2: Methods", 15, "11"],
    [2, "2.1 Data Collection", 16, "12"],
    [3, "2.1.1 Sources", 17, "13"],
    [2, "2.2 Analysis", 20, "16"]
  ],
  "total_entries": 8,
  "max_depth_found": 3
}

# Example with filtering:
{
  "file": "research_paper.pdf",
  "fuzzy_filter": "chapter"
}

# Returns:
{
  "outline": [
    [1, "Chapter 1: Background", 5, "1"],
    [1, "Chapter 2: Methods", 15, "11"]
  ],
  "total_entries": 8,
  "max_depth_found": 3,
  "filtered_count": 2
}

# Example with detailed output:
{
  "file": "research_paper.pdf",
  "simple": false,
  "max_depth": 2
}

# Returns:
{
  "outline": [
    [1, "Introduction", 1, "i", {
      "page": 1,
      "uri": "#page=1&zoom=100,0,0",
      "is_external": false,
      "is_open": true,
      "dest": {
        "kind": 1,
        "page": 0,
        "uri": "#page=1&zoom=100,0,0"
      }
    }],
    # ... more entries with link details
  ],
  "total_entries": 8,
  "max_depth_found": 2
}

Formato do Sumário:

Modo simples retorna: [level, title, page, page_label]
- level: Nível da hierarquia (baseado em 1, 1 = nível superior)
- title: O título da entrada do marcador/sumário
- page: Número da página (baseado em 1)
- page_label: Rótulo da página como exibido nos leitores de PDF (ex.: "i", "ii", "1", "ToC")
O modo detalhado adiciona um 5º elemento com informações de link incluindo detalhes de destino

Ferramentas do Servidor SQLite

`query`

Execute consultas SELECT no banco de dados.

Parâmetros:

query (obrigatório): Consulta SELECT a executar
db_path (opcional): Caminho para o banco de dados SQLite (padrão: db_path configurado ou ':memory:')

Exemplo:

{
  "query": "SELECT * FROM users WHERE active = 1 ORDER BY created_at DESC LIMIT 10",
  "db_path": "myapp.db"
}

`execute`

Execute consultas INSERT, UPDATE ou DELETE (requer permissões de escrita).

Parâmetros:

query (obrigatório): Consulta INSERT, UPDATE ou DELETE a executar
db_path (opcional): Caminho para o banco de dados SQLite

Exemplo:

{
  "query": "UPDATE users SET last_login = datetime('now') WHERE id = 123",
  "db_path": "myapp.db"
}

`list_tables`

Liste todas as tabelas no banco de dados.

Parâmetros:

db_path (opcional): Caminho para o banco de dados SQLite

Exemplo:

{
  "db_path": "myapp.db"
}

`describe_table`

Obtenha informações detalhadas do esquema para uma tabela específica, incluindo colunas, tipos, restrições e índices.

Parâmetros:

table_name (obrigatório): Nome da tabela a descrever
db_path (opcional): Caminho para o banco de dados SQLite

Exemplo:

{
  "table_name": "users",
  "db_path": "myapp.db"
}

`create_table`

Crie uma nova tabela com colunas especificadas (requer permissões de escrita).

Parâmetros:

table_name (obrigatório): Nome da tabela a criar
columns (obrigatório): Lista de definições de colunas
db_path (opcional): Caminho para o banco de dados SQLite

Definição de Coluna:

name (obrigatório): Nome da coluna
type (obrigatório): Tipo de dado SQLite (TEXT, INTEGER, REAL, BLOB, etc.)
constraints (opcional): Restrições da coluna (PRIMARY KEY, NOT NULL, UNIQUE, etc.)

Exemplo:

{
  "table_name": "sessions",
  "columns": [
    {
      "name": "id",
      "type": "TEXT",
      "constraints": "PRIMARY KEY"
    },
    {
      "name": "user_id",
      "type": "INTEGER",
      "constraints": "NOT NULL"
    },
    {
      "name": "created_at",
      "type": "TIMESTAMP",
      "constraints": "DEFAULT CURRENT_TIMESTAMP"
    },
    {
      "name": "expires_at",
      "type": "TIMESTAMP",
      "constraints": "NOT NULL"
    }
  ],
  "db_path": "myapp.db"
}

Ferramentas do Servidor de Pensamento Sequencial

`sequentialthinking`

Registre um único passo em uma cadeia de pensamentos dinâmica e revisável. Chame repetidamente — revisando, ramificando ou estendendo o total — até que nextThoughtNeeded seja false.

Parâmetros:

thought (obrigatório, string): O passo de pensamento atual. Pode ser um passo analítico, uma revisão de um pensamento anterior, uma pergunta, uma hipótese ou uma verificação.
nextThoughtNeeded (obrigatório, booleano): Se outro passo de pensamento é necessário. Aceita true/false ou as strings "true"/"false".
thoughtNumber (obrigatório, inteiro ≥ 1): Número atual do pensamento na sequência. Aceita valores numéricos ou strings numéricas.
totalThoughts (obrigatório, inteiro ≥ 1): Estimativa atual do total de pensamentos necessários. Pode ser ajustada para cima ou para baixo entre chamadas. Aceita valores numéricos ou strings numéricas.
isRevision (opcional, booleano): Se este pensamento revisa um anterior.
revisesThought (opcional, inteiro ≥ 1): Quando isRevision é true, o número do pensamento sendo reconsiderado.
branchFromThought (opcional, inteiro ≥ 1): Ao ramificar, o número do pensamento do qual este ramo diverge.
branchId (opcional, string): Identificador para o ramo atual.
needsMoreThoughts (opcional, booleano): Defina como true se você chegar ao fim mas perceber que mais pensamentos são necessários.

Saída (estruturada):

thoughtNumber, totalThoughts, nextThoughtNeeded, branches (lista de IDs de ramos ativos), thoughtHistoryLength.

Exemplo:

{
  "thought": "First, I need to map out the failure modes before proposing a fix.",
  "nextThoughtNeeded": true,
  "thoughtNumber": 1,
  "totalThoughts": 5
}

Exemplo de revisão:

{
  "thought": "Reconsidering thought 2 — the retry logic is actually the root cause, not the timeout.",
  "nextThoughtNeeded": true,
  "thoughtNumber": 4,
  "totalThoughts": 6,
  "isRevision": true,
  "revisesThought": 2
}

Exemplo de ramificação:

{
  "thought": "Alternative approach: skip the cache entirely and hit the DB directly.",
  "nextThoughtNeeded": true,
  "thoughtNumber": 5,
  "totalThoughts": 7,
  "branchFromThought": 3,
  "branchId": "no-cache"
}

Nota: Todos os campos numéricos e booleanos também aceitam entradas de string (ex.: "1", "true"). Esta é a correção de modelcontextprotocol/servers#3856 e é o que torna o servidor utilizável a partir do Claude Code, que às vezes serializa esses campos como strings.

Desenvolvimento

Estrutura do Projeto

mcp-personal/
├── mcp_fd_server.py            # File search MCP server
├── mcp_fuzzy_search.py         # Fuzzy content search MCP server
├── mcp_sqlite_server.py        # SQLite database MCP server
├── mcp_sequential_thinking.py  # Sequential thinking MCP server
├── tests/                      # Test suite
│   ├── test_simple.py          # Direct function tests
│   ├── test_fd_server.py       # File search MCP integration tests
│   ├── test_fuzzy_search.py    # Fuzzy search tests
│   ├── test_sqlite_server.py   # SQLite server tests
│   ├── test_sequential_thinking.py # Sequential thinking tests
│   └── test_cli.py             # CLI interface tests
├── pyproject.toml        # Project configuration
├── Makefile              # Development commands
├── CLAUDE.md             # Claude-specific instructions
└── README.md             # This file

Adicionando Novos Servidores MCP

Para adicionar um novo servidor MCP a esta coleção:

Crie um novo arquivo Python (ex.: mcp_new_server.py)
Implemente usando o framework FastMCP
Adicione testes no diretório tests/
Atualize este README com documentação
Adicione um exemplo de configuração para o Claude Desktop

Executando Testes

# Run all tests
make test

# Run specific test categories
make test-simple  # Direct function tests
make test-cli     # CLI interface tests
make test-full    # Full MCP integration tests

# Run with coverage
make test-cov

Comandos de Desenvolvimento

make help         # Show all available commands
make setup        # Install development dependencies
make test         # Run tests
make lint         # Run linting
make format       # Format code
make type-check   # Run type checking
make clean        # Clean generated files

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça suas alterações
Execute os testes (make test)
Execute o linting (make check)
Faça commit das suas alterações
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Arquitetura

Todos os servidores MCP nesta coleção são construídos usando:

FastMCP: Framework de servidor MCP de alto nível do SDK oficial Python
uv: Gerenciador de pacotes Python rápido
Scripts autocontidos: Cada servidor usa #!/usr/bin/env -S uv run --script para fácil implantação

Servidor de Busca de Arquivos

Adicionalmente usa:

fd: Localizador de arquivos moderno escrito em Rust
fzf: Localizador difuso de linha de comando

Servidor de Busca Difusa

Adicionalmente usa:

ripgrep: Ferramenta de busca extremamente rápida que respeita o gitignore
fzf: Localizador difuso de linha de comando (usado no modo de filtro)

Servidor de Pensamento Sequencial

Python puro — nenhum binário extra necessário. Mantém uma lista em memória de pensamentos e um mapa de ramos durante a vida útil do processo; o estado não é persistido entre execuções.

Considerações de Segurança

Geral

Todos os servidores executam com as permissões do usuário que os executa
Considere as implicações de segurança das capacidades de cada servidor
Revise o código do servidor antes da instalação

Proteção de Caminho Raiz

Mecanismo de segurança integrado: Todas as funções de busca previnem buscas acidentais a partir do diretório raiz (/) por padrão
Buscar a partir da raiz sem confirmação explícita retorna uma mensagem de erro
Para buscar a partir do diretório raiz, você deve definir explicitamente confirm_root=True (ferramentas MCP) ou usar o sinalizador --confirm-root (CLI)
Isso previne problemas de desempenho não intencionais e acesso excessivo ao sistema de arquivos
Suporte multiplataforma: protege contra a raiz Unix (/) e raízes de unidades Windows (C:, etc.)

Servidor de Busca de Arquivos

Tem acesso ao sistema de arquivos baseado nas permissões do usuário
Tenha cuidado ao buscar em diretórios sensíveis
O sinalizador --no-ignore incluirá arquivos normalmente ocultos por .gitignore

Servidor de Busca Difusa

Tem acesso de leitura ao sistema de arquivos baseado nas permissões do usuário
Pode buscar conteúdo de arquivos, incluindo código-fonte e arquivos de configuração
Respeita .gitignore por padrão (use --hidden para incluir arquivos ignorados)
Esteja atento ao buscar em repositórios com dados sensíveis

Servidor SQLite

Somente leitura por padrão - Previne modificação acidental de dados
Operações de escrita requerem o sinalizador --allow-writes explícito ou variável de ambiente
Tem acesso total ao banco de dados baseado nas permissões do arquivo
Pode executar consultas SQL arbitrárias quando o modo de escrita está habilitado
Seja extremamente cauteloso com permissões de escrita em bancos de dados de produção
Considere usar usuários de banco de dados separados somente leitura quando possível

Servidor de Pensamento Sequencial

Sem acesso a sistema de arquivos, rede ou banco de dados
Armazena pensamentos apenas em memória; sem persistência entre execuções de processo
Pensamentos formatados são escritos no stderr por padrão — defina DISABLE_THOUGHT_LOGGING=true se os pensamentos podem conter conteúdo sensível que você não quer no fluxo de stderr do processo pai

Solução de Problemas

"Não é possível encontrar o binário `fd`"

Certifique-se de que o fd está instalado e no seu PATH
No Debian/Ubuntu, o fd pode estar instalado como fdfind

"Não é possível encontrar o binário `fzf`"

Instale o fzf usando seu gerenciador de pacotes
Certifique-se de que está disponível no seu PATH

"Buscar a partir do diretório raiz (/) provavelmente está incorreto e pode ser muito lento"

Esta mensagem de segurança aparece ao tentar buscar a partir do diretório raiz sem confirmação explícita
Para buscar a partir da raiz, adicione o parâmetro confirm_root=True (ferramentas MCP) ou o sinalizador --confirm-root (CLI)
Considere usar um caminho de diretório mais específico para melhor desempenho
Exemplo: ./mcp_fuzzy_search.py search-files "config" / --confirm-root

Testes falhando

Verifique se os binários necessários estão instalados para cada servidor
Execute make check-deps para verificar se os binários estão disponíveis
Alguns testes requerem um ambiente semelhante ao Unix

Licença

Este projeto é open source e está disponível sob a Licença MIT.

Agradecimentos

Model Context Protocol - O protocolo que permite interações entre IA e ferramentas
FastMCP - O framework Python para construir servidores MCP
uv - Um instalador e resolvedor de pacotes Python extremamente rápido

Servidor de Busca de Arquivos

fd - Uma alternativa simples, rápida e amigável ao find
fzf - Um localizador difuso de linha de comando

Servidor de Busca Difusa

ripgrep - Pesquisa recursivamente diretórios por padrões de texto
fzf - Um localizador difuso de linha de comando
PyMuPDF - Ligações Python para MuPDF para processamento de PDF (opcional)
ripgrep-all - ripgrep, mas também pesquisa em PDFs, E-Books, documentos do Office (opcional)
pandoc - Conversor universal de marcação (opcional)

Servidor SQLite

SQLite - Mecanismo de banco de dados SQL autossuficiente, sem servidor e sem configuração

Servidor de Pensamento Sequencial

@modelcontextprotocol/server-sequential-thinking - O servidor TypeScript original do qual este é portado

MCP Personal

Documentação

MCP Personal - Coleção de Servidores MCP Pessoais

Servidores MCP Disponíveis

1. Servidor de Busca de Arquivos (mcp_fd_server.py)

2. Servidor de Busca Difusa (mcp_fuzzy_search.py)

3. Servidor SQLite (mcp_sqlite_server.py)

4. Servidor de Pensamento Sequencial (mcp_sequential_thinking.py)

Pré-requisitos

Requisitos Gerais

Nota sobre Recursos Opcionais

Requisitos do Servidor de Busca de Arquivos

macOS

Ubuntu/Debian

Outros Sistemas

Requisitos do Servidor de Busca Difusa

macOS

Ubuntu/Debian

Outros Sistemas

Instalação

Clonar o Repositório

Configurar Servidores MCP

Usando a CLI do Claude Code

Configuração Manual (Claude Desktop)

Tornar Scripts Executáveis

Para Desenvolvimento

Testes e Desenvolvimento

MCP Inspector

Teste Rápido

Usando o Inspector

Configuração Avançada

Uso

Servidor de Busca de Arquivos

Como Servidor MCP

Uso via CLI

Servidor de Busca Difusa

Como Servidor MCP

Uso via CLI

Servidor SQLite

Como Servidor MCP

Uso via CLI

Servidor de Pensamento Sequencial

Como Servidor MCP

Registro

Modo de Busca Multilinha

O que é o Modo Multilinha?

Quando Usar o Modo Multilinha

Exemplos de Multilinha

Servidor de Pesquisa de Arquivos Multilinha (Pesquisa de Conteúdo)

Servidor de Pesquisa Difusa Multilinha

Considerações de Desempenho

Dicas para Consultas Multilinha

Guia de Sintaxe de Pesquisa fzf

Sintaxe Básica

Correspondência Exata

Âncoras de Posição

Negação (Exclusão)

Exemplos Avançados

Padrões Específicos de Pesquisa de Conteúdo

Referência de Flags do ripgrep (rg)

Sensibilidade a Maiúsculas/Minúsculas

Filtragem por Tipo de Arquivo

Linhas de Contexto

Manipulação de Arquivos

Correspondência de Padrões

Recursos Avançados

Controle de Saída

Combinações Práticas

Documentação das Ferramentas MCP

Ferramentas do Servidor de Pesquisa de Arquivos

search_files

filter_files

Ferramentas do Servidor de Pesquisa Difusa

fuzzy_search_files

fuzzy_search_content

fuzzy_search_documents

extract_pdf_pages

get_pdf_page_labels

get_pdf_page_count

get_pdf_outline

1. Servidor de Busca de Arquivos (`mcp_fd_server.py`)

2. Servidor de Busca Difusa (`mcp_fuzzy_search.py`)

3. Servidor SQLite (`mcp_sqlite_server.py`)

4. Servidor de Pensamento Sequencial (`mcp_sequential_thinking.py`)

`search_files`

`filter_files`

`fuzzy_search_files`

`fuzzy_search_content`

`fuzzy_search_documents`

`extract_pdf_pages`

`get_pdf_page_labels`

`get_pdf_page_count`

`get_pdf_outline`

`query`

`execute`

`list_tables`

`describe_table`

`create_table`

`sequentialthinking`

"Não é possível encontrar o binário `fd`"

"Não é possível encontrar o binário `fzf`"