LiviuBirjega/files-mcp

Files MCP Server (Go)

A lightweight Model Context Protocol (MCP) server implementation in Go that provides a few file management capabilities.

Overview

This MCP server enables AI assistants to interact with the file system through a standardized protocol. It provides four core tools for file operations:

• reading,
• writing,
• listing files, and
• detailed directory exploration

Why Go for MCP Servers?

Go is an exceptional choice for building MCP servers, offering significant advantages over alternatives like TypeScript/Node.js or C:

🚀 Performance & Efficiency

• Compiled Binary: Go produces a single, self-contained executable with no runtime dependencies
• Low Memory Footprint: Minimal resource usage compared to Node.js V8 engine overhead
• Fast Startup: Near-instantaneous server startup vs. Node.js initialization time
• Efficient Concurrency: Goroutines handle multiple requests with minimal overhead

🔧 Operational Excellence

• Single Binary Deployment: No need to install Node.js, npm packages, or manage dependencies
• Cross-Platform: Same codebase compiles to Windows, macOS, and Linux without modification
• No Runtime Dependencies: Unlike Node.js which requires the runtime to be installed
• Predictable Performance: No garbage collection pauses like in Node.js or memory management issues like in C

🛡️ Reliability & Safety

• Strong Type System: Compile-time error detection prevents runtime failures
• Memory Safety: Automatic memory management without manual allocation/deallocation (unlike C)
• Error Handling: Explicit error handling prevents unexpected crashes
• Standard Library: Rich standard library reduces external dependencies

📈 Development Experience

• Simple Syntax: Easier to learn and maintain than C, more structured than JavaScript
• Fast Compilation: Quick build times enable rapid development cycles
• Built-in Testing: Comprehensive testing framework included
• Excellent Tooling: go fmt, go vet, go mod provide consistent development experience

🔄 MCP-Specific Benefits

• JSON Handling: Excellent built-in JSON marshaling/unmarshaling for MCP protocol
• Stdin/Stdout: Native support for stdio communication required by MCP
• Process Management: Clean shutdown handling and signal management
• Minimal Logging: Easy to implement minimal logging required for MCP client integration

📊 Comparison with Alternatives

🎯 Perfect Fit for MCP

MCP servers are typically:

• Long-running background processes → Go's efficiency shines
• Lightweight and resource-conscious → Go's minimal footprint is ideal
• Cross-platform compatible → Go's compilation model excels
• Reliability-critical → Go's type safety and error handling provide confidence
• Easy to deploy → Single binary deployment is perfect for MCP client integration

Result: Go delivers the perfect balance of performance, reliability, and simplicity for MCP server development.

Features

🛠️ Available Tools

• read_file - Read the contents of text files
• list_files - List files and directories in a specified path
• list_dir - Lists files and directories with detailed information including file sizes, modification times, and directory item counts
• write_file - Create new files or modify existing ones

🚀 Key Capabilities

• Cross-platform compatibility (Windows, macOS, Linux)
• MCP 2024-11-05 protocol compliance
• Graceful shutdown handling
• Error handling and validation
• Directory creation for write operations
• Minimal logging for production use
• Automatic process management via MCP clients

Installation

Prerequisites

• Go 1.19 or higher
• Git

Build from Source

git clone <repository-url>
cd files-mcp
go mod tidy
go build -o files-mcp.exe main.go

Usage

Integration with MCP Clients

This server is designed to be managed automatically by MCP-compatible clients like Windsurf. The server runs silently in the background and communicates via stdin/stdout using JSON-RPC 2.0.

Important: Do not run the server manually in a console. Let your MCP client (like Windsurf) manage the server process automatically.

MCP Client Configuration

Add the following configuration to your MCP client:

{
  "mcpServers": {
    "files-mcp": {
      "command": "/path/to/files-mcp.exe",
      "args": []
    }
  }
}

Server Lifecycle Management

The MCP server follows an automatic lifecycle managed by your MCP client:

When MCP Client Starts (e.g., Windsurf opens):

• ✅ MCP server process starts automatically
• Server reads configuration and initializes
• Tools become available for AI assistant use
• Process runs silently in the background

When MCP Client Closes (e.g., Windsurf closes):

• ✅ MCP server process stops automatically
• Graceful shutdown with proper cleanup
• No orphaned processes left running
• No manual intervention required

Lifecycle Benefits:

• No manual management - everything is automatic
• No resource waste - server only runs when needed
• Clean startup/shutdown - no leftover processes
• Consistent state - fresh server instance each session

MCP Client Starts → MCP Server Starts → Tools Available
MCP Client Closes → MCP Server Stops  → Clean Shutdown

Using with AI Assistants

Once configured, you can ask the AI assistant to:

• File Management: "List all files in my project directory"
• Code Analysis: "Read the contents of main.go and explain what it does"
• File Creation: "Create a new configuration file with these settings"
• Directory Exploration: "Show me what's in the src folder"

API Reference

Tools

read_file

Reads the contents of a text file.

Parameters:

• path (string, required): Path to the file to read

Example:

{
  "name": "read_file",
  "arguments": {
    "path": "/path/to/file.txt"
  }
}

list_files

Lists files and directories in a specified directory.

Parameters:

• directory (string, required): Directory path to list files from

Example:

{
  "name": "list_files",
  "arguments": {
    "directory": "/path/to/directory"
  }
}

