Java Filesystem & Web MCP Server

Un servidor MCP para que agentes LLM realicen operaciones del sistema de archivos y accedan a recursos web.

GitHub
25
Prueba este MCPPatrocinado

Documentación

Java Filesystem & Web MCP Server

Este proyecto implementa un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona operaciones de sistema de archivos y herramientas de acceso web para agentes de Modelos de Lenguaje Grande (LLM). Permite a los asistentes de IA interactuar tanto con el sistema de archivos local como con recursos web a través de un conjunto de operaciones bien definidas.

Características

El servidor proporciona las siguientes operaciones:

Operaciones de Sistema de Archivos

  • Lectura de Archivos: Lee el contenido completo de un archivo con detección adecuada de codificación
  • Escritura de Archivos: Crea o sobrescribe archivos con contenido nuevo
  • Edición de Archivos: Realiza ediciones basadas en líneas con generación de diff estilo git
  • Búsqueda de Archivos: Busca recursivamente archivos y directorios usando patrones glob
  • Listado de Directorios: Obtiene listados detallados del contenido de directorios
  • Creación de Directorios: Crea directorios y estructuras de directorios anidadas
  • Grep de Archivos: Busca patrones de texto dentro de archivos con números de línea y contexto, similar al comando grep de Unix
  • Comando Bash: Ejecuta comandos bash en el shell del sistema y captura su salida

Operaciones Web

  • Obtención de Páginas Web: Recupera contenido de páginas web con tiempos de espera configurables
  • Extracción de Contenido HTML: Extrae contenido de texto de documentos HTML

Estas operaciones se exponen como herramientas para Modelos de Lenguaje Grande mediante el Protocolo de Contexto de Modelo (MCP), permitiendo que los sistemas de IA interactúen de forma segura con el sistema de archivos y accedan a recursos web.

Ejemplo de la herramienta Java MCP con DevoxxGenie

Screenshot 2025-03-26 at 09 52 26

Comenzando

Requisitos Previos

  • Java 17 o superior
  • Maven 3.6+
  • Spring Boot 3.3.6
  • Componentes Spring AI MCP Server

Construyendo el Proyecto

Construya el proyecto usando Maven:

mvn clean package

Ejecutando el Servidor

El servidor soporta dos modos de transporte:

Modo SSE (basado en HTTP, predeterminado)

Ejecute el servidor para comunicación basada en SSE:

java -jar target/devoxx-filesystem-0.0.1-SNAPSHOT.jar

Esto inicia un servidor HTTP en el puerto 8081 con el endpoint SSE en /sse.

Modo STDIO (para clientes MCP como Claude Desktop o DevoxxGenie)

Para comunicación basada en STDIO (requerida por la mayoría de los clientes MCP):

java -Dspring.ai.mcp.server.stdio=true \
     -Dspring.main.web-application-type=none \
     -Dspring.main.banner-mode=off \
     -Dlogging.pattern.console= \
     -jar target/devoxx-filesystem-0.0.1-SNAPSHOT.jar

Banderas importantes para el modo STDIO:

  • -Dspring.ai.mcp.server.stdio=true - Habilita el transporte STDIO
  • -Dspring.main.web-application-type=none - Deshabilita el servidor web
  • -Dspring.main.banner-mode=off - Deshabilita el banner de Spring Boot (requerido para evitar corromper la comunicación JSON-RPC)
  • -Dlogging.pattern.console= - Deshabilita el registro de consola

Servicios de Herramientas

Herramientas de Sistema de Archivos

ReadFileService

readFile(String fullPathFile)

Lee el contenido completo de un archivo del sistema de archivos. Maneja varias codificaciones de texto y proporciona mensajes de error detallados si el archivo no se puede leer.

WriteFileService

writeFile(String path, String content)

Crea un archivo nuevo o sobrescribe completamente un archivo existente con contenido nuevo. Crea los directorios padre si no existen.

EditFileService

editFile(String path, String edits, Boolean dryRun)

Realiza ediciones basadas en líneas en un archivo de texto. Cada edición reemplaza secuencias de líneas exactas con contenido nuevo. Devuelve un diff estilo git que muestra los cambios realizados. El parámetro dryRun permite ver los cambios sin aplicarlos.

