The Model Context Protocol (MCP) is revolutionizing how AI assistants interact with tools and data sources. In this comprehensive guide, we’ll build a production-ready MCP server in Go that provides powerful file operations—think of it as the strings utility package, but for files and AI assistants.

What is MCP?

MCP (Model Context Protocol) is a standardized way for AI assistants to interact with external tools and data sources. Instead of custom integrations for each tool, MCP provides a universal protocol that works with any compliant server.

Why build MCP tools in Go?

  • ✅ Excellent performance for file I/O operations
  • ✅ Built-in concurrency for handling multiple requests
  • ✅ Strong typing prevents runtime errors
  • ✅ Easy deployment (single binary)
  • ✅ Cross-platform compatibility

What We’re Building

An MCP server that provides:

  1. Search files: Find files by name pattern
  2. Show results: List search results with metadata
  3. Fetch content: Read file contents
  4. Modify file: Write or update files
  5. Search within files: Find text patterns in file contents
  6. Replace content: Find and replace text in files

Architecture Overview

graph TB A[AI Assistant] -->|MCP Protocol| B[MCP Server] B --> C[Tool Router] C --> D[SearchFiles] C --> E[FetchContent] C --> F[ModifyFile] C --> G[SearchContent] C --> H[ReplaceContent] D --> I[File System] E --> I F --> I G --> I H --> I style A fill:#3498db,color:#fff style B fill:#9b59b6,color:#fff style C fill:#e74c3c,color:#fff style I fill:#27ae60,color:#fff

Project Structure

mcp-file-tool/
├── cmd/
│   └── server/
│       └── main.go           # Entry point
├── internal/
│   ├── mcp/
│   │   ├── protocol.go       # MCP protocol types
│   │   └── server.go         # MCP server implementation
│   └── tools/
│       ├── search.go         # File search tool
│       ├── content.go        # Content operations
│       ├── modify.go         # File modification
│       └── replace.go        # Content replacement
├── go.mod
└── go.sum

Implementation

Step 1: MCP Protocol Types

// internal/mcp/protocol.go
package mcp

import "encoding/json"

// Request represents an MCP request
type Request struct {
    ID     string          `json:"id"`
    Method string          `json:"method"`
    Params json.RawMessage `json:"params,omitempty"`
}

// Response represents an MCP response
type Response struct {
    ID     string      `json:"id"`
    Result interface{} `json:"result,omitempty"`
    Error  *Error      `json:"error,omitempty"`
}

// Error represents an MCP error
type Error struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Data    interface{} `json:"data,omitempty"`
}

// ToolDefinition describes a tool's capabilities
type ToolDefinition struct {
    Name        string                 `json:"name"`
    Description string                 `json:"description"`
    InputSchema map[string]interface{} `json:"inputSchema"`
}

// Standard error codes
const (
    ErrCodeParseError     = -32700
    ErrCodeInvalidRequest = -32600
    ErrCodeMethodNotFound = -32601
    ErrCodeInvalidParams  = -32602
    ErrCodeInternalError  = -32603
)

Step 2: File Search Tool

// internal/tools/search.go
package tools

import (
    "fmt"
    "os"
    "path/filepath"
    "regexp"
    "time"
)

// FileSearchParams defines search parameters
type FileSearchParams struct {
    Pattern   string `json:"pattern"`    // Glob pattern or regex
    Path      string `json:"path"`       // Root path to search
    MaxDepth  int    `json:"maxDepth"`   // Maximum directory depth
    MaxResults int   `json:"maxResults"` // Limit results
}

// FileInfo represents a found file
type FileInfo struct {
    Path       string    `json:"path"`
    Name       string    `json:"name"`
    Size       int64     `json:"size"`
    ModTime    time.Time `json:"modTime"`
    IsDir      bool      `json:"isDir"`
    Extension  string    `json:"extension"`
}

// SearchResult contains search results
type SearchResult struct {
    Files      []FileInfo `json:"files"`
    TotalFound int        `json:"totalFound"`
    Truncated  bool       `json:"truncated"`
}

