Add config externalization and tool title annotations

Author: Dimitar Grigorov

README.md

@@ -117,6 +117,29 @@ Once installed, just ask Claude:
 - **Automatic:** Claude Desktop/Code provide workspace directories automatically
 - **Manual:** Specify directories in config `args: ["/path/to/project"]`
 
+## Configuration
+
+The server can be configured via environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MCP_DEFAULT_ENCODING` | Default encoding for `write_file` when none specified | `cp1251` |
+| `MCP_MAX_FILE_SIZE` | Maximum file size in bytes for operations | `10485760` (10MB) |
+
+**Example (Claude Desktop config):**
+```json
+{
+  "mcpServers": {
+    "file-tools": {
+      "command": "/path/to/mcp-file-tools",
+      "env": {
+        "MCP_DEFAULT_ENCODING": "utf-8"
+      }
+    }
+  }
+}
+```
+
 ## Use Cases
 
 ### Legacy Codebases

cmd/mcp-file-tools/main.go

@@ -33,7 +33,8 @@ func main() {
 
 	// Create MCP server with allowed directories (can be empty, directories can be added dynamically)
 	// Pass nil for logger to disable logging middleware (recovery still active)
-	server := filetoolsserver.NewServer(normalized, nil)
+	// Pass nil for config to load from environment variables (MCP_DEFAULT_ENCODING, MCP_MAX_FILE_SIZE)
+	server := filetoolsserver.NewServer(normalized, nil, nil)
 
 	// Run server on stdio transport
 	ctx := context.Background()

filetoolsserver/handler/handler.go

@@ -3,27 +3,47 @@ package handler
 import (
 	"sync"
 
+	"github.com/dimitar-grigorov/mcp-file-tools/internal/config"
 	"github.com/dimitar-grigorov/mcp-file-tools/internal/security"
 )
 
-const (
-	// DefaultEncoding is the default encoding used when none is specified
-	DefaultEncoding = "cp1251"
-)
-
 // Handler handles all file tool operations
 type Handler struct {
-	defaultEncoding string
-	allowedDirs     []string
-	mu              sync.RWMutex
+	config      *config.Config
+	allowedDirs []string
+	mu          sync.RWMutex
+}
+
+// Option is a functional option for configuring Handler
+type Option func(*Handler)
+
+// WithConfig sets the configuration for the handler
+func WithConfig(cfg *config.Config) Option {
+	return func(h *Handler) {
+		if cfg != nil {
+			h.config = cfg
+		}
+	}
 }
 
-// NewHandler creates a new Handler with allowed directories
-func NewHandler(allowedDirs []string) *Handler {
-	return &Handler{
-		defaultEncoding: DefaultEncoding,
-		allowedDirs:     allowedDirs,
+// NewHandler creates a new Handler with allowed directories and optional configuration.
+// If no config is provided via WithConfig, default configuration is used.
+func NewHandler(allowedDirs []string, opts ...Option) *Handler {
+	h := &Handler{
+		config:      config.Load(), // Load defaults from environment
+		allowedDirs: allowedDirs,
 	}
+
+	for _, opt := range opts {
+		opt(h)
+	}
+
+	return h
+}
+
+// GetConfig returns the handler's configuration
+func (h *Handler) GetConfig() *config.Config {
+	return h.config
 }
 
 // GetAllowedDirectories returns a copy of the allowed directories

filetoolsserver/handler/write.go

@@ -19,8 +19,8 @@ func (h *Handler) HandleWriteFile(ctx context.Context, req *mcp.CallToolRequest,
 	}
 	validatedPath := v.Path
 
-	// Default encoding
-	encodingName := h.defaultEncoding
+	// Default encoding from config
+	encodingName := h.config.DefaultEncoding
 	if input.Encoding != "" {
 		encodingName = strings.ToLower(input.Encoding)
 	}

filetoolsserver/server.go

@@ -4,6 +4,7 @@ import (
 	"log/slog"
 
 	"github.com/dimitar-grigorov/mcp-file-tools/filetoolsserver/handler"
+	"github.com/dimitar-grigorov/mcp-file-tools/internal/config"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
@@ -28,21 +29,26 @@ func boolPtr(b bool) *bool {
 
 // NewServer creates a new MCP server with all file tools registered.
 // If logger is nil, logging middleware is disabled but recovery is still active.
-func NewServer(allowedDirs []string, logger *slog.Logger) *mcp.Server {
-	h := handler.NewHandler(allowedDirs)
+// If cfg is nil, configuration is loaded from environment variables.
+func NewServer(allowedDirs []string, logger *slog.Logger, cfg *config.Config) *mcp.Server {
+	var handlerOpts []handler.Option
+	if cfg != nil {
+		handlerOpts = append(handlerOpts, handler.WithConfig(cfg))
+	}
+	h := handler.NewHandler(allowedDirs, handlerOpts...)
 
 	impl := &mcp.Implementation{
 		Name:    "mcp-file-tools",
 		Version: Version,
 	}
 
-	opts := &mcp.ServerOptions{
+	serverOpts := &mcp.ServerOptions{
 		Instructions:            serverInstructions,
 		Logger:                  logger,
 		InitializedHandler:      createInitializedHandler(h),
 		RootsListChangedHandler: createRootsListChangedHandler(h),
 	}
-	server := mcp.NewServer(impl, opts)
+	server := mcp.NewServer(impl, serverOpts)
 
 	// Register all tools using the new AddTool API with annotations
 	// All handlers are wrapped with recovery middleware (and logging if logger is provided)
@@ -52,6 +58,7 @@ func NewServer(allowedDirs []string, logger *slog.Logger) *mcp.Server {
 		Name:        "read_text_file",
 		Description: "Read files with automatic encoding detection and conversion to UTF-8. USE THIS instead of built-in Read tool when files may contain non-UTF-8 encodings. Auto-detects encoding if not specified. Parameters: path (required), encoding (optional), head (optional), tail (optional).",
 		Annotations: &mcp.ToolAnnotations{
+			Title:         "Read Text File",
 			ReadOnlyHint:  true,
 			OpenWorldHint: boolPtr(false),
 		},
@@ -61,6 +68,7 @@ func NewServer(allowedDirs []string, logger *slog.Logger) *mcp.Server {
 		Name:        "list_directory",
 		Description: "List files and directories with optional glob pattern filtering (e.g., *.pas, *.dfm). Parameters: path (required), pattern (optional, default: *).",
 		Annotations: &mcp.ToolAnnotations{
+			Title:         "List Directory",
 			ReadOnlyHint:  true,
 			OpenWorldHint: boolPtr(false),
 		},
@@ -70,6 +78,7 @@ func NewServer(allowedDirs []string, logger *slog.Logger) *mcp.Server {
 		Name:        "list_encodings",
 		Description: "List all supported file encodings (UTF-8, CP1251, CP1252, KOI8-R, ISO-8859-x, and others). Returns name, aliases, and description for each.",
 		Annotations: &mcp.ToolAnnotations{
+			Title:         "List Encodings",
 			ReadOnlyHint:  true,
 			OpenWorldHint: boolPtr(false),
 		},
@@ -79,6 +88,7 @@ func NewServer(allowedDirs []string, logger *slog.Logger) *mcp.Server {
 		Name:        "detect_encoding",
 		Description: "Auto-detect file encoding with confidence score and BOM detection. ALWAYS use this first when you encounter � characters or unknown encoding. Returns encoding name, confidence percentage (0-100), and whether file has BOM. Parameter: path (required).",
 		Annotations: &mcp.ToolAnnotations{
+			Title:         "Detect Encoding",
 			ReadOnlyHint:  true,
 			OpenWorldHint: boolPtr(false),
 		},
@@ -88,6 +98,7 @@ func NewServer(allowedDirs []string, logger *slog.Logger) *mcp.Server {
 		Name:        "list_allowed_directories",
 		Description: "Returns the list of directories this server is allowed to access. Subdirectories are also accessible. If empty, user needs to add directory paths as args in .mcp.json.",
 		Annotations: &mcp.ToolAnnotations{
+			Title:         "List Allowed Directories",
 			ReadOnlyHint:  true,
 			OpenWorldHint: boolPtr(false),
 		},
@@ -97,6 +108,7 @@ func NewServer(allowedDirs []string, logger *slog.Logger) *mcp.Server {
 		Name:        "get_file_info",
 		Description: "Retrieve detailed metadata about a file or directory. Returns size, creation time, last modified time, last accessed time, permissions, and type (file/directory). Only works within allowed directories. Parameter: path (required).",
 		Annotations: &mcp.ToolAnnotations{
+			Title:         "Get File Info",
 			ReadOnlyHint:  true,
 			OpenWorldHint: boolPtr(false),
 		},
@@ -106,6 +118,7 @@ func NewServer(allowedDirs []string, logger *slog.Logger) *mcp.Server {
 		Name:        "directory_tree",
 		Description: "Get a recursive tree view of files and directories as a JSON structure. Each entry includes 'name', 'type' (file/directory), and 'children' for directories. Files have no children array, while directories always have a children array (which may be empty). The output is formatted with 2-space indentation for readability. Only works within allowed directories. Parameters: path (required), excludePatterns (optional array of glob patterns to exclude).",
 		Annotations: &mcp.ToolAnnotations{
+			Title:         "Directory Tree",
 			ReadOnlyHint:  true,
 			OpenWorldHint: boolPtr(false),
 		},
@@ -115,6 +128,7 @@ func NewServer(allowedDirs []string, logger *slog.Logger) *mcp.Server {
 		Name:        "search_files",
 		Description: "Recursively search for files and directories matching a glob pattern. Use '*.ext' to match in current directory, '**/*.ext' to match recursively in all subdirectories. Returns full paths to matching items. Parameters: path (required), pattern (required), excludePatterns (optional array of patterns to skip).",
 		Annotations: &mcp.ToolAnnotations{
+			Title:         "Search Files",
 			ReadOnlyHint:  true,
 			OpenWorldHint: boolPtr(false),
 		},
@@ -125,6 +139,7 @@ func NewServer(allowedDirs []string, logger *slog.Logger) *mcp.Server {
 		Name:        "create_directory",
 		Description: "Create a directory recursively (mkdir -p). Succeeds silently if already exists. Parameter: path (required).",
 		Annotations: &mcp.ToolAnnotations{
+			Title:           "Create Directory",
 			ReadOnlyHint:    false,
 			IdempotentHint:  true,
 			DestructiveHint: boolPtr(false),
@@ -134,8 +149,9 @@ func NewServer(allowedDirs []string, logger *slog.Logger) *mcp.Server {
 
 	mcp.AddTool(server, &mcp.Tool{
 		Name:        "write_file",
-		Description: "Write files with encoding conversion from UTF-8. USE THIS instead of built-in Write tool when writing to non-UTF-8 files (legacy codebases, Cyrillic text). Default encoding is cp1251 for backward compatibility. Parameters: path (required), content (required), encoding (cp1251/windows-1251/utf-8, default: cp1251).",
+		Description: "Write files with encoding conversion from UTF-8. USE THIS instead of built-in Write tool when writing to non-UTF-8 files (legacy codebases, Cyrillic text). Default encoding is cp1251 (configurable via MCP_DEFAULT_ENCODING). Parameters: path (required), content (required), encoding (cp1251/windows-1251/utf-8, default: cp1251).",
 		Annotations: &mcp.ToolAnnotations{
+			Title:           "Write File",
 			ReadOnlyHint:    false,
 			IdempotentHint:  true,
 			DestructiveHint: boolPtr(true),
@@ -147,6 +163,7 @@ func NewServer(allowedDirs []string, logger *slog.Logger) *mcp.Server {
 		Name:        "move_file",
 		Description: "Move or rename files and directories. Can move files between directories and rename them in a single operation. Fails if destination already exists. Works for both files and directories. Parameters: source (required), destination (required).",
 		Annotations: &mcp.ToolAnnotations{
+			Title:           "Move File",
 			ReadOnlyHint:    false,
 			IdempotentHint:  false,
 			DestructiveHint: boolPtr(false),
@@ -158,6 +175,7 @@ func NewServer(allowedDirs []string, logger *slog.Logger) *mcp.Server {
 		Name:        "edit_file",
 		Description: "Make line-based edits to a text file. Each edit replaces exact text sequences with new content. Supports whitespace-flexible matching when exact match fails. Returns a git-style unified diff showing the changes. Parameters: path (required), edits (required array of {oldText, newText}), dryRun (optional bool, default false - if true, returns diff without writing).",
 		Annotations: &mcp.ToolAnnotations{
+			Title:           "Edit File",
 			ReadOnlyHint:    false,
 			IdempotentHint:  false,
 			DestructiveHint: boolPtr(true),

internal/config/config.go

@@ -0,0 +1,58 @@
+// Package config provides configuration management for MCP file tools server.
+package config
+
+import (
+	"os"
+	"strconv"
+
+	"github.com/dimitar-grigorov/mcp-file-tools/internal/encoding"
+)
+
+const (
+	// Environment variable names
+	EnvDefaultEncoding = "MCP_DEFAULT_ENCODING"
+	EnvMaxFileSize     = "MCP_MAX_FILE_SIZE"
+
+	// Default values
+	DefaultEncoding = "cp1251"
+	DefaultMaxSize  = int64(10 * 1024 * 1024) // 10MB
+)
+
+// Config holds server configuration loaded from environment variables.
+type Config struct {
+	// DefaultEncoding is the default encoding for write_file when none is specified.
+	// Set via MCP_DEFAULT_ENCODING environment variable.
+	// Default: "cp1251" (for backward compatibility with legacy codebases)
+	DefaultEncoding string
+
+	// MaxFileSize is the maximum file size in bytes for read/write operations.
+	// Set via MCP_MAX_FILE_SIZE environment variable.
+	// Default: 10485760 (10MB)
+	MaxFileSize int64
+}
+
+// Load reads configuration from environment variables with sensible defaults.
+func Load() *Config {
+	cfg := &Config{
+		DefaultEncoding: DefaultEncoding,
+		MaxFileSize:     DefaultMaxSize,
+	}
+
+	// Load default encoding from environment
+	if enc := os.Getenv(EnvDefaultEncoding); enc != "" {
+		// Validate encoding exists
+		if _, ok := encoding.Get(enc); ok {
+			cfg.DefaultEncoding = enc
+		}
+		// If invalid encoding, silently use default (cp1251)
+	}
+
+	// Load max file size from environment
+	if sizeStr := os.Getenv(EnvMaxFileSize); sizeStr != "" {
+		if size, err := strconv.ParseInt(sizeStr, 10, 64); err == nil && size > 0 {
+			cfg.MaxFileSize = size
+		}
+	}
+
+	return cfg
+}

internal/config/config_test.go

@@ -0,0 +1,80 @@
+package config
+
+import (
+	"os"
+	"testing"
+)
+
+func TestLoad_Defaults(t *testing.T) {
+	// Clear any environment variables
+	os.Unsetenv(EnvDefaultEncoding)
+	os.Unsetenv(EnvMaxFileSize)
+
+	cfg := Load()
+
+	if cfg.DefaultEncoding != DefaultEncoding {
+		t.Errorf("expected default encoding %q, got %q", DefaultEncoding, cfg.DefaultEncoding)
+	}
+
+	if cfg.MaxFileSize != DefaultMaxSize {
+		t.Errorf("expected default max size %d, got %d", DefaultMaxSize, cfg.MaxFileSize)
+	}
+}
+
+func TestLoad_CustomEncoding(t *testing.T) {
+	os.Setenv(EnvDefaultEncoding, "utf-8")
+	defer os.Unsetenv(EnvDefaultEncoding)
+
+	cfg := Load()
+
+	if cfg.DefaultEncoding != "utf-8" {
+		t.Errorf("expected encoding utf-8, got %q", cfg.DefaultEncoding)
+	}
+}
+
+func TestLoad_InvalidEncoding(t *testing.T) {
+	os.Setenv(EnvDefaultEncoding, "invalid-encoding-xyz")
+	defer os.Unsetenv(EnvDefaultEncoding)
+
+	cfg := Load()
+
+	// Should fall back to default when invalid
+	if cfg.DefaultEncoding != DefaultEncoding {
+		t.Errorf("expected fallback to %q for invalid encoding, got %q", DefaultEncoding, cfg.DefaultEncoding)
+	}
+}
+
+func TestLoad_CustomMaxFileSize(t *testing.T) {
+	os.Setenv(EnvMaxFileSize, "5242880")
+	defer os.Unsetenv(EnvMaxFileSize)
+
+	cfg := Load()
+
+	if cfg.MaxFileSize != 5242880 {
+		t.Errorf("expected max size 5242880, got %d", cfg.MaxFileSize)
+	}
+}
+
+func TestLoad_InvalidMaxFileSize(t *testing.T) {
+	os.Setenv(EnvMaxFileSize, "not-a-number")
+	defer os.Unsetenv(EnvMaxFileSize)
+
+	cfg := Load()
+
+	// Should fall back to default when invalid
+	if cfg.MaxFileSize != DefaultMaxSize {
+		t.Errorf("expected fallback to %d for invalid size, got %d", DefaultMaxSize, cfg.MaxFileSize)
+	}
+}
+
+func TestLoad_NegativeMaxFileSize(t *testing.T) {
+	os.Setenv(EnvMaxFileSize, "-1000")
+	defer os.Unsetenv(EnvMaxFileSize)
+
+	cfg := Load()
+
+	// Should fall back to default when negative
+	if cfg.MaxFileSize != DefaultMaxSize {
+		t.Errorf("expected fallback to %d for negative size, got %d", DefaultMaxSize, cfg.MaxFileSize)
+	}
+}