SearchFilesService

searchFiles(String path, String pattern)

Busca recursivamente archivos y directorios que coincidan con un patrón. Busca en todos los subdirectorios desde la ruta inicial. La búsqueda no distingue entre mayúsculas y minúsculas y coincide con nombres parciales.

ListDirectoryService

listDirectory(String path)

Obtiene un listado detallado de todos los archivos y directorios en una ruta especificada. Los resultados distinguen claramente entre archivos y directorios con metadatos adicionales.

GrepFilesService

grepFiles(String directory, String pattern, String fileExtension, Boolean useRegex, Integer contextLines, Integer maxResults, Boolean ignoreCase)

Busca patrones de texto dentro de archivos. Devuelve archivos coincidentes con números de línea y contexto. Similar al comando 'grep' de Unix pero con características adicionales para la visualización de contexto. Soporta patrones regex, búsqueda sin distinción de mayúsculas y minúsculas, y líneas de contexto antes/después de las coincidencias.

CreateDirectoryService

createDirectory(List<String> directories)

Crea directorios nuevos o asegura que los directorios existan. Puede crear múltiples directorios en una sola operación. Si un directorio ya existe, la operación se completa silenciosamente. Perfecto para configurar estructuras de directorios para proyectos o asegurar que existan las rutas requeridas.

BashService

executeBash(String command, String workingDirectory, Integer timeoutSeconds)

Ejecuta un comando Bash en el shell del sistema y devuelve la salida. Esta herramienta permite ejecutar comandos del sistema y capturar sus flujos de salida estándar y de error. Úsela con precaución ya que algunos comandos pueden tener efectos a nivel de sistema.

Herramientas Web

FetchWebpageService

fetchWebpage(String url, Integer timeoutMs)

Obtiene o lee una página web desde una URL y devuelve su contenido. El servicio utiliza jsoup para conectarse a la página web y recuperar su contenido. El parámetro opcional timeoutMs permite establecer un tiempo de espera de conexión personalizado.

Pruebas

Ejecutando Pruebas Unitarias

Se proporciona un conjunto completo de pruebas unitarias para todas las clases de servicio. Ejecútelas usando:

mvn test

Las pruebas utilizan JUnit 5 y Mockito para simular dependencias externas como la biblioteca jsoup para solicitudes web.

Ejecutando Pruebas de Integración

Las pruebas de integración verifican el transporte STDIO iniciando el servidor como un subproceso. Primero construya el JAR, luego ejecute las pruebas de integración:

mvn package -DskipTests
mvn test -Pintegration-tests

Clientes de Prueba

Se proporcionan clientes de prueba para demostrar el uso del protocolo MCP:

  • ClientStdio.java - Demuestra la comunicación de transporte STDIO
  • ClientSse.java - Demuestra la comunicación de transporte SSE

Configuración

La aplicación se configura mediante application.properties:

spring.main.web-application-type=none
spring.main.banner-mode=off
logging.pattern.console=

spring.ai.mcp.server.name=filesystem-server
spring.ai.mcp.server.version=0.0.1

logging.file.name=,/JavaFileSystemMCP/target/filesystem-server.log

Estructura del Proyecto

JavaFileSystemMCP/
  src/
    main/
      java/
        com/
          devoxx/
            mcp/
              filesystem/
                tools/
                  EditFileService.java
                  ReadFileService.java
                  WriteFileService.java
                  SearchFilesService.java
                  FetchWebpageService.java
                  ListDirectoryService.java
                  CreateDirectoryService.java
                  GrepFilesService.java
                  BashService.java
                McpServerApplication.java
      resources/
        application.properties
    test/
      java/
        com/
          devoxx/
            mcp/
              filesystem/
                tools/
                  ReadFileServiceTest.java
                  WriteFileServiceTest.java
                  EditFileServiceTest.java
                  SearchFilesServiceTest.java
                  FetchWebpageServiceTest.java
                  ListDirectoryServiceTest.java
                  CreateDirectoryServiceTest.java
                  GrepFilesServiceTest.java
                ClientStdio.java
  pom.xml
  README.md

Dependencias