// SearchFiles searches for files matching a pattern
func SearchFiles(params FileSearchParams) (*SearchResult, error) {
    if params.Path == "" {
        params.Path = "."
    }

    if params.MaxResults == 0 {
        params.MaxResults = 100 // Default limit
    }

    if params.MaxDepth == 0 {
        params.MaxDepth = 10 // Default depth
    }

    var files []FileInfo
    currentDepth := 0

    // Compile pattern if it's a regex
    var pattern *regexp.Regexp
    var err error

    if isRegexPattern(params.Pattern) {
        pattern, err = regexp.Compile(params.Pattern)
        if err != nil {
            return nil, fmt.Errorf("invalid regex pattern: %w", err)
        }
    }

    err = filepath.Walk(params.Path, func(path string, info os.FileInfo, err error) error {
        if err != nil {
            return nil // Skip files we can't access
        }

        // Check depth
        depth := getDepth(params.Path, path)
        if depth > params.MaxDepth {
            if info.IsDir() {
                return filepath.SkipDir
            }
            return nil
        }

        // Match pattern
        matched := false
        if pattern != nil {
            matched = pattern.MatchString(info.Name())
        } else {
            matched, _ = filepath.Match(params.Pattern, info.Name())
        }

        if matched {
            files = append(files, FileInfo{
                Path:      path,
                Name:      info.Name(),
                Size:      info.Size(),
                ModTime:   info.ModTime(),
                IsDir:     info.IsDir(),
                Extension: filepath.Ext(info.Name()),
            })
        }

        // Limit results
        if len(files) >= params.MaxResults {
            return filepath.SkipAll
        }

        return nil
    })

    if err != nil {
        return nil, fmt.Errorf("search failed: %w", err)
    }

    return &SearchResult{
        Files:      files,
        TotalFound: len(files),
        Truncated:  len(files) >= params.MaxResults,
    }, nil
}

// Helper functions
func getDepth(root, path string) int {
    rel, _ := filepath.Rel(root, path)
    if rel == "." {
        return 0
    }
    return len(filepath.SplitList(rel))
}

func isRegexPattern(pattern string) bool {
    // Simple heuristic: if it contains regex metacharacters, treat as regex
    regexChars := []string{"^", "$", "(", ")", "[", "]", "{", "}", "|", "+", "?"}
    for _, char := range regexChars {
        if contains(pattern, char) {
            return true
        }
    }
    return false
}

func contains(s, substr string) bool {
    return len(s) > 0 && len(substr) > 0 && s != substr && len(s) >= len(substr) &&
           s[0:len(substr)] == substr || (len(s) > len(substr) && contains(s[1:], substr))
}

Step 3: Content Operations

// internal/tools/content.go
package tools

import (
    "bufio"
    "fmt"
    "os"
)

// FetchContentParams defines content fetch parameters
type FetchContentParams struct {
    Path       string `json:"path"`
    StartLine  int    `json:"startLine,omitempty"`  // 1-indexed
    EndLine    int    `json:"endLine,omitempty"`    // 1-indexed, 0 = end of file
    MaxSize    int64  `json:"maxSize,omitempty"`    // Bytes
}

// ContentResult contains file content
type ContentResult struct {
    Path      string   `json:"path"`
    Content   string   `json:"content"`
    Lines     []string `json:"lines,omitempty"`
    TotalLines int     `json:"totalLines"`
    Truncated bool     `json:"truncated"`
}

