MCP Java File System

Java文件系统和Web MCP服务器

该项目实现了一个模型上下文协议（MCP）服务器，为大型语言模型（LLM）代理提供文件系统操作和web访问工具。它使AI助手能够通过一组定义良好的操作与本地文件系统和web资源进行交互。

特性

服务器提供以下操作：

文件系统操作

• 读取文件：通过适当的编码检测读取文件的完整内容
• 写入文件：用新内容创建或覆盖文件
• 编辑文件：使用git风格的diff生成进行基于行的编辑
• 搜索文件：使用glob模式递归搜索文件和目录
• 列表目录：获取目录内容的详细列表
• 目录创建：创建目录和嵌套目录结构
• Grep文件：在具有行号和上下文的文件中搜索文本模式，类似于Unix grep命令
• Bash命令：在系统shell中执行bash命令并捕获其输出

Web操作

• 网页抓取：使用可配置的超时从网页中检索内容
• HTML内容提取：从HTML文档中提取文本内容

这些操作作为使用模型上下文协议（MCP）的大型语言模型的工具公开，允许AI系统安全地与文件系统交互并访问web资源。

MCP Java工具示例 DevoxxGenie

入门指南

先决条件

• Java 17或更高版本
• Maven 3.6+
• 弹簧靴3.3.6
• Spring AI MCP服务器组件

建设项目

使用Maven构建项目：

mvn clean package

运行服务器

服务器支持两种传输模式：

SSE模式（基于HTTP，默认）

运行服务器进行基于SSE的通信：

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

这将在端口8081上启动一个HTTP服务器，SSE端点位于 /sse.

STDIO模式（适用于Claude Desktop或DevoxxGenie等MCP客户端）

对于基于STDIO的通信（大多数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

STDIO模式的重要标志：

• -Dspring.ai.mcp.server.stdio=true -启用STDIO传输
• -Dspring.main.web-application-type=none -禁用web服务器
• -Dspring.main.banner-mode=off -禁用Spring Boot横幅（需要避免损坏JSON-RPC通信）
• -Dlogging.pattern.console= -禁用控制台日志记录

工具服务

文件系统工具

ReadFile服务

readFile(String fullPathFile)

从文件系统读取文件的完整内容。处理各种文本编码，并在无法读取文件时提供详细的错误消息。

WriteFileService

writeFile(String path, String content)

创建新文件或用新内容完全覆盖现有文件。如果父目录不存在，则创建父目录。

编辑文件服务

editFile(String path, String edits, Boolean dryRun)

对文本文件进行基于行的编辑。每次编辑都会用新内容替换精确的行序列。返回一个git风格的diff，显示所做的更改。这 dryRun 参数允许在不应用更改的情况下查看更改。

搜索文件服务

searchFiles(String path, String pattern)

递归搜索与模式匹配的文件和目录。从起始路径搜索所有子目录。搜索不区分大小写，并匹配部分名称。

列表目录服务

listDirectory(String path)

获取指定路径中所有文件和目录的详细列表。结果清楚地区分了具有额外元数据的文件和目录。

GrepFiles服务

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

在文件中搜索文本模式。返回具有行号和上下文的匹配文件。类似于Unix的“grep”命令，但具有用于上下文显示的附加功能。支持正则表达式模式、不区分大小写的搜索以及匹配前后的上下文行。

创建目录服务

createDirectory(List directories)

创建新目录或确保目录存在。可以在一次操作中创建多个目录。如果目录已存在，则操作将自动成功。非常适合为项目设置目录结构或确保存在所需的路径。

BashService

executeBash(String command, String workingDirectory, Integer timeoutSeconds)

在系统shell中执行Bash命令并返回输出。此工具允许运行系统命令并捕获其标准输出和错误流。请谨慎使用，因为某些命令可能会对整个系统产生影响。

Web工具

获取网页服务

fetchWebpage(String url, Integer timeoutMs)

从URL获取或读取网页并返回其内容。该服务使用jsoup连接到网页并检索其内容。可选 timeoutMs 参数允许设置自定义连接超时。

测试

运行单元测试

为所有服务类别提供了一套全面的单元测试。使用以下命令运行它们：

mvn test

这些测试使用JUnit5和Mockito来模拟外部依赖关系，如用于web请求的jsoup库。

运行集成测试

集成测试通过将服务器作为子进程生成来验证STDIO传输。首先构建JAR，然后运行集成测试：

mvn package -DskipTests
mvn test -Pintegration-tests

测试客户端

提供测试客户端以演示MCP协议的使用：

• ClientStdio.java -演示STDIO传输通信
• ClientSse.java -演示SSE传输通信

配置

应用程序通过以下方式配置 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

项目结构

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

依赖项

该项目使用：

• 弹簧靴3.3.6
• Spring AI MCP服务器组件
• Jackson用于JSON处理
• jsoup用于HTML解析和web内容检索
• JUnit5和Mockito用于测试

实施说明

• 服务器设计为使用STDIO传输机制运行
• 禁用横幅模式和控制台日志记录，以允许STDIO传输正常工作
• 错误处理提供了有关操作过程中遇到的问题的详细信息
• 每个工具服务都包括全面的错误处理，并以标准化的JSON格式返回结果
• 这 EditFileService 包括用于跟踪变化的复杂差异生成
• 这 SearchFilesService 支持glob模式以实现灵活的文件匹配
• 这 FetchWebpageService 包括可配置的超时和针对web请求的稳健错误处理

与DevoxxGenie MCP支持集成

此服务器可以使用MCP（模型上下文协议）支持轻松地与DevoxxGenie集成。以下是如何设置它：

DevoxxGenie中的配置

1. 在DevoxxGenie中，访问MCP服务器配置屏幕
2. 使用以下设置配置服务器：

- 名字: JavaFilesystem （或任何描述性名称）

- 传输类型: STDIO

- 命令：Java可执行文件的完整路径（例如。， /Library/Java/JavaVirtualMachines/liberica-jdk-23.jdk/Contents/Home/bin/java)

- 参数:

     -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

在新行中输入每个参数。您可能需要更改-jar的路径，以指向构建jar的位置。

重要：The -Dspring.main.banner-mode=off 需要标志来禁用Spring Boot横幅，否则会干扰STDIO上的JSON-RPC通信。

使用DevoxxGenie

配置后，DevoxxGenie将自动发现此MCP服务器提供的工具。然后，AI助手可以使用这些工具：

1. 在本地系统上读写文件
2. 搜索文件和目录
3. 列出目录内容
4. 对现有文件进行编辑
5. 在文件中搜索文本模式（grep）
6. 创建目录和嵌套目录结构
7. 在系统shell中执行bash命令
8. 获取网页并提取内容

所有操作都将在运行DevoxxGenie应用程序的用户的权限下执行。

与Claude Desktop一起使用

使用以下命令编辑claude_desktop_config.json文件：

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

您可能需要更改-jar的路径，以指向构建jar的位置。

重要：The -Dspring.main.banner-mode=off 需要标志来禁用Spring Boot横幅，否则会干扰STDIO上的JSON-RPC通信。

安全考虑

使用此服务器时，请注意：

• LLM代理将有权读取和写入主机系统上的文件
• 代理可以在运行应用程序的用户的权限下执行bash命令
• 代理可以从任何可访问的web URL获取内容
• 考虑在受控环境中以适当的权限运行服务器
• 服务器未实现身份验证或授权机制
• 如果需要限制web访问，请考虑网络防火墙规则