MCP Personal

Una colección de servidores MCP para diversas herramientas y utilidades de productividad personal.

Documentación

MCP Personal - Colección de Servidores MCP Personales

Una colección de servidores Model Context Protocol (MCP) para diversas herramientas y utilidades de productividad personal.

Servidores MCP Disponibles

1. Servidor de Búsqueda de Archivos (`mcp_fd_server.py`)

Capacidades de búsqueda difusa de NOMBRES de archivos usando fd y fzf:

Búsqueda rápida de nombres de archivos usando fd (busca nombres/rutas de archivos, NO contenidos)
Filtrado difuso de nombres de archivos con fzf para coincidencia inteligente de nombres
Coincidencia de patrones con soporte de regex y glob para nombres de archivos
Limitación de resultados con el parámetro limit para restringir el número de coincidencias
Manejo adecuado de errores para códigos de salida de fzf (distingue "sin coincidencias" de errores)
Modo multilínea (avanzado): también puede buscar contenidos de archivos cuando está habilitado
CLI independiente para pruebas y uso directo
Punto clave: El propósito principal es encontrar archivos por NOMBRE, no buscar contenidos

2. Servidor de Búsqueda Difusa (`mcp_fuzzy_search.py`)

Búsqueda avanzada con capacidades tanto de nombre de archivo como de contenido usando ripgrep y fzf:

Búsqueda difusa de nombres de archivos - encuentra archivos por nombres parciales/difusos
Búsqueda de contenido usando ripgrep para buscar texto dentro de archivos
Filtrado difuso de resultados usando fzf --filter
Manejo adecuado de errores para códigos de salida de fzf (distingue "sin coincidencias" de errores)
Dos modos distintos:
- fuzzy_search_files: Busca NOMBRES/rutas de archivos
- fuzzy_search_content: Busca CONTENIDOS de archivos con coincidencia de ruta+contenido por defecto
Búsqueda de PDF y documentos (opcional) - busca en PDFs, documentos de Office y archivos usando ripgrep-all
Extracción de páginas PDF (opcional) - extrae páginas específicas de PDFs usando PyMuPDF con soporte de etiquetas de página
Herramientas de información PDF (opcional) - obtiene etiquetas de página, número de páginas y tabla de contenidos de archivos PDF:
- get_pdf_page_labels: Obtiene todas las etiquetas de página de un archivo PDF
- get_pdf_page_count: Obtiene el número total de páginas de un archivo PDF
- get_pdf_outline: Extrae tabla de contenidos/marcadores de un archivo PDF
Interfaz simplificada - solo proporciona términos de búsqueda difusa (sin soporte de regex)
Procesamiento de registros multilínea para coincidencia de patrones complejos
CLI independiente para pruebas y uso directo

3. Servidor SQLite (`mcp_sqlite_server.py`)

Operaciones de base de datos SQLite con permisos de lectura/escritura configurables:

Solo lectura por defecto - Las operaciones de escritura están deshabilitadas a menos que se habiliten explícitamente
Amigable para agentes - Descripciones y ejemplos claros de herramientas para facilitar el uso por agentes de IA
Soporte de base de datos en memoria - Usa :memory: para bases de datos temporales
Operaciones completas - Consultar, ejecutar, listar tablas, describir esquema, crear tablas
Características de seguridad - Validación de consultas, restricciones de operaciones de escritura, mensajes de error claros
CLI independiente para pruebas y uso directo

4. Servidor de Pensamiento Secuencial (`mcp_sequential_thinking.py`)

Resolución de problemas dinámica y reflexiva a través de una cadena estructurada de pensamientos — un puerto Python del servidor oficial @modelcontextprotocol/server-sequential-thinking:

Resolución dinámica de problemas — divide problemas complejos en pasos de pensamiento discretos y ajustables
Revisión de pensamientos — revisa pensamientos anteriores cuando la comprensión se profundiza (isRevision / revisesThought)
Ramificación — explora rutas de razonamiento alternativas desde cualquier pensamiento anterior (branchFromThought / branchId)
Totales ajustables — escala totalThoughts hacia arriba o hacia abajo durante el proceso, o extiende más allá de la estimación inicial con needsMoreThoughts
Generación y verificación de hipótesis — genera soluciones candidatas y verifícalas contra la cadena de pensamiento
Corrección de coerción de cadenas — acepta entradas de cadena para campos numéricos (thoughtNumber, totalThoughts) y booleanos (nextThoughtNeeded, isRevision, needsMoreThoughts), por lo que funciona con Claude Code de inmediato. Incluye la corrección de modelcontextprotocol/servers#3856, que aún no se ha incluido en la versión npm (2025.12.18)
Registro de pensamientos opcional — los pensamientos formateados se envían a stderr por defecto; establece DISABLE_THOUGHT_LOGGING=true para silenciarlos
Herramienta única: sequentialthinking

Requisitos Previos

Requisitos Generales

Python 3.10 o superior
uv (recomendado) o pip

Para instalar 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 Características Opcionales

Las herramientas de búsqueda y extracción de PDF en el Servidor de Búsqueda Difusa son opcionales. El servidor funcionará sin estos binarios instalados - solo las herramientas específicas de PDF no estarán disponibles. Esto te permite usar la funcionalidad principal de búsqueda difusa sin requerir todas las dependencias.

Requisitos del Servidor de Búsqueda de Archivos