// FetchContent reads file content
func FetchContent(params FetchContentParams) (*ContentResult, error) {
    // Check file exists and is readable
    info, err := os.Stat(params.Path)
    if err != nil {
        return nil, fmt.Errorf("file not found: %w", err)
    }

    if info.IsDir() {
        return nil, fmt.Errorf("path is a directory, not a file")
    }

    // Check size limit
    if params.MaxSize > 0 && info.Size() > params.MaxSize {
        return nil, fmt.Errorf("file size (%d bytes) exceeds limit (%d bytes)",
            info.Size(), params.MaxSize)
    }

    // Read file
    file, err := os.Open(params.Path)
    if err != nil {
        return nil, fmt.Errorf("failed to open file: %w", err)
    }
    defer file.Close()

    var lines []string
    scanner := bufio.NewScanner(file)
    lineNum := 0

    for scanner.Scan() {
        lineNum++

        // Handle line range
        if params.StartLine > 0 && lineNum < params.StartLine {
            continue
        }

        if params.EndLine > 0 && lineNum > params.EndLine {
            break
        }

        lines = append(lines, scanner.Text())
    }

    if err := scanner.Err(); err != nil {
        return nil, fmt.Errorf("error reading file: %w", err)
    }

    // Build content string
    content := ""
    for _, line := range lines {
        content += line + "\n"
    }

    return &ContentResult{
        Path:       params.Path,
        Content:    content,
        Lines:      lines,
        TotalLines: lineNum,
        Truncated:  params.EndLine > 0 && lineNum > params.EndLine,
    }, nil
}

Step 4: File Modification

// internal/tools/modify.go
package tools

import (
    "fmt"
    "os"
    "path/filepath"
)

// ModifyFileParams defines modification parameters
type ModifyFileParams struct {
    Path      string `json:"path"`
    Content   string `json:"content"`
    Mode      string `json:"mode"`      // "write", "append", "insert"
    LineNum   int    `json:"lineNum,omitempty"` // For insert mode
    Backup    bool   `json:"backup"`    // Create backup before modifying
}

// ModifyResult contains modification result
type ModifyResult struct {
    Path        string `json:"path"`
    BytesWritten int   `json:"bytesWritten"`
    BackupPath  string `json:"backupPath,omitempty"`
    Success     bool   `json:"success"`
}

// ModifyFile writes or modifies a file
func ModifyFile(params ModifyFileParams) (*ModifyResult, error) {
    // Validate mode
    if params.Mode == "" {
        params.Mode = "write"
    }

    validModes := map[string]bool{"write": true, "append": true, "insert": true}
    if !validModes[params.Mode] {
        return nil, fmt.Errorf("invalid mode: %s (use: write, append, insert)", params.Mode)
    }

    // Create backup if requested
    backupPath := ""
    if params.Backup {
        if _, err := os.Stat(params.Path); err == nil {
            backupPath = params.Path + ".backup"
            if err := copyFile(params.Path, backupPath); err != nil {
                return nil, fmt.Errorf("failed to create backup: %w", err)
            }
        }
    }

    var bytesWritten int
    var err error

    switch params.Mode {
    case "write":
        bytesWritten, err = writeFile(params.Path, params.Content)

    case "append":
        bytesWritten, err = appendFile(params.Path, params.Content)

    case "insert":
        bytesWritten, err = insertAtLine(params.Path, params.Content, params.LineNum)
    }

    if err != nil {
        // Restore backup on failure
        if backupPath != "" {
            copyFile(backupPath, params.Path)
        }
        return nil, err
    }

    return &ModifyResult{
        Path:         params.Path,
        BytesWritten: bytesWritten,
        BackupPath:   backupPath,
        Success:      true,
    }, nil
}

// Helper functions
func writeFile(path, content string) (int, error) {
    // Ensure directory exists
    dir := filepath.Dir(path)
    if err := os.MkdirAll(dir, 0755); err != nil {
        return 0, fmt.Errorf("failed to create directory: %w", err)
    }

    err := os.WriteFile(path, []byte(content), 0644)
    if err != nil {
        return 0, fmt.Errorf("failed to write file: %w", err)
    }

    return len(content), nil
}

func appendFile(path, content string) (int, error) {
    file, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
    if err != nil {
        return 0, fmt.Errorf("failed to open file: %w", err)
    }
    defer file.Close()

    n, err := file.WriteString(content)
    if err != nil {
        return 0, fmt.Errorf("failed to append: %w", err)
    }

    return n, nil
}

