Accessing Local File System with Spring AI MCP
Case 1: Accessing Local File System with Spring AI MCP
Here we provide a sample agent application that can query or update the local file system via MCP and interact with the model using data from the file system as context. This example demonstrates how to use the Model Context Protocol (MCP) to integrate Spring AI with the local file system.
You can view the complete source code for this example.
Running the Example
Prerequisites
-
Install npx (Node Package eXecute): First, ensure that npm is installed on your local machine, then run the following command:
Terminal window npm install -g npx -
Download the example source code
Terminal window git clone https://github.com/springaialibaba/spring-ai-alibaba-examples.gitcd spring-ai-alibaba-examples/spring-ai-alibaba-mcp-example/spring-ai-alibaba-mcp-manual-example/ai-mcp-fileserver -
Set environment variables
Terminal window # Tongyi LLM Dashscope API-KEYexport AI_DASHSCOPE_API_KEY=${your-api-key-here} -
Build the example
Terminal window ./mvnw clean install
Running the Sample Application
Run the example, and the agent will send questions to the model (the source code includes preset questions, which you can view in the source code). You can check the output results through the console.
./mvnw spring-boot:run
If you are running the example in an IDE and encounter file access permission issues returned by the filesystem mcp server, please ensure that the current process working directory is set to the spring-ai-alibaba-mcp-example/filesystem directory.
Example Architecture (Source Code Explanation)
In the previous section, we explained the basic architecture of integrating Spring AI with MCP. In the following example, we will use these key components:
- MCP Client, the key to integrating with MCP, providing the ability to interact with the local file system.
- Function Callbacks, Spring AI MCP’s function calling declaration method.
- Chat Client, a key component of Spring AI, used for LLM model interaction and agent proxying.
Declaring ChatClient
// List<McpFunctionCallback> functionCallbacks;var chatClient = chatClientBuilder.defaultFunctions(functionCallbacks).build();
As with developing previous Spring AI applications, we first define a ChatClient Bean for interacting with the large model. Note that the functions we inject into ChatClient are created through the MCP component (McpFunctionCallback).
Let’s take a closer look at how McpFunctionCallback is used.
Declaring MCP Function Callbacks
The following code snippet interacts with the MCP server through mcpClient
and adapts MCP tools as standard Spring AI functions through McpFunctionCallback.
- Discover the list of available tools in the MCP server (called functions in Spring AI)
- Convert each tool into a Spring AI function callback
- We will ultimately register these McpFunctionCallbacks with ChatClient
@Beanpublic List<McpFunctionCallback> functionCallbacks(McpSyncClient mcpClient) { // Get the list of tools from the MCP server return mcpClient.listTools(null) // Convert each tool to a Function Callback .tools() .stream() .map(tool -> new McpFunctionCallback(mcpClient, tool)) .toList();}
As you can see, the process of ChatClient interacting with the model remains unchanged. When needed, the model informs ChatClient to make function calls, but Spring AI delegates the actual function call process to MCP through McpFunctionCallback, interacting with the local file system via the standard MCP protocol:
- During interaction with the large model, ChatClient handles related function calls requests
- ChatClient calls MCP tools (through McpClient)
- McpClient interacts with the MCP server (i.e., filesystem)
Initializing McpClient
This agent application uses a synchronous MCP client to communicate with the locally running filesystem MCP server:
@Bean(destroyMethod = "close")public McpSyncClient mcpClient() { // Configure server startup parameters var stdioParams = ServerParameters.builder("npx") .args("-y", "@modelcontextprotocol/server-filesystem", "path")) .build(); // 1
// Create synchronous MCP client var mcpClient = McpClient.sync(new StdioServerTransport(stdioParams), Duration.ofSeconds(10), new ObjectMapper()); //2
// Initialize client connection var init = mcpClient.initialize(); // 3 System.out.println("MCP Initialized: " + init);
return mcpClient;}
In the code above:
- Configure the MCP server startup command and parameters
- Initialize McpClient: associate with MCP server, specify timeout, etc.
- Spring AI will use
npx -y @modelcontextprotocol/server-filesystem "/path/to/file"
to create a separate subprocess (representing the local Mcp server) on the local machine. Spring AI communicates with McpClient, which in turn operates on the local file through the connection with the Mcp server.