El servidor de búsqueda de archivos requiere las siguientes herramientas de línea de comandos:

macOS

brew install fd fzf

Ubuntu/Debian

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

Otros Sistemas

Requisitos del Servidor de Búsqueda Difusa

El servidor de búsqueda difusa requiere:

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

Otros Sistemas

Guía de instalación de ripgrep
Guía de instalación de fzf
Instalación de ripgrep-all (opcional, para búsqueda de PDF)
Instalación de pandoc (opcional, para extracción de PDF)

Instalación

Clonar el Repositorio

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

Configurar Servidores MCP

Usando la CLI de Claude Code

La forma más fácil de agregar servidores MCP a Claude Code es usando la 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:

El separador -- es importante antes del comando y sus argumentos
Las variables de entorno usan la sintaxis -e KEY=value
Usa -s user para servidores personales disponibles en todos los proyectos
Tanto las rutas relativas como las absolutas funcionan

Configuración Manual (Claude Desktop)

Para Claude Desktop, agrega manualmente servidores a ~/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"
      }
    }
  }
}

Hacer Ejecutables los Scripts

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

Para Desarrollo

# Install with development dependencies
uv sync --dev

# Or use make
make setup

Pruebas y Desarrollo

Inspector MCP

El Inspector MCP es una herramienta de desarrollo interactiva para probar y depurar servidores MCP. Proporciona una interfaz basada en web que te permite:

Probar visualmente tus servidores MCP con una interfaz interactiva
Depurar implementaciones de servidores examinando flujos de solicitud/respuesta
Probar herramientas, recursos y prompts con diferentes argumentos
Validar el comportamiento del servidor antes del despliegue

Pruebas Rápidas

Prueba cualquier servidor MCP usando el 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

Esto:

Iniciará el servidor proxy del Inspector MCP (puerto predeterminado 6277)
Lanzará una interfaz web (puerto predeterminado 6274)
Se conectará a tu servidor MCP mediante transporte stdio
Abrirá tu navegador en la interfaz del inspector

Usando el Inspector

Una vez que el inspector esté ejecutándose:

