File Explorer MCP Server & Client

Este proyecto es una implementación didáctica de un servidor y cliente que utilizan el protocolo MCP (Multi-Client Protocol) sobre JSON-RPC 2.0 para explorar archivos y carpetas de manera programática.

¿Qué es este proyecto?

• file_explorer_server.py: Un servidor que expone herramientas ("tools") para listar archivos y directorios usando el protocolo MCP. Responde a mensajes JSON-RPC por la entrada/salida estándar (stdio).
• file_explorer_client.py: Un cliente sencillo que se comunica con el servidor, envía solicitudes y muestra las respuestas.

¿Cómo usan MCP el servidor y el cliente?

El servidor (file_explorer_server.py)

• Implementa el protocolo MCP completo
• Expone herramientas ("tools") que siguen la especificación MCP
• Responde a mensajes JSON-RPC 2.0 con los métodos MCP estándar:
  • initialize - Inicialización del servidor
  • tools/list - Lista las herramientas disponibles
  • tools/call - Ejecuta una herramienta específica

El cliente (file_explorer_client.py)

• Es un cliente MCP simple y autónomo
• Se comunica con el servidor usando el protocolo MCP
• Lanza el servidor como subproceso y se comunica con él
• No necesita mcp.json porque maneja la conexión directamente

La diferencia clave

• El cliente es un "cliente MCP completo" que maneja todo por sí mismo
• Los clientes que necesitan mcp.json son clientes MCP más avanzados (como IDEs) que quieren descubrir y conectar con múltiples servidores MCP de forma automática

Ambos usan MCP, pero el cliente es autosuficiente y no necesita configuración externa.

¿Para qué sirve?

Permite explorar el sistema de archivos de manera estructurada y automatizada, usando un protocolo estándar. Es útil para aprender sobre:

• Comunicación entre procesos
• Protocolos de mensajes (JSON-RPC)
• Automatización de tareas de exploración de archivos

¿Cómo se usa?

1. Requisitos

• Python 3.x instalado

2. Ejecución rápida

Abre una terminal en la carpeta del proyecto y ejecuta:

python3 file_explorer_client.py [ruta/opcional]

• Si no pasas ningún argumento, listará el directorio actual.
• Si pasas una ruta como argumento, listará los archivos y carpetas de esa ruta.

Ejemplos:

python3 file_explorer_client.py

python3 file_explorer_client.py /ruta/que/quieras

Esto hará lo siguiente:

1. Iniciará el servidor como un subproceso.
2. Enviará una solicitud de inicialización (initialize).
3. Pedirá la lista de herramientas disponibles (tools/list).
4. Usará la herramienta list_files para listar los archivos y carpetas del directorio indicado (o el actual si no se pasa argumento).
5. Mostrará todas las respuestas en pantalla en formato JSON.

3. Interpretar los resultados

• initialize: Devuelve información sobre el servidor y el protocolo soportado.
• tools/list: Muestra las herramientas disponibles y los argumentos que aceptan.
• tools/call: Ejecuta una herramienta (por ejemplo, list_files) y devuelve el resultado, que puede ser una lista de archivos y carpetas.

Ejemplo de respuesta para list_files:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Contents of '.':\n\nDirectories:\n  DIR: .cursor\n\nFiles:\n  FILE: file_explorer_client.py\n  FILE: file_explorer_server.py\n"
      }
    ]
  }
}

• Directories: Listado de carpetas (DIR:).
• Files: Listado de archivos (FILE).

4. Personalización

Puedes modificar el cliente para explorar otras rutas cambiando el argumento de línea de comandos al ejecutarlo:

python3 file_explorer_client.py otra/carpeta

¿Cómo funciona internamente?

• El cliente y el servidor se comunican usando JSON-RPC 2.0 por stdio.
• El servidor expone herramientas que el cliente puede descubrir y utilizar dinámicamente.
• El flujo es: inicializar → descubrir herramientas → llamar herramientas → mostrar resultados.

Configuración MCP con mcp.json

¿Qué es mcp.json?

El archivo mcp.json es un archivo de configuración que define los servidores MCP disponibles para un cliente. Se ubica típicamente en:

• macOS/Linux: ~/.cursor/mcp.json
• Windows: %APPDATA%\mcp.json

Estructura del archivo

{
	"mcpServers": {
	  "file_explorer": {
		"command": "python3",
		"args": ["[ruta-completa]file_explorer/file_explorer_server.py"],
		"env": {}
	  }
	}
  }

Alcance y funcionalidad

• Descubrimiento automático: Los clientes MCP buscan automáticamente este archivo para encontrar servidores disponibles.
• Configuración centralizada: Permite configurar múltiples servidores MCP desde un solo lugar.
• Integración con IDEs: Muchos editores de código (VS Code, Cursor, etc.) pueden usar esta configuración para integrar herramientas MCP.
• Herramientas dinámicas: Una vez configurado, las herramientas del servidor estarán disponibles en el IDE sin necesidad de ejecutar manualmente el cliente.

Configuración para este proyecto

Para integrar este servidor de exploración de archivos con un cliente MCP:

1. Crea o edita el archivo ~/.cursor/mcp.json
2. Añade la configuración del servidor con la ruta completa a file_explorer_server.py
3. Reinicia tu IDE o cliente MCP

Ejemplo de configuración completa:

{
	"mcpServers": {
	  "file_explorer": {
		"command": "python3",
		"args": ["[ruta-completa]file_explorer/file_explorer_server.py"],
		"env": {}
	  }
	}
  }

Una vez configurado, podrás usar las herramientas de exploración de archivos directamente desde tu IDE o cliente MCP preferido.