func insertAtLine(path, content string, lineNum int) (int, error) {
    // Read existing content
    existing, err := os.ReadFile(path)
    if err != nil && !os.IsNotExist(err) {
        return 0, fmt.Errorf("failed to read file: %w", err)
    }

    // Split into lines
    lines := splitLines(string(existing))

    // Insert content
    if lineNum < 0 || lineNum > len(lines) {
        return 0, fmt.Errorf("line number %d out of range (1-%d)", lineNum, len(lines))
    }

    newLines := append(lines[:lineNum], append([]string{content}, lines[lineNum:]...)...)
    newContent := joinLines(newLines)

    // Write back
    return writeFile(path, newContent)
}

func copyFile(src, dst string) error {
    data, err := os.ReadFile(src)
    if err != nil {
        return err
    }
    return os.WriteFile(dst, data, 0644)
}

func splitLines(s string) []string {
    var lines []string
    start := 0
    for i := 0; i < len(s); i++ {
        if s[i] == '\n' {
            lines = append(lines, s[start:i])
            start = i + 1
        }
    }
    if start < len(s) {
        lines = append(lines, s[start:])
    }
    return lines
}

func joinLines(lines []string) string {
    result := ""
    for i, line := range lines {
        result += line
        if i < len(lines)-1 {
            result += "\n"
        }
    }
    return result
}

Step 5: Content Search and Replace

// internal/tools/replace.go
package tools

import (
    "bufio"
    "fmt"
    "os"
    "regexp"
    "strings"
)

// SearchContentParams defines content search parameters
type SearchContentParams struct {
    Path       string `json:"path"`
    Pattern    string `json:"pattern"`
    Regex      bool   `json:"regex"`
    IgnoreCase bool   `json:"ignoreCase"`
    MaxMatches int    `json:"maxMatches"`
}

// SearchMatch represents a match
type SearchMatch struct {
    Line      int    `json:"line"`
    Column    int    `json:"column"`
    Text      string `json:"text"`
    Context   string `json:"context"`
}

// SearchContentResult contains search results
type SearchContentResult struct {
    Matches    []SearchMatch `json:"matches"`
    TotalFound int           `json:"totalFound"`
    Truncated  bool          `json:"truncated"`
}

// SearchContent searches for text within a file
func SearchContent(params SearchContentParams) (*SearchContentResult, error) {
    file, err := os.Open(params.Path)
    if err != nil {
        return nil, fmt.Errorf("failed to open file: %w", err)
    }
    defer file.Close()

    if params.MaxMatches == 0 {
        params.MaxMatches = 100
    }

    var pattern *regexp.Regexp
    if params.Regex {
        flags := ""
        if params.IgnoreCase {
            flags = "(?i)"
        }
        pattern, err = regexp.Compile(flags + params.Pattern)
        if err != nil {
            return nil, fmt.Errorf("invalid regex: %w", err)
        }
    }

    var matches []SearchMatch
    scanner := bufio.NewScanner(file)
    lineNum := 0

    for scanner.Scan() {
        lineNum++
        line := scanner.Text()

        var found bool
        var col int

        if pattern != nil {
            loc := pattern.FindStringIndex(line)
            found = loc != nil
            if found {
                col = loc[0]
            }
        } else {
            searchText := params.Pattern
            searchLine := line

            if params.IgnoreCase {
                searchText = strings.ToLower(searchText)
                searchLine = strings.ToLower(line)
            }

            col = strings.Index(searchLine, searchText)
            found = col >= 0
        }

        if found {
            matches = append(matches, SearchMatch{
                Line:    lineNum,
                Column:  col,
                Text:    params.Pattern,
                Context: line,
            })

            if len(matches) >= params.MaxMatches {
                break
            }
        }
    }

    if err := scanner.Err(); err != nil {
        return nil, fmt.Errorf("error scanning file: %w", err)
    }

    return &SearchContentResult{
        Matches:    matches,
        TotalFound: len(matches),
        Truncated:  len(matches) >= params.MaxMatches,
    }, nil
}

// ReplaceContentParams defines replacement parameters
type ReplaceContentParams struct {
    Path        string `json:"path"`
    Pattern     string `json:"pattern"`
    Replacement string `json:"replacement"`
    Regex       bool   `json:"regex"`
    IgnoreCase  bool   `json:"ignoreCase"`
    ReplaceAll  bool   `json:"replaceAll"`
    Backup      bool   `json:"backup"`
}

