Folder MCP

Un servidor para operaciones de carpetas locales y acceso al sistema de archivos.

Documentación

folder-mcp (En Desarrollo, se lanzará pronto)

Servidor de Protocolo de Contexto de Modelo para Operaciones de Carpetas

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona herramientas para leer y analizar estructuras de carpetas, permitiendo que los LLMs interactúen con sistemas de archivos locales de manera segura y eficiente.

Resumen

folder-mcp fue creado con un propósito simple pero poderoso: tomar tu carpeta local y hacerla accesible a Modelos de Lenguaje Grande (LLMs) que se ejecutan en cualquier lugar. No necesitas subir tus archivos a la nube ni usar un servicio de terceros.

Crea capacidades de RAG (Generación Aumentada por Recuperación) para tus archivos locales, permitiendo que los LLMs lean, busquen y analicen documentos de manera segura y estructurada. Este servidor implementa el estándar de Protocolo de Contexto de Modelo (MCP), permitiendo que los LLMs interactúen con sistemas de archivos locales a través de un conjunto de herramientas definidas. Este proyecto está diseñado para funcionar con clientes MCP como Claude Desktop, Cursor, VsCode y otros, proporcionando una forma segura y eficiente de acceder y manipular archivos dentro de carpetas especificadas.

Características

✅ Acceso Seguro a Archivos

Lectura de archivos desde carpetas especificadas con validación de rutas
Comprobaciones de seguridad para prevenir ataques de traversal de directorios
Soporte para varios tipos de archivos y codificaciones

✅ Operaciones del Sistema de Archivos

Listar todos los archivos en una carpeta de forma recursiva
Buscar archivos por patrones de nombre (soporte glob)
Obtener información de carpetas y metadatos
Excluir directorios comunes como node_modules y .git

✅ Integración MCP

Implementación estándar del servidor de Protocolo de Contexto de Modelo
Funciona con Claude Desktop y otros clientes MCP
Transporte Stdio para integración sin problemas
Definiciones de herramientas estructuradas con esquemas JSON

✅ Amigable para Desarrolladores

Implementación en TypeScript con seguridad de tipos completa
Manejo claro de errores y respuestas informativas
Interfaz CLI simple para pruebas y desarrollo

Instalación

git clone https://github.com/okets/folder-mcp.git
cd folder-mcp
npm install
npm run build

Configuración

folder-mcp utiliza un sistema de configuración centralizado almacenado en config.yaml en la raíz del proyecto. Este archivo YAML contiene configuraciones para embeddings, caché, procesamiento, API, registro y configuraciones de desarrollo.

Modelos de Embedding

El sistema soporta múltiples modelos de embedding con aceleración GPU a través de Ollama:

Modelo	Dimensiones	Descripción
`nomic-v1.5`	768	Alta calidad de propósito general (predeterminado)
`mxbai-large`	1024	Modelo grande con excelente rendimiento
`all-minilm`	384	Ligero y rápido
`bge-small`	384	Embedding general BAAI, versión pequeña
`gte-base`	768	Modelo de Text Embeddings general

Estructura de Configuración

# Embedding Model Configuration
embeddings:
  defaultModel: "nomic-v1.5"
  ollamaApiUrl: "http://127.0.0.1:11434"
  batchSize: 32
  timeoutMs: 30000
  models:
    # Model definitions with dimensions, descriptions, etc.

# Cache Configuration  
cache:
  defaultCacheDir: "~/.cache/folder-mcp"
  maxCacheSize: "10GB"
  cleanupIntervalHours: 24

# Text Processing Configuration
processing:
  defaultChunkSize: 1000
  defaultOverlap: 200
  maxConcurrentOperations: 10

# Development & Logging options
logging:
  level: "info"
  format: "json"
  
development:
  enableDebugOutput: false
  mockOllamaApi: false

Para opciones de configuración detalladas, consulta CONFIGURATION.md.

Estado Actual

🚀 Versión 1.0 - Servidor MCP Básico (13/30 características planificadas completadas)

Esta es la versión fundacional que proporciona acceso seguro al sistema de archivos a través de MCP. La visión completa incluye búsqueda semántica, embeddings y análisis inteligente de documentos - consulta ROADMAP.md para el plan de desarrollo completo.

Lo que funciona ahora:

✅ Lectura básica de archivos y operaciones de carpetas
✅ Validación de seguridad y protección de rutas
✅ Búsqueda de archivos basada en patrones
✅ Integración del protocolo MCP

Lo que viene después: Fragmentación inteligente de texto, embeddings semánticos, búsqueda vectorial (ver las 30 características planificadas)

Uso

Como Servidor MCP

Este servidor está diseñado para usarse con clientes MCP como Claude Desktop. Añádelo a tu configuración de Claude Desktop:

{
  "mcpServers": {
    "folder-mcp": {
      "command": "node",
      "args": [
        "C:\\Path\\To\\folder-mcp\\dist\\mcp-server.js",
        "C:\\Path\\To\\folder-mcp"
      ],
      "env": {}
    }
  }
}

⚠️ Nota Crítica de Integración con Claude Desktop: El protocolo MCP requiere que SOLO mensajes JSON-RPC válidos vayan a stdout. Cualquier registro o salida de depuración a stdout romperá la conexión. Todos los registros deben redirigirse solo a stderr. Consulta CLAUDE_DESKTOP_SETUP.md para consejos detallados de solución de problemas.

Herramientas Disponibles

El servidor actualmente proporciona las siguientes herramientas:

get_status - Una herramienta de estado del sistema que devuelve información de procesamiento para verificar la conexión
- Parámetro opcional: name - Un nombre para incluir en el saludo

1. `read_file`

