path-management

Path Management System

This document provides a detailed explanation of the path management system used in the MCP Server. It covers the architecture, components, workflows, and security considerations.

Overview

The path management system provides a centralized, secure, and consistent way to handle file paths and directory navigation throughout the application. It was designed to address several key challenges:

1. Security: Prevent access to unauthorized parts of the filesystem
2. Consistency: Handle diverse path formats in a uniform manner
3. Clarity: Provide clear error messages and path resolution
4. Navigation: Support intuitive directory navigation with memory of previous locations
5. Validation: Ensure paths meet security and format requirements

Components

The system consists of three main components:

1. PathManager

PathManager is the core class responsible for all path-related operations. It handles:

• Path normalization and expansion
• Security boundary enforcement
• Path validation for reading and writing
• Directory change tracking
• Path joining and relation checking

// Example: Creating and using PathManager
const pathManager = new PathManager(config);
pathManager.setProjectsBaseDir('/path/to/projects');
pathManager.setActiveProject('/path/to/projects/MyProject.xcodeproj');

// Normalize and validate paths
const normalizedPath = pathManager.normalizePath('~/projects/file.txt');
const isAllowed = pathManager.isPathAllowed(normalizedPath);

2. SafeFileOperations

SafeFileOperations builds on PathManager to provide secure file operations with consistent error handling. It includes:

• Safe file reading with validation
• Secure file writing with directory creation
• Safe directory listing
• Consistent error handling

// Example: Using SafeFileOperations
const fileOps = new SafeFileOperations(pathManager);

// Reading a file safely
const fileContent = await fileOps.readFile('config.json');

// Writing a file with proper validation
await fileOps.writeFile('settings.json', jsonContent, true);