// ReplaceResult contains replacement results
type ReplaceResult struct {
    Path          string `json:"path"`
    Replacements  int    `json:"replacements"`
    BackupPath    string `json:"backupPath,omitempty"`
    Success       bool   `json:"success"`
}

// ReplaceContent finds and replaces text in a file
func ReplaceContent(params ReplaceContentParams) (*ReplaceResult, error) {
    // Read file
    content, err := os.ReadFile(params.Path)
    if err != nil {
        return nil, fmt.Errorf("failed to read file: %w", err)
    }

    text := string(content)
    var newText string
    var count int

    // Perform replacement
    if params.Regex {
        flags := ""
        if params.IgnoreCase {
            flags = "(?i)"
        }

        pattern, err := regexp.Compile(flags + params.Pattern)
        if err != nil {
            return nil, fmt.Errorf("invalid regex: %w", err)
        }

        if params.ReplaceAll {
            newText = pattern.ReplaceAllString(text, params.Replacement)
            count = len(pattern.FindAllString(text, -1))
        } else {
            newText = pattern.ReplaceAllStringFunc(text, func(match string) string {
                if count == 0 {
                    count++
                    return params.Replacement
                }
                return match
            })
        }
    } else {
        oldText := params.Pattern
        if params.IgnoreCase {
            // Case-insensitive non-regex replacement is complex
            // For simplicity, we'll use regex
            pattern := regexp.MustCompile("(?i)" + regexp.QuoteMeta(params.Pattern))
            if params.ReplaceAll {
                newText = pattern.ReplaceAllString(text, params.Replacement)
                count = len(pattern.FindAllString(text, -1))
            } else {
                count = 0
                newText = pattern.ReplaceAllStringFunc(text, func(match string) string {
                    if count == 0 {
                        count++
                        return params.Replacement
                    }
                    return match
                })
            }
        } else {
            if params.ReplaceAll {
                count = strings.Count(text, oldText)
                newText = strings.ReplaceAll(text, oldText, params.Replacement)
            } else {
                newText = strings.Replace(text, oldText, params.Replacement, 1)
                if newText != text {
                    count = 1
                }
            }
        }
    }

    // Create backup if requested
    backupPath := ""
    if params.Backup {
        backupPath = params.Path + ".backup"
        if err := os.WriteFile(backupPath, content, 0644); err != nil {
            return nil, fmt.Errorf("failed to create backup: %w", err)
        }
    }

    // Write modified content
    if err := os.WriteFile(params.Path, []byte(newText), 0644); err != nil {
        return nil, fmt.Errorf("failed to write file: %w", err)
    }

    return &ReplaceResult{
        Path:         params.Path,
        Replacements: count,
        BackupPath:   backupPath,
        Success:      true,
    }, nil
}

Step 6: MCP Server Implementation

// internal/mcp/server.go
package mcp

import (
    "encoding/json"
    "fmt"
    "io"
    "log"

    "mcp-file-tool/internal/tools"
)

// Server is the MCP server
type Server struct {
    tools map[string]ToolHandler
}

// ToolHandler processes tool calls
type ToolHandler func(params json.RawMessage) (interface{}, error)

// NewServer creates a new MCP server
func NewServer() *Server {
    s := &Server{
        tools: make(map[string]ToolHandler),
    }

    // Register tools
    s.registerTools()

    return s
}

// registerTools registers all available tools
func (s *Server) registerTools() {
    s.tools["search_files"] = s.handleSearchFiles
    s.tools["fetch_content"] = s.handleFetchContent
    s.tools["modify_file"] = s.handleModifyFile
    s.tools["search_content"] = s.handleSearchContent
    s.tools["replace_content"] = s.handleReplaceContent
}