Lee el contenido de un archivo específico dentro de una carpeta.

Parámetros:

folder_path: Ruta a la carpeta que contiene el archivo
file_path: Ruta relativa al archivo dentro de la carpeta

2. `search_files`

Busca archivos que coincidan con un patrón específico.

Parámetros:

folder_path: Ruta a la carpeta para buscar
pattern: Patrón de archivo (ej., ".md", ".txt", "config.*")

3. `list_files`

Lista todos los archivos en una carpeta de forma recursiva.

Parámetros:

folder_path: Ruta a la carpeta para listar

4. `get_folder_info`

Obtiene información sobre una carpeta incluyendo el recuento de archivos y metadatos.

Parámetros:

folder_path: Ruta a la carpeta para analizar

Características de Seguridad

Validación de Rutas: Previene el acceso a archivos fuera de la carpeta especificada
Exclusiones de Directorios: Excluye automáticamente node_modules, .git y carpetas de caché
Manejo de Errores: Manejo elegante de errores de permisos y rutas inválidas

Arquitectura

Implementación del Servidor MCP

El servidor implementa el estándar de Protocolo de Contexto de Modelo con los siguientes componentes:

📡 MCP Client (Claude Desktop) ↔ 📞 Stdio Transport ↔ 🖥️ MCP Server ↔ 📁 File System

Patrón de Acceso a Archivos

1. Client Request → 2. Tool Validation → 3. Path Security Check → 4. File Operation → 5. Response

Componentes del Servidor

Manejadores de Herramientas: Procesan solicitudes de read_file, search_files, list_files y get_folder_info
Capa de Seguridad: Valida rutas y previene traversal de directorios
Operaciones de Archivos: Usa Node.js fs y glob para acceso eficiente al sistema de archivos
Capa de Transporte: Transporte Stdio para comunicación con clientes MCP

Detalles Técnicos

Dependencias

@modelcontextprotocol/sdk: Implementación del protocolo MCP
glob: Búsqueda de archivos basada en patrones
typescript: Desarrollo con seguridad de tipos
Bibliotecas adicionales para futuras capacidades de análisis de archivos

Patrones de Archivos

El servidor usa patrones glob para la búsqueda de archivos:

* - Todos los archivos
*.md - Solo archivos Markdown
**/*.js - Archivos JavaScript recursivamente
config.* - Cualquier archivo que comience con "config"

Directorios Excluidos

Excluidos automáticamente de todas las operaciones:

**/node_modules/**
**/.git/**
**/.folder-mcp/**

Desarrollo

Construyendo el Proyecto

npm run build

Ejecutando el Servidor

npm start

Modo de Desarrollo

npm run dev

Pruebas con Clientes MCP

El servidor puede probarse con cualquier cliente compatible con MCP. Para Claude Desktop, añade la configuración a tu archivo de configuración.

Mejoras Futuras

📋 Hoja de Ruta de Desarrollo: Consulta ROADMAP.md para el progreso visual y GITHUB_ISSUES.md para el desglose detallado de tareas.

Características Planificadas (17 tareas restantes):

Fase 3: Fragmentación inteligente de texto y embeddings semánticos
Fase 4: Búsqueda vectorial FAISS y coincidencia de similitud
Fase 5: Integración MCP mejorada con búsqueda semántica
Fase 6: Monitoreo de archivos en tiempo real y sistema de configuración
Fase 7: Optimización de rendimiento y pruebas exhaustivas
Fase 8: Documentación y publicación en npm

Visión: Herramienta Universal de Carpeta a MCP

Transforma cualquier carpeta en una base de conocimiento inteligente con:

Análisis multi-formato: PDF, Word, Excel, PowerPoint con preservación de estructura
Embeddings semánticos: Modelo Nomic Embed para comprensión inteligente de contenido
Búsqueda vectorial: Búsqueda de similitud impulsada por FAISS para recuperación consciente del contexto
Fragmentación inteligente: Segmentación de contenido basada en significado
Actualizaciones en tiempo real: Monitoreo de archivos con re-indexación automática
Capacidades RAG: Permite que los LLMs consulten contenidos de carpetas de manera inteligente

Contribuciones

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/amazing-feature)
Haz commit de tus cambios (git commit -m 'Add amazing feature')
Haz push a la rama (git push origin feature/amazing-feature)
Abre una Solicitud de Extracción (Pull Request)

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

Agradecimientos

Construido con el SDK de Protocolo de Contexto de Modelo
Usa TypeScript para seguridad de tipos y experiencia de desarrollador
Diseñado para acceso seguro y eficiente al sistema de archivos
Compatible con Claude Desktop y otros clientes MCP

¡Habilita tu LLM para trabajar con carpetas locales a través del Protocolo de Contexto de Modelo! 🚀

Folder MCP

Documentación

folder-mcp (En Desarrollo, se lanzará pronto)

Resumen

Características

Instalación

Configuración

Modelos de Embedding

Estructura de Configuración

Estado Actual

Uso

Como Servidor MCP

Herramientas Disponibles

1. read_file

2. search_files

3. list_files

4. get_folder_info

Características de Seguridad

Arquitectura

Implementación del Servidor MCP

Patrón de Acceso a Archivos

Componentes del Servidor

Detalles Técnicos

Dependencias

Patrones de Archivos

Directorios Excluidos

Desarrollo

Construyendo el Proyecto

Ejecutando el Servidor

Modo de Desarrollo

Pruebas con Clientes MCP

Mejoras Futuras

Características Planificadas (17 tareas restantes):

Visión: Herramienta Universal de Carpeta a MCP

Contribuciones

Licencia

Agradecimientos

1. `read_file`

2. `search_files`

3. `list_files`

4. `get_folder_info`