使用说明

Java MCP文件系统服务器

Java中的模型上下文协议（MCP）服务器实现，为AI助手提供文件系统访问。这个多模块项目提供了三种不同的传输机制（stdio、HTTP、SSE），它们都共享文件操作的通用业务逻辑。

特性

多种运输方式

标准：用于命令行集成的独立应用程序（Claude Desktop等）
超文本传输协议：基于Servlet的HTTP通信实现
上海证券交易所：用于实时流式传输的服务器发送事件servlet

全面的文件操作

服务器公开了10个MCP工具用于文件系统操作：

read_file：读取单个文件的完整内容
read_multiple_files：在一次操作中高效读取多个文件
write_file：创建新文件或覆盖现有文件
edit_file：使用diff预览支持进行基于行的编辑
create_directory：创建单个或嵌套目录结构
list_directory：使用类型指示符列出目录的内容
directory_tree：获取目录的递归JSON树视图
move_file：移动或重命名文件和目录
search_files：递归搜索与glob模式匹配的文件
get_file_info：检索详细的文件元数据（大小、时间戳、权限）

需求

Java 25
Gradle 9.x（用于从源代码构建）
HTTP/SSE模块的Servlet容器（Tomcat、Jetty等）
GraalVM（可选，用于本机映像编译）

从源头构建

克隆存储库：

git clone <repository-url>
cd mcp-server-filesystem

构建所有模块：

./gradlew clean build

这将创建以下工件：

标准: stdio/build/libs/stdio-1.0.0.jar -独立应用程序JAR
超文本传输协议: http/build/libs/http-1.0.0.war -HTTP servlet WAR文件
SSE: sse/build/libs/sse-1.0.0.war -SSE servlet WAR文件
工具: tools/build/libs/tools-1.0.0.jar -共享库JAR

构建单个模块：

./gradlew :stdio:build
./gradlew :http:build
./gradlew :sse:build

构建本机可执行文件（可选，需要GraalVM）：

./gradlew :stdio:nativeCompile

本机可执行文件将在以下位置创建 stdio/build/native/nativeCompile/mcp-server-filesystem 并提供更快的启动时间和更低的内存占用。

用法

选项1:stdio传输（独立）

stdio传输使用stdin/stdout进行通信。

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

或者运行本机可执行文件（如果使用GraalVM构建）：

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

使用Claude Desktop进行配置

添加到您的 claude_desktop_config.json:

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

选项2:HTTP传输（Servlet）

将WAR文件部署到servlet容器：

cp http/build/libs/http-1.0.0.war $TOMCAT_HOME/webapps/

HTTP端点将在以下位置可用：

http://localhost:8080/v1/mcp

安装tomcat server.xml

<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
    <Context path="/v1" docBase="http-1.0.0.war" reloadable="true" />
</Host>

选项3:SSE传输（Servlet）

将WAR文件部署到servlet容器：

cp sse/build/libs/sse-1.0.0.war $TOMCAT_HOME/webapps/

SSE端点将在以下位置可用：

SSE endpoint: http://localhost:8080/v2/sse
Messages endpoint: http://localhost:8080/v2/messages

安装tomcat server.xml

<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
    <Context path="/v2" docBase="sse-1.0.0.war" reloadable="true" />
</Host>

开发命令

# 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

关键依赖关系

io.modelcontextprotocol.sdk:mcp:0.15.0 -Java版MCP SDK
jakarta.servlet:jakarta.servlet-api:6.1.0 -Servlet API
io.github.java-diff-utils:java-diff-utils:4.12 -用于编辑操作的差异生成
com.fasterxml.jackson.core:jackson-databind:2.19.1 -JSON处理
Spock框架2.4-M6-groovy-4.0-测试

安全考虑

重要：本次实施具有 无路径验证 或目录限制。所有文件系统操作都不受限制，仅受运行服务器的用户权限的限制。

无路径限制：文件操作可以访问用户有权访问的任何路径
用户权限：服务器以与启动它的用户相同的权限运行
生产使用：考虑在部署到生产环境之前实施路径验证

备注：工具架构描述引用了“允许的目录”，但此功能在当前实现中不存在。

工具示例

读取文件

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

使用预览编辑文件

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

搜索文件

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

故障排除

常见问题

服务器无法启动：验证Java 25是否已安装并位于PATH中
WAR部署失败：确保您的servlet容器支持Jakarta servlet API 6.1 3权限错误：服务器只能访问运行用户有权访问的文件

调试

检查应用程序日志（stdio的stdout/stderr，HTTP/SSE的容器日志）中的错误消息。

版本历史

1.0.0 -具有stdio、HTTP和SSE传输的多模块架构
0.7.2 -具有单模块实现的早期版本

贡献

欢迎投稿！请确保：

代码遵循Java命名约定
共享中添加了新工具 tools 模块
工具模式在中定义正确 ToolSchemas.java
使用MCP客户端测试更改
测试是使用Spock Framework编写的 tools 模块

许可证

[在此处指定您的许可证]

作者

布鲁诺·罗赞多

致谢

与模型上下文协议SDK 对于Java
受TypeScript参考实现的启发