// GetTools returns tool definitions
func (s *Server) GetTools() []ToolDefinition {
    return []ToolDefinition{
        {
            Name:        "search_files",
            Description: "Search for files matching a pattern",
            InputSchema: map[string]interface{}{
                "type": "object",
                "properties": map[string]interface{}{
                    "pattern":    map[string]string{"type": "string"},
                    "path":       map[string]string{"type": "string"},
                    "maxResults": map[string]string{"type": "integer"},
                },
                "required": []string{"pattern"},
            },
        },
        {
            Name:        "fetch_content",
            Description: "Fetch content from a file",
            InputSchema: map[string]interface{}{
                "type": "object",
                "properties": map[string]interface{}{
                    "path":      map[string]string{"type": "string"},
                    "startLine": map[string]string{"type": "integer"},
                    "endLine":   map[string]string{"type": "integer"},
                },
                "required": []string{"path"},
            },
        },
        {
            Name:        "modify_file",
            Description: "Write or modify a file",
            InputSchema: map[string]interface{}{
                "type": "object",
                "properties": map[string]interface{}{
                    "path":    map[string]string{"type": "string"},
                    "content": map[string]string{"type": "string"},
                    "mode":    map[string]string{"type": "string"},
                    "backup":  map[string]string{"type": "boolean"},
                },
                "required": []string{"path", "content"},
            },
        },
        {
            Name:        "search_content",
            Description: "Search for text within a file",
            InputSchema: map[string]interface{}{
                "type": "object",
                "properties": map[string]interface{}{
                    "path":    map[string]string{"type": "string"},
                    "pattern": map[string]string{"type": "string"},
                    "regex":   map[string]string{"type": "boolean"},
                },
                "required": []string{"path", "pattern"},
            },
        },
        {
            Name:        "replace_content",
            Description: "Find and replace text in a file",
            InputSchema: map[string]interface{}{
                "type": "object",
                "properties": map[string]interface{}{
                    "path":        map[string]string{"type": "string"},
                    "pattern":     map[string]string{"type": "string"},
                    "replacement": map[string]string{"type": "string"},
                    "regex":       map[string]string{"type": "boolean"},
                    "backup":      map[string]string{"type": "boolean"},
                },
                "required": []string{"path", "pattern", "replacement"},
            },
        },
    }
}

// Tool handlers
func (s *Server) handleSearchFiles(params json.RawMessage) (interface{}, error) {
    var p tools.FileSearchParams
    if err := json.Unmarshal(params, &p); err != nil {
        return nil, err
    }
    return tools.SearchFiles(p)
}

func (s *Server) handleFetchContent(params json.RawMessage) (interface{}, error) {
    var p tools.FetchContentParams
    if err := json.Unmarshal(params, &p); err != nil {
        return nil, err
    }
    return tools.FetchContent(p)
}

func (s *Server) handleModifyFile(params json.RawMessage) (interface{}, error) {
    var p tools.ModifyFileParams
    if err := json.Unmarshal(params, &p); err != nil {
        return nil, err
    }
    return tools.ModifyFile(p)
}

func (s *Server) handleSearchContent(params json.RawMessage) (interface{}, error) {
    var p tools.SearchContentParams
    if err := json.Unmarshal(params, &p); err != nil {
        return nil, err
    }
    return tools.SearchContent(p)
}

func (s *Server) handleReplaceContent(params json.RawMessage) (interface{}, error) {
    var p tools.ReplaceContentParams
    if err := json.Unmarshal(params, &p); err != nil {
        return nil, err
    }
    return tools.ReplaceContent(p)
}

// HandleRequest processes an MCP request
func (s *Server) HandleRequest(req Request) Response {
    switch req.Method {
    case "tools/list":
        return Response{
            ID:     req.ID,
            Result: map[string]interface{}{"tools": s.GetTools()},
        }

    case "tools/call":
        var callParams struct {
            Name      string          `json:"name"`
            Arguments json.RawMessage `json:"arguments"`
        }

        if err := json.Unmarshal(req.Params, &callParams); err != nil {
            return s.errorResponse(req.ID, ErrCodeInvalidParams, "Invalid parameters")
        }

        handler, exists := s.tools[callParams.Name]
        if !exists {
            return s.errorResponse(req.ID, ErrCodeMethodNotFound,
                fmt.Sprintf("Tool not found: %s", callParams.Name))
        }

        result, err := handler(callParams.Arguments)
        if err != nil {
            return s.errorResponse(req.ID, ErrCodeInternalError, err.Error())
        }

        return Response{ID: req.ID, Result: result}

    default:
        return s.errorResponse(req.ID, ErrCodeMethodNotFound,
            fmt.Sprintf("Unknown method: %s", req.Method))
    }
}

