Java MCP Filesystem Server

Un servidor MCP seguro basado en Java que proporciona acceso controlado al sistema de archivos a

GitHub
1
Prueba este MCPPatrocinado

Documentación

Java MCP Filesystem Server

Una implementación de servidor del Model Context Protocol (MCP) en Java que proporciona acceso al sistema de archivos a asistentes de IA. Este proyecto multimódulo ofrece tres mecanismos de transporte diferentes (stdio, HTTP, SSE) que comparten toda la lógica de negocio común para operaciones de archivos.

Características

Múltiples opciones de transporte

  • stdio: Aplicación independiente para integración por línea de comandos (Claude Desktop, etc.)
  • HTTP: Implementación basada en servlets para comunicación HTTP
  • SSE: Servlet de Server-Sent Events para transmisión en tiempo real

Operaciones completas de archivos

El servidor expone 10 herramientas MCP para la manipulación del sistema de archivos:

  • read_file: Leer el contenido completo de un solo archivo
  • read_multiple_files: Leer eficientemente múltiples archivos en una sola operación
  • write_file: Crear archivos nuevos o sobrescribir los existentes
  • edit_file: Realizar ediciones basadas en líneas con soporte de vista previa de diff
  • create_directory: Crear estructuras de directorios simples o anidadas
  • list_directory: Listar el contenido de un directorio con indicadores de tipo
  • directory_tree: Obtener una vista de árbol JSON recursiva de directorios
  • move_file: Mover o renombrar archivos y directorios
  • search_files: Buscar recursivamente archivos que coincidan con patrones glob
  • get_file_info: Recuperar metadatos detallados de archivos (tamaño, marcas de tiempo, permisos)

Requisitos

  • Java 25
  • Gradle 9.x (para compilar desde el código fuente)
  • Contenedor de servlets (Tomcat, Jetty, etc.) para los módulos HTTP/SSE
  • GraalVM (opcional, para compilación de imagen nativa)

Compilación desde el código fuente

  1. Clona el repositorio:
git clone <repository-url>
cd mcp-server-filesystem
  1. Compila todos los módulos:
./gradlew clean build

Esto crea los siguientes artefactos:

  • stdio: stdio/build/libs/stdio-1.0.0.jar - JAR de aplicación independiente
  • http: http/build/libs/http-1.0.0.war - Archivo WAR de servlet HTTP
  • sse: sse/build/libs/sse-1.0.0.war - Archivo WAR de servlet SSE
  • tools: tools/build/libs/tools-1.0.0.jar - JAR de biblioteca compartida
  1. Compila módulos individuales:
./gradlew :stdio:build
./gradlew :http:build
./gradlew :sse:build
  1. Compila el ejecutable nativo (opcional, requiere GraalVM):
./gradlew :stdio:nativeCompile

El ejecutable nativo se creará en stdio/build/native/nativeCompile/mcp-server-filesystem y ofrece tiempos de inicio más rápidos y un menor uso de memoria.

Uso

Opción 1: Transporte stdio (independiente)

El transporte stdio utiliza stdin/stdout para la comunicación.

java -jar stdio/build/libs/stdio-1.0.0.jar

O ejecuta el ejecutable nativo (si se compiló con GraalVM):

./stdio/build/native/nativeCompile/mcp-server-filesystem

Configuración con Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/stdio-1.0.0.jar"
      ]
    }
  }
}

Opción 2: Transporte HTTP (Servlet)

  1. Despliega el archivo WAR en tu contenedor de servlets:
cp http/build/libs/http-1.0.0.war $TOMCAT_HOME/webapps/
  1. El endpoint HTTP estará disponible en:
http://localhost:8080/v1/mcp
  1. Configura tomcat server.xml
<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
    <Context path="/v1" docBase="http-1.0.0.war" reloadable="true" />
</Host>

Opción 3: Transporte SSE (Servlet)

  1. Despliega el archivo WAR en tu contenedor de servlets:
cp sse/build/libs/sse-1.0.0.war $TOMCAT_HOME/webapps/
  1. Los endpoints SSE estarán disponibles en:
SSE endpoint: http://localhost:8080/v2/sse
Messages endpoint: http://localhost:8080/v2/messages
  1. Configura tomcat server.xml
<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
    <Context path="/v2" docBase="sse-1.0.0.war" reloadable="true" />
</Host>

Comandos de desarrollo

# Run all tests
./gradlew test

# Run tests for tools module
./gradlew :tools:test

# Build without tests
./gradlew build -x test

# Generate test coverage report
./gradlew :tools:test jacocoTestReport

Dependencias clave

  • io.modelcontextprotocol.sdk:mcp:0.15.0 - MCP SDK para Java
  • jakarta.servlet:jakarta.servlet-api:6.1.0 - API de servlets
  • io.github.java-diff-utils:java-diff-utils:4.12 - Generación de diff para operaciones de edición
  • com.fasterxml.jackson.core:jackson-databind:2.19.1 - Procesamiento de JSON
  • Spock Framework 2.4-M6-groovy-4.0 - Pruebas

Consideraciones de seguridad

IMPORTANTE: Esta implementación no tiene validación de rutas ni restricciones de directorios. Todas las operaciones del sistema de archivos no están restringidas y solo están limitadas por los permisos del usuario que ejecuta el servidor.

  1. Sin restricciones de rutas: Las operaciones de archivos pueden acceder a cualquier ruta para la que el usuario tenga permisos
  2. Permisos de usuario: El servidor se ejecuta con los mismos permisos que el usuario que lo inicia
  3. Uso en producción: Considera implementar validación de rutas antes de desplegar en entornos de producción

Nota: Las descripciones del esquema de herramientas hacen referencia a "directorios permitidos", pero esta funcionalidad no existe en la implementación actual.

Ejemplos de herramientas

Lectura de un archivo

{
  "tool": "read_file",
  "parameters": {
    "path": "/Users/myuser/documents/example.txt"
  }
}

Edición de un archivo con vista previa

{
  "tool": "edit_file",
  "parameters": {
    "path": "/Users/myuser/documents/example.txt",
    "edits": [
      {
        "oldText": "Hello World",
        "newText": "Hello MCP"
      }
    ],
    "dryRun": true
  }
}

Búsqueda de archivos

{
  "tool": "search_files",
  "parameters": {
    "path": "/Users/myuser/projects",
    "pattern": "*.java",
    "excludePatterns": ["**/build/**", "**/target/**"]
  }
}

Solución de problemas

Problemas comunes

  1. El servidor no se inicia: Verifica que Java 25 esté instalado y en tu PATH
  2. El despliegue del WAR falla: Asegúrate de que tu contenedor de servlets sea compatible con Jakarta Servlet API 6.1 3Errores de permisos: El servidor solo puede acceder a archivos para los que el usuario en ejecución tenga permisos

Depuración

Revisa los registros de la aplicación (stdout/stderr para stdio, registros del contenedor para HTTP/SSE) para ver mensajes de error.

Historial de versiones

  • 1.0.0 - Arquitectura multimódulo con transportes stdio, HTTP y SSE
  • 0.7.2 - Versión anterior con implementación de módulo único

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, asegúrate de:

  1. El código sigue las convenciones de nomenclatura de Java
  2. Las nuevas herramientas se añaden al módulo compartido tools
  3. Los esquemas de herramientas están definidos correctamente en ToolSchemas.java
  4. Los cambios se prueban con un cliente MCP
  5. Las pruebas se escriben usando Spock Framework en el módulo tools

Licencia

[Especifica tu licencia aquí]

Autor

Bruno Rozendo

Agradecimientos