El proyecto utiliza:

  • Spring Boot 3.3.6
  • Componentes Spring AI MCP Server
  • Jackson para procesamiento JSON
  • jsoup para análisis HTML y recuperación de contenido web
  • JUnit 5 y Mockito para pruebas

Notas de Implementación

  • El servidor está diseñado para operar usando el mecanismo de transporte STDIO
  • El modo banner y el registro de consola están deshabilitados para permitir que el transporte STDIO funcione correctamente
  • El manejo de errores proporciona información detallada sobre los problemas encontrados durante las operaciones
  • Cada servicio de herramienta incluye manejo de errores integral y devuelve resultados en un formato JSON estandarizado
  • El EditFileService incluye generación de diff sofisticada para el seguimiento de cambios
  • El SearchFilesService soporta patrones glob para coincidencia flexible de archivos
  • El FetchWebpageService incluye tiempos de espera configurables y manejo de errores robusto para solicitudes web

Integración con el Soporte MCP de DevoxxGenie

Este servidor se puede integrar fácilmente con DevoxxGenie usando el soporte MCP (Protocolo de Contexto de Modelo). Así es como configurarlo:

Configuración en DevoxxGenie

  1. En DevoxxGenie, acceda a la pantalla de configuración del Servidor MCP
  2. Configure el servidor con los siguientes ajustes:

    • Nombre: JavaFilesystem (o cualquier nombre descriptivo)

    • Tipo de Transporte: STDIO

    • Comando: Ruta completa a su ejecutable de Java (por ejemplo, /Library/Java/JavaVirtualMachines/liberica-jdk-23.jdk/Contents/Home/bin/java)

    • Argumentos:

      -Dspring.ai.mcp.server.stdio=true
-Dspring.main.web-application-type=none
-Dspring.main.banner-mode=off
-Dlogging.pattern.console=
-jar
~/JavaFileSystemMCP/target/devoxx-filesystem-0.0.1-SNAPSHOT.jar

      Ingrese cada argumento en una línea nueva. Es posible que deba cambiar la ruta de -jar para que apunte a donde ha construido el jar.

      Importante: La bandera -Dspring.main.banner-mode=off es necesaria para deshabilitar el banner de Spring Boot, que de otro modo interferiría con la comunicación JSON-RPC a través de STDIO.

Uso con DevoxxGenie

Una vez configurado, DevoxxGenie descubrirá automáticamente las herramientas proporcionadas por este servidor MCP. El asistente de IA puede entonces usar estas herramientas para:

  1. Leer y escribir archivos en el sistema local
  2. Buscar archivos y directorios
  3. Listar el contenido de directorios
  4. Realizar ediciones en archivos existentes
  5. Buscar patrones de texto dentro de archivos (grep)
  6. Crear directorios y estructuras de directorios anidadas
  7. Ejecutar comandos bash en el shell del sistema
  8. Obtener páginas web y extraer contenido

Todas las operaciones se realizarán con los permisos del usuario que ejecuta la aplicación DevoxxGenie.

Uso con Claude Desktop

Edite su archivo claude_desktop_config.json con lo siguiente:

{
  "mcpServers": {
    "filesystem": {
      "command": "/Library/Java/JavaVirtualMachines/liberica-jdk-23.jdk/Contents/Home/bin/java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dspring.main.banner-mode=off",
        "-Dlogging.pattern.console=",
        "-jar",
        "~/JavaFileSystemMCP/target/devoxx-filesystem-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

Es posible que deba cambiar la ruta de -jar para que apunte a donde ha construido el jar.

Importante: La bandera -Dspring.main.banner-mode=off es necesaria para deshabilitar el banner de Spring Boot, que de otro modo interferiría con la comunicación JSON-RPC a través de STDIO.

image

Consideraciones de Seguridad

Al usar este servidor, tenga en cuenta que:

  • El agente LLM tendrá acceso para leer y escribir archivos en el sistema host
  • El agente puede ejecutar comandos bash con los permisos del usuario que ejecuta la aplicación
  • El agente puede obtener contenido de cualquier URL web accesible
  • Considere ejecutar el servidor con permisos apropiados y en un entorno controlado
  • El servidor no implementa mecanismos de autenticación o autorización
  • Considere las reglas del firewall de red si se requiere restringir el acceso web