list_dir

Lists files and directories in a given path with detailed information including file sizes, modification times, and directory item counts.

Parameters:

• DirectoryPath (string, required): The absolute path to the directory to list (must be absolute, not relative)

Example:

{
  "name": "list_dir",
  "arguments": {
    "DirectoryPath": "/absolute/path/to/directory"
  }
}

write_file

Writes content to a file, creating directories as needed.

Parameters:

• path (string, required): Path to the file to write
• content (string, required): Content to write to the file

Example:

{
  "name": "write_file",
  "arguments": {
    "path": "/path/to/newfile.txt",
    "content": "Hello, World!"
  }
}

Development

Project Structure

files-mcp/
├── main.go               # Entry point (47 lines, clean and focused)
├── go.mod                # Go module definition
├── README.md             # This file
├── internal/             # Internal packages (not exposed externally)
│   ├── protocol/         # MCP protocol definitions
│   │   ├── types.go      # All MCP protocol types and structs
│   │   └── constants.go  # Error codes and constants
│   ├── server/           # Core server logic
│   │   └── server.go     # MCPServer struct and request handling
│   └── tools/            # Tool implementations
│       ├── files.go      # File operations (read, write, list)
│       └── resources.go  # Resource handling
└── .gitignore            # Git ignore file

Modular Architecture

This project follows a clean, modular architecture with clear separation of concerns:

Benefits of the Modular Design:

• 🔧 Separation of Concerns: Protocol types, server logic, and tool implementations are in separate packages
• 🛠️ Maintainability: Each file has a single responsibility and is easier to understand
• 🧪 Testability: Individual components can be unit tested in isolation
• 📈 Extensibility: New tools can be easily added to the tools package
• ♻️ Code Reusability: Protocol types can be reused across different server implementations

Key Design Decisions:

• internal/ directory: Prevents external packages from importing internal implementation details
• Protocol separation: MCP protocol types are separated from business logic
• Pure functions: Tool handlers are pure functions that can be easily tested
• Minimal main.go: Entry point contains only essential bootstrapping logic (47 lines)

Package Responsibilities:

• internal/protocol/: Contains all MCP protocol types, structs, and constants
• internal/server/: Core server logic, request routing, and MCP message handling
• internal/tools/: Individual tool implementations (files, resources)
• main.go: Application entry point and server initialization

Protocol Implementation

This server implements the MCP (Model Context Protocol) specification:

• Protocol Version: 2024-11-05
• Capabilities: Tools and Resources
• Transport: stdio (stdin/stdout)
• Message Format: JSON-RPC 2.0

Error Handling

The server provides comprehensive error handling for:

• Invalid file paths
• Permission errors
• File not found scenarios
• JSON parsing errors
• Invalid tool parameters

Logging

The server uses minimal logging to stderr for essential error information only. This ensures clean operation when managed by MCP clients.

Architecture

MCP Client-Server Model

┌─────────────┐    MCP Protocol    ┌─────────────────┐
│             │ ◄─────────────────►│                 │
│ MCP Client  │     (JSON-RPC)     │  MCP Server     │
│ (Windsurf)  │                    │ (This Go App)   │
│ (Cursor)    │                    │                 │
│             │                    │                 │
└─────────────┘                    └─────────────────┘

• MCP Client (e.g., Windsurf, Cursor) manages the server process lifecycle
• MCP Server (this Go application) provides file operation tools
• Communication happens via JSON-RPC 2.0 over stdin/stdout

Examples

Reading a File

Ask your AI assistant:

"Read the contents of config.json"

Listing Directory Contents

Ask your AI assistant:

"Show me all files in the src directory"

Creating Files

Ask your AI assistant:

"Create a new package.json file for a Node.js project"

Troubleshooting

Common Issues

1. Server Not Starting: Ensure the executable path in your MCP configuration is correct
2. Permission Denied: Ensure the server has read/write permissions for target directories
3. File Not Found: Verify file paths are correct and files exist
4. Multiple Processes: Don't run the server manually - let your MCP client manage it

Debugging

• Check your MCP client's logs for connection issues
• Essential errors are logged to stderr
• Verify the executable builds without errors: go build -o files-mcp.exe main.go
• Use Task Manager to verify only one server process runs when MCP client is active

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with an MCP client
5. Submit a pull request

License

This project is open source. Please check the license file for details.

Version History

• v2.0.0 - Modular Architecture Refactoring

  • 🏗️ Major Refactoring: Transformed monolithic 650+ line main.go into modular architecture
  • 📦 New Package Structure: Organized code into internal/protocol/, internal/server/, and internal/tools/
  • 🧪 Improved Testability: Components can now be unit tested in isolation
  • 📈 Enhanced Extensibility: Easy to add new tools and features
  • 🔧 Better Maintainability: Clear separation of concerns and single responsibility principle
  • ♻️ Code Reusability: Protocol types can be reused across implementations
  • 🎯 Clean Entry Point: main.go reduced to 47 lines of focused bootstrapping code

• v1.0.0 - Initial release with core file operations

  • read_file tool
  • list_files tool
  • list_dir tool
  • write_file tool
  • MCP 2024-11-05 compliance
  • Cross-platform support
  • Minimal logging for production use
  • Automatic lifecycle management

Built with ❤️ using Go and the Model Context Protocol