func (s *Server) errorResponse(id string, code int, message string) Response {
    return Response{
        ID: id,
        Error: &Error{
            Code:    code,
            Message: message,
        },
    }
}

// Serve handles stdio communication
func (s *Server) Serve(reader io.Reader, writer io.Writer) error {
    decoder := json.NewDecoder(reader)
    encoder := json.NewEncoder(writer)

    log.Println("MCP File Operations Server started")

    for {
        var req Request
        if err := decoder.Decode(&req); err != nil {
            if err == io.EOF {
                break
            }
            log.Printf("Decode error: %v", err)
            continue
        }

        log.Printf("Request: %s - %s", req.ID, req.Method)

        resp := s.HandleRequest(req)

        if err := encoder.Encode(resp); err != nil {
            log.Printf("Encode error: %v", err)
        }
    }

    return nil
}

Step 7: Main Entry Point

// cmd/server/main.go
package main

import (
    "log"
    "os"

    "mcp-file-tool/internal/mcp"
)

func main() {
    server := mcp.NewServer()

    // Serve over stdio (standard for MCP)
    if err := server.Serve(os.Stdin, os.Stdout); err != nil {
        log.Fatalf("Server error: %v", err)
    }
}

MCP Request/Response Flow

sequenceDiagram participant AI as AI Assistant participant MCP as MCP Server participant Tool as Tool Handler participant FS as File System AI->>MCP: {"method": "tools/list"} MCP-->>AI: {tools: [...]} AI->>MCP: {"method": "tools/call", "name": "search_files"} MCP->>Tool: searchFiles(params) Tool->>FS: filepath.Walk() FS-->>Tool: Files found Tool-->>MCP: SearchResult MCP-->>AI: {result: {...}} AI->>MCP: {"method": "tools/call", "name": "fetch_content"} MCP->>Tool: fetchContent(params) Tool->>FS: os.ReadFile() FS-->>Tool: File content Tool-->>MCP: ContentResult MCP-->>AI: {result: {...}} AI->>MCP: {"method": "tools/call", "name": "replace_content"} MCP->>Tool: replaceContent(params) Tool->>FS: Read + Replace + Write FS-->>Tool: Success Tool-->>MCP: ReplaceResult MCP-->>AI: {result: {replacements: 3}}

Building and Testing

Build the Server

# Initialize module
go mod init mcp-file-tool

# Install dependencies
go get github.com/fsnotify/fsnotify

# Build
go build -o mcp-file-server ./cmd/server

# Or build for multiple platforms
GOOS=linux GOARCH=amd64 go build -o mcp-file-server-linux ./cmd/server
GOOS=darwin GOARCH=amd64 go build -o mcp-file-server-mac ./cmd/server
GOOS=windows GOARCH=amd64 go build -o mcp-file-server.exe ./cmd/server

Test with Examples

// test/integration_test.go
package test

import (
    "encoding/json"
    "strings"
    "testing"

    "mcp-file-tool/internal/mcp"
)

func TestToolsList(t *testing.T) {
    server := mcp.NewServer()

    req := mcp.Request{
        ID:     "1",
        Method: "tools/list",
    }

    resp := server.HandleRequest(req)

    if resp.Error != nil {
        t.Fatalf("Error: %v", resp.Error)
    }

    // Verify we have all tools
    result := resp.Result.(map[string]interface{})
    tools := result["tools"].([]mcp.ToolDefinition)

    if len(tools) != 5 {
        t.Errorf("Expected 5 tools, got %d", len(tools))
    }
}

