alexgfeller/mcp-server-demo

MCP Server Demo with Spring AI

A Model Context Protocol (MCP) server implementation using Spring AI 1.0.1 and Spring Boot 3.5.4, featuring file system tools accessible via STDIO transport.

Features

• MCP Server with STDIO Transport: Communicates via standard input/output streams
• File System Tools: Read, write, list, delete files and get file information
• Spring AI Integration: Leverages Spring AI's MCP Server Boot Starter
• Security: Path validation to prevent directory traversal attacks
• Comprehensive Testing: Unit tests for all file operations

Prerequisites

• Java 17 or higher
• Maven 3.6+

Project Structure

mcp-server-demo/
├── src/main/java/io/gfeller/mcp/demo/
│   ├── McpServerDemoApplication.java      # Main application class
│   ├── config/
│   │   └── McpServerConfig.java          # MCP configuration
│   └── filesystem/
│       ├── FileSystemService.java        # Core file operations
│       └── FileSystemTools.java          # MCP tool annotations
├── src/main/resources/
│   └── application.yml                   # Application configuration
└── pom.xml                               # Maven dependencies

Available Tools

The MCP server exposes the following file system tools:

1. readFile(path) - Read file contents
2. writeFile(path, content) - Write content to a file
3. listFiles(directory) - List files in a directory
4. deleteFile(path) - Delete a file
5. fileExists(path) - Check if a file exists
6. getFileInfo(path) - Get detailed file information

Building and Running

Build the Project

mvn clean install

Run Tests

mvn test

Run the MCP Server

mvn spring-boot:run

Or run the JAR directly:

java -jar target/mcp-server-demo-0.0.1-SNAPSHOT.jar

Configuration

The server is configured via application.yml:

spring:
  ai:
    mcp:
      server:
        enabled: true        # Enable MCP server
        stdio: true         # Use STDIO transport
        name: file-system-mcp-server
        version: 1.0.0
        type: SYNC          # Synchronous operations
        capabilities:
          tool: true        # Enable tool support
          resource: true    # Enable resource support

Testing the MCP Server

Using STDIO

When running the server, it listens on standard input for MCP protocol messages. You can interact with it by sending JSON-RPC messages via STDIO.

Example request to list available tools:

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

Example request to read a file:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "readFile",
    "arguments": {
      "path": "/path/to/file.txt"
    }
  },
  "id": 2
}

Integration with MCP Clients

This server can be integrated with any MCP-compatible client, such as:

• Claude Desktop App
• Custom MCP clients built with Spring AI
• Other tools supporting the Model Context Protocol

Security Considerations

The FileSystemService includes basic security measures:

• Path normalization to prevent directory traversal
• Validation of file paths
• Error handling for unauthorized access attempts

For production use, consider adding:

• Whitelisting of allowed directories
• User authentication and authorization
• Rate limiting
• Audit logging

Troubleshooting

Common Issues

1. Dependencies not found: Ensure you have the Spring milestone/snapshot repositories configured in your pom.xml

2. STDIO not working: Make sure the application is running with stdio: true in the configuration

3. File access errors: Check file permissions and path validity

Logging

Enable debug logging for more detailed information:

logging:
  level:
    io.gfeller.mcp: DEBUG
    org.springframework.ai.mcp: DEBUG

License

This is a demonstration project for educational purposes.

References

• Spring AI Documentation
• Model Context Protocol Specification
• Spring Boot Documentation