Java Filesystem & Web MCP Server
This project implements a Model Context Protocol (MCP) server that provides filesystem operations and web access tools for Large Language Model (LLM) agents. It enables AI assistants to interact with both the local filesystem and web resources through a set of well-defined operations.
Features
The server provides the following operations:
Filesystem Operations
- Reading Files: Read the complete contents of a file with proper encoding detection
- Writing Files: Create or overwrite files with new content
- Editing Files: Make line-based edits with git-style diff generation
- Searching Files: Recursively search for files and directories using glob patterns
- Listing Directories: Get detailed listings of directory contents
- Directory Creation: Create directories and nested directory structures
- Grep Files: Search for text patterns within files with line numbers and context, similar to Unix grep command
- Bash Command: Execute bash commands in the system shell and capture their output
Web Operations
- Web Page Fetching: Retrieve content from web pages with configurable timeouts
- HTML Content Extraction: Extract text content from HTML documents
These operations are exposed as tools for Large Language Models using the Model Context Protocol (MCP), allowing AI systems to safely interact with the filesystem and access web resources.
Example of the MCP Java tool with [DevoxxGenie](https://github.com/devoxx/DevoxxGenieIDEAPlugin)
Getting Started
Prerequisites
- Java 17 or higher
- Maven 3.6+
- Spring Boot 3.3.6
- Spring AI MCP Server components
Building the Project
Build the project using Maven:
Running the Server
Run the server using the following command:
The server uses STDIO for communication, so it doesn't expose any HTTP endpoints. It's designed to be launched by an MCP client.
Tool Services
Filesystem Tools
ReadFileService
Reads the complete contents of a file from the file system. Handles various text encodings and provides detailed error messages if the file cannot be read.
WriteFileService
Creates a new file or completely overwrites an existing file with new content. Creates parent directories if they don't exist.
EditFileService
Makes line-based edits to a text file. Each edit replaces exact line sequences with new content. Returns a git-style diff showing the changes made. The
dryRun parameter allows viewing changes without applying them.SearchFilesService
Recursively searches for files and directories matching a pattern. Searches through all subdirectories from the starting path. The search is case-insensitive and matches partial names.
ListDirectoryService
Gets a detailed listing of all files and directories in a specified path. Results clearly distinguish between files and directories with additional metadata.
GrepFilesService
Searches for text patterns within files. Returns matching files with line numbers and context. Similar to the Unix 'grep' command but with additional features for context display. Supports regex patterns, case-insensitive search, and context lines before/after matches.
CreateDirectoryService
Creates new directories or ensures that directories exist. Can create multiple directories in one operation. If a directory already exists, the operation succeeds silently. Perfect for setting up directory structures for projects or ensuring required paths exist.
BashService
Execute a Bash command in the system shell and return the output. This tool allows running system commands and capturing their standard output and error streams. Use with caution as some commands may have system-wide effects.
Web Tools
FetchWebpageService
Fetches or reads a webpage from a URL and returns its content. The service uses jsoup to connect to the webpage and retrieve its content. The optional
timeoutMs parameter allows setting a custom connection timeout.Testing
Running the Tests
A comprehensive set of unit tests is provided for all service classes. Run them using:
The tests use JUnit 5 and Mockito for mocking external dependencies like the jsoup library for web requests.
Test Client
A test client is provided in
ClientStdio.java which demonstrates how to invoke the tools using the MCP protocol.Configuration
The application is configured via
application.properties:Project Structure
Dependencies
The project uses:
- Spring Boot 3.3.6
- Spring AI MCP Server Components
- Jackson for JSON processing
- jsoup for HTML parsing and web content retrieval
- JUnit 5 and Mockito for testing
Implementation Notes
- The server is designed to operate using the STDIO transport mechanism
- Banner mode and console logging are disabled to allow the STDIO transport to work properly
- Error handling provides detailed information about issues encountered during operations
- Each tool service includes comprehensive error handling and returns results in a standardized JSON format
- The
EditFileServiceincludes sophisticated diff generation for tracking changes
- The
SearchFilesServicesupports glob patterns for flexible file matching
- The
FetchWebpageServiceincludes configurable timeouts and robust error handling for web requests
Integration with DevoxxGenie MCP Support
This server can be easily integrated with DevoxxGenie using the MCP (Model Context Protocol) support. Here's how to set it up:
Configuration in DevoxxGenie
- In DevoxxGenie, access the MCP Server configuration screen
- Configure the server with the following settings:
Usage with DevoxxGenie
Once configured, DevoxxGenie will automatically discover the tools provided by this MCP server. The AI assistant can then use these tools to:
- Read and write files on the local system
- Search for files and directories
- List directory contents
- Make edits to existing files
- Search for text patterns within files (grep)
- Create directories and nested directory structures
- Execute bash commands in the system shell
- Fetch web pages and extract content
All operations will be performed with the permissions of the user running the DevoxxGenie application.
Using with Claude Desktop
Edit your claude_desktop_config.json file with the following:
Security Considerations
When using this server, be aware that:
- The LLM agent will have access to read and write files on the host system
- The agent can execute bash commands with the permissions of the user running the application
- The agent can fetch content from any accessible web URL
- Consider running the server with appropriate permissions and in a controlled environment
- The server does not implement authentication or authorization mechanisms
- Consider network firewall rules if restricting web access is required
Java Filesystem & Web MCP Server
This project implements a Model Context Protocol (MCP) server that provides filesystem operations and web access tools for Large Language Model (LLM) agents. It enables AI assistants to interact with both the local filesystem and web resources through a set of well-defined operations.
Features
The server provides the following operations:
Filesystem Operations
- Reading Files: Read the complete contents of a file with proper encoding detection
- Writing Files: Create or overwrite files with new content
- Editing Files: Make line-based edits with git-style diff generation
- Searching Files: Recursively search for files and directories using glob patterns
- Listing Directories: Get detailed listings of directory contents
- Directory Creation: Create directories and nested directory structures
- Grep Files: Search for text patterns within files with line numbers and context, similar to Unix grep command
- Bash Command: Execute bash commands in the system shell and capture their output
Web Operations
- Web Page Fetching: Retrieve content from web pages with configurable timeouts
- HTML Content Extraction: Extract text content from HTML documents
These operations are exposed as tools for Large Language Models using the Model Context Protocol (MCP), allowing AI systems to safely interact with the filesystem and access web resources.
Example of the MCP Java tool with [DevoxxGenie](https://github.com/devoxx/DevoxxGenieIDEAPlugin)
Getting Started
Prerequisites
- Java 17 or higher
- Maven 3.6+
- Spring Boot 3.3.6
- Spring AI MCP Server components
Building the Project
Build the project using Maven:
Running the Server
Run the server using the following command:
The server uses STDIO for communication, so it doesn't expose any HTTP endpoints. It's designed to be launched by an MCP client.
Tool Services
Filesystem Tools
ReadFileService
Reads the complete contents of a file from the file system. Handles various text encodings and provides detailed error messages if the file cannot be read.
WriteFileService
Creates a new file or completely overwrites an existing file with new content. Creates parent directories if they don't exist.
EditFileService
Makes line-based edits to a text file. Each edit replaces exact line sequences with new content. Returns a git-style diff showing the changes made. The
dryRun parameter allows viewing changes without applying them.SearchFilesService
Recursively searches for files and directories matching a pattern. Searches through all subdirectories from the starting path. The search is case-insensitive and matches partial names.
ListDirectoryService
Gets a detailed listing of all files and directories in a specified path. Results clearly distinguish between files and directories with additional metadata.
GrepFilesService
Searches for text patterns within files. Returns matching files with line numbers and context. Similar to the Unix 'grep' command but with additional features for context display. Supports regex patterns, case-insensitive search, and context lines before/after matches.
CreateDirectoryService
Creates new directories or ensures that directories exist. Can create multiple directories in one operation. If a directory already exists, the operation succeeds silently. Perfect for setting up directory structures for projects or ensuring required paths exist.
BashService
Execute a Bash command in the system shell and return the output. This tool allows running system commands and capturing their standard output and error streams. Use with caution as some commands may have system-wide effects.
Web Tools
FetchWebpageService
Fetches or reads a webpage from a URL and returns its content. The service uses jsoup to connect to the webpage and retrieve its content. The optional
timeoutMs parameter allows setting a custom connection timeout.Testing
Running the Tests
A comprehensive set of unit tests is provided for all service classes. Run them using:
The tests use JUnit 5 and Mockito for mocking external dependencies like the jsoup library for web requests.
Test Client
A test client is provided in
ClientStdio.java which demonstrates how to invoke the tools using the MCP protocol.Configuration
The application is configured via
application.properties:Project Structure
Dependencies
The project uses:
- Spring Boot 3.3.6
- Spring AI MCP Server Components
- Jackson for JSON processing
- jsoup for HTML parsing and web content retrieval
- JUnit 5 and Mockito for testing
Implementation Notes
- The server is designed to operate using the STDIO transport mechanism
- Banner mode and console logging are disabled to allow the STDIO transport to work properly
- Error handling provides detailed information about issues encountered during operations
- Each tool service includes comprehensive error handling and returns results in a standardized JSON format
- The
EditFileServiceincludes sophisticated diff generation for tracking changes
- The
SearchFilesServicesupports glob patterns for flexible file matching
- The
FetchWebpageServiceincludes configurable timeouts and robust error handling for web requests
Integration with DevoxxGenie MCP Support
This server can be easily integrated with DevoxxGenie using the MCP (Model Context Protocol) support. Here's how to set it up:
Configuration in DevoxxGenie
- In DevoxxGenie, access the MCP Server configuration screen
- Configure the server with the following settings:
Usage with DevoxxGenie
Once configured, DevoxxGenie will automatically discover the tools provided by this MCP server. The AI assistant can then use these tools to:
- Read and write files on the local system
- Search for files and directories
- List directory contents
- Make edits to existing files
- Search for text patterns within files (grep)
- Create directories and nested directory structures
- Execute bash commands in the system shell
- Fetch web pages and extract content
All operations will be performed with the permissions of the user running the DevoxxGenie application.
Using with Claude Desktop
Edit your claude_desktop_config.json file with the following:
Security Considerations
When using this server, be aware that:
- The LLM agent will have access to read and write files on the host system
- The agent can execute bash commands with the permissions of the user running the application
- The agent can fetch content from any accessible web URL
- Consider running the server with appropriate permissions and in a controlled environment
- The server does not implement authentication or authorization mechanisms
- Consider network firewall rules if restricting web access is required