func TestSearchFiles(t *testing.T) {
    server := mcp.NewServer()

    params := map[string]interface{}{
        "pattern": "*.go",
        "path":    ".",
    }

    paramsJSON, _ := json.Marshal(params)
    callParams := map[string]interface{}{
        "name":      "search_files",
        "arguments": json.RawMessage(paramsJSON),
    }

    callParamsJSON, _ := json.Marshal(callParams)

    req := mcp.Request{
        ID:     "2",
        Method: "tools/call",
        Params: json.RawMessage(callParamsJSON),
    }

    resp := server.HandleRequest(req)

    if resp.Error != nil {
        t.Fatalf("Error: %v", resp.Error)
    }

    t.Logf("Search result: %+v", resp.Result)
}

Manual Testing with JSON

# Start server
./mcp-file-server

# Send request (paste into stdin):
{"id":"1","method":"tools/list"}

# Expected response:
{"id":"1","result":{"tools":[...]}}

# Search files:
{"id":"2","method":"tools/call","params":{"name":"search_files","arguments":{"pattern":"*.go","path":"."}}}

Integration with AI Assistants

Configure in Claude Desktop

{
  "mcpServers": {
    "file-operations": {
      "command": "/path/to/mcp-file-server",
      "args": []
    }
  }
}

Using with OpenAI

import subprocess
import json

def call_mcp_tool(tool_name, params):
    process = subprocess.Popen(
        ['./mcp-file-server'],
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        text=True
    )

    request = {
        "id": "1",
        "method": "tools/call",
        "params": {
            "name": tool_name,
            "arguments": params
        }
    }

    process.stdin.write(json.dumps(request) + '\n')
    process.stdin.flush()

    response = process.stdout.readline()
    return json.loads(response)

Performance Optimizations

1. Concurrent File Operations

// Process multiple files concurrently
func SearchFilesConcurrent(params FileSearchParams) (*SearchResult, error) {
    results := make(chan FileInfo, 100)
    errors := make(chan error, 1)
    var wg sync.WaitGroup

    // Worker pool for processing
    for i := 0; i < runtime.NumCPU(); i++ {
        wg.Add(1)
        go worker(&wg, results, errors)
    }

    // ... search logic

    go func() {
        wg.Wait()
        close(results)
    }()

    // Collect results
    // ...
}

2. Caching for Repeated Searches

type CachedServer struct {
    *Server
    cache *lru.Cache
}

func (s *CachedServer) handleSearchFiles(params json.RawMessage) (interface{}, error) {
    // Check cache
    key := string(params)
    if cached, ok := s.cache.Get(key); ok {
        return cached, nil
    }

    // Call original handler
    result, err := s.Server.handleSearchFiles(params)
    if err == nil {
        s.cache.Add(key, result)
    }

    return result, err
}

Production Considerations

  1. Security:

    • Validate all file paths (prevent path traversal)
    • Set file size limits
    • Restrict access to certain directories
    • Sanitize regex patterns

  2. Performance:

    • Stream large files instead of loading into memory
    • Use worker pools for concurrent operations
    • Implement caching for frequently accessed files
    • Add rate limiting

  3. Reliability:

    • Always create backups for modifications
    • Use atomic writes (write to temp, then rename)
    • Handle symlinks carefully
    • Proper error messages

  4. Monitoring:

    • Log all file operations
    • Track operation latencies
    • Monitor memory usage
    • Export metrics (Prometheus)

Conclusion

We’ve built a complete MCP server in Go that provides powerful file operations for AI assistants. This tool demonstrates:

  • ✅ Full MCP Protocol Implementation: Standards-compliant server
  • ✅ Comprehensive File Operations: Search, read, write, find/replace
  • ✅ Production-Ready Code: Error handling, backups, validation
  • ✅ High Performance: Efficient file I/O and concurrent processing
  • ✅ Easy Integration: Works with any MCP-compatible AI assistant

The same architecture can be extended to support:

  • Database operations
  • API integrations
  • Code analysis tools
  • Build system integrations
  • DevOps automation

Previous in series: Building a Real-Time File Monitor

MCP Documentation: modelcontextprotocol.io

Source code: Available on GitHub with complete implementation and tests.