Navega a la interfaz web (generalmente http://localhost:6274)
Explora las pestañas:
- Herramientas: Prueba search_files, filter_files, fuzzy_search_files, fuzzy_search_content, fuzzy_search_documents, extract_pdf_pages
- Recursos: Ve cualquier recurso expuesto (si está implementado)
- Prompts: Prueba cualquier prompt expuesto (si está implementado)
Prueba diferentes escenarios:
- Prueba varios patrones de búsqueda y filtros
- Prueba la funcionalidad multilínea
- Experimenta con diferentes rutas de archivos y banderas
- Prueba la búsqueda de PDF con fuzzy_search_documents (si los binarios están instalados)
- Prueba la extracción de páginas PDF con extract_pdf_pages (si los binarios están instalados)
- Valida el manejo de errores con entradas inválidas

Configuración Avanzada

También puedes usar archivos de configuración para configuraciones complejas:

# 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

El Inspector MCP es particularmente valioso para:

Prototipado rápido - prueba rápidamente nueva funcionalidad
Depuración - identifica problemas antes de la integración con Claude
Documentación - entiende exactamente qué expone tu servidor
Validación - asegura el manejo adecuado de errores y casos límite

Uso

Servidor de Búsqueda de Archivos

Como Servidor MCP

Una vez configurado en Claude Desktop, puedes usar lenguaje natural para buscar archivos por NOMBRE:

"Encuentra todos los archivos Python en el directorio src" (busca nombres de archivos que terminan en .py)
"Busca archivos con 'config' en su nombre" (coincidencia difusa de nombres de archivos)
"Encuentra archivos de prueba por nombre" (busca archivos con 'test' en el nombre)
"Usa búsqueda difusa para encontrar 'mainpy'" (encuentra main.py, main_py.txt, etc.)

Uso CLI

El servidor de búsqueda de archivos también funciona como herramienta CLI independiente:

# 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 Búsqueda Difusa

Como Servidor MCP

Una vez configurado en Claude Desktop, puedes usar lenguaje natural para búsqueda avanzada:

"Busca comentarios TODO que mencionen 'implement'"
"Encuentra todos los archivos con 'test' en el nombre usando búsqueda difusa"
"Busca código de manejo de errores en archivos Python"
"Busca archivos de configuración que contengan configuraciones de base de datos"
"Encuentra definiciones de métodos llamadas 'update_ondemand_max_spend'"
"Busca funciones asíncronas con manejo de errores"
"Busca 'update' solo en archivos test.py" (funciona porque el modo predeterminado también coincide con rutas)
"Busca 'async' solo en contenido, ignora rutas de archivos" (usa el modo content_only)
"Busca 'vector' en documentos PDF" (requiere ripgrep-all)
"Encuentra todas las referencias a 'machine learning' en PDFs y documentos de Word"
"Extrae las páginas 5-10 del PDF del manual de usuario"
"Obtén la tabla de contenidos del PDF del artículo de investigación"
"Muéstrame el esquema de capítulos del manual de usuario"

Uso CLI

El servidor de búsqueda difusa también funciona como herramienta CLI independiente:

# 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

Una vez configurado en Claude Desktop, puedes usar lenguaje natural para operaciones de base de datos:

"Lista todas las tablas en la base de datos"
"Muéstrame el esquema de la tabla de usuarios"
"Consulta los últimos 10 pedidos de la tabla de pedidos"
"Cuenta usuarios activos en la base de datos"
"Actualiza el estado de usuarios a inactivo para aquellos que no han iniciado sesión en un año" (requiere permisos de escritura)
"Crea una nueva tabla para almacenar datos de sesión" (requiere permisos de escritura)

Uso CLI

El servidor SQLite también funciona como herramienta CLI independiente:

# 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 Pensamiento Secuencial

Como Servidor MCP

Una vez configurado, Claude puede invocar sequentialthinking para trabajar a través de problemas en pasos explícitos y revisables. Prompts de lenguaje natural que lo activan:

"Piensa paso a paso sobre cómo diseñar esta capa de caché"
"Usa pensamiento secuencial para depurar por qué esta prueba es inestable"
"Divide esta refactorización en pensamientos y revísalos a medida que avanzas"
"Planifica la migración con la herramienta de pensamiento secuencial, ramificando si ves alternativas"

Cada llamada registra un pensamiento y devuelve el estado actual (thoughtNumber, totalThoughts, nextThoughtNeeded, branches activo y thoughtHistoryLength). Claude sigue llamando a la herramienta — revisando, ramificando o extendiendo el total según sea necesario — hasta que nextThoughtNeeded sea falso.

Registro

Por defecto, los pensamientos formateados se envían a stderr a medida que llegan (útil cuando se ejecuta el servidor interactivamente o a través del Inspector MCP). Establece DISABLE_THOUGHT_LOGGING=true en el entorno para silenciar el registro mientras se mantiene intacta la salida estructurada de la herramienta.

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

Modo de Búsqueda Multilínea

Ambos servidores MCP soportan el modo de búsqueda multilínea que cambia el comportamiento de búsqueda:

¿Qué es el Modo Multilínea?

Comportamiento predeterminado (multiline=false):

Servidor de Búsqueda de Archivos: Busca solo NOMBRES/RUTAS de archivos
Servidor de Búsqueda Difusa: Busca línea por línea dentro de los contenidos de archivos

Con modo multilínea (multiline=true):

Servidor de Búsqueda de Archivos: Cambia a buscar CONTENIDOS de archivos en lugar de nombres
Servidor de Búsqueda Difusa: Trata el contenido completo de archivos como unidades de búsqueda únicas

Cuándo Usar el Modo Multilínea

El modo multilínea sirve para buscar en el CONTENIDO de archivos (no en los nombres):

Encontrar definiciones de clases con sus métodos: "class UserService authenticate" (coincidencia difusa en contenidos)
Localizar implementaciones de funciones: "async function await fetch" (todos los términos en un archivo)
Buscar bloques de configuración: "database host port" (encuentra archivos que contienen todos los términos)
Encontrar estructuras de código entre líneas: "try catch finally" (coincidencias difusas entre líneas)
Importante: ¡Esto busca en CONTENIDOS, no en nombres de archivos!

Ejemplos de Multilínea

Servidor de Búsqueda de Archivos Multilínea (Búsqueda de Contenido)

# 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 Búsqueda Difusa Multilínea

# 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

Consideraciones de Rendimiento

Tamaño de archivo: El modo multilínea lee archivos completos en memoria; es mejor para archivos de código fuente típicos
Tamaño de resultados: Los resultados multilínea incluyen el contenido completo del archivo, que puede truncarse para su visualización
Complejidad de patrones: Los patrones difusos simples funcionan bien; las consultas complejas pueden ser más lentas

Consejos para Consultas Multilínea

Usa términos específicos: "class MyClass def method" es mejor que solo "class def" (¡sin regex!)
Combina estructura y contenido: "import React export default" encuentra componentes de React
Ten en cuenta la salida: Los resultados muestran el contenido completo del archivo coincidente
Prueba de forma incremental: Comienza con patrones simples y refina

Guía de Sintaxis de Búsqueda fzf

Ambos servidores MCP usan la sintaxis de búsqueda extendida de fzf para un filtrado difuso potente. Comprender esta sintaxis te ayudará a construir consultas precisas.

IMPORTANTE: El parámetro fuzzy_filter en fuzzy_search_content NO admite expresiones regulares. Usa la sintaxis de coincidencia difusa de fzf como se describe a continuación. Si necesitas patrones similares a regex, usa los anclajes de posición y las funciones de coincidencia exacta de la sintaxis de fzf.

Sintaxis Básica

Patrón	Descripción	Ejemplo
`term`	Coincidencia difusa (predeterminada)	`config` coincide con "configuration"
`term1 term2`	Lógica Y (todos los términos deben coincidir)	`main config` requiere ambos términos
`term1 \| term2`	Lógica O (cualquier término puede coincidir)	`py$ \| js$ \| go$` coincide con archivos que terminan en cualquiera

Coincidencia Exacta

Patrón	Descripción	Ejemplo
`'term`	Coincidencia exacta parcial	`'main` coincide exactamente con la subcadena "main"
`'term'`	Coincidencia exacta de límites	`'main.py'` coincide exactamente en los límites de palabras

Anclajes de Posición

Patrón	Descripción	Ejemplo
`^term`	Coincidencia de prefijo (empieza con)	`^src` coincide con "src/file.py"
`term$`	Coincidencia de sufijo (termina con)	`.json$` coincide con "config.json"
`^term$`	Coincidencia exacta (cadena completa)	`^README$` coincide solo con "README"

Negación (Exclusión)

Patrón	Descripción	Ejemplo
`!term`	Excluir coincidencias difusas	`config !test` excluye archivos de prueba
`!'term`	Excluir coincidencias exactas	`!'backup'` excluye archivos con "backup" exacto
`!^term`	Excluir coincidencias de prefijo	`!^.` excluye archivos ocultos
`!term$`	Excluir coincidencias de sufijo	`!.tmp$` excluye archivos temporales

Ejemplos Avanzados

Nota: Estos ejemplos muestran cómo lograr un filtrado similar a regex SIN usar expresiones regulares, ya que fuzzy_filter no admite 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$

Patrones Específicos de Búsqueda de Contenido

Al usar fuzzy_search_content, las consultas funcionan con el formato file:line:content:

Modo Predeterminado (coincide con rutas de archivo Y contenido):

# 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 Solo Contenido (ignora rutas de archivo):

# 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

Referencia de Banderas de ripgrep (rg)

La herramienta fuzzy_search_content acepta rg_flags para búsquedas mejoradas. Estas son las banderas más útiles:

Sensibilidad a Mayúsculas

Banderas	Descripción	Ejemplo
`-i, --ignore-case`	Búsqueda insensible a mayúsculas	`rg -i "todo"` coincide con TODO, Todo, todo
`-S, --smart-case`	Insensible a mayúsculas si es minúscula, sensible si es mixta	`rg -S "Todo"` es sensible a mayúsculas
`-s, --case-sensitive`	Forzar sensibilidad a mayúsculas (predeterminado)	`rg -s "TODO"` coincide solo con TODO

Filtrado por Tipo de Archivo

Banderas	Descripción	Ejemplo
`-t TYPE`	Buscar solo tipos de archivo específicos	`-t py` busca solo archivos de Python
`-T TYPE`	Excluir tipos de archivo específicos	`-T test` excluye archivos de prueba
`--type-list`	Mostrar todos los tipos de archivo admitidos	`rg --type-list`

Líneas de Contexto

Banderas	Descripción	Ejemplo
`-A NUM`	Mostrar NUM líneas después de la coincidencia	`-A 3` muestra 3 líneas después
`-B NUM`	Mostrar NUM líneas antes de la coincidencia	`-B 2` muestra 2 líneas antes
`-C NUM`	Mostrar NUM líneas antes y después	`-C 3` muestra 3 líneas en ambos lados

Manejo de Archivos

Banderas	Descripción	Ejemplo
`--hidden`	Buscar archivos/directorios ocultos	`--hidden` incluye archivos .hidden
`--no-ignore`	Ignorar reglas de .gitignore	`--no-ignore` busca archivos ignorados
`-u`	Reducir filtrado (1-3 veces)	`-uu` = `--no-ignore --hidden`

Coincidencia de Patrones

Banderas	Descripción	Ejemplo
`-F`	Búsqueda de cadena literal (sin regex)	`-F` busca texto exacto
`-w`	Coincidir solo palabras completas	`-w` no coincide con palabras parciales
`-v`	Invertir coincidencia (mostrar no coincidencias)	`-v` muestra líneas sin coincidencias
`-x`	Coincidir solo líneas completas	`-x` coincide con línea exacta

Funciones Avanzadas

Banderas	Descripción	Ejemplo
`-U`	Habilitar coincidencia multilínea	`-U` (nota: usa el parámetro multilínea en su lugar)
`-P`	Usar motor de regex PCRE2	`-P` para funciones avanzadas de regex
`-o`	Mostrar solo partes coincidentes	`-o` muestra solo el texto coincidente

Control de Salida

Banderas	Descripción	Ejemplo
`-c`	Contar coincidencias por archivo	`-c` muestra solo el conteo
`-l`	Mostrar solo nombres de archivo con coincidencias	`-l` lista archivos con coincidencias
`--column`	Mostrar números de columna	`--column` incluye información de columna

Combinaciones Prácticas

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

Documentación de Herramientas MCP

Herramientas del Servidor de Búsqueda de Archivos

`search_files`

Encuentra archivos por NOMBRE usando fd con patrones de regex o glob.

Propósito: Busca archivos cuando conoces patrones exactos, extensiones o regex para NOMBRES de archivos.

Parámetros:

pattern (obligatorio): Patrón de regex o glob para coincidir con nombres de archivos
path (opcional): Directorio para buscar (predeterminado: directorio actual)
limit (opcional): Número máximo de resultados a devolver (predeterminado: 0 = sin límite)
flags (opcional): Banderas adicionales para pasar a fd

Ejemplo:

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

`filter_files`

Búsqueda difusa de archivos por NOMBRE usando la coincidencia difusa de fzf.

Propósito: Encuentra archivos cuando solo conoces NOMBRES de archivos parciales o aproximados.

Parámetros:

filter (obligatorio): Cadena de búsqueda difusa para coincidir con nombres/rutas de archivos
pattern (opcional): Patrón inicial para que fd pre-filtre
path (opcional): Directorio para buscar
first (opcional): Devolver solo la mejor coincidencia
limit (opcional): Número máximo de resultados a devolver (predeterminado: 0 = sin límite)
fd_flags (opcional): Banderas adicionales para fd
fzf_flags (opcional): Banderas adicionales para fzf
multiline (opcional): Cuando es true, busca en CONTENIDOS de archivos en lugar de nombres (predeterminado: false)

Nota: Cuando se proporcionan tanto first como limit, first tiene prioridad y devuelve solo la mejor coincidencia.

Ejemplo (Búsqueda de Nombre de Archivo):

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

Ejemplo Multilínea (Búsqueda de Contenido):

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

Herramientas del Servidor de Búsqueda Difusa

`fuzzy_search_files`

Busca NOMBRES/RUTAS de archivos usando coincidencia difusa.

Propósito: Encuentra archivos por NOMBRE cuando solo conoces nombres parciales (por ejemplo, "mainpy" encuentra "main.py").

Parámetros:

fuzzy_filter (obligatorio): Cadena de búsqueda difusa para nombres/rutas de archivos
path (opcional): Directorio para buscar (predeterminado: directorio actual)
hidden (opcional): Incluir archivos ocultos (predeterminado: false)
limit (opcional): Resultados máximos a devolver (predeterminado: 20)
multiline (opcional): Cuando es true, busca en CONTENIDOS de archivos en lugar de nombres (predeterminado: false)
confirm_root (opcional): Permitir búsqueda desde el directorio raíz (/) (predeterminado: false)

Ejemplo (Búsqueda de Nombre de Archivo):

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

Ejemplo Multilínea (Búsqueda de Contenido):

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

`fuzzy_search_content`

Busca contenidos de archivos con filtrado difuso, coincidiendo en AMBAS rutas de archivo Y contenido de forma predeterminada.

Propósito: Encuentra texto/código específico usando búsqueda difusa que considera tanto dónde está (ruta) como qué es (contenido). Funciona de manera consistente con directorios y archivos individuales.

Parámetros:

fuzzy_filter (obligatorio): Consulta de búsqueda difusa para filtrar (NO admite regex - usa sintaxis de fzf)
path (opcional): Directorio/archivo para buscar (predeterminado: directorio actual)
- Soporte mejorado de rutas de archivo: Ahora puede buscar tanto directorios como archivos individuales
- Incluye automáticamente el nombre del archivo en la salida al buscar un solo archivo para resultados consistentes
hidden (opcional): Buscar archivos ocultos (predeterminado: false)
limit (opcional): Resultados máximos a devolver (predeterminado: 20)
rg_flags (opcional): Banderas adicionales para ripgrep (consulta la referencia de banderas de ripgrep)
multiline (opcional): Habilitar procesamiento de registros multilínea (predeterminado: false)
content_only (opcional): Coincidir SOLO en contenido, ignorar rutas de archivo (predeterminado: false)
confirm_root (opcional): Permitir búsqueda desde el directorio raíz (/) (predeterminado: false)

Comportamiento de Coincidencia:

Predeterminado (content_only=false): Coincide en AMBAS rutas de archivo Y contenido (omite números de línea)
- Por eso "test.py: update" encuentra "update" en archivos test.py - ¡coincide con la ruta!
- Buscar "src TODO" encuentra comentarios TODO en archivos bajo el directorio src/
- Incluso solo "update" coincidirá con archivos llamados "update.py" O que contengan "update"
Con content_only=true: Coincide SOLO en contenido, ignorando rutas de archivo por completo
- Búsqueda de contenido puro - "update" no coincidirá con el nombre de archivo "update.py", solo con contenido

Ejemplo (Predeterminado - Ruta + Contenido):

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

Ejemplo (Búsqueda de Archivo Único):

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

Ejemplo (Solo Contenido):

{
  "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`

Busca en PDFs y otros formatos de documentos usando ripgrep-all (requiere binarios opcionales).

Propósito: Busca PDFs, documentos de Office, archivos comprimidos y otros formatos binarios que la búsqueda de texto regular no puede manejar.

Parámetros:

fuzzy_filter (obligatorio): Consulta de búsqueda difusa para contenido de documentos
path (opcional): Directorio/archivo para buscar (predeterminado: directorio actual)
file_types (opcional): Tipos de archivo separados por comas para buscar (por ejemplo, "pdf,docx,epub")
preview (opcional): Incluir contexto de vista previa (predeterminado: true)
limit (opcional): Resultados máximos a devolver (predeterminado: 20)
confirm_root (opcional): Permitir búsqueda desde el directorio raíz (/) (predeterminado: false)

Ejemplo:

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

Devuelve:

{
  "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 archivos PDF, la herramienta devuelve:

page: El número de página basado en 1 de ripgrep-all (p. ej., 542 significa la página 542)
page_index_0based: El índice de página basado en 0 para acceso programático (p. ej., 541 para la página 542)
page_label: La etiqueta de página real tal como se muestra en los lectores de PDF (p. ej., "vii", "ToC", "19")

El campo de contenido ya no incluye el prefijo "Página N: " para una salida más limpia.

`extract_pdf_pages`

Extraer páginas específicas de un PDF y convertirlas a varios formatos usando PyMuPDF.

Propósito: Extraer páginas individuales o rangos de páginas de PDFs con soporte para etiquetas/alias de página tal como aparecen en los lectores de PDF.

Parámetros:

file (obligatorio): Ruta al archivo PDF
pages (obligatorio): Especificaciones de página separadas por comas: admite:
- Etiquetas de página: "v", "vii", "ToC", "Introducción" (tal como se muestran en los lectores de PDF)
- Rangos de páginas: "v-vii", "1-5"
- Páginas físicas: "1", "14" (basado en 1 si no se encuentra como etiqueta)
- Mixto: "v,vii,1,5-8,ToC"
format (opcional): Formato de salida: markdown, html, plain (predeterminado: markdown)
preserve_layout (opcional): Intentar preservar el diseño original (predeterminado: false)
clean_html (opcional): Eliminar etiquetas de estilo HTML como <span style="..."> (predeterminado: true)
fuzzy_hint (opcional): Cadena de búsqueda difusa para filtrar páginas extraídas por contenido
zero_based (opcional): Interpretar números de página como índices basados en 0 (predeterminado: false)
- Cuando es true, todos los números se tratan como índices de página directos basados en 0
- "0" = primera página, "266" = página 267, "0-4" = primeras 5 páginas
- No se realiza búsqueda de etiquetas de página cuando esto es true
- No se puede usar junto con one_based
one_based (opcional): Interpretar números de página como índices basados en 1 (predeterminado: false)
- Cuando es true, todos los números se tratan como índices de página directos basados en 1
- "1" = primera página, "267" = página 267, "1-5" = primeras 5 páginas
- No se realiza búsqueda de etiquetas de página cuando esto es true
- No se puede usar junto con zero_based

Ejemplo:

{
  "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`

Obtener todas las etiquetas de página de un archivo PDF.

Propósito: Devuelve un mapeo de índices de página a sus etiquetas/alias tal como se muestran en los lectores de PDF, útil para comprender las etiquetas de página disponibles antes de la extracción.

Parámetros:

file (obligatorio): Ruta al archivo PDF
start (opcional): Índice de inicio basado en 0 para dividir resultados (predeterminado: 0)
limit (opcional): Número máximo de etiquetas a devolver (predeterminado: todas las páginas)

Ejemplo:

{
  "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`

Obtener el número total de páginas en un archivo PDF.

Propósito: Devuelve el recuento total de páginas, útil para comprender el tamaño del documento antes de la extracción.

Parámetros:

file (obligatorio): Ruta al archivo PDF

Ejemplo:

{
  "file": "research_paper.pdf"
}

# Returns:
{
  "page_count": 150
}

`get_pdf_outline`

Extraer la tabla de contenidos (esquema/marcadores) de un archivo PDF.

Propósito: Devuelve la estructura jerárquica del esquema con niveles, títulos, números de página y etiquetas de página, útil para navegar PDFs complejos y comprender la estructura del documento.

Parámetros:

file (obligatorio): Ruta al archivo PDF
simple (opcional): Devolver información básica (predeterminado: true) o información detallada con datos de enlace (false)
max_depth (opcional): Profundidad máxima a recorrer en la jerarquía del esquema (predeterminado: ilimitado)
fuzzy_filter (opcional): Cadena de búsqueda difusa para filtrar entradas del esquema por título usando fzf

Ejemplo:

{
  "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 del esquema:

El modo simple devuelve: [level, title, page, page_label]
- level: Nivel de jerarquía (basado en 1, 1 = nivel superior)
- title: El título de la entrada de marcador/esquema
- page: Número de página (basado en 1)
- page_label: Etiqueta de página tal como se muestra en los lectores de PDF (p. ej., "i", "ii", "1", "ToC")
El modo detallado agrega un quinto elemento con información de enlace, incluidos detalles de destino

Herramientas del Servidor SQLite

`query`

Ejecutar consultas SELECT en la base de datos.

Parámetros:

query (obligatorio): Consulta SELECT a ejecutar
db_path (opcional): Ruta a la base de datos SQLite (por defecto usa db_path configurado o ':memory:')

Ejemplo:

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

`execute`

Ejecutar consultas INSERT, UPDATE o DELETE (requiere permisos de escritura).

Parámetros:

query (obligatorio): Consulta INSERT, UPDATE o DELETE a ejecutar
db_path (opcional): Ruta a la base de datos SQLite

Ejemplo:

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

`list_tables`

Listar todas las tablas en la base de datos.

Parámetros:

db_path (opcional): Ruta a la base de datos SQLite

Ejemplo:

{
  "db_path": "myapp.db"
}

`describe_table`

Obtener información detallada del esquema de una tabla específica, incluyendo columnas, tipos, restricciones e índices.

Parámetros:

table_name (obligatorio): Nombre de la tabla a describir
db_path (opcional): Ruta a la base de datos SQLite

Ejemplo:

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

`create_table`

Crear una nueva tabla con columnas especificadas (requiere permisos de escritura).

Parámetros:

table_name (obligatorio): Nombre de la tabla a crear
columns (obligatorio): Lista de definiciones de columnas
db_path (opcional): Ruta a la base de datos SQLite

Definición de columna:

name (obligatorio): Nombre de la columna
type (obligatorio): Tipo de dato SQLite (TEXT, INTEGER, REAL, BLOB, etc.)
constraints (opcional): Restricciones de columna (PRIMARY KEY, NOT NULL, UNIQUE, etc.)

Ejemplo:

{
  "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"
}

Herramientas del Servidor de Pensamiento Secuencial

`sequentialthinking`

Registrar un solo paso en una cadena de pensamientos dinámica y revisable. Llame repetidamente — revisando, ramificando o extendiendo el total — hasta que nextThoughtNeeded sea false.

Parámetros:

thought (obligatorio, cadena): El paso de pensamiento actual. Puede ser un paso analítico, una revisión de un pensamiento anterior, una pregunta, una hipótesis o una verificación.
nextThoughtNeeded (obligatorio, booleano): Si se necesita otro paso de pensamiento. Acepta true/false o las cadenas "true"/"false".
thoughtNumber (obligatorio, entero ≥ 1): Número de pensamiento actual en la secuencia. Acepta valores numéricos o cadenas numéricas.
totalThoughts (obligatorio, entero ≥ 1): Estimación actual del total de pensamientos necesarios. Puede ajustarse hacia arriba o hacia abajo entre llamadas. Acepta valores numéricos o cadenas numéricas.
isRevision (opcional, booleano): Si este pensamiento revisa uno anterior.
revisesThought (opcional, entero ≥ 1): Cuando isRevision es true, el número de pensamiento que se está reconsiderando.
branchFromThought (opcional, entero ≥ 1): Al ramificar, el número de pensamiento del que diverge esta rama.
branchId (opcional, cadena): Identificador de la rama actual.
needsMoreThoughts (opcional, booleano): Establecer en true si llega al final pero se da cuenta de que se necesitan más pensamientos.

Salida (estructurada):

thoughtNumber, totalThoughts, nextThoughtNeeded, branches (lista de IDs de ramas activas), thoughtHistoryLength.

Ejemplo:

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

Ejemplo de revisión:

{
  "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
}

Ejemplo de ramificación:

{
  "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 los campos numéricos y booleanos también aceptan entradas de cadena (p. ej., "1", "true"). Esta es la corrección de modelcontextprotocol/servers#3856 y es lo que hace que el servidor sea utilizable desde Claude Code, que a veces serializa esos campos como cadenas.

Desarrollo

Estructura del Proyecto

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

Agregar Nuevos Servidores MCP

Para agregar un nuevo servidor MCP a esta colección:

Cree un nuevo archivo Python (p. ej., mcp_new_server.py)
Implemente usando el framework FastMCP
Agregue pruebas en el directorio tests/
Actualice este README con documentación
Agregue un ejemplo de configuración para Claude Desktop

Ejecutar Pruebas

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

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

Contribuir

Haga un fork del repositorio
Cree una rama de características (git checkout -b feature/amazing-feature)
Haga sus cambios
Ejecute las pruebas (make test)
Ejecute el linting (make check)
Confirme sus cambios
Haga push a la rama (git push origin feature/amazing-feature)
Abra una Solicitud de Extracción (Pull Request)

Arquitectura

Todos los servidores MCP en esta colección están construidos usando:

FastMCP: Framework de servidor MCP de alto nivel del SDK oficial de Python
uv: Gestor de paquetes de Python rápido
Scripts autocontenidos: Cada servidor usa #!/usr/bin/env -S uv run --script para facilitar el despliegue

Servidor de Búsqueda de Archivos

Además usa:

fd: Buscador de archivos moderno escrito en Rust
fzf: Buscador difuso de línea de comandos

Servidor de Búsqueda Difusa

Además usa:

ripgrep: Herramienta de búsqueda extremadamente rápida que respeta gitignore
fzf: Buscador difuso de línea de comandos (usado en modo filtro)

Servidor de Pensamiento Secuencial

Python puro: no se requieren binarios adicionales. Mantiene una lista en memoria de pensamientos y un mapa de ramas durante la vida del proceso; el estado no se persiste entre ejecuciones.

Consideraciones de Seguridad

General

Todos los servidores se ejecutan con los permisos del usuario que los ejecuta
Considere las implicaciones de seguridad de las capacidades de cada servidor
Revise el código del servidor antes de la instalación

Protección de Ruta Raíz

Mecanismo de seguridad integrado: Todas las funciones de búsqueda evitan búsquedas accidentales desde el directorio raíz (/) por defecto
Buscar desde la raíz sin confirmación explícita devuelve un mensaje de error
Para buscar desde el directorio raíz, debe establecer explícitamente confirm_root=True (herramientas MCP) o usar el indicador --confirm-root (CLI)
Esto evita problemas de rendimiento no intencionados y acceso excesivo al sistema de archivos
Soporte multiplataforma: protege tanto la raíz de Unix (/) como las raíces de unidades de Windows (C:, etc.)

Servidor de Búsqueda de Archivos

Tiene acceso al sistema de archivos según los permisos del usuario
Tenga cuidado al buscar en directorios sensibles
El indicador --no-ignore incluirá archivos normalmente ocultos por .gitignore

Servidor de Búsqueda Difusa

Tiene acceso de lectura al sistema de archivos según los permisos del usuario
Puede buscar contenido de archivos, incluido código fuente y archivos de configuración
Respeta .gitignore por defecto (use --hidden para incluir archivos ignorados)
Tenga cuidado al buscar en repositorios con datos sensibles

Servidor SQLite

Solo lectura por defecto: evita la modificación accidental de datos
Las operaciones de escritura requieren el indicador --allow-writes explícito o una variable de entorno
Tiene acceso completo a la base de datos según los permisos de archivo
Puede ejecutar consultas SQL arbitrarias cuando el modo de escritura está habilitado
Sea extremadamente cauteloso con los permisos de escritura en bases de datos de producción
Considere usar usuarios de base de datos separados de solo lectura cuando sea posible

Servidor de Pensamiento Secuencial

Sin acceso al sistema de archivos, red o base de datos
Almacena pensamientos solo en memoria; sin persistencia entre ejecuciones de procesos
Los pensamientos formateados se escriben en stderr por defecto: establezca DISABLE_THOUGHT_LOGGING=true si los pensamientos pueden contener contenido sensible que no desea en el flujo de stderr del proceso padre

Solución de Problemas

"No se puede encontrar el binario `fd`"

Asegúrese de que fd esté instalado y en su PATH
En Debian/Ubuntu, fd podría estar instalado como fdfind

"No se puede encontrar el binario `fzf`"

Instale fzf usando su gestor de paquetes
Asegúrese de que esté disponible en su PATH

"Buscar desde el directorio raíz (/) es probablemente incorrecto y podría ser muy lento"

Este mensaje de seguridad aparece al intentar buscar desde el directorio raíz sin confirmación explícita
Para buscar desde la raíz, agregue el parámetro confirm_root=True (herramientas MCP) o el indicador --confirm-root (CLI)
Considere usar una ruta de directorio más específica para un mejor rendimiento
Ejemplo: ./mcp_fuzzy_search.py search-files "config" / --confirm-root

Pruebas fallando

Verifique que los binarios requeridos estén instalados para cada servidor
Ejecute make check-deps para verificar que los binarios estén disponibles
Algunas pruebas requieren un entorno similar a Unix

Licencia

Este proyecto es de código abierto y está disponible bajo la Licencia MIT.

Agradecimientos

Model Context Protocol - El protocolo que permite las interacciones entre IA y herramientas
FastMCP - El framework de Python para construir servidores MCP
uv - Un instalador y resolutor de paquetes de Python extremadamente rápido

Servidor de búsqueda de archivos

fd - Una alternativa simple, rápida y fácil de usar a find
fzf - Un buscador difuso de línea de comandos

Servidor de búsqueda difusa

ripgrep - Busca recursivamente en directorios patrones de texto
fzf - Un buscador difuso de línea de comandos
PyMuPDF - Enlaces de Python para MuPDF para procesamiento de PDF (opcional)
ripgrep-all - ripgrep, pero también busca en PDFs, libros electrónicos, documentos de Office (opcional)
pandoc - Convertidor universal de marcado (opcional)

Servidor SQLite

SQLite - Motor de base de datos SQL autónomo, sin servidor y sin configuración

Servidor de pensamiento secuencial

@modelcontextprotocol/server-sequential-thinking - El servidor TypeScript original del cual se portó este

MCP Personal

Documentación

MCP Personal - Colección de Servidores MCP Personales

Servidores MCP Disponibles

1. Servidor de Búsqueda de Archivos (mcp_fd_server.py)

2. Servidor de Búsqueda Difusa (mcp_fuzzy_search.py)

3. Servidor SQLite (mcp_sqlite_server.py)

4. Servidor de Pensamiento Secuencial (mcp_sequential_thinking.py)

Requisitos Previos

Requisitos Generales

Nota sobre Características Opcionales

Requisitos del Servidor de Búsqueda de Archivos

macOS

Ubuntu/Debian

Otros Sistemas

Requisitos del Servidor de Búsqueda Difusa

macOS

Ubuntu/Debian

Otros Sistemas

Instalación

Clonar el Repositorio

Configurar Servidores MCP

Usando la CLI de Claude Code

Configuración Manual (Claude Desktop)

Hacer Ejecutables los Scripts

Para Desarrollo

Pruebas y Desarrollo

Inspector MCP

Pruebas Rápidas

Usando el Inspector

Configuración Avanzada

Uso

Servidor de Búsqueda de Archivos

Como Servidor MCP

Uso CLI

Servidor de Búsqueda Difusa

Como Servidor MCP

Uso CLI

Servidor SQLite

Como Servidor MCP

Uso CLI

Servidor de Pensamiento Secuencial

Como Servidor MCP

Registro

Modo de Búsqueda Multilínea

¿Qué es el Modo Multilínea?

Cuándo Usar el Modo Multilínea

Ejemplos de Multilínea

Servidor de Búsqueda de Archivos Multilínea (Búsqueda de Contenido)

Servidor de Búsqueda Difusa Multilínea

Consideraciones de Rendimiento

Consejos para Consultas Multilínea

Guía de Sintaxis de Búsqueda fzf

Sintaxis Básica

Coincidencia Exacta

Anclajes de Posición

Negación (Exclusión)

Ejemplos Avanzados

Patrones Específicos de Búsqueda de Contenido

Referencia de Banderas de ripgrep (rg)

Sensibilidad a Mayúsculas

Filtrado por Tipo de Archivo

Líneas de Contexto

Manejo de Archivos

Coincidencia de Patrones

Funciones Avanzadas

Control de Salida

Combinaciones Prácticas

Documentación de Herramientas MCP

Herramientas del Servidor de Búsqueda de Archivos

search_files

filter_files

Herramientas del Servidor de Búsqueda 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 Búsqueda de Archivos (`mcp_fd_server.py`)

2. Servidor de Búsqueda Difusa (`mcp_fuzzy_search.py`)

3. Servidor SQLite (`mcp_sqlite_server.py`)

4. Servidor de Pensamiento Secuencial (`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`

"No se puede encontrar el binario `fd`"

"No se puede encontrar el binario `fzf`"